notification

README

pkg/notification

The notification package dispatches alerts when a Katalog condition evaluates to true. It supports email (SMTP) and Slack channels, with per-team interval enforcement to prevent alert floods. Dispatch is handled by a Notifier interface with two implementations: DirectNotifier sends directly to SMTP/Slack (standalone mode or local dev), and GatewayNotifier POSTs an Event payload to the Orkestra gateway's /notify endpoint (in-cluster default).

Notifications are condition-driven: a condition that is true triggers its notify: block. Each team listed in the block receives a message through every channel configured for that team. A per-condition, per-team timestamp gate suppresses re-delivery until the declared interval has elapsed.

What lives here

File	Role
notification.go	NotificationStack — holds Katalog, LastSent map, and Notifier; ProcessConditionNotifications entry point; dispatchTeam fan-out
notifier.go	Notifier interface and Event type — {KatalogName, CRName, CRNamespace, GVK, CondKey, TeamName, Subject, Message, Timestamp, Data}
direct_notifier.go	DirectNotifier — dispatches directly to SMTP/Slack; used in standalone mode or outside a cluster
email.go	sendEmailNotification — SMTP dispatch; SMTPConfig; STARTTLS upgrade
slack.go	sendSlackNotification — Incoming Webhook POST; SlackPayload JSON builder

Developer documentation

Full step-by-step documentation is in docs/.

I want to…	Go to
Understand the notification flow from condition to delivery	01 — Overview
Configure notify: on a condition	02 — NotifyBlock
Add a new channel or understand email / Slack dispatch	03 — Channels

Documentation

Overview

pkg/notification/email.go

Email notification dispatch via SMTP. SMTP credentials are read from pkg/konfig env vars:

SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM

Recipients are declared per team in the Katalog notification config. Multiple recipients receive one email each (BCC is not used — per-recipient tracking allows future per-recipient suppression).

pkg/notification/slack.go

Slack notification dispatch via incoming webhooks. One HTTP POST per channel per send. Channels are notified in parallel.

Message format: plain text with Markdown-like formatting that Slack renders. The message template is evaluated against the full resolver data map before dispatch so it can reference .spec.*, .metadata.*, .status.*, metrics.*, etc.

Index

• type DirectNotifier
  • func NewDirectNotifier(kat *katalog.Katalog) *DirectNotifier
  • func (d *DirectNotifier) Dispatch(ctx context.Context, ev Event) error
• type Event
• type GatewayNotifier
  • func NewGatewayNotifier(endpoint string) *GatewayNotifier
  • func (g *GatewayNotifier) Dispatch(ctx context.Context, ev Event) error
• type NotificationStack
  • func NewNotificationStack(kat *katalog.Katalog, notifier Notifier) *NotificationStack
  • func (s *NotificationStack) ProcessConditionNotifications(ctx context.Context, data map[string]interface{}, cond orktypes.Condition, ...)
• type NotificationState
  • func NewNotificationState() *NotificationState
• type Notifier
• type SMTPConfig
  • func (c SMTPConfig) EffectivePort() string
  • func (c SMTPConfig) IsConfigured() bool

Types

type DirectNotifier

type DirectNotifier struct {
	// contains filtered or unexported fields
}

DirectNotifier dispatches via SMTP/Slack without a gateway. Used when gatewayEndpoint is not configured.

func NewDirectNotifier

func NewDirectNotifier(kat *katalog.Katalog) *DirectNotifier

func (*DirectNotifier) Dispatch

func (d *DirectNotifier) Dispatch(ctx context.Context, ev Event) error

Dispatch fires the event directly to the team's configured channels. Throttle was already enforced by ProcessConditionNotifications — dispatch is unconditional.

type Event

type Event struct {
	KatalogName string                 `json:"katalogName"`
	CRName      string                 `json:"crName"`
	CRNamespace string                 `json:"crNamespace"`
	GVK         string                 `json:"gvk"`
	CondKey     string                 `json:"condKey"`
	TeamName    string                 `json:"teamName"`
	Subject     string                 `json:"subject"`
	Message     string                 `json:"message"`
	Timestamp   time.Time              `json:"timestamp"`
	Data        map[string]interface{} `json:"data,omitempty"`
}

Event is a dispatch-ready notification unit. The runtime builds one per condition+team pair after the throttle check passes.

type GatewayNotifier

type GatewayNotifier struct {
	// contains filtered or unexported fields
}

GatewayNotifier POSTs events to <endpoint>/notify. The gateway owns SMTP/Slack credential lookup and actual dispatch.

func NewGatewayNotifier

func NewGatewayNotifier(endpoint string) *GatewayNotifier

func (*GatewayNotifier) Dispatch

func (g *GatewayNotifier) Dispatch(ctx context.Context, ev Event) error

type NotificationStack

type NotificationStack struct {
	Katalog  *katalog.Katalog
	State    *NotificationState
	Notifier Notifier
}

NotificationStack combines Katalog context, throttle state, and the active Notifier. One instance per GenericReconciler when notification is enabled.

func NewNotificationStack

func NewNotificationStack(kat *katalog.Katalog, notifier Notifier) *NotificationStack

NewNotificationStack creates a ready-to-use stack. notifier is either a DirectNotifier (standalone) or GatewayNotifier (gateway path).

func (*NotificationStack) ProcessConditionNotifications

func (s *NotificationStack) ProcessConditionNotifications(
	ctx context.Context,
	data map[string]interface{},
	cond orktypes.Condition,
	now time.Time,
)

ProcessConditionNotifications enforces per-team throttle and fires an Event via s.Notifier for every team whose interval has elapsed.

Call this after a condition has already been evaluated as true.

type NotificationState

type NotificationState struct {
	// key: operatorName + "|" + conditionKey + "|" + teamName
	LastSent map[string]time.Time
}

NotificationState tracks per condition+team last-send timestamps for throttling.

func NewNotificationState

func NewNotificationState() *NotificationState

type Notifier

type Notifier interface {
	Dispatch(ctx context.Context, ev Event) error
}

Notifier dispatches a resolved, throttle-checked notification event. DirectNotifier handles standalone (no-gateway) deployments. GatewayNotifier delegates to the gateway process via HTTP.

type SMTPConfig

type SMTPConfig struct {
	Host string
	Port string // default "587"
	User string
	Pass string
	From string
}

SMTPConfig holds the SMTP connection parameters read from pkg/konfig. Constructed by the caller (notification.Notifier) from konfig at startup.

func (SMTPConfig) EffectivePort

func (c SMTPConfig) EffectivePort() string

EffectivePort returns the port, defaulting to 587 (STARTTLS submission).

func (SMTPConfig) IsConfigured

func (c SMTPConfig) IsConfigured() bool

IsConfigured returns true when the minimum required SMTP fields are present.