Crea un repository remoto Docker Hub

Crea un repository remoto Docker Hub

I repository remoti di Artifact Registry consentono di eseguire il proxy e memorizzare nella cache le immagini container da Docker Hub per ridurre la latenza di download ed evitare limiti di velocità non autenticati. In questa guida rapida, configurerai le credenziali di Docker Hub in Secret Manager, creerai un repository remoto ed eseguirai il pull di un'immagine di esempio.

Prima di iniziare

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry, Secret Manager APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry, Secret Manager APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

1. Crea un account Docker Hub.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare un repository remoto Docker Hub, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Per creare repository remoti e concedere l'accesso a singoli repository: Amministratore Artifact Registry (roles/artifactregistry.admin) sul progetto
• Per creare e gestire i secret: Ruolo Amministratore Secret Manager (roles/secretmanager.admin) nel progetto

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Scegliere una shell

Per completare questa guida rapida, utilizza Cloud Shell o la shell locale.

Cloud Shell

Cloud Shell è un ambiente shell per la gestione delle risorse ospitate su Google Cloud. È preinstallato con Docker e Google Cloud CLI, l'interfaccia a riga di comando principale per Google Cloud.

Shell locale

Se preferisci utilizzare la shell locale, devi installare Docker e gcloud CLI nel tuo ambiente.

Avviare Cloud Shell

Per avviare Cloud Shell, segui questi passaggi:

1. Vai alla console Google Cloud .

   Google Cloud console

2. Fai clic sul pulsante Attiva Cloud Shell: .

Una sessione di Cloud Shell si apre in un frame nella parte inferiore della console. Utilizza questa shell per eseguire i comandi gcloud.

Configurazione di una shell locale

Per installare gcloud CLI e Docker, segui questi passaggi:

1. Installa gcloud CLI. Per aggiornare un'installazione esistente, esegui il comando gcloud components update.

   Nota: su Ubuntu, utilizza il pacchetto Debian per installare gcloud CLI. Il pacchetto snap gcloud CLI non include kubectl o estensioni per l'autenticazione con Artifact Registry utilizzando gcloud CLI.

2. Installa Docker se non è già installato.

3. 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 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 di amministratore, esegui questo comando:

   net localgroup docker-users DOMAIN\USERNAME /add
   

   Dove

   • DOMAIN è il tuo dominio Windows.
   • USERNAME è il tuo nome utente.
   Nota :il gruppo di sicurezza Docker ha un accesso equivalente all'utente root o amministratore. Aggiungi solo utenti attendibili che richiedono l'accesso a Docker. Per informazioni dettagliate sull'impatto della sicurezza, vedi Sicurezza dei daemon Docker.

4. Disconnettiti e accedi di nuovo affinché le modifiche all'iscrizione al gruppo abbiano effetto. Se utilizzi una macchina virtuale, potrebbe essere necessario riavviare la macchina virtuale affinché le modifiche all'appartenenza abbiano effetto.

5. Per assicurarti che Docker sia in esecuzione, esegui questo comando Docker, che restituisce la data e l'ora correnti:

   docker run --rm busybox date
   

   Il flag --rm elimina l'istanza del container all'uscita.

Configura l'autenticazione di Docker Hub

Per impedire l'utilizzo della quota Docker Hub non autenticata, ti consigliamo di eseguire l'autenticazione in Docker Hub quando utilizzi repository remoti. I repository remoti ti consentono di aggiungere il tuo nome utente Docker Hub e un token di accesso personale salvato come secret per l'autenticazione in Docker Hub.

Crea un token di accesso personale Docker Hub

1. Accedi a Docker Hub.
2. Crea un token di accesso personale con autorizzazioni di sola lettura.

3. Copia il token di accesso.

   Avviso: il token di accesso viene visualizzato una sola volta. Se chiudi la finestra, non può essere recuperato e devi creare un nuovo token di accesso.

