Interacting with Docker Hub images

You can use container images from Docker Hub to execute your tasks in Cloud Build. Additionally, if your build produces images, you can push them to Docker Hub. This page describes how to write build config files to push and pull Docker Hub images. For an overview of all the fields available in a build config file, see Build Configuration Overview.

Pulling public images from Docker Hub

You can pull official Docker images, Docker-certified images, and custom images stored in Docker Hub in your build step by specifying the name of the image in the name field. Cloud Build will first pull the specified image from Docker Hub and then use the image to run the build step.

In the example below, Cloud Build pulls the Docker image for maven to run the mvn command specified in args:

YAML

steps:
- name: "maven"
  args: ["mvn", "--version"]

JSON

{
   "steps": [
      {
         "name": "maven",
         "args": [
            "mvn",
            "--version"
         ]
      }
   ]
}

Authenticating your Docker Hub account

To pull private images and to push public and private images, you will need to authenticate your Cloud Build account with your Docker Hub credentials. You can do this in one of the following ways:

Out of the three methods described above, encrypting your credentials using CryptoKeys is the most secure way to store your credentials without embedding them in source. Cloud Build integrates with CryptoKeys, which allow you to manage access to and rotation of encryption keys.

To encrypt your Docker Hub credentials using CryptoKey:

  1. Create a Cloud KMS KeyRing and CryptoKey, if you do not already have one.

  2. Grant the Cloud Build service account access to the CryptoKey.

  3. Encrypt your password to a base64-encoded string by running the following command:

     echo -n [PASSWORD] | gcloud kms encrypt \
       --plaintext-file=- \  # - reads from stdin
       --ciphertext-file=- \  # - writes to stdout
       --location=global \
       --keyring=[KEYRING-NAME] \
       --key=[KEY-NAME] | base64
    

    Where:

    • [PASSWORD] is your Docker Hub password.
    • [KEYRING-NAME] is the name of your key ring.
    • [KEY-NAME] is the name of your key.

    You will see a base-64-encoded string as your encrypted password, which you will later use to authenticate your Docker Hub account.

Pulling private images from Docker Hub

To pull private images from Docker Hub:

  1. Encrypt your Docker Hub credentials
  2. In your build config file:

    • Provide credentials for Docker Hub by passing in [PASSWORD] as an encrypted variable to the secretEnv field to authenticate your Docker Hub account.
    • Specify the name of the Docker builder in the name field.
    • Specify the arguments to pull and run the image in the args field.
    • Provide a secrets field containing your KMS name values and the encrypted value for your password.

    See a sample build config file below:

    YAML

    steps:
    - name: "gcr.io/cloud-builders/docker"
    entrypoint: "bash"
    args: ["-c", "docker login --username=[DOCKER_USER_ID] --password=$$PASSWORD"]
    secretEnv: ["PASSWORD"]
    - name: "gcr.io/cloud-builders/docker"
    args: ["run", "[DOCKER_USER_ID]/[IMAGE]:[TAG]"]
    secrets:
    - kmsKeyName: "projects/[PROJECT_ID]/locations/global/keyRings/[KEYRING-NAME]/cryptoKeys/[KEY-NAME]"
    secretEnv:
      PASSWORD: "[base64-encoded encrypted Dockerhub password]"
    

    JSON

    {
     "steps": [
        {
           "name": "gcr.io/cloud-builders/docker",
           "entrypoint": "bash",
           "args": [
              "-c",
              "docker login --username=[DOCKER_USER_ID] --password=$$PASSWORD"
           ],
           "secretEnv": [
              "PASSWORD"
           ]
        },
        {
           "name": "gcr.io/cloud-builders/docker",
           "args": [
              "run",
              "[DOCKER_USER_ID]/[IMAGE]:[TAG]"
            ]
        }
     ],
     "secrets": [
        {
           "kmsKeyName": "projects/[PROJECT_ID]/locations/global/keyRings/[KEYRING-NAME]/cryptoKeys/[KEY-NAME]",
           "secretEnv": {
              "PASSWORD": "[base64-encoded encrypted Dockerhub password]"
           }
        }
     ]
    }
    

    Where:

    • [DOCKER_USER_ID] is your Docker Hub username.
    • [IMAGE] is the name of the image you want to pull from Docker Hub.
    • [TAG] is the name of the tag associated with the image you would like to pull, if it exists.
    • [PROJECT_ID] is your project ID.
    • [KEYRING-NAME] is the name of your key ring.
    • [KEY-NAME] is the name of your key.
    • [base64-encoded encrypted Dockerhub password] is your encrypted password as a base-64 encoded string.
  3. To submit a build to pull an image from Docker Hub, you can either start a build manually or create a trigger to automate your build.

