Uso dei webhook di Registro Azure Container

Un Registro Azure Container archivia e gestisce le immagini dei contenitori Docker private, in modo analogo a come Docker Hub archivia le immagini Docker pubbliche. Può anche ospitare repository per grafici Helm (anteprima), un formato di creazione di pacchetti per la distribuzione di applicazioni in Kubernetes. È possibile usare i webhook per attivare eventi specifici quando in uno dei repository del registro si verificano determinate azioni. I webhook possono rispondere agli eventi a livello di registro oppure possono essere limitati a un tag di repository specifico. Con un registro con replica geografica, si configura ogni webhook per rispondere a eventi in una replica a livello di area specifica.

L'endpoint per un webhook deve essere accessibile pubblicamente dal registro. È possibile configurare le richieste webhook del registro per l'autenticazione a un endpoint protetto.

Per informazioni dettagliate sulle richieste di webhook, vedere le informazioni di riferimento sullo schema del webhook di Registro Azure Container.

Important

Usare HTTPS e inviare credenziali webhook solo nell'intestazione Authorization . Registro Azure Container maschera il valore dell'intestazione Authorization nella cronologia eventi del webhook. Non maschera le credenziali nell'URI del servizio, in altre intestazioni personalizzate o nei corpi di richiesta o risposta.

Non includere password, token di accesso, chiavi API o altri segreti in qualsiasi punto dell'URI del servizio. Questa restrizione include le credenziali prima del nome host (ad esempio, https://user:password@host), il percorso e la stringa di query. Comprende anche URL di callback firmati che contengono token di autenticazione nelle stringhe di query. Non includere segreti in alcuna intestazione personalizzata diversa da Authorization. Per altre informazioni, vedere Proteggere le credenziali del webhook.

Prerequisiti

Creare un webhook - Portale di Azure

  1. Accedere al portale di Azure.
  2. Passare al registro contenitori in cui si intende creare un webhook.
  3. In Servizi selezionare Webhook.
  4. Selezionare Aggiungi nella barra degli strumenti relativa al webhook.
  5. Completare il modulo Crea webhook con le informazioni seguenti:
valore Descrizione
Nome webhook Il nome da assegnare al webhook. Può contenere solo lettere e numeri e deve avere una lunghezza di 5-50 caratteri.
Location Per un registro di replica geografica , specificare l'area di Azure della replica del registro.
URI del servizio URI HTTPS in cui il webhook deve inviare notifiche POST. Non includere password, token di accesso, chiavi API o altri segreti in qualsiasi punto dell'URI. Questa regola si applica alle credenziali prima del nome host (ad esempio, https://user:password@host), del percorso e della stringa di query.
Intestazioni personalizzate Le intestazioni che si vuole passare insieme alla richiesta POST. Devono essere nel formato "chiave: valore". Inviare credenziali solo nell'intestazione Authorization . Non includere password, token di accesso, chiavi API o altri segreti in qualsiasi altra intestazione. Solo il valore dell'intestazione Authorization viene mascherato nella cronologia eventi del webhook.
Azioni trigger Le azioni che attivano il webhook. Le azioni includono push dell'immagine, eliminazione di immagini, push del grafico Helm, eliminazione del grafico Helm e quarantena delle immagini. È possibile scegliere una o più azioni per attivare il webhook.
Stato Lo stato del webhook dopo che è stato creato. È abilitata per impostazione predefinita.
Scope L'ambito in cui viene applicato il webhook. Se non specificato, l'ambito comprende tutti gli eventi del registro. Può essere specificato per un repository o un tag usando il formato "repository:tag" o "repository:*" per tutti i tag in un repository.

Modulo di webhook di esempio:

Screenshot che mostra l'interfaccia utente per la creazione di webhook del Registro Azure Container nel portale di Azure.

Creare un webhook - Interfaccia della riga di comando di Azure

Per creare un webhook usando l'interfaccia della riga di comando di Azure, usare il comando az acr webhook create. Il comando seguente crea un webhook per tutti gli eventi di eliminazione di immagini nel registro mycontainerregistry:

