Create a Docker Hub remote repository

Create a Docker Hub remote repository

Create a remote repository to act as a proxy for Docker Hub.

Before you begin

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

   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

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Artifact Registry, Secret Manager APIs.

   Enable the APIs

5. Install the Google Cloud CLI.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

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

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

   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

8. Make sure that billing is enabled for your Google Cloud project.

9. Enable the Artifact Registry, Secret Manager APIs.

   Enable the APIs

10. Install the Google Cloud CLI.

11. To initialize the gcloud CLI, run the following command:

    gcloud init

    Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
12. Create a Docker Hub account.

Required roles

To get the permissions that you need to create a Docker Hub remote repository, ask your administrator to grant you the following IAM roles:

• To create remote repositories and grant access to individual repositories: Artifact Registry Administrator (roles/artifactregistry.admin) on the project
• To create and manage secrets: Secret Manager Admin role (roles/secretmanager.admin) on the project

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Choose a shell

To complete this quickstart, use either Cloud Shell or your local shell.

Cloud Shell

Cloud Shell is a shell environment for managing resources hosted on Google Cloud. It comes preinstalled with Docker and the Google Cloud CLI, the primary command-line interface for Google Cloud.

Local shell

If you prefer using your local shell, you must install Docker and gcloud CLI in your environment.

Starting Cloud Shell

To launch Cloud Shell, perform the following steps:

1. Go to Google Cloud console.

   Google Cloud console

2. Click the Activate Cloud Shell button: .

A Cloud Shell session opens inside a frame lower on the console. You use this shell to run gcloud commands.

Setting up a local shell

To install gcloud CLI and Docker, perform the following steps:

1. Install the gcloud CLI. To update an existing installation, run the command gcloud components update.

   Note: On Ubuntu, use the Debian package to install gcloud CLI. The gcloud CLI snap package does not include kubectl or extensions to authenticate with Artifact Registry using the gcloud CLI.

2. Install Docker if it is not already installed.

3. Docker requires privileged access to interact with registries. On Linux or Windows, add the user that you use to run Docker commands to the Docker security group. This step is not required on macOS since Docker Desktop runs on a virtual machine as the root user.

   Linux

   The Docker security group is called docker. To add your username, run the following command:

   sudo usermod -a -G docker ${USER}
   

   Windows

   The Docker security group is called docker-users. To add a user from the Administrator command prompt, run the following command:

   net localgroup docker-users DOMAIN\USERNAME /add
   

   Where

   • DOMAIN is your Windows domain.
   • USERNAME is your username.
   Note: The Docker security group has access equivalent to the root or Administrator user. Only add trusted users who require access to Docker. For details about security impacts, see Docker daemon security.

4. Log out and log back in for group membership changes to take effect. If you are using a virtual machine, you may need to restart the virtual machine for membership changes to take effect.

5. To ensure that Docker is running, run the following Docker command, which returns the current time and date:

   docker run --rm busybox date
   

   The --rm flag deletes the container instance on exit.

Configure Docker Hub authentication

To prevent using unauthenticated Docker Hub quota, we recommend authenticating to Docker Hub when using remote repositories. Remote repositories allow you to add your Docker Hub username and a personal access token saved as a secret to authenticate to Docker Hub.

Create a Docker Hub personal access token

1. Login to Docker Hub.
2. Create a personal access token with read-only permissions.

3. Copy the access token.

   Warning: The access token is only displayed once. If you close the window it can't be retrieved and you have to create a new access token.

4. Save the access token in a text file in your local or Cloud Shell.

   Warning: Treat access tokens like passwords and keep them secure.

Save your personal access token in a secret

console

1. Go to the Secret Manager page in the Google Cloud console.

   Go to the Secret Manager page

2. On the Secret Manager page, click Create Secret.

3. On the Create secret page, under Name, name your secret my-secret

4. In the Secret value field, enter your Docker Hub personal access token.

5. Leave the Regions section unchanged.

6. Click the Create secret button.

gcloud CLI

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

Where /path/to/file.txt is the location of the text file with your personal access token.

Grant the Artifact Registry service account access to your secret

console

1. Go to the Secret Manager page in the Google Cloud console.

   Go to the Secret Manager page

2. On the Secret Manager page, click the checkbox next to my-secret.

