Scan External Kubernetes Clusters

The Mondoo Kubernetes Operator can scan remote Kubernetes clusters from a central installation. Instead of deploying the operator to every cluster, you install it once on a management cluster and configure it to reach out to your other clusters over the Kubernetes API.

This is useful when you:

• Cannot or do not want to install the operator on every cluster
• Want to centralize security scanning in a management or platform cluster
• Need to scan development or staging clusters from a single location

Prerequisites

• A running Mondoo Kubernetes Operator installation. See Scan Continuously for setup instructions.
• Network connectivity from the operator cluster to the API server of each target cluster.
• Read access to Kubernetes API resources on each target cluster.

Add external clusters to an integration

When creating or editing a Kubernetes integration in the Mondoo Console, expand the External clusters section and select Add external cluster.

For each external cluster, provide:

• Name: A unique identifier for this cluster (used in scan job names).
• Authentication method: How the operator authenticates to the remote cluster's API server. See Authentication methods below.
• Container image scanning (optional): Enable to also scan container images running on the remote cluster.
• Namespace filtering (optional): Restrict which namespaces are scanned on this cluster.

You can add multiple external clusters to the same integration. Each cluster gets its own scan CronJob.

If you only want to scan external clusters (not the cluster where the operator runs), disable the Scan local cluster toggle.

After creating the integration, the console walks you through the remaining setup steps, including any IAM bindings or target cluster RBAC commands specific to your chosen authentication method.

Authentication methods

The operator supports several authentication methods for reaching external clusters. Choose the one that fits your security requirements and infrastructure. The console wizard guides you through the required fields for each method.

Kubeconfig Secret

The most flexible option. Store a kubeconfig file in a Kubernetes Secret and reference it in the integration. This works with any cluster and any authentication mechanism that kubectl supports (client certificates, OIDC tokens, exec plugins, and others).

In the console, select Kubeconfig as the authentication method and enter the name of a Secret that contains the kubeconfig.

kubectl config view --minify --flatten --context=<remote-context> > remote-kubeconfig.yaml

kubectl create secret generic prod-kubeconfig \
  --namespace mondoo-operator \
  --from-file=kubeconfig=remote-kubeconfig.yaml

Service account token

Use a Kubernetes service account token with a CA certificate. This is simpler than a full kubeconfig when you need a static credential.

In the console, select Service Account Token and provide the target cluster's API server URL and the name of a Secret containing the token and CA certificate.

kubectl create serviceaccount mondoo-scanner -n kube-system
kubectl create clusterrolebinding mondoo-scanner \
  --clusterrole=view \
  --serviceaccount=kube-system:mondoo-scanner

kubectl create token mondoo-scanner -n kube-system --duration=8760h > token
kubectl config view --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > ca.crt

kubectl create secret generic prod-sa-credentials \
  --namespace mondoo-operator \
  --from-file=token=./token \
  --from-file=ca.crt=./ca.crt

GKE Workload Identity

Use Google Cloud Workload Identity to authenticate to a remote GKE cluster with no static credentials.

In the console, select GKE Workload Identity and provide:

• GCP Project ID
• Cluster name
• Cluster location (zone or region)
• Google service account email

After creating the integration, the console shows the IAM binding and target cluster RBAC commands you need to run.

gcloud iam service-accounts add-iam-policy-binding \
  scanner@my-gcp-project.iam.gserviceaccount.com \
  --project=my-gcp-project \
  --role="roles/iam.workloadIdentityUser" \
  --member="serviceAccount:my-gcp-project.svc.id.goog[mondoo-operator/<AUDIT_CONFIG_NAME>-wif-<CLUSTER_NAME>]"

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: mondoo-operator-k8s-resources-scanning
rules:
  - apiGroups: ['*']
    resources: ['*']
    verbs: [get, watch, list]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: mondoo-operator-k8s-resources-scanning
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: mondoo-operator-k8s-resources-scanning
subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: User
    name: scanner@my-gcp-project.iam.gserviceaccount.com

kubectl apply --context <target-cluster-context> -f target-rbac.yaml

