Configura l'autenticazione in Artifact Registry per Docker

Questa pagina descrive come configurare Docker per l'autenticazione in Artifact Registry Docker.

Non è necessario configurare l'autenticazione per Cloud Build o Google Cloud di ambienti di runtime come Google Kubernetes Engine e Cloud Run, ma verifica che le autorizzazioni richieste sono 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 sia autorizzazioni per accedere ad Artifact Registry. Ti consigliamo di utilizzare un account di servizio anziché rispetto a un account utente.
  4. Installa Docker, se non è già installato. Docker è incluso in Cloud Shell.

  5. Docker richiede un accesso privilegiato per interagire con i registri. Su Linux o Windows, aggiungi l'utente che utilizzi per eseguire i comandi Docker su gruppo di sicurezza Docker. Questo passaggio non è necessario su macOS perché 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 questo 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 questo comando :

    net localgroup docker-users DOMAIN\USERNAME /add

    Dove

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

    Esci e accedi nuovamente per rendere effettive le modifiche di appartenenza al gruppo. Se utilizzi una macchina virtuale, potresti dover riavviare il per rendere effettive le modifiche all'appartenenza.

Scelta di un metodo di autenticazione

Sono disponibili i seguenti metodi di autenticazione:

gcloud CLI credential helper
Configura le credenziali di Artifact Registry da utilizzare con Docker direttamente in gcloud CLI. Questo è il metodo di autenticazione più semplice, può essere più lento rispetto all'assistente autonomo delle credenziali.
Assistente per le credenziali Docker autonomo
Questa opzione è principalmente per configurare le credenziali da utilizzare con Docker in assenza di Google Cloud CLI. È molto più veloce dell'helper per le credenziali della CLI gcloud 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 utilizzare il token per l'autenticazione tramite password. Poiché il token è valido solo per 60 minuti, è un'opzione più sicura rispetto a una chiave dell'account di servizio.
Chiave account di servizio
Una coppia di chiavi gestita dall'utente che puoi utilizzare come credenziale per un l'account di servizio. Poiché la credenziale ha una lunga durata, è la meno sicura di tutti i metodi di autenticazione disponibili.

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

Impostazioni di autenticazione nel file di configurazione 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 distinte per i diversi metodi di autenticazione:

credHelpers
Se utilizzi l'assistente per le credenziali Docker per l'autenticazione Artifact Registry archivia le impostazioni dell'assistente per le credenziali credHelpers del file.
auths
Se usi Docker per accedere con un token o una chiave dell'account di servizio come per la password, Docker archivia una versione delle tue credenziali con codifica Base64 auths del file.
credStore
Se hai configurato un credential store per gestire le credenziali, le impostazioni dell'archivio credenziali sono nella sezione credStore del file.

Quando Docker si connette a un registro, verifica prima la presenza di un assistente per le credenziali associato all'host. Pertanto, se config.json include le impostazioni di Artifact Registry nelle sezioni credHelpers e auths; le impostazioni nella sezione auths vengono ignorate.

Assistente credenziali gcloud CLI

L'helper delle credenziali della gcloud CLI fornisce un accesso sicuro di breve durata le risorse del tuo progetto. Configura Docker per eseguire l'autenticazione Artifact Registry viene ospitato in qualsiasi ambiente in cui è installato Google Cloud CLI. Cloud Shell include Google Cloud CLI e una versione attuale di Docker.

L'helper delle credenziali della 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 strumento di assistenza per le credenziali dipende dalla CLI gcloud, può essere notevolmente più lento dello strumento di assistenza per le credenziali autonomo. Per le build automatizzate con strumenti di terze parti o client Docker con un numero elevato di registry configurati host, utilizza invece l'helper per le credenziali standalone.

