Eseguire la migrazione delle autorizzazioni del pool di agenti dell'attività ACR

A partire dal 1° giugno 2027, le richieste API di ACR Tasks di Registro Azure Container (ACR) che specificano agentPoolName richiedono che il chiamante disponga dell'autorizzazione Microsoft.ContainerRegistry/registries/agentpools/read per il pool di agenti specificato, oltre alle autorizzazioni già necessarie per l'operazione di attività.

Usare questo articolo per identificare le richieste interessate, aggiornare le autorizzazioni prima dell'applicazione, convalidare l'accesso e risolvere gli errori. Per informazioni sui pool di agenti dedicati, vedere Eseguire un'attività in un pool di agenti dedicato.

Comprendi quali richieste sono interessate

La tabella seguente elenca le operazioni API interessate e i campi da controllare in ogni corpo della richiesta JSON.

Per ogni richiesta che specifica un pool, identificare l'utente, l'entità servizio CI/CD o l'identità gestita di automazione che invia la richiesta API di gestione. Usare questa identità durante il controllo o l'aggiornamento dell'accesso in lettura al pool di agenti. L'identità di runtime dell'attività controlla l'accesso alle risorse durante l'esecuzione.

Il controllo aggiuntivo si applica solo alle richieste che specificano agentPoolName. I requisiti di accesso alle immagini e alle operazioni di attività esistenti continuano a essere applicati a tutte le richieste.

Ruoli predefiniti che concedono già la lettura del pool di agenti

I ruoli predefiniti seguenti nel cloud pubblico di Azure concedono Microsoft.ContainerRegistry/registries/agentpools/read tramite le autorizzazioni del piano di controllo, in modo esplicito o tramite un carattere jolly, tenendo conto di notActions. Se l'identità chiamante ha un'assegnazione effettiva di uno di questi ruoli in un ambito che copre il pool selezionato, non è necessario alcun aggiornamento delle autorizzazioni per questa modifica.

Assegnare l'autorizzazione di lettura del pool nel pool, nel registro o in un ambito padre che copre il pool. Quando si usa Reader per aggiungere l'accesso in lettura al pool, mantenere le autorizzazioni esistenti per le operazioni del chiamante per pianificare le esecuzioni e creare o aggiornare attività o esecuzioni di attività.

Le definizioni di ruolo predefinite possono cambiare e possono variare tra Azure cloud. Usare il pool-read check per confermare l'accesso effettivo prima di decidere se è necessario un aggiornamento. Per informazioni dettagliate sui ruoli, vedere le informazioni di riferimento sui ruoli predefiniti di Azure. Scegliere un ruolo che corrisponda all'attività del chiamante e ai requisiti del pool di agenti.

Esaminare i ruoli personalizzati dell'attività per Microsoft.ContainerRegistry/registries/agentpools/read nel loro actions, tenendo conto dei caratteri jolly e delle esclusioni notActions. Aggiornare le chiamate le cui assegnazioni effettive non dispongono di questa autorizzazione.

Prerequisites

Per controllare e aggiornare l'accesso, è necessario:

• I nomi della sottoscrizione, del gruppo di risorse, del registro e del pool di agenti.
• L'ID oggetto di ogni identità chiamante se è necessario esaminare o assegnare ruoli. Per un service principal, usare il relativo ID oggetto. Per un'identità gestita, usare il relativo ID entità servizio.
• Accesso in lettura dell'attività alle attività di inventario archiviate. L'ispezione dei ruoli richiede autorizzazioni di lettura per l'assegnazione del ruolo e la definizione del ruolo. Un amministratore di accesso può aiutare a esaminare i ruoli e applicare gli aggiornamenti.
• Per le modifiche ai ruoli personalizzati, Microsoft.Authorization/roleDefinitions/write su tutti gli ambiti assegnabili del ruolo. Per le assegnazioni di ruolo, Microsoft.Authorization/roleAssignments/write nell'ambito dell'assegnazione. Vedere Creare o aggiornare ruoli personalizzati e Assegnare ruoli Azure.
• interfaccia della riga di comando di Azure in un ambiente Bash, ad esempio Azure Cloud Shell.

Impostare le variabili seguenti per il registro e il pool che si sta controllando. Hai solo bisogno di principalObjectId per l'ispezione o l'assegnazione di ruoli:

subscriptionId="<subscription-id>"
resourceGroup="<resource-group>"
registryName="<registry-name>"
agentPoolName="<agent-pool-name>"
principalObjectId="<caller-object-id>"

az account set --subscription "$subscriptionId"

registryId="/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$registryName"
agentPoolId="$registryId/agentPools/$agentPoolName"

Ripetere i controlli per ogni sottoscrizione, registro, pool e identità chiamante usati dai flussi di lavoro.

