Configurare gli endpoint del Registro di sistema

I grafici del flusso di dati e il connettore HTTP/REST utilizzano endpoint del registro per eseguire il pull di moduli WebAssembly (WASM) e delle definizioni di grafo dai registri contenitori. Le operazioni IoT di Azure estraggono tutti i modelli di connettore personalizzati sviluppati dai registri contenitori. È possibile configurare le impostazioni dell'endpoint, l'autenticazione e altre impostazioni per connettersi a Registro Azure Container (ACR), Microsoft Container Registry (MCR) o GitHub Container Registry (ghcr.io).

Prerequisiti

• Istanza di Operazioni di Azure IoT distribuita in un cluster Kubernetes. Per altre informazioni, vedere Deploy Operazioni di Azure IoT.

• Operazioni di Azure IoT versione 1.2 o successiva.
• Accesso a un registro di container, come Azure Container Registry (ACR).

Gli esempi interfaccia della riga di comando di Azure in questo articolo usano variabili di ambiente così puoi impostare ogni valore una volta e poi copiare e incollare i comandi as-is. Se stai usando l'ambiente Operazioni di Azure IoT Codespaces dal quickstart, queste variabili sono già impostate per te e puoi saltare questo passaggio. Altrimenti, imposta le seguenti variabili di ambiente nella tua shell prima di eseguire i comandi.

I seguenti script impostano le variabili di ambiente più comunemente utilizzate:

SUBSCRIPTION_ID=<subscription-id>
RESOURCE_GROUP=<resource-group-name>
AIO_INSTANCE_NAME=<instance-name>
CLUSTER_NAME=<cluster-name>
LOCATION=<region>

$SUBSCRIPTION_ID = "<subscription-id>"
$RESOURCE_GROUP = "<resource-group-name>"
$AIO_INSTANCE_NAME = "<instance-name>"
$CLUSTER_NAME = "<cluster-name>"
$LOCATION = "<region>"

Devi solo impostare le variabili utilizzate in questo articolo. Questo articolo potrebbe utilizzare variabili ambientali aggiuntive per i nomi delle risorse che scegli. L'articolo spiega come posizionarli dove vengono introdotti.

Questo articolo utilizza anche le seguenti variabili di ambiente per i valori che scegli: REGISTRY_ENDPOINT (il nome dell'endpoint del registro), ACR_NAME (il nome Registro Azure Container), REGISTRY_HOST (il nome host del registro), CLIENT_ID (TENANT_IDgli identificatori di identità gestite assegnati dall'utente), REGISTRY_USERNAME e REGISTRY_PASSWORD (credenziali del registro), e GITHUB_USERNAMEGITHUB_PAT (GitHub credenziali del Registro Container). Imposta ognuno prima di eseguire i comandi correlati.

Creare un endpoint del registro

Un endpoint del registro definisce la connessione al registro contenitori. I grafici di flusso di dati usano gli endpoint dei registri per recuperare moduli WASM e definizioni di grafo. Le operazioni IoT di Azure usano gli endpoint del Registro di sistema per eseguire il pull dei modelli di connettore personalizzati. Dopo aver creato un endpoint del Registro di sistema:

• È possibile utilizzare qualsiasi grafico di cui è stato eseguito il push nel registro contenitori nella gestione operativa dei grafici del flusso di dati.
• È possibile usare tutti i connettori personalizzati di cui è stato eseguito il push nel registro contenitori nell'esperienza operativa per creare endpoint in ingresso del dispositivo.

az iot ops registry create \
  --name $REGISTRY_ENDPOINT \
  --instance $AIO_INSTANCE_NAME \
  --resource-group $RESOURCE_GROUP \
  --host $ACR_NAME.azurecr.io \
  --auth-type SystemAssignedManagedIdentity \
  --audience https://management.azure.com/

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param registryEndpointName string = '<REGISTRY_ENDPOINT_NAME>'
param acrName string = '<YOUR_ACR_NAME>'

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

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

resource registryEndpoint 'Microsoft.IoTOperations/instances/registryEndpoints@2026-03-01' = {
  parent: aioInstance
  name: registryEndpointName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    host: '${acrName}.azurecr.io'
    authentication: {
      method: 'SystemAssignedManagedIdentity'
      systemAssignedManagedIdentitySettings: {
        audience: 'https://management.azure.com/'
      }
    }
  }
}

az deployment group create --resource-group $RESOURCE_GROUP --template-file main.bicep

Opzioni di configurazione

Host

La host proprietà specifica solo il nome host del registro contenitori. Non includere il percorso del repository in cui sono archiviati gli artefatti. Per ACR, usare il formato <registry-name>.azurecr.io.

Esempi:

• myregistry.azurecr.io (Registro Azure Container)
• mcr.microsoft.com (Registro Contenitori Microsoft)
• ghcr.io (Container Registry di GitHub)
• docker.io (Hub Docker)

Percorsi degli artefatti e riferimenti ai moduli del grafo

