Configura l'autenticazione in Artifact Registry per Docker

Questa pagina descrive come configurare Docker per l'autenticazione nei repository Docker di Artifact Registry.

Non è necessario configurare l'autenticazione per Cloud Build o per gli ambienti di runtime Google Cloudcome Google Kubernetes Engine e Cloud Run, ma devi verificare che le autorizzazioni richieste siano configurate.

Prima di iniziare

  1. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init
  2. (Facoltativo) Configura i valori predefiniti per i comandi gcloud CLI.
  3. Verifica che l'account che utilizzi per l'autenticazione abbia l'autorizzazione per accedere ad Artifact Registry. Ti consigliamo di utilizzare un account di servizio anziché un account utente.
  4. Installa Docker se non è già installato. Docker è incluso in Cloud Shell.
  5. Docker richiede l'accesso con privilegi per interagire con i registri. Su Linux o Windows, aggiungi l'utente che utilizzi per eseguire i comandi Docker al gruppo di sicurezza Docker. Questo passaggio non è necessario su macOS poiché Docker Desktop viene eseguito su una macchina virtuale come utente root.

    Linux

    Il gruppo di sicurezza Docker si chiama docker. Per aggiungere il tuo nome utente, esegui il seguente comando: 

          sudo usermod -a -G docker ${USER}

    Windows

    Il gruppo di sicurezza Docker si chiama docker-users. Per aggiungere un utente dal prompt dei comandi dell'amministratore, esegui il seguente comando:

            net localgroup docker-users DOMAIN\USERNAME /add

    Dove:

    • DOMAIN è il tuo dominio Windows.
    • USERNAME è il tuo nome utente.

    Uscire e accedere di nuovo per applicare le modifiche all'appartenenza al gruppo. Se utilizzi una macchina virtuale, potrebbe essere necessario riavviare la macchina virtuale affinché le modifiche all'abbonamento vengano applicate.

Scelta di un metodo di autenticazione

Sono disponibili i seguenti metodi di autenticazione:

gcloud CLI credential helper
Configura le credenziali di Artifact Registry per l'utilizzo con Docker direttamente in gcloud CLI. Si tratta del metodo di autenticazione più semplice, ma può essere più lento dell'helper delle credenziali autonomo.
Utilità di assistenza per le credenziali Docker autonoma
Questa opzione è principalmente per configurare le credenziali per l'utilizzo con Docker in assenza di Google Cloud CLI. È molto più veloce dell'helper per le credenziali gcloud CLI e utilizza le credenziali predefinite dell'applicazione (ADC) per trovare automaticamente le credenziali nel tuo ambiente.
Token di accesso
Puoi generare un token di accesso di breve durata per un account di servizio e poi usarlo per l'autenticazione con password. Poiché il token è valido solo per 60 minuti, è un'opzione più sicura di una chiave dell'account di servizio.
Chiave account di servizio
Una coppia di chiavi gestita dall'utente che puoi utilizzare come credenziale per un account di servizio. Poiché la credenziale è permanente, è l'opzione meno sicura tra tutti i metodi di autenticazione disponibili.

Se possibile, utilizza un token di accesso o un helper per le credenziali per ridurre il rischio di accessi non autorizzati alle tue immagini container. Se devi utilizzare una chiave dell'account di servizio, assicurati di seguire le best practice per la gestione delle credenziali.

Impostazioni di autenticazione nel file di configurazione di Docker

Docker salva le impostazioni di autenticazione nel file di configurazione config.json.

  • Linux: ~/.docker/config.json
  • Windows: %USERPROFILE%\.docker\config.json

Il file contiene sezioni separate per i diversi metodi di autenticazione:

credHelpers
Se utilizzi l'helper per le credenziali Docker per l'autenticazione, Artifact Registry memorizza le impostazioni dell'helper per le credenziali nella sezione credHelpers del file.
auths
Se utilizzi Docker per accedere con un token o una chiave dell'account di servizio come password, Docker memorizza una versione codificata in base64 delle tue credenziali nella sezione auths del file.
credStore
Se hai configurato un archivio delle credenziali per gestire le tue credenziali, le impostazioni per l'archivio delle credenziali si trovano nella sezione credStore del file.

Quando Docker si connette a un registry, controlla prima se è presente un assistente per le credenziali associato all'host. Pertanto, se config.json include le impostazioni Artifact Registry sia nelle sezioni credHelpers sia in auths, le impostazioni nella sezione auths vengono ignorate.

Utilità di supporto delle credenziali gcloud CLI

Lo strumento di assistenza per le credenziali dellgcloud CLI fornisce accesso sicuro e temporaneo alle risorse del progetto. Configura Docker per eseguire l'autenticazione negli host di Artifact Registry in qualsiasi ambiente in cui è installato Google Cloud CLI. Cloud Shell include Google Cloud CLI e una versione aggiornata di Docker.

