Azure Container Registry
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.
| Method | Identity the Registry Scanner uses | Use when |
|---|---|---|
| Managed identity | The kubelet identity of the AKS cluster, or another user-assigned identity on the cluster nodes | The Registry Scanner runs on AKS and you want the simplest setup without stored credentials |
| Workload identity | A user-assigned identity federated to the Registry Scanner service account | The Registry Scanner runs on AKS and you want an identity that only the Registry Scanner holds |
| Registry token | An ACR token with the _repositories_admin scope map | The Registry Scanner runs outside AKS, or you prefer to use stored credentials |
| Service Principal | A Service Principal ID and password | The 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.0or later. - Registry Scanner
v0.14.0or later. - The
az,kubectl, andhelmcommand-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 mode | Value | Required roles |
|---|---|---|
| RBAC Registry Permissions | LegacyRegistryPermissions | AcrPull |
| RBAC Registry + ABAC Repository Permissions | AbacRepositoryPermissions | Container 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.
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)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" doneInstall 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.ioconfig.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 toconfig.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.
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-identityCreate 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)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://AzureADTokenExchangeThe subject must match the namespace and the service account name exactly. When the Helm release is named
registry-scanner, the chart names the service accountregistry-scanner. To use a different name, setserviceAccount.name.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" doneInstall 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_IDThe 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 message | Cause | Resolution |
|---|---|---|
requires the environment injected by the Azure Workload Identity webhook, missing: AZURE_CLIENT_ID | The service account has no azure.workload.identity/client-id annotation, or the annotation is empty | Set the annotation to the identity client ID, then delete the Registry Scanner pod so that a new pod picks it up |
ACR identity failure | The identity is unable to get a Microsoft Entra token | For 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 identity | ACR returned 401: the identity has no usable role on the registry | Assign the roles for the registry permission mode. After a role change, the next scan uses a new token |
ACR network rules blocked the request | ACR returned 403: the registry network rules block the Registry Scanner | Verify 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.