az acr webhook create --registry mycontainerregistry --name myacrwebhook01 --actions delete --uri https://webhookuri.com --headers "Authorization=$WEBHOOK_AUTH"

Proteggere le credenziali del webhook

Registro Azure Container archivia la configurazione del webhook e registra le richieste che invia al tuo endpoint, insieme alle risposte, nella cronologia degli eventi del webhook. Per ridurre il rischio di esposizione delle credenziali, seguire queste linee guida:

  • Usare un URI del servizio HTTPS. Non inviare credenziali tramite HTTP.
  • Inviare credenziali solo nell'intestazione Authorization . Nella cronologia eventi webhook Registro Azure Container maschera il valore dell'intestazione Authorization nelle intestazioni di richiesta e risposta registrate.
  • Non inserire le credenziali altrove. Registro Azure Container non maschera questi valori nella cronologia eventi del webhook:
    • URI del servizio, incluse le credenziali prima del nome host (ad esempio, https://user:password@host), il percorso e la stringa di query.
    • Intestazioni personalizzate diverse da Authorization.
    • Corpi di richiesta e risposta.
  • Assicurarsi che l'endpoint non riecheggi le credenziali nel corpo della risposta o nelle intestazioni di risposta diverse da Authorization.
  • Non fare affidamento sulla codifica per nascondere le credenziali. La codifica URL, la codifica Base64 e le virgolette della shell non proteggono un segreto.
  • Limitare chi può leggere la configurazione del webhook. Gli utenti con l'autorizzazione Microsoft.ContainerRegistry/registries/webhooks/getCallbackConfig/action possono leggere l'URI del servizio configurato e tutte le intestazioni personalizzate, incluso il valore dell'intestazione non mascherata Authorization . Gli utenti con l' Microsoft.ContainerRegistry/registries/webhooks/listEvents/action autorizzazione possono leggere la cronologia degli eventi del webhook, ma non possono visualizzare il valore dell'intestazione non mascherata Authorization . I ruoli predefiniti, ad esempio Proprietario e Collaboratore, includono queste autorizzazioni.
  • Se una credenziale è stata precedentemente inclusa nell'URI del servizio, in un'altra intestazione personalizzata o in un corpo della richiesta o della risposta, revocare o ruotare tale credenziale.

Testare un webhook

Portale di Azure

Prima di usare il webhook, è possibile testarlo con il pulsante Ping. Il comando Ping invia una richiesta POST generica all'endpoint specificato e registra la risposta. L'uso del comando Ping consente di verificare se la configurazione del webhook è corretta.

  1. Selezionare il webhook da testare.
  2. Nella barra degli strumenti superiore selezionare l'azione Ping.
  3. Controllare la risposta dell'endpoint nella colonna Stato HTTP.

Interfaccia utente per la creazione di webhook di Registro Azure Container nel portale di Azure

Interfaccia della riga di comando di Azure

Per testare un webhook di Registro Azure Container con l'interfaccia della riga di comando di Azure, usare il comando az acr webhook ping.

az acr webhook ping --registry mycontainerregistry --name myacrwebhook01

Per visualizzare i risultati, usare il comando az acr webhook list-events.

az acr webhook list-events --registry mycontainerregistry08 --name myacrwebhook01

Eliminare un webhook

Portale di Azure

Per eliminare un webhook, è possibile selezionarlo e usare il pulsante Elimina nel portale di Azure.

Interfaccia della riga di comando di Azure

az acr webhook delete --registry mycontainerregistry --name myacrwebhook01

Passaggi successivi

Informazioni di riferimento per lo schema di webhook

Per informazioni dettagliate sul formato e sulle proprietà dei payload degli eventi JSON generati da Registro Azure Container, vedere le informazioni di riferimento per lo schema di webhook:

Informazioni di riferimento allo schema del webhook del Registro Azure Container

Eventi di Griglia di eventi

Oltre agli eventi di webhook del registro nativo descritti in questo articolo, il Registro Azure Container può trasmettere eventi a Griglia di eventi:

Avvio rapido: inviare eventi del registro contenitori a Griglia di eventi

  • Ultimo aggiornamento: