Azure Container Registry

You can run Registry Scanner in an Azure Container Registry using a managed identity, a workload identity, a registry token, or a Service Principal.

Ensure you update the Sysdig Helm chart before installation. This lets you access the latest features and fixes.

Choose an Authentication Method

The Registry Scanner supports four ways to authenticate to Azure Container Registry (ACR). Managed identity and workload identity don’t need stored registry credentials.

MethodIdentity the Registry Scanner usesUse when
Managed identityThe kubelet identity of the AKS cluster, or another user-assigned identity on the cluster nodesThe Registry Scanner runs on AKS and you want the simplest setup without stored credentials
Workload identityA user-assigned identity federated to the Registry Scanner service accountThe Registry Scanner runs on AKS and you want an identity that only the Registry Scanner holds
Registry tokenAn ACR token with the _repositories_admin scope mapThe Registry Scanner runs outside AKS, or you prefer to use stored credentials
Service PrincipalA Service Principal ID and passwordThe Registry Scanner runs outside AKS, or you prefer to use stored credentials

Prerequisites for Managed Identity and Workload Identity

  • An AKS cluster to run the Registry Scanner.
  • An ACR registry in the same Microsoft Entra tenant as the identity.
  • The Registry Scanner Helm chart 1.12.0 or later.
  • Registry Scanner v0.14.0 or later.
  • The az, kubectl, and helm command-line tools, with permission to create role assignments on the registry.

Find the Registry Permission Mode

The registry permission mode decides which roles the identity needs. Run the following command:

az acr show --name <ACR_NAME> --query roleAssignmentMode --output tsv
Permission modeValueRequired roles
RBAC Registry PermissionsLegacyRegistryPermissionsAcrPull
RBAC Registry + ABAC Repository PermissionsAbacRepositoryPermissionsContainer Registry Repository Reader and Container Registry Repository Catalog Lister

In the RBAC Registry + ABAC Repository Permissions mode, ACR does not honor the AcrPull role. Without Container Registry Repository Catalog Lister, the Registry Scanner cannot list the registry repositories.

Scan Jobs

The Registry Scanner gets the ACR token and passes it to the scan jobs. Only the Registry Scanner pod uses the identity, so the scan job pods don’t need any identity configuration.

Authentication Using Managed Identity

With managed identity, the Registry Scanner uses the kubelet identity of the AKS cluster through the Azure Instance Metadata Service (IMDS).

Every pod on the cluster nodes can request tokens for the kubelet identity. To give registry access to the Registry Scanner only, use workload identity.

  1. Get the registry resource ID and the kubelet identity of the cluster:

    ACR_ID=$(az acr show --name <ACR_NAME> --query id --output tsv)
    KUBELET_OBJECT_ID=$(az aks show --name <AKS_CLUSTER> --resource-group <AKS_RESOURCE_GROUP> \
      --query identityProfile.kubeletidentity.objectId --output tsv)
    KUBELET_CLIENT_ID=$(az aks show --name <AKS_CLUSTER> --resource-group <AKS_RESOURCE_GROUP> \
      --query identityProfile.kubeletidentity.clientId --output tsv)
    
  2. Assign the required roles to the kubelet identity.

    For the RBAC Registry Permissions mode:

    az role assignment create --assignee-object-id "$KUBELET_OBJECT_ID" \
      --assignee-principal-type ServicePrincipal --role AcrPull --scope "$ACR_ID"
    

    For the RBAC Registry + ABAC Repository Permissions mode:

    for ROLE in "Container Registry Repository Reader" "Container Registry Repository Catalog Lister"; do
      az role assignment create --assignee-object-id "$KUBELET_OBJECT_ID" \
        --assignee-principal-type ServicePrincipal --role "$ROLE" --scope "$ACR_ID"
    done
    
  3. Install the Registry Scanner:

    helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
    --set config.secureBaseURL=<SYSDIG_SECURE_URL> \
    --set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
    --set config.registryType=acr \
    --set config.registryURL=<ACR_REGISTRY_URL> \
    --set config.azure.authMethod=managedIdentity \
    --set config.azure.clientId=$KUBELET_CLIENT_ID
    
  • <ACR_REGISTRY_URL>: The Azure registry URL.
    For example, testregistryscanner.azurecr.io
  • config.azure.clientId: The client ID of the identity to use. The previous command sets it to the kubelet identity. Set it when the cluster nodes have more than one user-assigned identity, which is common when AKS add-ons are enabled.
  • config.azure.resourceId: The resource ID of the identity to use, as an alternative to config.azure.clientId. You can’t set both.

Don’t set config.registryUser or config.registryPassword. The installation stops with an error if either one is set.

Authentication Using Workload Identity

