Questa pagina descrive come configurare Docker per l'autenticazione nei repository Artifact Registry Docker.
Non è necessario configurare l'autenticazione per gli ambienti di runtime Cloud Build o Google Cloud, come Google Kubernetes Engine e Cloud Run, ma devi verificare che siano configurate le autorizzazioni richieste.
Prima di iniziare
-
Installa Google Cloud CLI, quindi initialize eseguendo questo comando:
gcloud init
- (Facoltativo) Configura i valori predefiniti per la gcloud CLI;interfaccia a riga di comando gcloud.
- Verifica che l'account che utilizzi per l'autenticazione disponga delle autorizzazioni per accedere ad Artifact Registry. Ti consigliamo di utilizzare un account di servizio anziché un account utente.
- Installa Docker, se non è già installato. Docker è incluso in Cloud Shell.
Docker richiede un accesso privilegiato per interagire con i registry. Su Linux o Windows, aggiungi l'utente che utilizzi per eseguire i comandi Docker al gruppo di sicurezza Docker. Questo passaggio non è obbligatorio su macOS, poiché Docker Desktop viene eseguito su una macchina virtuale come utente root.
Linux
Il gruppo di sicurezza Docker è denominato
docker
. Per aggiungere il nome utente, esegui questo comando:sudo usermod -a -G docker ${USER}
Windows
Il gruppo di sicurezza Docker è denominato
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 di nuovo per applicare le modifiche all'appartenenza al gruppo. Se utilizzi una macchina virtuale, potrebbe essere necessario riavviare la macchina virtuale per applicare le modifiche all'abbonamento.
Scelta di un metodo di autenticazione
Sono disponibili i seguenti metodi di autenticazione:
- Assistente per le credenziali gcloud CLI;interfaccia a riga di comando gcloud
- Configura le credenziali Artifact Registry per l'utilizzo con Docker direttamente in gcloud CLI. Questo è il metodo di autenticazione più semplice, ma può essere più lento rispetto all'helper delle credenziali autonomo.
- Assistente per le credenziali Docker autonomo
- Questa opzione serve 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 quindi 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 account di servizio. Poiché la credenziale è di lunga durata, è l'opzione meno sicura tra tutti i metodi di autenticazione disponibili.
Se possibile, utilizza un token di accesso o un assistente per le credenziali per ridurre il rischio di accessi non autorizzati alle 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 Docker
Docker salva le impostazioni di autenticazione nel file di configurazione config.json.
- Linux:
~/.docker/config.json
- Windows:
%USERPROFILE%\.docker\config.json
Nel file sono presenti sezioni separate per i diversi metodi di autenticazione:
credHelpers
- Se usi l'helper per le credenziali Docker per l'autenticazione, Artifact Registry archivia 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 archivia una versione con codifica Base64 delle tue credenziali nella sezione
auths
del file. credStore
- Se hai configurato un archivio credenziali per gestire le tue credenziali, le impostazioni dell'archivio credenziali si trovano nella sezione
credStore
del file.
Quando Docker si connette a un registro, controlla prima se è presente un helper delle credenziali associato all'host. Pertanto, se config.json
include le impostazioni di Artifact Registry in entrambe le sezioni credHelpers
e auths
, le impostazioni nella sezione auths
vengono ignorate.
Assistente per le credenziali gcloud CLI
L'helper per le credenziali gcloud CLI fornisce un accesso sicuro e di breve durata alle risorse del tuo progetto. Configura Docker per l'autenticazione negli host Artifact Registry in qualsiasi ambiente in cui è installata Google Cloud CLI. Cloud Shell include Google Cloud CLI e una versione corrente di Docker.
L'helper per le 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 per le credenziali dipende da gcloud CLI, può essere molto più lento rispetto all'helper per le credenziali autonomo. Per le build automatizzate con strumenti di terze parti o client Docker con un numero elevato di host del registro configurati, utilizza invece l'helper autonomo per le credenziali.
Per eseguire l'autenticazione in Artifact Registry:
Accedi a gcloud CLI come utente che eseguirà i comandi Docker.
Per configurare l'autenticazione con credenziali utente, esegui questo 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 account di servizio nella pagina Account di servizio della console Google Cloud o con il comandogcloud iam service-accounts list
. - KEY-FILE è il file delle chiavi dell'account di servizio. Per informazioni sulla creazione di una chiave, consulta la documentazione di Identity and Access Management (IAM).
- ACCOUNT è l'account di servizio che vuoi utilizzare con
Artifact Registry nel formato
Esegui questo comando:
gcloud auth configure-docker HOSTNAME-LIST
Dove HOSTNAME-LIST è un elenco separato da virgole di nomi host del repository da aggiungere alla configurazione dell'helper per le credenziali.
Ad esempio, per aggiungere le regioni
us-central1
easia-northeast1
, esegui il comando:gcloud auth configure-docker us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
I nomi host specificati vengono aggiunti alla configurazione dell'helper per le credenziali. Puoi aggiungere altri nomi host alla configurazione in un secondo momento eseguendo di nuovo il comando.
Per visualizzare un elenco delle località di repository supportate, esegui il comando:
gcloud artifacts locations list
Il comando visualizza la sezione
credHelpers
della configurazione Docker attuale 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
- Linux:
Docker richiede che gli helper delle credenziali siano presenti nel sistema
PATH
. Assicurati che il comandogcloud
sia nel sistemaPATH
.
Assistente per le credenziali autonomo
L'helper autonomo delle credenziali Docker configura Docker per l'autenticazione in Artifact Registry su un sistema in cui gcloud CLI non è disponibile. È 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. Per operazioni diverse dal push e dal pull delle immagini, come il tagging o l'elenco delle 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 registro configurati.
L'helper delle credenziali Docker autonomo recupera le tue credenziali Artifact Registry e le scrive nel file di configurazione Docker. In questo modo, puoi utilizzare lo strumento a riga di comando di Docker, docker
, per interagire direttamente con
Artifact Registry.
Per utilizzare l'helper delle credenziali Docker:
Accedi alla macchina come utente che eseguirà i comandi Docker.
Scarica l'helper autonomo per le credenziali Docker da GitHub.
In via facoltativa, puoi utilizzare l'utilità a riga di comando
curl
. Ad esempio:VERSION=2.1.22 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/
Configura Docker in modo che utilizzi le tue credenziali Artifact Registry durante l'interazione con Artifact Registry (devi farlo solo una volta):
docker-credential-gcr configure-docker --registries=HOSTNAME-LIST
Dove HOSTNAME-LIST è un elenco separato da virgole di nomi host del repository da aggiungere alla configurazione dell'helper per le credenziali.
Ad esempio, per aggiungere le regioni
us-central1
easia-northeast1
, esegui il comando:docker-credential-gcr configure-docker --registries=us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
I nomi host specificati vengono aggiunti alla configurazione dell'helper per le credenziali. Puoi aggiungere altri nomi host alla configurazione in un secondo momento eseguendo di nuovo il comando.
Per visualizzare un elenco delle località di repository supportate, esegui il comando:
gcloud artifacts locations list
Per ulteriori informazioni, consulta la documentazione dell'helper per le credenziali Docker autonoma su GitHub.
Le credenziali vengono salvate nella home directory dell'utente.
- Linux:
$HOME/.docker/config.json
- Windows:
%USERPROFILE%/.docker/config.json
- Linux:
Docker richiede che gli helper delle credenziali siano presenti nel sistema
PATH
. Assicurati che il comandodocker-credential-gcr
sia nel sistemaPATH
.Per verificare che l'helper delle credenziali possa recuperare correttamente le tue 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-central1-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-central1-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 il pull delle immagini, assicurati che le autorizzazioni siano configurate correttamente.
Token di accesso
Puoi generare un token di accesso OAuth di breve durata per eseguire l'autenticazione con Artifact Registry. Poiché il token è valido per 60 minuti, devi richiederlo meno di un'ora prima di utilizzarlo per connetterti ad Artifact Registry.
Per utilizzare un token di accesso con le credenziali dell'account di servizio:
Crea un account di servizio che agisca per conto della tua applicazione oppure scegli un account di servizio esistente che utilizzi per l'automazione.
Concedi il ruolo Artifact Registry specifico all'account di servizio per fornire l'accesso al repository.
Genera un token di accesso per l'account di servizio e autentica:
Devi disporre delle autorizzazioni nel ruolo Creatore token account di servizio (
roles/iam.serviceAccountTokenCreator
) per impersonare un account di servizio, ottenere un token per l'account e poi autenticarti come account di servizio.Esegui il comando seguente, sostituendo ACCOUNT con l'indirizzo email del tuo account di servizio e con LOCATION la località a livello di una o più regioni 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.
Segui queste linee guida per limitare l'accesso ai repository:
- Creare 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 artefatti richiede solo il ruolo Lettore Artifact Registry.
- Configura le autorizzazioni per i tuoi account di servizio dedicati su ciascun 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 Artifact Registry per un repository di produzione e il ruolo Writer Artifact Registry per un 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:
Crea un account di servizio che agisca per conto della tua applicazione oppure scegli un account di servizio esistente che utilizzi per l'automazione.
Avrai bisogno della posizione del file della chiave dell'account di servizio per configurare l'autenticazione con Artifact Registry. Per gli account esistenti, puoi visualizzare le chiavi e crearne di nuove nella pagina Account di servizio.
Facoltativamente, puoi eseguire la codifica 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 e NEW-FILE-NAME è il file della chiave con codifica Base64.
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.
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 fornita al momento della creazione del file._json_key_base64
se hai codificato tutti i contenuti del file con codifica Base64.
- KEY-FILE è il nome del file della chiave dell'account di servizio in formato JSON.
- LOCATION è la località a livello di una o più regioni del repository in cui è archiviata l'immagine.
- KEY-TYPE è uno dei seguenti:
Docker è ora autenticato con Artifact Registry.