L'host dell'endpoint del registro identifica il registro. I percorsi degli artefatti identificano il repository e il tag all'interno di tale registry. Quando una definizione del grafo fa riferimento a un modulo WASM, il riferimento al modulo deve corrispondere alla posizione in cui è archiviato l'artefatto del modulo nel Registro di sistema.

Se si inviano artefatti graph e module nella radice del registro, utilizzare nomi di artefatto brevi come graph-simple:1.0.0 e temperature:1.0.0. Se si caricano artefatti in un percorso del repository, includere tale percorso sia nel riferimento all'artefatto del grafo del flusso di dati sia nei riferimenti ai moduli all'interno della definizione del grafo.

Metodi di autenticazione

Gli endpoint del Registro di sistema supportano diversi metodi di autenticazione. Il metodo scelto dipende dal registro contenitori e dai requisiti di sicurezza.

Identità gestita assegnata dal sistema

L'identità gestita assegnata dal sistema usa l'identità predefinita dell'istanza di Operazioni di Azure IoT per l'autenticazione al registro. Utilizzare questo approccio per ACR (Azure Container Registry), perché elimina la necessità di gestire le credenziali.

Prima di configurare l'endpoint di registro, verificare che l'identità gestita assegnata dal sistema per Operazioni di Azure IoT disponga delle autorizzazioni necessarie:

1. Nel portale di Azure passare all'istanza di Operazioni IoT di Azure e selezionare Panoramica.
2. Copiare il nome dell'estensione elencata dopo l'estensione Operazioni di Azure IoT Arc. Ad esempio, azure-iot-operations-xxxx7.
3. Passare al registro contenitori >Controllo di accesso (IAM)>Aggiungi assegnazione di ruolo.
4. Nella scheda Ruolo selezionare il ruolo AcrPull.
5. Nella scheda Membri, per Assegna accesso a, selezionare Utente, gruppo o entità servizio, quindi selezionare + Seleziona membri e cercare il nome dell’estensione Arc di Operazioni di Azure IoT. Scegliere l'estensione e selezionare Seleziona.
6. Selezionare Rivedi e assegna per completare l'assegnazione di ruolo.

az iot ops registry create \
  --name $REGISTRY_ENDPOINT \
  --instance $AIO_INSTANCE_NAME \
  --resource-group $RESOURCE_GROUP \
  --host $ACR_NAME.azurecr.io \
  --auth-type SystemAssignedManagedIdentity \
  --audience https://management.azure.com/

authentication: {
  method: 'SystemAssignedManagedIdentity'
  systemAssignedManagedIdentitySettings: {
    audience: 'https://management.azure.com/'
  }
}

L'operatore tenta di dedurre il gruppo di destinatari dall'endpoint se non lo si specifica. Per il Registro Azure Container, il gruppo di destinatari è generalmente https://management.azure.com/.

Identità gestita assegnata dall'utente

L'identità gestita assegnata dall'utente consente di usare un'identità gestita specifica creata e configurata con le autorizzazioni necessarie. Prima di configurare l'endpoint di registro, verificare che l'identità gestita assegnata dall'utente disponga del ruolo AcrPull nel registro contenitori.

az iot ops registry create \
  --name $REGISTRY_ENDPOINT \
  --instance $AIO_INSTANCE_NAME \
  --resource-group $RESOURCE_GROUP \
  --host $ACR_NAME.azurecr.io \
  --auth-type UserAssignedManagedIdentity \
  --client-id $CLIENT_ID \
  --tenant-id $TENANT_ID

authentication: {
  method: 'UserAssignedManagedIdentity'
  userAssignedManagedIdentitySettings: {
    clientId: '<CLIENT_ID>'
    tenantId: '<TENANT_ID>'
  }
}

L'operatore tenta di dedurre l'ambito dall'endpoint se non viene specificato.

Segreto pull di artefatto

I segreti pull degli artefatti consentono di usare l'autenticazione con nome utente e password per i registri che non supportano l'autenticazione con identità gestita.

Creare prima di tutto un segreto Kubernetes contenente le credenziali del Registro di sistema:

kubectl create secret docker-registry my-registry-secret \
  --docker-server=myregistry.azurecr.io \
  --docker-username=$REGISTRY_USERNAME \
  --docker-password=$REGISTRY_PASSWORD \
  -n azure-iot-operations

az iot ops registry create \
  --name $REGISTRY_ENDPOINT \
  --instance $AIO_INSTANCE_NAME \
  --resource-group $RESOURCE_GROUP \
  --host $REGISTRY_HOST \
  --auth-type ArtifactPullSecret \
  --secret-ref my-registry-secret

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

Autenticazione anonima

L'autenticazione anonima viene usata per i registri pubblici che non richiedono credenziali.

az iot ops registry create \
  --name $REGISTRY_ENDPOINT \
  --instance $AIO_INSTANCE_NAME \
  --resource-group $RESOURCE_GROUP \
  --host $REGISTRY_HOST \
  --no-auth

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

