Authenticate Azure for Cluster Shield

This topic provides detailed instructions to configure Cluster Shield to authenticate and pull container images from Azure Container Registry (ACR) using supported authentication methods. It also includes detailed instructions to troubleshoot authentication issues and configure Cluster Shield with ACR using Workload Identity Federation and Managed Identities.

Cluster Shield must authenticate with Azure Container Registry (ACR) for vulnerability management in Kubernetes workloads. Supported methods include:

  • Workload Identity Federation (WIF)

    WIF is recommended for security and minimal credential management.

  • Managed Identity attached to AKS node pools (VMSS)

  • Kubernetes Secrets (dockerconfigjson)

Workload Identity Federation

Prerequisites

Ensure that your AKS cluster has Workload Identity Federation and OpenID Connect issuer enabled. For more information, see Enable Workload Identity.

Configure WIF

  1. Create Managed Identity:

    az identity create --resource-group ${RESOURCE_GROUP} --name ${IDENTITY_NAME}

  2. Create Federated Identity Credential:

    az identity federated-credential create \
  --name ${FEDERATED_CREDENTIAL_NAME} \
  --identity-name ${IDENTITY_NAME} \
  --resource-group ${RESOURCE_GROUP} \
  --issuer ${OIDC_ISSUER_URL} \
  --subject system:serviceaccount:${NAMESPACE}:${SERVICE_ACCOUNT}

  3. Assign AcrPull Role to the Managed Identity:

    az role assignment create \
  --assignee $(az identity show --resource-group ${RESOURCE_GROUP} --name ${IDENTITY_NAME} --query 'clientId' --output tsv) \
  --role AcrPull \
  --scope /subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${ACR_RESOURCE_GROUP}/providers/Microsoft.ContainerRegistry/registries/${ACR_NAME}

  4. Annotate Kubernetes Service Account:

    kubectl annotate serviceaccount ${SERVICE_ACCOUNT} -n ${NAMESPACE} \
azure.workload.identity/client-id=$(az identity show --resource-group ${RESOURCE_GROUP} --name ${IDENTITY_NAME} --query 'clientId' -o tsv)

  5. Label the Cluster Shield Pod:

    metadata:
  labels:
    azure.workload.identity/use: "true"

​ Cluster Shield automatically uses this configuration.

Managed Identity Configuration

Prerequisites

  • AKS cluster node pools must have the Managed Identity attached. See Azure documentation for more information.
  • No extra Cluster Shield-specific configuration is necessary. Ensure Cluster Shield Pods have unrestricted access to Azure Instance Metadata Service (IMDS).

Kubernetes Secrets

Configure Kubernetes Secrets (dockerconfigjson) as given in the Kubernetes documentation.

Cluster Shield automatically uses these secrets if available.

Advanced Troubleshooting

Verify Managed Identity

  • Launch debug pod:

    kubectl run krane-utils --image=gcr.io/go-containerregistry/krane:debug -n ${NAMESPACE} --stdin --tty -- /busybox/sh

  • Retrieve Azure IMDS token:

    wget -Y off --header "Metadata: true" -q -O - "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://management.azure.com/"

Verify Workload Identity Federation

  • Check Kubernetes annotations and labels:

    kubectl get serviceaccount ${SERVICE_ACCOUNT} -n ${NAMESPACE} -o yaml
kubectl get pods -n ${NAMESPACE} --show-labels

  • Validate Environment Variables:

    env | grep AZURE

​ Expected variables:

- `AZURE_CLIENT_ID`
- `AZURE_FEDERATED_TOKEN_FILE`
- `AZURE_TENANT_ID`
- `AZURE_AUTHORITY_HOST`

  • Verify token retrieval with krane:

    krane auth token -v ${ACR_NAME}

Verify Role Assignments

Ensure the Managed Identity has the AcrPull role:

az role assignment list --assignee $(az identity show --resource-group ${RESOURCE_GROUP} --name ${IDENTITY_NAME} --query 'clientId' --output tsv)

Troubleshoot Kubernetes Secrets

Set log level to DEBUG in Cluster Shield deployment and verify secrets retrieval in logs.

Learn More