EKS IAM Roles for Service Accounts (IRSA)

Use AWS IRSA to authenticate to a remote EKS cluster with no static credentials.

In the console, select EKS IRSA and provide:

• AWS Region
• Cluster name
• IAM Role ARN

After creating the integration, the console shows the IAM trust policy and target cluster access commands you need to run.

{
  "Effect": "Allow",
  "Principal": {
    "Federated": "arn:aws:iam::123456789012:oidc-provider/oidc.eks.us-west-2.amazonaws.com/id/OIDC_ID"
  },
  "Action": "sts:AssumeRoleWithWebIdentity",
  "Condition": {
    "StringEquals": {
      "oidc.eks.us-west-2.amazonaws.com/id/OIDC_ID:sub": "system:serviceaccount:mondoo-operator:<AUDIT_CONFIG_NAME>-wif-<CLUSTER_NAME>"
    }
  }
}

AKS Workload Identity

Use Azure Workload Identity to authenticate to a remote AKS cluster with no static credentials.

In the console, select AKS Workload Identity and provide:

• Subscription ID
• Resource group
• Cluster name
• Client ID (managed identity)
• Tenant ID

After creating the integration, the console shows the federated credential and target cluster access commands you need to run.

az identity federated-credential create \
  --name mondoo-scanner-<CLUSTER_NAME> \
  --identity-name my-managed-identity \
  --resource-group my-resource-group \
  --issuer "$(az aks show -g my-resource-group -n scanner-cluster --query oidcIssuerProfile.issuerUrl -o tsv)" \
  --subject "system:serviceaccount:mondoo-operator:<AUDIT_CONFIG_NAME>-wif-<CLUSTER_NAME>" \
  --audience api://AzureADTokenExchange

HashiCorp Vault

Use Vault's Kubernetes secrets engine to dynamically generate short-lived service account tokens for each scan. This avoids managing any static credentials for target clusters.

In the console, select Vault and provide:

Optional fields:

SPIFFE/SPIRE

Use SPIFFE/SPIRE for zero-trust authentication with auto-rotating X.509 certificates.

In the console, select SPIFFE and provide:

• Remote API server URL: The Kubernetes API server address of the target cluster.
• Trust bundle Secret name: A Secret in the operator namespace containing the SPIRE trust bundle (ca.crt key).
• Socket path (optional): Custom SPIRE agent socket path. Defaults to /run/spire/sockets/agent.sock.

Configure external clusters without the console

If you prefer to manage the MondooAuditConfig directly instead of using the console wizard, you can configure external clusters in YAML.

apiVersion: k8s.mondoo.com/v1alpha2
kind: MondooAuditConfig
metadata:
  name: mondoo-client
  namespace: mondoo-operator
spec:
  mondooCredsSecretRef:
    name: mondoo-client
  kubernetesResources:
    enable: true
    externalClusters:
      - name: production
        kubeconfigSecretRef:
          name: prod-kubeconfig
      - name: staging
        kubeconfigSecretRef:
          name: staging-kubeconfig

externalClusters:
  - name: production
    kubeconfigSecretRef:
      name: prod-kubeconfig
    schedule: '0 */2 * * *'
    filtering:
      namespaces:
        exclude:
          - kube-system
          - monitoring
    containerImageScanning: true
    privateRegistriesPullSecretRef:
      name: prod-registry-creds

Private container image scanning with Workload Identity

When scanning container images on external clusters (or the local cluster), you can use Workload Identity Federation to authenticate to cloud container registries instead of managing static pull secrets. The operator creates a dedicated Kubernetes ServiceAccount with the appropriate cloud annotations and uses short-lived registry credentials at runtime.

This supports GCR/Artifact Registry (GKE), ECR (EKS), and ACR (AKS).

Enable container image scanning in the integration, then expand Container registry workload identity and select your cloud provider. The console prompts for provider-specific fields and generates the IAM binding commands after creation.

Next steps

• Scan Continuously to learn about operator installation, integration setup, and multi-integration support.
• Run ad hoc Kubernetes security scans from your workstation for one-time scans without the operator.