ArkEvent

ArkEvent defines event sources that trigger ArkTeam runs — HTTP webhooks, cron schedules, and team-output triggers with fan-out support.

API: arkonis.dev/v1alpha1 Kind: ArkEvent Scope: Namespaced

ArkEvent defines an event source that triggers one or more ArkTeam pipeline runs. Three source types are supported: HTTP webhook, cron schedule, and the output of another team. A single event can fan out to multiple teams in parallel.

Webhook trigger

Listens for inbound HTTP POST requests. The operator creates a bearer-token Secret per event and writes the full cluster-internal URL to .status.webhookURL.

apiVersion: arkonis.dev/v1alpha1
kind: ArkEvent
metadata:
  name: pipeline-trigger
  namespace: ai-team
spec:
  source:
    type: webhook
  targets:
    - team: my-team
    - team: analytics-pipeline   # fan-out: both fire in parallel

Fire the webhook:

TOKEN=$(kubectl get secret pipeline-trigger-webhook-token -n ai-team \
  -o jsonpath='{.data.token}' | base64 -d)

WEBHOOK_URL=$(kubectl get arkevent pipeline-trigger -n ai-team \
  -o jsonpath='{.status.webhookURL}')

# Async (returns immediately)
curl -X POST "$WEBHOOK_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"topic": "quantum computing"}'

# Sync (waits for completion, returns output)
curl -X POST "$WEBHOOK_URL?mode=sync&timeout=120s" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"topic": "quantum computing"}'

Sync mode: if the run does not complete within the timeout, the server returns 504 with a JSON body containing the ArkRun name so you can poll for the result separately.

Cron trigger

Fires on a standard 5-field cron schedule (UTC).

apiVersion: arkonis.dev/v1alpha1
kind: ArkEvent
metadata:
  name: daily-report
  namespace: ai-team
spec:
  source:
    type: cron
    cron: "0 8 * * *"   # every day at 08:00 UTC
  concurrencyPolicy: Forbid   # skip if previous run still active
  targets:
    - team: report-team
      input:
        date: "{{ .trigger.firedAt }}"

Common schedules:

Schedule	Expression
Every hour	`0 * * * *`
Daily at 08:00 UTC	`0 8 * * *`
Weekdays at 09:00 UTC	`0 9 * * 1-5`
Every 15 minutes	`/15 * * *`

Team-output trigger

Fires when another team reaches a specific phase. Useful for chaining independent teams without embedding them in a single pipeline.

apiVersion: arkonis.dev/v1alpha1
kind: ArkEvent
metadata:
  name: post-research
  namespace: ai-team
spec:
  source:
    type: team-output
    teamOutput:
      name: research-team
      onPhase: Succeeded
  targets:
    - team: summarize-team
      input:
        content: "{{ .trigger.output }}"
    - team: publish-team   # fan-out: both fire in parallel

Input templates

Target inputs support Go templates with trigger context:

Expression	Available in
`{{ .trigger.name }}`	all types
`{{ .trigger.firedAt }}`	all types
`{{ .trigger.body.<field> }}`	webhook only — JSON body fields
`{{ .trigger.output }}`	team-output only — upstream team result

Concurrency policy

Value	Behavior
`Allow` (default)	Always dispatch a new run, even if a previous one is running.
`Forbid`	Skip the fire if any run owned by this event is still `Running`.

Suspending and resuming

kubectl patch arkevent daily-report -n ai-team \
  --type=merge -p '{"spec":{"suspended":true}}'

kubectl patch arkevent daily-report -n ai-team \
  --type=merge -p '{"spec":{"suspended":false}}'

Exposing webhooks externally

The operator’s webhook port is 8092. Expose via Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ark-webhooks
  namespace: ark-system
spec:
  rules:
    - host: ark.example.com
      http:
        paths:
          - path: /triggers
            pathType: Prefix
            backend:
              service:
                name: ark-operator
                port:
                  number: 8092

Spec reference

`spec`

Field	Type	Required	Default	Description
`source`	EventSource	yes	—	Defines what fires the trigger.
`targets`	[]EventTarget	yes	—	Teams to dispatch when the trigger fires. All targets run in parallel.
`concurrencyPolicy`	string	no	`Allow`	`Allow` — always dispatch. `Forbid` — skip if a previous run is still `Running`.
`suspended`	bool	no	`false`	Pause all fires without deleting the resource.

`spec.source`

Field	Type	Required	Description
`type`	string	yes	`webhook` \| `cron` \| `team-output`
`cron`	string	cron only	Standard 5-field cron expression (UTC).
`teamOutput`	TeamOutputSource	team-output only	Upstream team to watch.

`spec.source.teamOutput`

Field	Type	Required	Default	Description
`name`	string	yes	—	Name of the upstream `ArkTeam` in the same namespace.
`onPhase`	string	no	`Succeeded`	Phase that fires the trigger: `Succeeded` or `Failed`.

`spec.targets[]`

Field	Type	Required	Description
`team`	string	yes	Name of an `ArkTeam` in the same namespace to trigger.
`input`	map[string]string	no	Input overrides. Values are Go templates evaluated with trigger context.

Webhook authentication

The operator creates a bearer-token Secret named {event-name}-webhook-token in the same namespace.

Webhook URL query parameters:

Parameter	Description
`mode=sync`	Hold the connection open until the run completes.
`timeout=<duration>`	Max wait in sync mode (e.g. `120s`). Defaults to `60s`. Returns `504` on timeout.

Sync response:

{
  "status": "succeeded",
  "output": "The result string...",
  "durationMs": 14200,
  "runName": "my-team-run-a1b2c3"
}

`status`

Field	Type	Description
`webhookURL`	string	Cluster-internal webhook URL (webhook type only).
`lastFiredAt`	Time	When the event last fired.
`nextFireAt`	Time	Next scheduled fire time (cron type only).
`firedCount`	int64	Total number of times this event has fired.
`observedGeneration`	int64	The `.metadata.generation` this status reflects.
`conditions`	[]Condition	`Ready=True` when the source is active.