Integrazione di Registro Azure Container

Azure Container Registry è il registro dei contenitori consigliato per le operazioni IoT di Azure. Registro Azure Container offre registri contenitori Docker sicuri e privati, con autenticazione integrata tramite Microsoft Entra ID.

Prerequisiti per Registro Azure Container

1. Creare un'istanza ACR: se non ne hai una disponibile, crea un'istanza di Azure Container Registry nella tua sottoscrizione.
2. Configurare le autorizzazioni: verificare che l'identità gestita di Operazioni di Azure IoT disponga delle autorizzazioni AcrPull nel registro.
3. Eseguire il push degli artefatti: caricare i moduli WASM e le definizioni di grafico nel registro usando strumenti come l'interfaccia della riga di comando di ORAS.

Usare un registro pubblico

È possibile configurare un endpoint del Registro di sistema in modo che punti direttamente a un registro compatibile con OCI pubblico. Questo approccio ti permette di fare riferimento a moduli WASM predefiniti e definizioni di grafi senza dover creare un proprio registro privato.

Ad esempio, i moduli WASM di esempio di Operazioni di Azure IoT e le definizioni dei grafi sono pubblicati sotto ghcr.io/azure-samples/explore-iot-operations. Crea un endpoint del registro per l'host ghcr.io del registro e autentica con un PAT di GitHub. Inserire il percorso del azure-samples/explore-iot-operations repository nei riferimenti agli artefatti.

Per prima cosa, crea un segreto Kubernetes che contenga il nome utente GitHub e un PAT con l'ambito read:packages:

kubectl create secret docker-registry ghcr-pull-secret \
  --docker-server=ghcr.io \
  --docker-username=$GITHUB_USERNAME \
  --docker-password=$GITHUB_PAT \
  -n azure-iot-operations

Poi crea l'endpoint del registro che fa riferimento al segreto.

az iot ops registry create \
  --name public-ghcr \
  --instance $AIO_INSTANCE_NAME \
  --resource-group $RESOURCE_GROUP \
  --host ghcr.io \
  --auth-type ArtifactPullSecret \
  --secret-ref ghcr-pull-secret

resource publicRegistryEndpoint 'Microsoft.IoTOperations/instances/registryEndpoints@2026-03-01' = {
  parent: aioInstance
  name: 'public-ghcr'
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    host: 'ghcr.io'
    authentication: {
      method: 'ArtifactPullSecret'
      artifactPullSecretSettings: {
        secretRef: 'ghcr-pull-secret'
      }
    }
  }
}

Dopo aver creato questo endpoint del Registro di sistema, è possibile farvi riferimento nel grafico del flusso di dati come registryEndpointRef: public-ghcr. Il runtime utilizza il pull secret per autenticarsi su ghcr.io ed estrae direttamente gli artefatti di esempio.

Per l'elenco dei moduli WASM di esempio predefiniti e delle definizioni dei grafi disponibili in ghcr.io/azure-samples/explore-iot-operations, vedere Usare moduli predefiniti da un registro pubblico.

Endpoint predefinito del registro MCR

Quando si distribuisce Operazioni di Azure IoT, viene creato automaticamente un endpoint del Registro di sistema denominato default . Questo endpoint punta a Registro Microsoft Container (mcr.microsoft.com) con autenticazione anonima.

az iot ops registry show \
  --name default \
  --instance $AIO_INSTANCE_NAME \
  --resource-group $RESOURCE_GROUP

az iot ops registry list \
  --instance $AIO_INSTANCE_NAME \
  --resource-group $RESOURCE_GROUP

resource defaultRegistryEndpoint 'Microsoft.IoTOperations/instances/registryEndpoints@2026-03-01' = {
  parent: aioInstance
  name: 'default'
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    host: 'mcr.microsoft.com'
    authentication: {
      method: 'Anonymous'
      anonymousSettings: {}
    }
  }
}

I grafici del flusso di dati predefiniti (mappa, filtro, ramo, concatenazione, finestra, limite) usano questo endpoint per recuperare gli artefatti di elaborazione da MCR. Quando utilizzi registryEndpointRef: default in una risorsa DataflowGraph, non è necessaria alcuna configurazione aggiuntiva del registro. Per altre informazioni sulle trasformazioni predefinite, vedere Panoramica dei grafici del flusso di dati.

Altri registri contenitori

Gli endpoint del Registro di sistema supportano qualsiasi registro contenitori compatibile con OCI, tra cui Docker Hub, GitHub Container Registry (ghcr.io), Harbor, AWS Elastic Container Registry (ECR) e Google Container Registry (GCR). Per i registri pubblici, usare l'autenticazione anonima. Per i registri privati, usare i segreti pull degli artefatti o l'autenticazione con identità gestita in base alle esigenze.

Passaggi successivi

• Panoramica dei grafici del flusso di dati
• Usare trasformazioni WASM nei grafici del flusso di dati
• Configurare gli endpoint del flusso di dati
• Configurare i profili dei flussi di dati