Individuare i chiamanti che necessitano di un aggiornamento dell'autorizzazione

Identificare l'utilizzo dei pool denominati, quindi controllare le autorizzazioni effettive di ogni chiamante sul pool selezionato.

Configurazione dell'attività di inventario e della richiesta

Rivedere gli script, le pipeline CI/CD, le chiamate SDK e le definizioni Infrastructure as Code per i campi nella tabella delle richieste interessate. Includere comandi di interfaccia della riga di comando di Azure che usano --agent-pool, ad esempio compilazioni rapide, esecuzioni rapide e creazione o aggiornamenti delle attività.

Come amministratore con accesso in lettura alle attività, elencare le attività archiviate che specificano un pool di agenti:

az acr task list \
    --registry "$registryName" \
    --resource-group "$resourceGroup" \
    --query "[?agentPoolName].{task:name,agentPool:agentPoolName}" \
    --output table

Elenca anche le risorse di esecuzione delle attività:

az acr taskrun list \
    --registry "$registryName" \
    --resource-group "$resourceGroup" \
    --output json

Esaminare i modelli di distribuzione o la configurazione della richiesta originale per ogni esecuzione di attività per identificare properties.runRequest.agentPoolName. Esaminare il corpo delle richieste dirette scheduleRun per includere esecuzioni rapide e altre richieste su richiesta nel tuo inventario.

Per ogni flusso di lavoro, registrare l'operazione, l'ID risorsa del pool di destinazione e l'ID oggetto del principal chiamante. Includi flussi di lavoro poco frequenti, pianificati e in fase di distribuzione. Esaminare le definizioni del workflow anche quando gli elenchi di attività e esecuzione attività archiviati sono vuoti.

Controllare le autorizzazioni effettive per ogni pool

Accedi con l'identità che invia le richieste di attività oppure esegui questo comando nell'ambiente della pipeline o di automazione che usa tale identità.

az acr agentpool show \
    --subscription "$subscriptionId" \
    --registry "$registryName" \
    --resource-group "$resourceGroup" \
    --name "$agentPoolName" \
    --query id \
    --output tsv

Se non è possibile eseguire il test come identità chiamante, chiedere a un amministratore di accesso di esaminare le assegnazioni di ruolo nell'ambito del pool. Includi l'accesso ereditato e basato su gruppi e tenere conto delle assegnazioni di negazione. Confrontare i ruoli predefiniti con l'elenco dei ruoli; per i ruoli personalizzati, controllare actions e notActions per verificare l'autorizzazione di lettura richiesta. Usare una visualizzazione completa dell'accesso effettivo per determinare se è necessario un aggiornamento delle autorizzazioni.

Assegnare l'autorizzazione di lettura al pool di agenti

Per i chiamanti che necessitano di un aggiornamento delle autorizzazioni, è consigliabile usare Container Registry Tasks Contributor a livello di registro per la gestione delle attività di ACR. Se si ha familiarità con la gestione dei ruoli personalizzati e si vuole mantenere un set di autorizzazioni più ristretto, è possibile aggiungere l'autorizzazione di lettura del pool di agenti specifica al ruolo personalizzato esistente del chiamante.

Mantenere le autorizzazioni del task esistente del chiamante. Chiedere a un amministratore autorizzato di applicare una delle opzioni seguenti.

Opzione 1: Assegnare un ruolo predefinito

Assegnare il ruolo predefinito Container Registry Tasks Contributor nell'ambito del registro. Include autorizzazioni di gestione delle attività, Microsoft.ContainerRegistry/registries/agentpools/read, e Microsoft.ContainerRegistry/registries/read. Il comando seguente lo assegna all'entità servizio chiamante o all'identità gestita:

az role assignment create \
    --subscription "$subscriptionId" \
    --assignee-object-id "$principalObjectId" \
    --assignee-principal-type ServicePrincipal \
    --role "Container Registry Tasks Contributor" \
    --scope "$registryId"

Per un utente o un gruppo, usare il relativo ID oggetto e modificare --assignee-principal-type in User o Group. Ripetere per ogni registro di sistema necessario al chiamante.

Questo ruolo concede le autorizzazioni di gestione di attività e pool di agenti. Verificare l'accesso prima di assegnarlo. Usare l'opzione 2 per mantenere un set di autorizzazioni personalizzato più ristretto.

Opzione 2: Aggiornare il ruolo personalizzato esistente

Se si ha familiarità con la gestione dei ruoli personalizzati e si usa già un ruolo personalizzato per le attività per il caller, aggiungere solo Microsoft.ContainerRegistry/registries/agentpools/read alle azioni del piano di controllo di quel ruolo. Mantenere invariate le altre autorizzazioni. Esportare la definizione corrente:

