Create a Docker Hub remote repository

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

Before you begin

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Artifact Registry, Secret Manager APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  4. Install the Google Cloud CLI.

  5. Configure the gcloud CLI to use your federated identity.

    For more information, see Sign in to the gcloud CLI with your federated identity.

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

    gcloud init
  7. 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:

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 Cloud de Confiance by S3NS. It comes preinstalled with Docker and the Google Cloud CLI, the primary command-line interface for Cloud de Confiance.
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 Cloud de Confiance console.

    Cloud de Confiance 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.

  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.

  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.

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

Save your personal access token in a secret

console

  1. Go to the Secret Manager page in the Cloud de Confiance 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 Cloud de Confiance 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

    service-PROJECT-NUMBER@gcp-sa-artifactregistry.s3ns-system.iam.gserviceaccount.com

    Where PROJECT-NUMBER is your project number.

    To find your project number:

    • Go to the Dashboard page in the Cloud de Confiance 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:service-PROJECT-NUMBER@gcp-sa-artifactregistry.s3ns-system.iam.gserviceaccount.com" \
    --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 Cloud de Confiance 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 Cloud de Confiance 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 Cloud de Confiance by S3NS 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 Cloud de Confiance 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 Cloud de Confiance 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

  1. In the Cloud de Confiance 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