Connect a cluster
EKS cluster
EKS clusters work out of the box. The agent automatically detects the AWS region from node labels and discovers IRSA bindings.
# Make sure kubectl points at your EKS cluster
kubectl config current-context
# Apply the manifest from the Integrations page
kubectl apply -f guardmap-agent.yaml
The IRSA graph (ServiceAccount → IAM Role → AWS Resource) only appears for pods with the eks.amazonaws.com/role-arn annotation on their ServiceAccount.
minikube
minikube is fully supported. IAM/IRSA nodes won't appear (no AWS), but all K8s security checks still run.
minikube start
kubectl apply -f guardmap-agent.yaml
Other clusters (GKE, AKS, on-prem)
Any CNCF-conformant Kubernetes cluster works. The agent uses standard K8s APIs only.
kubectl apply -f guardmap-agent.yaml
Region detection relies on the topology.kubernetes.io/region node label. On non-AWS clusters this will be empty — you can set the region manually when creating the cluster in the dashboard.
Verifying the agent
# Check the CronJob is running
kubectl get cronjob -n guardmap
# Trigger a manual scan
kubectl create job -n guardmap --from=cronjob/guardmap-scanner guardmap-manual
# Watch the logs
kubectl logs -n guardmap job/guardmap-manual -f
A successful scan looks like:
{"msg":"scan complete","nodes":173,"edges":68,"findings":71,"score":13,"k8s_version":"v1.34.0","node_count":1}
{"msg":"scan submitted","scan_id":"52134294-da94-4efa-9c34-520b3180bb72"}
Troubleshooting
Status stays Pending after applying the manifest
The agent hasn't submitted its first scan yet. Trigger one manually:
kubectl create job -n guardmap --from=cronjob/guardmap-scanner guardmap-manual
kubectl logs -n guardmap job/guardmap-manual
invalid_api_key error in logs
The API key in the Secret is wrong or has been revoked. Delete the old manifest, generate a new token in Integrations, and re-apply.
cluster_not_found error in logs
The CLUSTER_NAME env var in the Secret doesn't match the name you entered in the dashboard. Both must be identical.
rate_limit_exceeded error
More than 10 scans were submitted in the last hour for this cluster. Wait and try again.