Skip to main content

Codiac Agent Reference

The Codiac in-cluster agent runs inside your Kubernetes cluster and enables Codiac to manage workloads, configurations, and cluster-level operations there. This document covers install, configuration, and removal — both via the Codiac CLI and via the underlying Helm commands.

Overview​

The agent is a Helm chart. Every cod cluster agent command is a thin wrapper around a single helm invocation. This means you can manage the agent entirely with standard Helm tooling if you prefer — useful when building IaC pipelines, GitOps workflows, or CI scripts that don't invoke the Codiac CLI directly.

The agent must be installed before any cod cluster install or cod cluster stack install operation can succeed.

Installing the Agent​

Via Codiac CLI​

# Interactive — select cluster from list
cod cluster agent install

# Specify cluster directly
cod cluster agent install my-cluster

# Scripted (non-interactive)
cod cluster agent install my-cluster --silent

Via Helm (manual equivalent)​

helm install codiac-agent oci://registry-1.docker.io/codiacimages/codiac-umbrella \
  --namespace codiac-components \
  --create-namespace

Uninstalling the Agent​

Via Codiac CLI​

cod cluster agent uninstall my-cluster

Via Helm​

helm uninstall codiac-agent --namespace codiac-components

Configuring the Agent​

The cod cluster agent configure command lets you update agent settings without reinstalling. It supports two modes:

ModeBehavior
overlay (default)Merges the provided settings on top of the existing configuration
replaceOverwrites the entire agent configuration with the provided settings

Use overlay for targeted changes. Use replace only when you want to fully reset the configuration to a known state.

Settings can be provided three ways:

  1. Interactively — the CLI prompts you to select a setting key and enter a value
  2. Inline JSON/YAML flag — --settings '{"key": "value"}'
  3. Piped stdin — cat mysettings.yaml | cod cluster agent configure my-cluster

Examples​

# Interactive — prompts for cluster, mode, and a single key-value pair
cod cluster agent configure

# Patch a single setting inline
cod cluster agent configure my-cluster \
  --settings '{"keel": {"image": {"tag": "v1.2.3"}}}'

# Replace the entire config from a YAML file
cat mysettings.yaml | cod cluster agent configure my-cluster --mode replace

# Scripted
cod cluster agent configure my-cluster \
  --settings '{"keel": {"image": {"tag": "v1.2.3"}}}' \
  --silent

Via Helm (manual equivalent)​

# Overlay settings
helm upgrade codiac-agent oci://registry-1.docker.io/codiacimages/codiac-umbrella \
  --namespace codiac-components \
  --reuse-values \
  --set keel.image.tag=v1.2.3

# Replace configuration entirely
helm upgrade codiac-agent oci://registry-1.docker.io/codiacimages/codiac-umbrella \
  --namespace codiac-components \
  -f my-full-values.yaml

Settings Schema​

The following settings are available on the agent. Use the dot-path notation with the --settings flag, or select them interactively from the prompted list.

Codiac Cluster Agent Chart​

SettingDescription
codiac-cluster-agent-chart.fullnameOverrideOverride for the full Helm release name of the cluster agent chart
codiac-cluster-agent-chart.configMap.createWhether to create the agent ConfigMap (true/false)
codiac-cluster-agent-chart.env.<VAR_NAME>An environment variable on the cluster agent container (replace <VAR_NAME> with the variable name)
codiac-cluster-agent-chart.keel.policyKeel image watch policy (all, major, minor, patch, force)
codiac-cluster-agent-chart.keel.pollScheduleKeel poll schedule as a cron expression (e.g., @every 3m)
codiac-cluster-agent-chart.keel.triggerKeel trigger type (e.g., poll)

Keel Chart​

Keel is the image auto-updater bundled with the Codiac agent.

SettingDescription
keel.image.repositoryRepository for the Keel image
keel.image.tagTag (version) of the Keel image to run
keel.image.pullPolicyImage pull policy (Always, IfNotPresent, Never)
keel.helmProvider.enabledWhether to enable the Helm provider for Keel (true/false)
keel.helmProvider.versionVersion of the Helm binary for Keel to use
keel.resources.limits.cpuCPU limit for Keel (e.g., 100m)
keel.rbac.enabledWhether to enable RBAC for Keel (true/false)
keel.rbac.role.createWhether to create the Keel RBAC role (true/false)
keel.rbac.serviceAccount.createWhether to create the Keel service account (true/false)
keel.nodeSelector.<label-key>A node selector label for the Keel pod (replace <label-key> with the label)

Typical Post-Install Configuration​

For most users, the default agent configuration works immediately after install. The settings most commonly changed after a first install are:

  • keel.image.tag — pin Keel to a specific version rather than using the chart default
  • codiac-cluster-agent-chart.keel.pollSchedule — adjust the image poll interval for your update cadence (default is frequent; you may want to slow it down)
  • codiac-cluster-agent-chart.env.* — inject environment variables needed by your specific cluster configuration or private registry setup

Checking Agent Status​

After installing, you can verify the agent is running with standard kubectl commands once you have connected your local context (cod cluster connect <cluster-name>):

kubectl get pods -n codiac-components
kubectl logs -n codiac-components -l app=codiac-cluster-agent

Command Reference​

GoalCommand
Install the agentcod cluster agent install <cluster>
Uninstall the agentcod cluster agent uninstall <cluster>
Configure the agent (interactive)cod cluster agent configure <cluster>
Configure the agent (inline)cod cluster agent configure <cluster> --settings '<json>'
Configure from filecat settings.yaml | cod cluster agent configure <cluster>
Replace full configcod cluster agent configure <cluster> --mode replace --settings '<json>'