L'helper delle credenziali gcloud CLI è il metodo di autenticazione più semplice da configurare. Configura Docker con le credenziali dell'account utente o di servizio attivo nella sessione gcloud CLI. Poiché questo helper delle credenziali dipende dalla gcloud CLI, può essere notevolmente più lento dell'helper delle credenziali autonomo. Per le build automatiche con strumenti di terze parti o client Docker con un numero elevato di host di registry configurati, utilizza lo strumento di assistenza per le credenziali autonomo.

Per autenticarti ad Artifact Registry:

  1. Accedi a gcloud CLI come utente che eseguirà i comandi Docker.

    • Per configurare l'autenticazione con le credenziali utente, esegui il seguente comando:

      gcloud auth login

    • Per configurare l'autenticazione con le credenziali dell'account di servizio, esegui questo comando:

      gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE

      Dove

      • ACCOUNT è l'account di servizio che vuoi utilizzare con Artifact Registry nel formato USERNAME@PROJECT-ID.iam.gserviceaccount.com. Se vuoi utilizzare un account esistente, puoi visualizzare un elenco di service account nella pagina Service account della console Google Cloud o con il comando gcloud iam service-accounts list
      • KEY-FILE è il file della chiave dell'account di servizio. Per informazioni sulla creazione di una chiave, consulta la documentazione di Identity and Access Management (IAM).

  2. Esegui questo comando:

    gcloud auth configure-docker HOSTNAME-LIST

    dove HOSTNAME-LIST è un elenco separato da virgole di hostname dei repository da aggiungere alla configurazione dell'helper delle credenziali.

    Ad esempio, per aggiungere le regioni us-west1 e asia-northeast1, esegui il comando:

    gcloud auth configure-docker us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

    I nomi host specificati vengono aggiunti alla configurazione dell'helper delle credenziali. Puoi aggiungere altri nomi host alla configurazione in un secondo momento eseguendo nuovamente il comando.

    Per visualizzare un elenco delle posizioni dei repository supportate, esegui il comando:

    gcloud artifacts locations list

  3. Il comando mostra la sezione credHelpers della configurazione Docker corrente e la configurazione aggiornata dopo l'aggiunta dei nomi host specificati.

    Per accettare le modifiche alla configurazione, inserisci y.

    Le credenziali vengono salvate nella home directory dell'utente.

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

  4. Docker richiede che gli helper per le credenziali siano nel sistema PATH. Assicurati che il comando gcloud sia nel sistema PATH.

Assistente per le credenziali autonomo

L'assistente per le credenziali Docker autonomo configura Docker per eseguire l'autenticazione in Artifact Registry su un sistema in cui la gcloud CLI non è disponibile. È molto più veloce dell'utilità di credenziali della CLI gcloud e utilizza le credenziali predefinite dell'applicazione (ADC) per trovare automaticamente le credenziali nel tuo ambiente. Per operazioni diverse dall'invio e dal recupero di immagini, ad esempio il tagging o la pubblicazione di immagini. Ti consigliamo di utilizzare questo metodo di autenticazione per le build automatiche con strumenti di terze parti o client Docker con un numero elevato di host del registry configurati.

L'assistente per le credenziali Docker autonomo recupera le credenziali di Artifact Registry e le scrive nel file di configurazione di Docker. In questo modo, puoi utilizzare lo strumento a riga di comando Docker, docker, per interagire direttamente con Artifact Registry.

Per utilizzare l'assistente per le credenziali Docker:

  1. Accedi alla macchina come utente che eseguirà i comandi Docker.

  2. Scarica l'assistente per le credenziali Docker autonomo da GitHub.

    Se vuoi, puoi utilizzare l'utilità a riga di comando curl. Ad esempio:

    VERSION=2.1.25
OS=linux  # or "darwin" for OSX, "windows" for Windows.
ARCH=amd64  # or "386" for 32-bit OSs

curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
| tar xz docker-credential-gcr \
&& chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/

  3. Configura Docker in modo che utilizzi le tue credenziali di Artifact Registry quando interagisci con Artifact Registry (devi eseguire questa operazione solo una volta):

    docker-credential-gcr configure-docker --registries=HOSTNAME-LIST

    dove HOSTNAME-LIST è un elenco separato da virgole di hostname dei repository da aggiungere alla configurazione dell'helper delle credenziali.

    Ad esempio, per aggiungere le regioni us-west1 e asia-northeast1, esegui il comando:

    docker-credential-gcr configure-docker --registries=us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

    I nomi host specificati vengono aggiunti alla configurazione dell'helper delle credenziali. Puoi aggiungere altri nomi host alla configurazione in un secondo momento eseguendo nuovamente il comando.

    Per visualizzare un elenco delle posizioni dei repository supportate, esegui il comando:

    gcloud artifacts locations list

    Per maggiori informazioni, consulta la documentazione dell'helper per le credenziali Docker autonomo su GitHub.

    Le credenziali vengono salvate nella home directory dell'utente.

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

  4. Docker richiede che gli helper per le credenziali siano nel sistema PATH. Assicurati che il comando docker-credential-gcr sia nel sistema PATH.

  5. Per verificare che lo strumento di assistenza per le credenziali possa recuperare correttamente le tue credenziali, esegui il seguente comando:

    echo "https://HOSTNAME" | docker-credential-gcr get

    Sostituisci HOSTNAME con un nome host che hai aggiunto alla configurazione. Ad esempio:

    echo "https://us-west1-docker.pkg.dev" | docker-credential-gcr get

    Se il comando ha esito positivo, l'output JSON restituito include un token nel campo Secret. Ad esempio:

    {"ServerURL":"https://us-west1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}

Docker è ora configurato per l'autenticazione con Artifact Registry. Per inviare e recuperare le immagini, assicurati che le autorizzazioni siano configurate correttamente.

Token di accesso

Puoi generare un token di accesso OAuth di breve durata per autenticarti con Artifact Registry. Poiché il token è valido per 60 minuti, lo devi richiedere meno di un'ora prima di utilizzarlo per connetterti a Artifact Registry.

Per utilizzare un token di accesso con le credenziali dell'account di servizio:

  1. Crea un account di servizio che agisca per conto della tua applicazione oppure scegli un account di servizio esistente che utilizzi per l'automazione.

  2. Concedi il ruolo Artifact Registry specifico all'account di servizio per fornire l'accesso al repository.

  3. Genera un token di accesso per l'account di servizio e autenticati:

    Devi disporre delle autorizzazioni nel ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator) per rubare l'identità di un account di servizio, ottenere un token per l'account e poi autenticarti come account di servizio.

    Esegui il seguente comando, sostituendo ACCOUNT con il tuo LOCATION con la località regionale o multiregionale del repository.

    Linux

    gcloud auth print-access-token \
    --impersonate-service-account ACCOUNT | docker login \
    -u oauth2accesstoken \
    --password-stdin https://LOCATION-docker.pkg.dev

    Windows

    gcloud auth print-access-token --impersonate-service-account ACCOUNT | docker login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev

Docker è ora autenticato con Artifact Registry.

Chiave account di servizio

Chiunque abbia accesso a una chiave privata valida per un account di servizio potrà accedere alle risorse tramite l'account di servizio. Tieni presente che il ciclo di vita dell'accesso della chiave all'account di servizio (e quindi ai dati a cui ha accesso l'account di servizio) è indipendente dal ciclo di vita dell'utente che ha scaricato la chiave.

Utilizza le seguenti linee guida per limitare l'accesso ai tuoi repository:

  • Crea account di servizio dedicati che vengono utilizzati solo per interagire con i repository.
  • Concedi il ruolo Artifact Registry specifico per l'accesso richiesto dall'account di servizio. Ad esempio, un account di servizio che scarica solo gli elementi richiede solo il ruolo Artifact Registry Reader.
  • Configura le autorizzazioni per i tuoi account di servizio dedicati su ogni repository anziché a livello di progetto. Puoi quindi specificare l'accesso in base al contesto del repository. Ad esempio, un account di servizio per le build di sviluppo potrebbe avere il ruolo Lettore di Artifact Registry per un repository di produzione e il ruolo Writer di Artifact Registry per un repository di staging.
  • Segui le best practice per la gestione delle credenziali.

Per creare un nuovo account di servizio e una chiave dell'account di servizio da utilizzare solo con i repository Artifact Registry:

  1. Crea un account di servizio per agire per conto della tua applicazione oppure scegli un account di servizio esistente che utilizzi per l'automazione.

    Per configurare l'autenticazione con Artifact Registry, devi conoscere la posizione del file della chiave dell'account di servizio. Per gli account esistenti, puoi visualizzare le chiavi e crearne di nuove nella pagina Account di servizio.

    Vai alla pagina Account di servizio

  2. Se vuoi, puoi codificare in base64 tutti i contenuti del file della chiave.

    Linux

    base64 FILE-NAME > NEW-FILE-NAME

    macOS

    base64 -i FILE-NAME -o NEW-FILE-NAME

    Windows

    Base64.exe -e FILE-NAME > NEW-FILE-NAME

    dove FILE-NAME è il nome file della chiave originale e NEW-FILE-NAME è il file della chiave codificato in base64.

  3. Verifica che le autorizzazioni siano configurate correttamente per l'account di servizio. Se utilizzi l'account di servizio Compute Engine, devi configurare correttamente sia le autorizzazioni sia gli ambiti di accesso.

  4. Utilizza la chiave dell'account di servizio per configurare l'integrazione con Docker:

    Esegui questo comando:

    Linux / macOS

    cat KEY-FILE | docker login -u KEY-TYPE --password-stdin \
https://LOCATION-docker.pkg.dev

    Windows

    Get-Content KEY-FILE |
docker login -u KEY-TYPE --password-stdin https://LOCATION-docker.pkg.dev

    Sostituisci quanto segue:

    • KEY-TYPE è uno dei seguenti:
      • _json_key se utilizzi la chiave dell'account di servizio in formato JSON come fornito al momento della creazione del file.
      • _json_key_base64 se hai codificato in base64 tutti i contenuti del file.
    • KEY-FILE è il nome del file della chiave dell'account di servizio in formato JSON.
    • LOCATION è la località regionale o multiregionale del repository in cui è archiviata l'immagine.

Docker è ora autenticato con Artifact Registry.