Configure registry endpoints (preview)

2025-10-01

Important

This page includes instructions for managing Azure IoT Operations components using Kubernetes deployment manifests, which is in preview. This feature is provided with several limitations, and shouldn't be used for production workloads.

See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

Data flow graphs use registry endpoints to pull WebAssembly (WASM) modules and graph definitions from container registries. You can configure the endpoint settings, authentication, and other settings to connect to Azure Container Registry (ACR) or other OCI-compatible registries.

Prerequisites

An instance of Azure IoT Operations, version 1.2 preview or later
Access to a container registry, such as Azure Container Registry

Registry endpoint overview

A registry endpoint defines the connection details and authentication method for accessing a container registry. Registry endpoints are used by:

Data flow graphs: To pull WASM modules and graph definitions
Akri connectors: To pull custom connector templates

Registry endpoints support authentication through:

System-assigned managed identity
User-assigned managed identity
Artifact pull secrets (username and password)
Anonymous access (for public registries)

Create a registry endpoint

You can create a registry endpoint using Bicep or Kubernetes.

Bicep
Kubernetes

Create a Bicep .bicep file with the following content:

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param registryEndpointName string = '<REGISTRY_ENDPOINT_NAME>'
param registryHost string = '<REGISTRY_HOST>' // For example, myregistry.azurecr.io

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource registryEndpoint 'Microsoft.IoTOperations/instances/registryEndpoints@2025-07-01-preview' = {
  parent: aioInstance
  name: registryEndpointName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    host: registryHost
    authentication: {
      method: 'SystemAssignedManagedIdentity'
      systemAssignedManagedIdentitySettings: {
        audience: 'https://management.azure.com/'
      }
    }
  }
}

Deploy the Bicep file using Azure CLI:

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

Create a Kubernetes manifest .yaml file with the following content:

apiVersion: connectivity.iotoperations.azure.com/v1beta1
kind: RegistryEndpoint
metadata:
  name: <REGISTRY_ENDPOINT_NAME>
  namespace: azure-iot-operations
spec:
  host: <REGISTRY_HOST>
  authentication:
    method: SystemAssignedManagedIdentity
    systemAssignedManagedIdentitySettings:
      audience: https://management.azure.com/

Apply the manifest file to the Kubernetes cluster:

kubectl apply -f <FILE>.yaml

Configuration options

This section describes the configuration options available for registry endpoints.

Host

The host property specifies the container registry hostname. For Azure Container Registry, use the format <registry-name>.azurecr.io. The host property supports HTTPS URLs or just the hostname.

Examples:

myregistry.azurecr.io
https://myregistry.azurecr.io

Pattern: Must match the pattern ^(https:\/\/)?[a-zA-Z0-9\-]+\.azurecr\.io$ for Azure Container Registry.

Authentication methods

Registry endpoints support several authentication methods to securely access container registries.

System-assigned managed identity

System-assigned managed identity uses the Azure IoT Operations instance's built-in identity to authenticate with the registry. This is the recommended approach for Azure Container Registry as it eliminates the need for managing credentials.

Before configuring the registry endpoint, ensure the Azure IoT Operations system-assigned managed identity has the necessary permissions:

In Azure portal, go to your Azure IoT Operations instance and select Overview.
Copy the name of the extension listed after Azure IoT Operations Arc extension. For example, azure-iot-operations-xxxx7.
Go to your container registry > Access control (IAM) > Add role assignment.
On the Role tab, select AcrPull role.
On the Members tab, for Assign access to, select User, group, or service principal, then select + Select members and search for the Azure IoT Operations Arc extension name. Choose the extension and select Select.
Select Review + assign to complete the role assignment.

Bicep
Kubernetes

authentication: {
  method: 'SystemAssignedManagedIdentity'
  systemAssignedManagedIdentitySettings: {
    audience: 'https://management.azure.com/'
    extensionName: null  // Optional: specific extension name
    tenantId: null       // Optional: specific tenant ID
  }
}

authentication:
  method: SystemAssignedManagedIdentity
  systemAssignedManagedIdentitySettings:
    audience: https://management.azure.com/
    extensionName:  # Optional: specific extension name
    tenantId:       # Optional: specific tenant ID

System-assigned managed identity settings:

Property	Description	Required	Type
`audience`	Audience of the service to authenticate against.	No	String
`extensionName`	Specific extension name to use.	No	String
`tenantId`	Tenant ID for authentication.	No	String

The operator attempts to infer the audience from the endpoint if not provided. For Azure Container Registry, the audience is typically https://management.azure.com/.

User-assigned managed identity

User-assigned managed identity allows you to use a specific managed identity that you've created and configured with the necessary permissions.

Before configuring the registry endpoint, ensure the user-assigned managed identity has the AcrPull role on your container registry.

Bicep
Kubernetes

authentication: {
  method: 'UserAssignedManagedIdentity'
  userAssignedManagedIdentitySettings: {
    clientId: '<CLIENT_ID>'
    tenantId: '<TENANT_ID>'
    scope: null  // Optional: specific scope
  }
}

authentication:
  method: UserAssignedManagedIdentity
  userAssignedManagedIdentitySettings:
    clientId: <CLIENT_ID>
    tenantId: <TENANT_ID>
    scope:  # Optional: specific scope

User-assigned managed identity settings:

Property	Description	Required	Type
`clientId`	Client ID for the user-assigned managed identity.	Yes	String
`tenantId`	Tenant ID where the managed identity is located.	Yes	String
`scope`	Scope of the resource with `.default` suffix.	No	String

The operator attempts to infer the scope from the endpoint if not provided.

Artifact pull secret

Artifact pull secrets lets you use username and password authentication for registries that don't support managed identity authentication.

First, create a Kubernetes secret containing the registry credentials:

kubectl create secret docker-registry my-registry-secret \
  --docker-server=myregistry.azurecr.io \
  --docker-username=<USERNAME> \
  --docker-password=<PASSWORD> \
  -n azure-iot-operations

Bicep
Kubernetes

authentication: {
  method: 'ArtifactPullSecret'
  artifactPullSecretSettings: {
    secretRef: 'my-registry-secret'
  }
}

authentication:
  method: ArtifactPullSecret
  artifactPullSecretSettings:
    secretRef: my-registry-secret

Anonymous authentication

Anonymous authentication is used for public registries that don't require authentication.

Bicep
Kubernetes

authentication: {
  method: 'Anonymous'
  anonymousSettings: {}
}

authentication:
  method: Anonymous
  anonymousSettings: {}

Azure Container Registry integration

Azure Container Registry (ACR) is the recommended container registry for Azure IoT Operations. ACR provides secure, private Docker container registries with integrated authentication through Microsoft Entra ID.

Prerequisites for ACR

Create an ACR instance: If you don't have one, create an Azure Container Registry instance in your subscription.
Configure permissions: Ensure the Azure IoT Operations managed identity has AcrPull permissions on the registry.
Push artifacts: Upload your WASM modules and graph definitions to the registry using tools like ORAS CLI.

ACR configuration example

Here's a complete example for configuring an ACR registry endpoint:

Bicep
Kubernetes

param aioInstanceName string = 'my-aio-instance'
param customLocationName string = 'my-custom-location'
param acrName string = 'myregistry'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource acrRegistryEndpoint 'Microsoft.IoTOperations/instances/registryEndpoints@2025-07-01-preview' = {
  parent: aioInstance
  name: 'acr-endpoint'
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    host: '${acrName}.azurecr.io'
    authentication: {
      method: 'SystemAssignedManagedIdentity'
      systemAssignedManagedIdentitySettings: {
        audience: 'https://management.azure.com/'
      }
    }
  }
}

apiVersion: connectivity.iotoperations.azure.com/v1beta1
kind: RegistryEndpoint
metadata:
  name: acr-endpoint
  namespace: azure-iot-operations
spec:
  host: myregistry.azurecr.io
  authentication:
    method: SystemAssignedManagedIdentity
    systemAssignedManagedIdentitySettings:
      audience: https://management.azure.com/

Other container registries

Registry endpoints also support other OCI-compatible container registries such as:

Docker Hub
Harbor
AWS Elastic Container Registry (ECR)
Google Container Registry (GCR)

For these registries, you typically use artifact pull secrets for authentication, unless they support Azure managed identity.

Next steps

Feedback

Was this page helpful?