> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komodor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure koperator

> Choose the namespaces koperator manages, set its guardrails, share Secrets with agents, and set up its network, proxy and KEDA.

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

| Mode | `namespaces` | Koperator manages | Permissions it gets |
| - | - | - | - |
| A list (default) | `["team-a","team-b"]` | The listed namespaces only. To add one, run `helm upgrade` with the new list. **Change the namespaces** on the deploy target page writes that command for you. | A `Role` in each listed namespace. |
| Cluster-wide | `["*"]` | Every namespace that is not denied, including namespaces created later. | One `ClusterRole` for the whole cluster. |

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.

> [!WARNING]
>
> 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.

| Value | What koperator refuses |
| - | - |
| `guardrails.maxCpu`, `guardrails.maxMemory` | A pod whose containers together request, or are limited to, more CPU or memory than the ceiling. An init container counts alone. With a ceiling set, a container without a request or a limit is refused too. |
| `guardrails.maxReplicas` | A replica count, or a KEDA minimum or maximum, above the ceiling. |
| `guardrails.runBehaviours` | A run behaviour that is not in the list: `always_on`, `scale_to_zero` or `pod_per_run`. Empty allows all. |
| `guardrails.registries` | An image whose registry and path do not start with an entry, for example `ghcr.io/acme`. An image name without a registry counts as `docker.io`. Empty allows all. |
| `guardrails.allowedFields` | A spec field that is not in the list. Empty allows every field koperator supports. The list can only make that set smaller. |

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.

```sh theme={null}
kubectl -n team-a label secret shared-llm-key agentops.komodor.io/agent-usable=true
kubectl -n team-a label serviceaccount agents-s3-reader agentops.komodor.io/agent-usable=true
```

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.

| From | To | For |
| - | - | - |
| The koperator pod | Your KAOP host, `agentops.komodor.com` (the `controlPlane.url` value) | Registration, the heartbeat, the long-poll for changes, status reports and worker tokens. |
| The koperator pod | Each registry your agent images come from | A manifest `HEAD` to pin each image to its digest. |
| KEDA | Your KAOP host | The queue depth of each agent that scales to zero. |
| Your nodes | `ghcr.io` | The koperator image `ghcr.io/komodorio/agentops-koperator`, the agent base image `ghcr.io/komodorio/agentops-agent-base`, and the KEDA images when the chart installs KEDA. |
| Your Helm client or GitOps tool | `ghcr.io` | The chart, `oci://ghcr.io/komodorio/charts/koperator`. |
| The koperator pod (optional) | Your OTLP collector | Only when you set `telemetry.otlpEndpoint`. |

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:

```sh theme={null}
kubectl -n agentops create configmap internal-ca --from-file=ca.crt=/path/to/ca.crt
```

Then add these flags to the `helm upgrade --install` command:

```sh theme={null}
--set proxy=http://proxy.example.com:3128 \
--set proxyEnv.httpsProxy=http://proxy.example.com:3128 \
--set 'proxyEnv.noProxy={.corp.example.com}' \
--set caBundle.existingConfigMap=internal-ca
```

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](https://docs.komodor.com/manage-your-agents/build/scale-to-zero.md) 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

> [card] [Scale agents to zero](https://docs.komodor.com/manage-your-agents/build/scale-to-zero.md)
>
> Run no replica while an agent is idle.

> [card] [Network & egress control](https://docs.komodor.com/security-and-governance/architecture-considerations/network-egress-control.md)
>
> What agent traffic may reach, and how to scope it.


## Related topics

- [Koperator](https://docs.komodor.com/manage-your-agents/build/koperator/overview.md)
- [Upgrade koperator](https://docs.komodor.com/manage-your-agents/build/koperator/upgrade.md)
- [Install koperator on a deploy target](https://docs.komodor.com/manage-your-agents/build/koperator/install.md)
- [Scale agents to zero](https://docs.komodor.com/manage-your-agents/build/scale-to-zero.md)
- [Uninstall koperator](https://docs.komodor.com/manage-your-agents/build/koperator/uninstall.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.