Connect your cluster to Aikido

Aikido can scan your Kubernetes cluster for misconfigurations and, optionally, the container images it runs for vulnerabilities. To do that, the Aikido Kubernetes agent runs in your cluster and reports to your Aikido workspace. We install, configure and upgrade the agent for you. You only create the Aikido token, because it belongs to your Aikido workspace, where we don’t have admin access.

The agent is off by default. This page explains what it sends to Aikido and how to set it up.

What leaves your cluster

The agent reads your cluster’s objects and sends them to your Aikido workspace: pods and workload definitions (including environment variables written directly in them), ConfigMaps, RBAC rules, Services, Ingresses and IngressRoutes, among others. It cannot read Kubernetes Secrets, except for the one holding its own token.

A few things we set differently from Aikido’s defaults, so your cluster stays under control:

• No automatic agent updates. By default, Aikido can change which agent version runs in your cluster. We turn that off and upgrade the agent ourselves, like every other component of your platform.
• No access to your nodes. The agent and the optional image scanner run as regular, unprivileged pods.

Set it up

1. Create the token in Aikido

In your Aikido workspace, add a Kubernetes cluster integration, one per cluster. Aikido then gives you an API token for that cluster. Keep it at hand for the next step. You don’t need to run the installation command Aikido shows; we install the agent for you.

2. Store the token in your cluster

Create the aikido-agent-config Secret in the aikido namespace. Make sure your kubectl context points at the right cluster, then run:

# Create the namespace, unless it already exists
kubectl get namespace aikido >/dev/null 2>&1 || kubectl create namespace aikido

# Paste the token when asked (it isn't shown, and it doesn't end up in your shell history)
printf 'Aikido token: '; read -rs AIKIDO_TOKEN; echo

printf 'apiEndpoint: https://k8s.aikido-security.com\napiToken: %s\n' "$AIKIDO_TOKEN" \
  | kubectl create secret generic aikido-agent-config --namespace aikido \
      --from-file=config.yaml=/dev/stdin --dry-run=client -o yaml \
  | kubectl annotate --local -f - helm.sh/resource-policy=keep -o yaml \
  | kubectl create -f -

unset AIKIDO_TOKEN

Keep the annotation: the agent needs it to save a new token when Aikido rotates it.

3. Turn on the agent

Ask us to enable it, or enable it yourself in your cluster definition:

spec:
  aikido:
    enabled: true

Once the change has rolled out, your cluster shows up as connected in Aikido. If you enable the agent before you create the Secret, it waits until the Secret exists, then connects.

Optional: scan your container images

Aikido can also check the images running in your cluster for known vulnerabilities. Turn it on with:

spec:
  aikido:
    enabled: true
    sbomCollector:
      enabled: true

The image scanner pulls each running image from its registry, lists the packages inside it (a software bill of materials, or SBOM), and sends that list to Aikido. Your images themselves don’t leave your cluster.

What it can scan:

• Images in Amazon ECR, including our ECR pull-through cache. The scanner gets read-only access to ECR in your cluster’s AWS account. For an image in another account’s ECR, that repository’s policy has to allow it too. Ask us if you need that.
• Public images, from any registry.

What it can’t scan: images from other private registries, such as a private GitHub Container Registry or Docker Hub repository. Scanning those would mean giving the scanner access to your registry passwords, so we leave it off.

If your images already go through Aikido from your container registry or CI, you might not need this at all.

Replace the token

The agent keeps its token up to date by itself when Aikido rotates it. To swap in a new token yourself, for example after removing and re-adding the cluster in Aikido, delete the Secret, create it again as in step 2, and restart the agent:

kubectl delete secret aikido-agent-config --namespace aikido
# ... step 2 ...
kubectl rollout restart deployment aikido-kubernetes-agent --namespace aikido

Turn it off

Set spec.aikido.enabled to false, or ask us to. This removes the aikido namespace, including the Secret. Then remove the cluster integration in your Aikido workspace.