Per eseguire l'autenticazione in Artifact Registry:

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

  2. Esegui questo comando:

    gcloud auth configure-docker HOSTNAME-LIST

    Dove HOSTNAME-LIST è un elenco di repository separato da virgole nomi host da aggiungere alla configurazione dell'assistente per le 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 visualizza la sezione credHelpers del tuo Docker corrente configurazione e la configurazione aggiornata dopo aver aggiunto e nomi host.

    Per accettare le modifiche alla configurazione, inserisci y.

    Le tue credenziali vengono salvate nella home directory dell'utente.

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

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

Assistente per le credenziali autonomo

L'helper delle credenziali Docker standalone configura Docker per l'autenticazione ad Artifact Registry su un sistema in cui gcloud CLI non è disponibile. È molto più veloce rispetto all'helper delle credenziali dell'interfaccia a riga di comando gcloud e usa le Credenziali predefinite dell'applicazione (ADC) per trovare automaticamente e credenziali nel tuo ambiente. Per operazioni diverse dal push e estrarre immagini, ad esempio taggandole o elencarle. Ti consigliamo di usare questa metodo di autenticazione per build automatizzate con strumenti di terze parti o Docker con un numero elevato di host del registro configurati.

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

Per utilizzare l'helper per le credenziali Docker:

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

  2. Scarica l'helper per le credenziali Docker standalone da GitHub.

    Facoltativamente, 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 Artifact Registry quando interagendo con Artifact Registry (devi eseguire solo questa operazione una volta):

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

    Dove HOSTNAME-LIST è un elenco di repository separato da virgole nomi host da aggiungere alla configurazione dell'assistente per le 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 località dei repository supportate, esegui il comando:

    gcloud artifacts locations list

    Consulta le documentazione di supporto per le credenziali Docker standalone su GitHub per maggiori informazioni.

    Le tue credenziali vengono salvate nella home directory dell'utente.

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

  4. Docker richiede che gli helper delle credenziali siano nel sistema PATH. Assicurati che il comando docker-credential-gcr si trova nel sistema PATH.

  5. Per verificare che l'aiutante delle credenziali possa recuperare correttamente il tuo credenziali, esegui questo 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 in il 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 eseguire il push e estrarre 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, dovresti richiederlo meno di un'ora prima di utilizzarlo per connetterti Artifact Registry.

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

  1. Crea un account di servizio per agire per conto della tua applicazione. o scegli un account di servizio esistente da usare 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 ed esegui l'autenticazione:

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

      Esegui questo comando, sostituendo ACCOUNT con il tuo indirizzo email dell'account di servizio e LOCATION una o più regioni posizione di nel 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 sarà in grado di per accedere alle risorse tramite l'account di servizio. Tieni presente che il ciclo di vita l'accesso della chiave all'account di servizio (e quindi ai dati di cui l'account di servizio all'accesso) è indipendente dal ciclo di vita dell'utente che ha scaricato chiave.

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

  • Crea account di servizio dedicati che vengono utilizzati solo per interagire con i repository.
  • Concedi lo specifico Ruolo Artifact Registry per l'accesso richiesto dall'account di servizio. Ad esempio, un account di servizio che scarica solo gli artefatti richiede solo Artifact Registry Reader ruolo.
  • Configura le autorizzazioni per i tuoi account di servizio dedicati non 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 potrebbero avere il ruolo Lettore Artifact Registry un repository di produzione e il ruolo Writer Artifact Registry per repository gestione temporanea.
  • 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 o scegli un account di servizio esistente che utilizzi per l'automazione.

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

    Vai alla pagina Account di servizio

  2. Facoltativamente, puoi eseguire la codifica in base64 di 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 NEW-FILE-NAME è il tuo file di chiave con codifica Base64.

  3. Verifica che le autorizzazioni siano configurate correttamente per l'account di servizio. Se utilizzi Compute Engine, devi configurare correttamente sia le autorizzazioni che di accesso agli 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 fornito al momento della creazione del file.
      • _json_key_base64 se hai codificato in base64 tutti i contenuti dei file .
    • KEY-FILE è il nome del file della chiave dell'account di servizio in JSON.
    • LOCATION è il una o più regioni località del repository in cui dell'immagine.

Docker è ora autenticato con Artifact Registry.