4. Salva il token di accesso in un file di testo in locale o in Cloud Shell.

   Avviso: tratta i token di accesso come password e mantienili al sicuro.

Salva il token di accesso personale in un secret

console

1. Vai alla pagina Secret Manager nella console Google Cloud .

   Vai alla pagina Secret Manager

2. Nella pagina Secret Manager, fai clic su Crea secret.

3. Nella pagina Crea secret, in Nome, assegna al secret il nome my-secret.

4. Nel campo Valore secret, inserisci il token di accesso personale di Docker Hub.

5. Lascia invariata la sezione Regioni.

6. Fai clic sul pulsante Crea secret.

gcloud CLI

gcloud secrets create my-secret --data-file="/path/to/file.txt"

dove /path/to/file.txt è la posizione del file di testo con il tuo token di accesso personale.

Concedi al account di servizio Artifact Registry l'accesso al tuo secret

console

1. Vai alla pagina Secret Manager nella console Google Cloud .

   Vai alla pagina Secret Manager

2. Nella pagina Secret Manager, fai clic sulla casella di controllo accanto a my-secret.

3. Se non è già aperto, fai clic su Mostra riquadro informazioni per aprire il riquadro.

4. Nel riquadro informazioni, fai clic su Aggiungi entità.

5. Nell'area di testo Nuove entità, inserisci l'indirizzo email del account di servizio Artifact Registry. L'indirizzo email del account di servizio Artifact Registry è formattato nel seguente modo

   [e-mail]

   Dove PROJECT-NUMBER è il numero di progetto.

   Per trovare il numero di progetto:

   • Vai alla pagina Dashboard nella console Google Cloud .

     Vai alla pagina Dashboard

   • Fai clic sull'elenco a discesa Seleziona da nella parte superiore della pagina.

   • Nella finestra Seleziona da visualizzata, seleziona il tuo progetto.

     L'ID progetto e il numero del progetto vengono visualizzati nella scheda Informazioni sul progetto della dashboard.

6. Nel menu a discesa Seleziona un ruolo, scegli Secret Manager e poi Secret Manager Secret Accessor.

gcloud CLI

gcloud secrets add-iam-policy-binding my-secret \
    --member="serviceAccount:[e-mail]" \
    --role="roles/secretmanager.secretAccessor"

Dove PROJECT-NUMBER è il numero di progetto del tuo progetto.

Per trovare il numero di progetto:

• Vai alla pagina Dashboard nella console Google Cloud .

  Vai alla pagina Dashboard

• Fai clic sull'elenco a discesa Seleziona da nella parte superiore della pagina.

• Nella finestra Seleziona da visualizzata, seleziona il tuo progetto.

  L'ID progetto e il numero del progetto vengono visualizzati nella scheda Informazioni sul progetto della dashboard.

Crea un repository remoto

Crea un repository remoto Artifact Registry denominato quickstart-docker-hub-remote nella località us-central1 con le tue credenziali Docker Hub eseguendo il seguente comando:

gcloud artifacts repositories create quickstart-docker-hub-remote \
    --project=PROJECT_ID \
    --repository-format=DOCKER  \
    --location=us-central1 \
    --description="Remote Docker repository" \
    --mode=remote-repository \
    --remote-repo-config-desc="Docker Hub" \
    --remote-docker-repo=DOCKER-HUB \
    --remote-username=USERNAME \
    --remote-password-secret-version=projects/PROJECT/secrets/my-secret/versions/1

Dove:

• quickstart-docker-hub-remote è il nome del repository. Per ogni posizione del repository in un progetto, i nomi dei repository devono essere univoci.
• PROJECT_ID è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.
• us-central1 è la posizione regionale o multiregionale del repository. Puoi omettere questo flag se imposti un valore predefinito. Per visualizzare un elenco delle località supportate, esegui il comando gcloud artifacts locations list.
• "Remote Docker repository" è la descrizione facoltativa del repository. Non includere dati sensibili, poiché le descrizioni dei repository non sono crittografate.
• "Docker Hub" è la descrizione facoltativa per la configurazione del repository esterno per questo repository remoto.
• DOCKER-HUB imposta il repository remoto a monte sul repository Docker Hub pubblico.
• USERNAME è il tuo nome utente Docker Hub.
• projects/PROJECT/secrets/my-secret/versions/1 è la versione del secret che hai creato per archiviare il token di accesso personale di Docker Hub.

