ArkNotify

ArkNotify defines a reusable notification policy that routes team run events to Slack or webhook channels with configurable rate limiting.

API: arkonis.dev/v1alpha1 Kind: ArkNotify Short name: anfy Scope: Namespaced

ArkNotify is a reusable notification policy. Attach it to an ArkTeam via spec.notifyRef to receive alerts when runs succeed, fail, time out, or hit token budgets. Attach it to an ArkAgent to be notified when agents degrade.

Events

EventFired when
TeamSucceededAn ArkRun reaches Succeeded phase.
TeamFailedAn ArkRun reaches Failed phase.
TeamTimedOutA run hits spec.timeoutSeconds.
BudgetExceededA run hits spec.maxTokens.
DailyLimitReachedThe team’s rolling 24h budget is consumed; replicas scaled to 0.
AgentDegradedAn ArkAgent semantic health check fails.

Omit spec.on to receive all events.

Example: Slack on failure

apiVersion: arkonis.dev/v1alpha1
kind: ArkNotify
metadata:
  name: on-failure-slack
  namespace: my-org
spec:
  on:
    - TeamFailed
    - TeamTimedOut
    - BudgetExceeded
  rateLimitSeconds: 300
  channels:
    - type: slack
      slack:
        webhookURLFrom:
          name: slack-secrets
          key: incoming-webhook-url

Attach to a team:

apiVersion: arkonis.dev/v1alpha1
kind: ArkTeam
metadata:
  name: blog-pipeline
spec:
  notifyRef:
    name: on-failure-slack

Example: Generic webhook on all events

apiVersion: arkonis.dev/v1alpha1
kind: ArkNotify
metadata:
  name: audit-all
  namespace: my-org
spec:
  rateLimitSeconds: 0   # no rate limiting
  channels:
    - type: webhook
      webhook:
        urlFrom:
          name: audit-secrets
          key: webhook-url
        headers:
          - name: Authorization
            valueFrom:
              name: audit-secrets
              key: token
        template: |
          {{ .Event }} — {{ .TeamName }}/{{ .RunName }}
          {{ .Message }}

Rate limiting

rateLimitSeconds prevents notification storms. After one notification fires for a (team, event) pair, subsequent fires are suppressed until the window passes.

  • Tracked per (team, event) pair — TeamFailed and BudgetExceeded are independent.
  • Default: 300 seconds (5 minutes).
  • Set to 0 to disable.

Spec reference

spec

FieldTypeRequiredDefaultDescription
on[]stringnoall eventsEvent types that trigger notifications. Valid values: TeamSucceeded, TeamFailed, TeamTimedOut, BudgetExceeded, DailyLimitReached, AgentDegraded.
channels[]ChannelSpecyes—Notification targets. At least one required.
rateLimitSecondsintno300Minimum interval between notifications for the same (team, event) pair. 0 to disable.

spec.channels[]

FieldTypeRequiredDescription
typestringyeswebhook or slack.
webhookWebhookChannelSpecwebhook onlyHTTP POST target configuration.
slackSlackChannelSpecslack onlySlack incoming webhook configuration.
templatestringnoGo template for the message body.

channels[].webhook

FieldTypeRequiredDefaultDescription
urlstringone of—Literal webhook URL.
urlFromSecretKeySelectorone of—Read the URL from a Secret key. Takes precedence over url.
methodstringnoPOSTHTTP method.
headers[]WebhookHeaderno—Additional HTTP headers.

channels[].webhook.headers[]

FieldTypeRequiredDescription
namestringyesHTTP header name.
valuestringone ofLiteral header value.
valueFromSecretKeySelectorone ofRead value from a Secret key.

channels[].slack

FieldTypeRequiredDescription
webhookURLFromSecretKeySelectoryesSecret key containing the Slack incoming webhook URL.

Message template context

FieldTypeDescription
.EventstringEvent type string, e.g. "TeamFailed"
.TeamNamestringArkTeam name
.RunNamestringArkRun name (empty for AgentDegraded)
.PhasestringTerminal phase of the run
.NamespacestringKubernetes namespace
.MessagestringHuman-readable detail
.FiredAttime.TimeWhen the notification was dispatched

status

FieldTypeDescription
lastDispatches[]DispatchResultMost recent dispatch result per channel.
conditions[]ConditionReady.

status.lastDispatches[]

FieldTypeDescription
channelIndexintZero-based index into spec.channels.
lastFiredAtTimeWhen the most recent dispatch attempt was made.
lastEventstringEvent type that triggered the dispatch.
succeededboolfalse when all retry attempts failed.
errorstringLast error message when succeeded is false.

See also