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.
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 withguardrail_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.- 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:proxyis used for koperator’s calls to KAOP only.proxyEnv.httpsProxy,proxyEnv.httpProxyandproxyEnv.noProxysetHTTPS_PROXY,HTTP_PROXYandNO_PROXYin the koperator container. When you set them, the chart always adds the Kubernetes API (kubernetes.default.svc,.svc,.cluster.localand the service host) toNO_PROXY.
helm upgrade --install command:
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 setskeda.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.shexists and this release did not install it, the install fails. - Keep
keda.enabled=truein every later upgrade. An upgrade without it removes KEDA. helm uninstallkeeps the KEDA CRDs. Deleting them would delete every ScaledObject in the cluster, including those of other teams. To remove KEDA completely, delete the*.keda.shCRDs 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 afterleaderElection.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. SettopologySpreadConstraintsto 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 port8080 (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.