Artifact Registry crea il repository e lo aggiunge all'elenco dei repository.

Configura l'autenticazione Docker

Prima di eseguire il push o il pull delle immagini, configura Docker in modo che utilizzi Google Cloud CLI per autenticare le richieste ad Artifact Registry.

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

   gcloud auth login
   

2. Per configurare l'autenticazione nei repository Docker della regione us-central1, esegui questo comando:

   gcloud auth configure-docker us-central1-docker.pkg.dev
   

   Il comando aggiorna la configurazione Docker. Ora puoi connetterti con Artifact Registry nel tuo progetto Google Cloud per eseguire il push e il pull delle immagini.

Per informazioni su altri metodi di autenticazione, vedi Metodi di autenticazione.

Eseguire il pull di un'immagine nel repository remoto

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

   gcloud auth login
   

2. Esegui il pull di un'immagine da Docker Hub sulla tua macchina e nel tuo repository remoto con questo comando:

   docker pull us-central1-docker.pkg.dev/PROJECT/quickstart-docker-hub-remote/busybox:latest
   

   Dove:

   • us-central1 è la posizione del repository remoto.
   • us-central1-docker.pkg.dev è il nome host del repository Docker che hai creato.
   • PROJECT è il tuo Google Cloud ID progetto. Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.
   • quickstart-docker-hub-remote è l'ID del repository che hai creato.
   • busybox è il nome dell'immagine di cui vuoi fare il pull da Docker Hub in quickstart-docker-hub-remote.
   • latest è la versione dell'immagine con tag di cui vuoi fare il pull da Docker Hub.

   L'immagine viene estratta sulla tua macchina e memorizzata nella cache nel repository remoto. Se esegui di nuovo il pull della stessa immagine con tag, questa verrà estratta dal repository remoto. Vengono utilizzate le tue credenziali Docker Hub.

3. Elenca gli artefatti archiviati nel repository remoto:

   gcloud artifacts packages list \
       --location=us-central1 \
       --repository=quickstart-docker-hub-remote
   

   L'output è simile al seguente:

   Listing items under project my-project, location us-central1, repository quickstart-docker-hub-remote.
   
   PACKAGE: busybox
   CREATE_TIME: 2023-06-19T18:59:09
   UPDATE_TIME: 2023-06-19T18:59:10
   

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questa pagina, segui questi passaggi.

Eliminare il repository

Se vuoi conservare il progetto ed eliminare solo la risorsa repository, segui i passaggi descritti in questa sezione. Se vuoi eliminare l'intero progetto, segui i passaggi descritti in Eliminare il progetto.

Prima di rimuovere il repository, assicurati che tutte le immagini che vuoi conservare siano disponibili in un'altra posizione.

Per eliminare il repository:

Console

1. Apri la pagina Repository nella console Google Cloud .

   Apri la pagina Repositori

2. Nell'elenco dei repository, seleziona il repository quickstart-docker-hub-remote.

3. Fai clic su Elimina.

gcloud

Per eliminare il repository quickstart-docker-hub-remote, esegui questo comando:

gcloud artifacts repositories delete quickstart-docker-hub-remote \
    --location=us-central1

Elimina il progetto

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per, le attività descritte in questo documento, eliminerai anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

1. Nella console Google Cloud , vai alla pagina Gestisci risorse.

   Vai a Gestisci risorse

2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
3. Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.

Passaggi successivi

• Scopri di più sulle diverse modalità del repository di Artifact Registry.
• Scopri di più sui repository remoti di Artifact Registry.
• Scopri di più su CI/CD.