Pushing images to Docker Hub

To push public and private images to Docker Hub:

  1. Encrypt your Docker Hub credentials
  2. In your build config file:

    • Provide credentials for Docker Hub by passing in [PASSWORD] as an encrypted variable to the secretEnv field to authenticate your Docker Hub account.
    • Specify the name of the Docker builder in the name field.
    • Specify the arguments to build the image in the args field.
    • Specify the name of the image you want to push in the images field.
    • Provide a secrets field containing your KMS name values and the encrypted value for your password.

    See a sample build config file below:

    YAML

    steps:
    - name: "gcr.io/cloud-builders/docker"
    entrypoint: "bash"
    args: ["-c", "docker login --username=[DOCKER_USER_ID] --password=$$PASSWORD"]
    secretEnv: ["PASSWORD"]
    - name: "gcr.io/cloud-builders/docker"
    args: ["build", "-t", "[DOCKER_USER_ID]/[IMAGE]:[TAG]", "."]
    images: "[DOCKER_USER_ID]/[IMAGE]:[TAG]"
    secrets:
    - kmsKeyName: "projects/[PROJECT_ID]/locations/global/keyRings/[KEYRING-NAME]/cryptoKeys/[KEY-NAME]"
    secretEnv:
      PASSWORD: "[base64-encoded encrypted Dockerhub password]"
    

    JSON

    {
     "steps": [
        {
           "name": "gcr.io/cloud-builders/docker",
           "entrypoint": "bash",
           "args": [
              "-c",
              "docker login --username=[DOCKER_USER_ID] --password=$$PASSWORD"
           ],
           "secretEnv": [
              "PASSWORD"
           ]
        },
        {
           "name": "gcr.io/cloud-builders/docker",
           "args": [
              "build",
              "-t",
              "[DOCKER_USER_ID]/[IMAGE]:[TAG]",
              "."
           ]
        }
     ],
     "images": "[DOCKER_USER_ID]/[IMAGE]:[TAG]",
     "secrets": [
        {
           "kmsKeyName": "projects/[PROJECT_ID]/locations/global/keyRings/[KEYRING-NAME]/cryptoKeys/[KEY-NAME]",
           "secretEnv": {
              "PASSWORD": "[base64-encoded encrypted Dockerhub password]"
           }
        }
     ]
    }
    

    Where:

    • [DOCKER_USER_ID] is your Docker Hub username.
    • [IMAGE] is the name of the image you want to push from Docker Hub.
    • [TAG] is the name of the tag associated with the image you would like to push, if it exists.
    • [PROJECT_ID] is your project ID.
    • [KEYRING-NAME] is the name of your key ring.
    • [KEY-NAME] is the name of your key.
    • [base64-encoded encrypted Dockerhub password] is your encrypted password as a base-64 encoded string.
  3. Define the image you are pushing by including Dockerfile in your workspace.

    See below for an example of a Dockerfile that invokes \bin\bash:

    FROM gcr.io/cloud-builders/gcloud
    ENTRYPOINT ["/bin/bash"]
    
  4. To submit a build to pull an image from Docker Hub, you can either start a build manually or create a trigger to automate your build.

What's next

Was deze pagina nuttig? Laat ons weten hoe goed we u hebben geholpen:

Feedback verzenden over...

Cloud Build Documentation