az role definition list \
    --subscription "$subscriptionId" \
    --name "<custom-role-name-or-id>" \
    --query "[0]" \
    --output json > acr-task-role.json

Verificare che acr-task-role.json contenga il ruolo personalizzato corretto, quindi aggiungere l'azione all'array permissions del blocco actions esistente. Mantenere invariato l'ID ruolo, altre autorizzazioni e gli ambiti assegnabili. Verificare in notActions che l'azione aggiunta sia consentita. Esaminare il modo in cui la modifica influisce sulle identità che usano già questo ruolo prima di applicare l'aggiornamento:

az role definition update \
    --subscription "$subscriptionId" \
    --role-definition acr-task-role.json

L'assegnazione di ruolo del chiamante deve coprire il pool. Per le assegnazioni con ambito a un'attività o a un'esecuzione di attività, usare l'opzione 1 per concedere l'accesso a livello di registro.

Per altre informazioni, vedere ruoli personalizzati di ACR.

Convalidare la migrazione

Eseguire il test usando l'identità che invia la richiesta originale. Attendere l'applicazione delle modifiche di ruolo e assegnazione e quindi aggiornare il token di accesso o di accesso utente del chiamante prima di riprovare. Per informazioni dettagliate, vedere Risolvere i problemi di Azure RBAC.

1. Ripetere il controllo di lettura del pool dopo qualsiasi aggiornamento delle autorizzazioni.
2. In un ambiente di test inviare nuovamente la richiesta originale usando lo stesso chiamante e il pool. Verificare che la richiesta includa il agentPoolName campo elencato nella tabella delle richieste interessate. Ripetere per ogni operazione API usata dai flussi di lavoro, inclusa la pianificazione delle esecuzioni e la creazione o l'aggiornamento di attività o esecuzioni di attività.
3. Verificare che l'operazione sia accettata e, per una richiesta di esecuzione, che l'esecuzione proceda nel pool previsto. Risolvi qualsiasi attività, immagine, sorgente o autorizzazioni di runtime separate richieste dal carico di lavoro.
4. Ripetere il controllo per ogni identità chiamante e pool.

Usare questi risultati previsti durante la verifica dopo l'applicazione:

Risolvere i problemi di autorizzazione

Dopo l'applicazione, le richieste interessate non superano l'autorizzazione quando il chiamante non dispone dell'accesso in lettura al pool specificato. Aggiornare le autorizzazioni del chiamante prima di ritentare la richiesta. Gli errori di autorizzazione impediscono la creazione dell'attività richiesta, l'aggiornamento dell'attività o l'invio dell'esecuzione.

Il pool-read check conferma l'accesso in lettura del chiamante al pool di agenti.

Se una richiesta coinvolta fallisce:

1. Registrare lo stato HTTP restituito, il codice di errore e il messaggio di errore completo. Controllare se l'errore identifica l'accesso in lettura al pool di agenti e l'ID risorsa del pool. Un errore per un'azione o una risorsa diversa richiede un'indagine separata.
2. Verificare l'ID oggetto principale e il tenant dell'identità che ha inviato la richiesta, insieme alla sottoscrizione e al pool di destinazione.
3. Ricontrollare l'accesso diretto, ereditato e basato su gruppo in tale pool, incluse le esclusioni dei ruoli e le assegnazioni di negazione.
4. Chiedere a un amministratore autorizzato di aggiungere o correggere l'assegnazione. Attendere che la modifica venga applicata, aggiornare le credenziali del chiamante e inviare nuovamente la richiesta originale.
5. Se la lettura del pool ha esito positivo e l'operazione non riesce, esaminare le autorizzazioni originali dell'operazione e l'errore restituito. Limita qualsiasi aggiornamento delle autorizzazioni all'azione e alla risorsa identificata dall'errore.

Contatta il supporto

Se l'errore persiste, aprire una richiesta di supporto per ACR. Includere:

• La sottoscrizione, l'ID risorsa del registro e l'ID risorsa del pool di agenti.
• ID dell'oggetto principal chiamante e ID del tenant.
• L'operazione API, la versione api, l'ora dell'errore UTC e l'ID di richiesta o correlazione dalla risposta.
• Stato HTTP, codice di errore e messaggio di errore completo.
• Copia della richiesta con segreti rimossi, che mostra il campo del pool di agenti, le definizioni dei ruoli e gli ambiti di assegnazione controllati e i passaggi usati per controllare l'accesso.

Rimuovere token di accesso, segreti del client, password del registro, credenziali di origine e altri valori sensibili prima di condividere queste informazioni con il supporto.

Passaggi successivi

• Eseguire un'attività in un pool di agenti dedicato.
• Gestire i ruoli personalizzati di ACR.
• Esaminare i ruoli predefiniti di ACR.