GitOps

ark-operator resources are standard Kubernetes manifests. They work with any GitOps tool without modification. Promoting a new system prompt is a pull request; rolling it back is a git revert.

Repository layout

A typical GitOps repository for an agent team:

agents/
├── prompts/
│   ├── researcher.txt       ← system prompt files
│   ├── writer.txt
│   └── editor.txt
├── configmaps/
│   ├── researcher-prompt.yaml   ← ConfigMap wrapping each prompt file
│   ├── writer-prompt.yaml
│   └── editor-prompt.yaml
├── agents/
│   ├── researcher-agent.yaml    ← ArkAgent referencing the ConfigMap
│   ├── writer-agent.yaml
│   └── editor-agent.yaml
└── teams/
    └── content-pipeline.yaml    ← ArkTeam wiring them together

System prompts as files

Store prompts in plain .txt files and manage them with kubectl create configmap --from-file:

prompts/researcher.txt:

You are a research specialist. Given a topic, provide a detailed summary
of key facts, recent developments, and notable perspectives.

Always cite specific points. Structure your response as:
1. Background
2. Key findings
3. Open questions

Create the ConfigMap:

kubectl create configmap researcher-prompt \
  --from-file=system.txt=./prompts/researcher.txt \
  --namespace my-org \
  --dry-run=client -o yaml > configmaps/researcher-prompt.yaml

configmaps/researcher-prompt.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: researcher-prompt
  namespace: my-org
data:
  system.txt: |
    You are a research specialist. Given a topic, provide a detailed summary
    of key facts, recent developments, and notable perspectives.
    ...

Reference from the ArkAgent:

spec:
  model: llama3.2
  systemPromptRef:
    configMapKeyRef:
      name: researcher-prompt
      key: system.txt

How the operator detects prompt changes

When a ConfigMap referenced by systemPromptRef is updated, the operator detects the change during its next reconcile loop (typically within 30 seconds). It updates the backing Deployment’s pod template, which triggers a rolling restart of agent pods.

No manual intervention needed. No kubectl rollout restart. The operator handles it.

ArgoCD setup

Point ArgoCD at your agents repository. ArgoCD applies manifests in the order they appear; since ConfigMaps have no dependencies, they apply before ArkAgents by default.

# argocd-app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: content-agents
  namespace: argocd
spec:
  source:
    repoURL: https://github.com/my-org/agents-repo
    path: agents/
    targetRevision: HEAD
  destination:
    server: https://kubernetes.default.svc
    namespace: my-org
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Flux setup

Create a GitRepository and Kustomization:

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: agents-repo
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/my-org/agents-repo
  ref:
    branch: main
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: content-agents
  namespace: flux-system
spec:
  interval: 5m
  path: ./agents
  prune: true
  sourceRef:
    kind: GitRepository
    name: agents-repo
  targetNamespace: my-org

The `ark deploy` command

For local and CI usage, ark deploy applies a multi-doc YAML file in the correct dependency order:

ark deploy team.yaml -n my-org

Order of application:

ConfigMaps (prompt files)
ArkSettings
ArkMemory
ArkAgents
ArkTeams
ArkServices
ArkEvents

This ensures all dependencies exist before the resources that reference them are created.

Dry run to see what would be applied:

ark deploy team.yaml -n my-org --dry-run

Prompt review workflow

A pull request that changes a system prompt:

- You are a research assistant. Be thorough.
+ You are a research specialist. Be thorough and always cite your sources.
+ Structure your response as numbered points.

The review process is identical to a code change: diff review, approval, merge, ArgoCD sync. If the new prompt degrades output quality, revert the commit — ArgoCD syncs and the agent pods restart with the old prompt within seconds.

Secret management

API keys should never be committed to git. Use your existing secret management approach:

External Secrets Operator:

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: ark-api-keys
  namespace: my-org
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
    kind: SecretStore
  target:
    name: ark-api-keys
  data:
    - secretKey: OPENAI_API_KEY
      remoteRef:
        key: secret/ark/openai
        property: api_key

Sealed Secrets:

kubectl create secret generic ark-api-keys \
  --from-literal=OPENAI_API_KEY=sk-... \
  --dry-run=client -o yaml | kubeseal > sealed-api-keys.yaml

Reference the secret from Helm:

helm upgrade ark-operator arkonis/ark-operator \
  --set apiKeys.existingSecret=ark-api-keys