With workload identity, the Registry Scanner uses a user-assigned identity that is federated to its Kubernetes service account. Only pods that run with that service account can use the identity.

  1. Verify that the cluster has the OIDC issuer and workload identity enabled:

    az aks show --name <AKS_CLUSTER> --resource-group <AKS_RESOURCE_GROUP> \
      --query "{oidcIssuer:oidcIssuerProfile.enabled, workloadIdentity:securityProfile.workloadIdentity.enabled}"
    

    If either value is false, enable both. You don’t need to recreate the cluster:

    az aks update --name <AKS_CLUSTER> --resource-group <AKS_RESOURCE_GROUP> \
      --enable-oidc-issuer --enable-workload-identity
    
  2. Create a user-assigned identity for the Registry Scanner:

    az identity create --name <IDENTITY_NAME> --resource-group <IDENTITY_RESOURCE_GROUP>
    IDENTITY_CLIENT_ID=$(az identity show --name <IDENTITY_NAME> --resource-group <IDENTITY_RESOURCE_GROUP> \
      --query clientId --output tsv)
    IDENTITY_PRINCIPAL_ID=$(az identity show --name <IDENTITY_NAME> --resource-group <IDENTITY_RESOURCE_GROUP> \
      --query principalId --output tsv)
    
  3. Federate the identity to the Registry Scanner service account:

    OIDC_ISSUER=$(az aks show --name <AKS_CLUSTER> --resource-group <AKS_RESOURCE_GROUP> \
      --query oidcIssuerProfile.issuerUrl --output tsv)
    
    az identity federated-credential create --name registry-scanner \
      --identity-name <IDENTITY_NAME> --resource-group <IDENTITY_RESOURCE_GROUP> \
      --issuer "$OIDC_ISSUER" \
      --subject system:serviceaccount:<NAMESPACE>:registry-scanner \
      --audiences api://AzureADTokenExchange
    

    The subject must match the namespace and the service account name exactly. When the Helm release is named registry-scanner, the chart names the service account registry-scanner. To use a different name, set serviceAccount.name.

  4. Assign the required roles to the identity:

    ACR_ID=$(az acr show --name <ACR_NAME> --query id --output tsv)
    

    For the RBAC Registry Permissions mode:

    az role assignment create --assignee-object-id "$IDENTITY_PRINCIPAL_ID" \
      --assignee-principal-type ServicePrincipal --role AcrPull --scope "$ACR_ID"
    

    For the RBAC Registry + ABAC Repository Permissions mode:

    for ROLE in "Container Registry Repository Reader" "Container Registry Repository Catalog Lister"; do
      az role assignment create --assignee-object-id "$IDENTITY_PRINCIPAL_ID" \
        --assignee-principal-type ServicePrincipal --role "$ROLE" --scope "$ACR_ID"
    done
    
  5. Install the Registry Scanner in the namespace that you used in the federated credential:

    helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
    --namespace <NAMESPACE> --create-namespace \
    --set config.secureBaseURL=<SYSDIG_SECURE_URL> \
    --set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
    --set config.registryType=acr \
    --set config.registryURL=<ACR_REGISTRY_URL> \
    --set config.azure.authMethod=workloadIdentity \
    --set serviceAccount.annotations."azure\.workload\.identity/client-id"=$IDENTITY_CLIENT_ID
    

    The chart adds the azure.workload.identity/use: "true" label to the Registry Scanner pod. The AKS workload identity webhook then injects the identity into the pod.

Pass the client ID as a key under serviceAccount.annotations, as shown. Setting serviceAccount.annotations to a string makes the installation stop with a YAML parse error. An empty client ID installs without an error, but the Registry Scanner does not start.

Don’t set config.registryUser or config.registryPassword. The installation stops with an error if either one is set.

Verify the Identity Authentication

After a scan starts, the Registry Scanner logs the authentication method and the identity it uses:

ACR auth OK: method=workloadIdentity, clientId=<CLIENT_ID>, token exp=<EXPIRATION_TIME>

If the log shows discovered total number of repositories: 0 for a registry that has repositories, verify the role assignments. Role assignments can take a few minutes to take effect.

Troubleshoot Identity Authentication

The Registry Scanner logs one of the following errors when identity authentication is unable to complete.

Log messageCauseResolution
requires the environment injected by the Azure Workload Identity webhook, missing: AZURE_CLIENT_IDThe service account has no azure.workload.identity/client-id annotation, or the annotation is emptySet the annotation to the identity client ID, then delete the Registry Scanner pod so that a new pod picks it up
ACR identity failureThe identity is unable to get a Microsoft Entra tokenFor managed identity, verify that the identity is assigned to the cluster nodes and that config.azure.clientId is correct. For workload identity, verify that the federated credential issuer and subject match the cluster and the service account
ACR rejected the identityACR returned 401: the identity has no usable role on the registryAssign the roles for the registry permission mode. After a role change, the next scan uses a new token
ACR network rules blocked the requestACR returned 403: the registry network rules block the Registry ScannerVerify the registry public network access, selected networks, and private endpoint settings. This is not a role assignment issue

Identity Authentication Limitations

  • Managed identity and workload identity support the Azure public cloud only.

Authentication Using Registry Token

To run the scanner in Azure Container Registry (ACR) using a registry token, you must have a token with _repositories_admin scope map to read the full registry.

$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=acr \
--set config.registryURL=<ACR_REGISTRY_URL> \
--set config.registryUser=<ACR_TOKEN_NAME> \
--set config.registryPassword=<ACR_TOKEN_PASSWORD>
  • <ACR_REGISTRY_URL>: The Azure registry URL
    For example, testregistryscanner.azurecr.io
  • <ACR_TOKEN_NAME>: The Azure registry token name
  • <ACR_TOKEN_PASSWORD>: The Azure registry token password

Limitations

The registry token must use the _repositories_admin scope map. For more information, see the Azure ACR documentation.

Authentication by Service Principal

To run the scanner in Azure Container Registry (ACR) using Service Principal, follow the Azure ACR instructions to create Service Principal with acrpull role and scoped to your registry.

$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=acr \
--set config.registryURL=<ACR_REGISTRY_URL> \
--set config.registryUser=<SP_ID> \
--set config.registryPassword=<SP_PASSWORD>
  • <ACR_REGISTRY_URL>: The Azure registry URL.
    For example, testregistryscanner.azurecr.io
  • <SP_ID>: The Azure Service Principal ID.
  • <SP_PASSWORD>: The Azure Service Principal password.