Kubernetes agent

This guide shows how to register a Kubernetes cluster by deploying the Kubernetes Service (chart airlock-kube-agent) on the cluster to be protected.

The Kubernetes Service pod detects that it is running inside Kubernetes and automatically registers the cluster in Airlock.

Prerequisites

• A running Airlock cluster, airctl and airsh at a version compatible with the server:

airctl version
airsh version

• Kubernetes >= 1.28, Helm >= 3.14, kubectl with access to the target cluster:

helm version
kubectl version

• Administrator access to the Airlock web interface (for the enrollment wizard) or the ability to perform the steps manually below.

Step 1 of 3. RBAC in Airlock and Kubernetes

Airlock role

Create kube-access.yaml:

kind: role
metadata:
  name: kube-access
version: v6
spec:
  allow:
    kubernetes_labels:
      '*': '*'
    kubernetes_resources:
      - kind: 'pod'
        namespace: '*'
        name: '*'
    kubernetes_groups:
    - viewers
  deny: {}

airctl create -f kube-access.yaml

Assign the role to the user via airctl users update.

ClusterRoleBinding in Kubernetes

The viewers group must have permissions in the cluster. Create viewers-bind.yaml:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: viewers-crb
subjects:
- kind: Group
  name: viewers
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: view
  apiGroup: rbac.authorization.k8s.io

kubectl apply -f viewers-bind.yaml

Step 2 of 3. Deploy the Kubernetes Service

Helm repository

helm repo add airlock https://charts.airlock.deckhouse.ru
helm repo update

Manual installation

Generate a join token:

airctl tokens add --type=kube --ttl=1h

Create a values file airlock-kube-agent-values.yaml (substitute the token and proxy address):

roles: kube
proxyAddr: airlock.example.com:443
authToken: "YOUR_KUBE_JOIN_TOKEN"
kubeClusterName: my-k8s-cluster

Install the chart into the airlock-agent namespace:

kubectl create namespace airlock-agent
helm install airlock-agent airlock/airlock-kube-agent \
  --namespace airlock-agent \
  --values airlock-kube-agent-values.yaml

Verify the pod:

kubectl get pods -n airlock-agent

Via the web interface: Enroll New Resource → Kubernetes — copy the generated command and run it on your workstation.

Step 3 of 3. Verify access

Log in to Airlock:

airsh login --proxy=airlock.example.com:443 --user=myuser

List clusters:

airsh kube ls

Obtain credentials for kubectl:

airsh kube login my-k8s-cluster
kubectl get pods -n airlock-agent

Expected output:

NAME               READY   STATUS    RESTARTS   AGE
airlock-agent-0   1/1     Running   0          8m

Next steps

• Restrict access using Kubernetes labels and Airlock roles instead of broad view rights across all namespaces.
• If Auth Service and Proxy Service are already deployed separately, an agent without the airlock-cluster chart is sufficient.