Troubleshoot Azure Authentication for Cluster Shield

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

• Azure Workload Identity Federation for AKS
• Azure Managed Identity
• Azure Instance Metadata Service
• Kubernetes Private Registry Secrets
• Azure Container Registry Roles