Skip to main content
You configure koperator with Helm values. The install command that the Komodor Agentic Operation Platform (KAOP) gives you sets the values you chose for the deploy target. To change one later, run helm upgrade with the new value and keep the others.

Namespace modes

In both modes, koperator never manages kube-system, kube-public, kube-node-lease, its own release namespace (agentops), or a namespace in deniedNamespaces. KAOP refuses a deploy there before it reaches the cluster, and koperator refuses it too.
Choose cluster-wide mode only for a cluster that one team owns. Kubernetes RBAC cannot grant “every namespace except these”, so in cluster-wide mode koperator’s ServiceAccount can read and write Secrets in every namespace, kube-system included. Only koperator’s own code keeps it out of the denied namespaces. A cluster-wide koperator must also be the only koperator in the cluster.
Several koperators can share a cluster when each manages its own list of namespaces, also from different KAOP accounts. Each koperator claims its namespaces at install time with a Lease named koperator-claim. An install that names a namespace another koperator holds fails, and the error names that koperator. If a koperator was deleted without helm uninstall, take its namespace over with --set 'forceClaim={team-b}', or --set 'forceClaim={*}' for a stale cluster-wide claim.

Guardrails

Koperator checks every agent spec against the guardrails in your values before it applies anything. If one check fails, it refuses the whole spec with guardrail_refused, applies no part of it, and the agent keeps its last applied state. The refusal names each field and rule, and the developer sees it in KAOP. A spec can never set the pod or container security context, ServiceAccount annotations, RBAC, the Service, or an inline secret value. Koperator also refuses pod annotations for kube2iam and kiam (iam.amazonaws.com/), AppArmor and seccomp. The full allowlist is in the chart’s README. The create dialog sets every guardrail except allowedFields. Set that one in your values.

Let agents use your Secrets and ServiceAccounts

An agent can refer only to a Secret that koperator created for it, or to a Secret or ServiceAccount that you labelled. Every other reference is refused.
Koperator sends KAOP the names of the labelled Secrets and ServiceAccounts, never their values, so the deploy wizard offers only those. When you label a Secret that a refused agent needs, koperator checks that agent again.
  • Developers cannot set ServiceAccount annotations. To give agents a cloud identity, create a ServiceAccount with the IRSA or Workload Identity annotation yourself and label it.
  • The install key Secret and Helm release Secrets are never usable, even with the label.
  • You do not create a Secret for the agent’s worker token. Koperator gets it from KAOP and writes it to a Secret it owns, <agent>-agentops-bootstrap, where <agent> is the name of the agent’s Deployment. When KAOP rotates the token, koperator rolls the agent’s pods, and the old pod finishes its runs first.

Network requirements

Koperator needs outbound HTTPS (443) only. Nothing connects in. To pull from a mirror instead of ghcr.io, set image.registry for koperator itself and registry for agent images. If the registry refuses the digest request, for example because your nodes pull with a cloud role that koperator does not have, koperator applies the image by its tag instead.

Proxy and internal CA

Two independent values control the proxy:
  • proxy is used for koperator’s calls to KAOP only.
  • proxyEnv.httpsProxy, proxyEnv.httpProxy and proxyEnv.noProxy set HTTPS_PROXY, HTTP_PROXY and NO_PROXY in the koperator container. When you set them, the chart always adds the Kubernetes API (kubernetes.default.svc, .svc, .cluster.local and the service host) to NO_PROXY.
If your proxy intercepts TLS, or KAOP is behind an internal CA, put the CA in a ConfigMap in the release namespace:
Then add these flags to the helm upgrade --install command:
The proxy must not cut long-lived connections: koperator holds a long-poll open to KAOP so that a change starts to apply within 30 seconds.

KEDA

Agents that scale to zero need KEDA 2.10 or later. Use your own KEDA if the cluster has one. If it does not, select Install KEDA with koperator when you create the deploy target, and the command sets keda.enabled=true. The chart then installs KEDA 2.20.2 in the release namespace.
  • The chart never installs over an existing KEDA. If scaledobjects.keda.sh exists and this release did not install it, the install fails.
  • Keep keda.enabled=true in every later upgrade. An upgrade without it removes KEDA.
  • helm uninstall keeps the KEDA CRDs. Deleting them would delete every ScaledObject in the cluster, including those of other teams. To remove KEDA completely, delete the *.keda.sh CRDs yourself.

High availability

Koperator runs two replicas by default. One is the leader, which calls KAOP and changes agents; the other waits to take over. When the leader stops cleanly, the other replica takes over in about 2 seconds. When the leader crashes or its node stops, the other replica takes over after leaderElection.leaseDuration, 15 seconds by default. The agents keep running in both cases.
  • With more than one replica, the chart adds a PodDisruptionBudget (maxUnavailable: 1) and spreads the replicas across nodes when it can. Set topologySpreadConstraints to spread them another way, for example across zones.
  • Both replicas report ready on /readyz. Some koperator metrics come only from the leader; the chart’s README lists them. Alert on them with that in mind.
  • To halve the footprint, set replicaCount=1. A node that stops then stops all changes and status reports until Kubernetes starts the pod on another node.

Footprint

Each koperator replica requests 100m CPU and 256 Mi memory, with a 256 Mi memory limit and no CPU limit, so the default two replicas request 200m CPU and 512 Mi memory. Each pod runs as a non-root user, with a read-only root filesystem, no privilege escalation and no Linux capabilities. The install and uninstall hooks run short Jobs that request 10m CPU and up to 64 Mi memory. Metrics are on port 8080 (Service <release>-metrics), and the health probes are /healthz and /readyz on port 8081. Set telemetry.otlpEndpoint to also send koperator’s metrics and traces to your OTLP/HTTP collector.

Next steps

Scale agents to zero

Run no replica while an agent is idle.

Network & egress control

What agent traffic may reach, and how to scope it.