3. If it is not already open, click Show Info Panel to open the panel.

4. In the info panel, click Add Principal.

5. In the New principals text area, enter the email address of the Artifact Registry service account. The Artifact Registry service account email address is formatted in the following way

   [e-mail]

   Where PROJECT-NUMBER is your project number.

   To find your project number:

   • Go to the Dashboard page in the Google Cloud console.

     Go to the Dashboard page

   • Click the Select from drop-down list at the top of the page.

   • In the Select from window that appears, select your project.

     The project ID and project number are displayed on the project Dashboard Project info card.

6. In the Select a role dropdown, choose Secret Manager and then Secret Manager Secret Accessor.

gcloud CLI

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

Where PROJECT-NUMBER is the project number of your project.

To find your project number:

• Go to the Dashboard page in the Google Cloud console.

  Go to the Dashboard page

• Click the Select from drop-down list at the top of the page.

• In the Select from window that appears, select your project.

  The project ID and project number are displayed on the project Dashboard Project info card.

Create a remote repository

Create an Artifact Registry remote repository named quickstart-docker-hub-remote in location us-central1 with your Docker Hub credentials by running the following command:

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

Where:

• quickstart-docker-hub-remote is the name of the repository. For each repository location in a project, repository names must be unique.
• PROJECT_ID is your project ID. If this flag is omitted, the current or default project is used.
• us-central1 is the regional or multi-regional location for the repository. You can omit this flag if you set a default. To view a list of supported locations, run the command gcloud artifacts locations list.
• "Remote Docker repository" is the optional description of your repository. Do not include sensitive data, since repository descriptions are not encrypted.
• "Docker Hub" is the optional description for the external repository configuration for this remote repository.
• DOCKER-HUB sets the remote repository upstream to the public Docker Hub upstream.
• USERNAME is your Docker Hub username.
• projects/PROJECT/secrets/my-secret/versions/1 is the secret version you created to store your Docker Hub personal access token.

Artifact Registry creates the repository and adds it to the list of repositories.

Configure Docker authentication

Before you can push or pull images, configure Docker to use the Google Cloud CLI to authenticate requests to Artifact Registry.

1. Sign in to gcloud CLI as the user that will run Docker commands.

   gcloud auth login
   

2. To set up authentication to Docker repositories in the region us-central1, run the following command:

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

   The command updates your Docker configuration. You can now connect with Artifact Registry in your Google Cloud project to push and pull images.

For information about other authentication methods, see Authentication methods.

Pull an image into your remote repository

1. Sign in to gcloud CLI as the user that will run Docker commands.

   gcloud auth login
   

2. Pull an image from Docker Hub onto your machine, and into your remote repository with the following command:

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

   Where:

   • us-central1 is the remote repository location.
   • us-central1-docker.pkg.dev is the hostname for the Docker repository you created.
   • PROJECT is your Google Cloud project ID. If your project ID contains a colon (:), see Domain-scoped projects.
   • quickstart-docker-hub-remote is the ID of the repository you created.
   • busybox is the name of the image you want to pull from Docker Hub into quickstart-docker-hub-remote.
   • latest is the tagged image version you want to pull from Docker Hub.

   The image is pulled onto your machine and cached in the remote repository. If you pull the same tagged image again, it will be pulled from your remote repository. Your Docker Hub credentials are used.

3. List the artifacts stored in your remote repository:

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

   The output resembles the following:

   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
   

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.

Delete your repository

If you want to keep your project and only delete the repository resource, follow the steps in this section. If you want to delete your entire project, follow the steps in Delete your project

Before you remove the repository, ensure that any images you want to keep are available in another location.

To delete the repository:

Console

1. Open the Repositories page in the Google Cloud console.

   Open the Repositories page

2. In the repository list, select the quickstart-docker-hub-remote repository.

3. Click Delete.

gcloud

To delete the quickstart-docker-hub-remote repository, run the following command:

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

Delete your project

Caution: Deleting a project has the following effects:

• Everything in the project is deleted. If you used an existing project for the tasks in this document, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as an appspot.com URL, delete selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple architectures, tutorials, or quickstarts, reusing projects can help you avoid exceeding project quota limits.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

What's next

• Read about the different Artifact Registry repository modes.
• Learn more about Artifact Registry remote repositories.
• Learn more about CI/CD.