Before you start
- A Kubernetes cluster, and Helm 3 or later on the machine you install from.
- The namespaces that koperator will manage. Koperator never creates a namespace.
- For agents that scale to zero, KEDA 2.10 or later. If the cluster has no KEDA, koperator can install it (see KEDA).
- Outbound access to the hosts in Network requirements.
Install
1
Create the deploy target in KAOP
In Settings → Deploy targets, choose Create deploy target. Give it a name and a
description, the namespaces it manages (Specific namespaces or All namespaces), the
namespaces it never manages, labels such as
env and team for label-scoped grants, whether to
Install KEDA with koperator, and its guardrails. KAOP then opens the deploy target page with
the install command, which holds the install key.The key is shown once. Copy the whole command before you choose Hide the key or leave
the page. After that, the page shows the command with a placeholder where the key goes.2
Run the install command
Run the command on the cluster. It has three steps:
<name> is the deploy target’s name in lower case, with each run of other characters than
letters and digits changed to -. The deploy target page shows the exact release name. KAOP adds deniedNamespaces, guardrails
and keda.enabled to the command when they apply, and --version when your KAOP control plane
names a chart version. The first line fails when the agentops
namespace already exists, for example when a second koperator runs on the cluster. That is
expected: run the next two lines.The chart never takes the install key as a value, because a value goes into your shell history,
your CI logs and the stored Helm release. It reads the key from the Secret.3
Check the connection
The deploy target shows Connected and the koperator version after the first heartbeat,
within about 30 seconds. If it does not, see Troubleshooting.
Rotate the install key
On the deploy target page, Rotate key returns the new key and a command that replaces it in the cluster’s Secret. Koperator reads the mounted key again before each call, so it needs no restart. The old key keeps working until koperator first uses the new one, or for 24 hours. Revoke now stops every key at once, and koperator stays disconnected until you install a new key: after a revoke, Issue a new key gives one, with its command. Running agents keep serving while koperator is disconnected.Troubleshooting
Koperator runs two replicas, and only the leader calls KAOP and changes agents. To read the right
log, find the leader first. The lease holder starts with the leader’s pod name, before the
_:
Next steps
Configure koperator
Namespaces, guardrails, Secrets, network, proxy and KEDA.
Adopt agents installed with Helm
Let KAOP manage agents you already run from a Helm release.