Interactúa con imágenes de Docker Hub

Puedes usar imágenes de contenedor desde Docker Hub para ejecutar tus tareas en Cloud Build. Además, si la compilación genera imágenes, puedes enviarlas a Docker Hub. En esta página, se describe cómo escribir archivos de configuración de compilación para enviar y extraer imágenes de Docker Hub. Para obtener una descripción general de todos los campos disponibles en un archivo de configuración de compilación, consulta Descripción general de la configuración de compilación.

Extrae imágenes públicas de Docker Hub

Si especificas el nombre de la imagen en el campo name, puedes extraer imágenes oficiales de Docker, imágenes certificadas por Docker y, también, imágenes personalizadas almacenadas en Docker Hub en tu paso de compilación. Cloud Build primero extraerá la imagen especificada de Docker Hub y, luego, la usará para ejecutar el paso de compilación.

En el siguiente ejemplo, Cloud Build extrae la imagen de Docker para que maven ejecute el comando mvn especificado en args:

YAML 

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

JSON 

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

Almacena credenciales de Docker en Secret Manager

Para extraer imágenes privadas y enviar imágenes públicas y privadas a Docker Hub, Cloud Build deberá autenticarse en Docker con tus credenciales. Si deseas incluir credenciales de Docker en tus compilaciones, primero debes almacenarlas en Administrador de secretos y, luego, otorgar permiso para que Cloud Build acceda al secreto desde Secret Manager.

Para almacenar credenciales de Docker en Secret Manager, haz lo siguiente:

  1. Ve a la página de Secret Manager en la consola de Google Cloud:

    Ir a la página Secret Manager

  2. En la página de Secret Manager, haz clic en Crear secreto.

  3. En la página Crear secreto, en Nombre, ingresa docker-username.

  4. En el campo Valor del secreto, ingresa tu nombre de usuario de Docker.

  5. Deja la sección Regiones sin modificar.

  6. Haz clic en el botón Crear secreto.

Repite los pasos anteriores para almacenar tu contraseña de Docker en Secret Manager.

Para otorgar la función de IAM de Descriptor de acceso a secretos de Secret Manager del secreto a la cuenta de servicio que usas para la compilación, haz lo siguiente:

  1. Abre la página de Secret Manager en la consola de Google Cloud:

    Ir a la página Secret Manager

  2. Selecciona la casilla de verificación del secreto que corresponde a tu nombre de usuario y contraseña de Docker.

  3. Si aún no está abierto, haz clic en Mostrar panel de información para abrir el panel.

  4. En el panel, en Permisos, haz clic en Agregar principal.

  5. En el campo Principales nuevas, ingresa la dirección de correo electrónico de tu cuenta de servicio.

  6. En el cuadro desplegable Selecciona una función, selecciona la función Administrador y descriptor de acceso a secretos.

  7. Haz clic en Guardar.

Extrae imágenes privadas de Docker Hub

Para obtener imágenes privadas de Docker Hub, sigue estos pasos:

  1. Asegúrate de haber almacenado tus credenciales de Docker en Secret Manager y de haber otorgado permisos para que Cloud Build acceda al secreto.

  2. En el archivo de configuración de compilación:

    • Después de toda la steps de compilación, agrega un campo availableSecrets que especifique la versión del secreto y la variable de entorno para el nombre de usuario y la contraseña de Docker.
    • En el paso de compilación en el que deseas especificar el nombre de usuario y la contraseña, haz lo siguiente:
      • Agrega un campo entrypoint que apunte a bash para usar la herramienta bash en el paso de compilación. Esto es necesario para hacer referencia a la variable de entorno del secreto.
      • Agrega un campo secretEnv que especifique la variable de entorno para el nombre de usuario y la contraseña.
      • En el campo args, agrega una marca -c como primer argumento. Cualquier string que pases después de -c se trata como un comando. Si deseas obtener más información para ejecutar comandos bash con -c, consulta la documentación de bash.
      • Cuando especifiques el secreto en el campo args, hazlo mediante la variable de entorno con el prefijo $$.

    The following build config file shows how to login to Docker using the Docker username and password stored in Secret Manager, and run a private image.

    YAML 

     steps:
 - name: 'gcr.io/cloud-builders/docker'
   entrypoint: 'bash'
   args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
   secretEnv: ['USERNAME', 'PASSWORD']
 - name: "gcr.io/cloud-builders/docker"
   entrypoint: 'bash'
   args: ['-c', 'docker run $$USERNAME/REPOSITORY:TAG']
   secretEnv: ['USERNAME']
 availableSecrets:
   secretManager:
   - versionName: projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION
     env: 'PASSWORD'
   - versionName: projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION
     env: 'USERNAME'
.

     JSON 
    {
  "steps": [
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker login --username=$$USERNAME --password=$$PASSWORD"
    ],
    "secretEnv": [
      "USERNAME",
      "PASSWORD"
    ]
  },
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker run $$USERNAME/REPOSITORY:TAG"
     ],
     "secretEnv": [
      "USERNAME"
    ]
  }
  ],
  "availableSecrets": {
    "secretManager": [{
      "versionName": "projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION",
      "env": "PASSWORD"
  }, {
    "versionName": "projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION",
    "env": "USERNAME"
     }]
  }
}

    Replace the placeholder values in the above commands with the following:

    • PROJECT_ID: The ID of the Google Cloud project where you've stored your secrets.
    • DOCKER_USERNAME_SECRET_NAME: The secret name corresponding to your Docker username.
    • DOCKER_USERNAME_SECRET_VERSION: The secret version of your Docker username.
    • DOCKER_PASSWORD_SECRET_NAME: The secret name corresponding to your Docker password.
    • DOCKER_PASSWORD_SECRET_VERSION: The secret version of your Docker password.
    • REPOSITORY: The name of your Docker repository from where you're pulling the image.
    • TAG: The tag name of your image.

  3. Use the build config file to manually start a build or to automate builds using triggers.

Pushing images to Docker Hub

To push public and private images to Docker Hub:

  1. Make sure you've stored your Docker credentials in Secret Manager and granted permissions for Cloud Build to access the secret.

  2. In the build config file:

    • After all the build steps, add an availableSecrets field specifying the secret version and the env variable for the Docker username and password.
    • In the build step where you want to specify the username and password:
      • Add an entrypoint field pointing to bash to use the bash tool in the build step. This is required to refer to the environment variable for the secret.
      • Add a secretEnv field specifying the environment variable for username and password.
      • In the args field, add a -c flag as the first argument. Any string you pass after -c is treated as a command. For more information on running bash commands with -c, see the bash documentation.
      • When specifying the secret in the args field, specify it using the environment variable prefixed with $$.

    The following example build config file shows how to login to Docker, build an image with source code stored locally, and then push the image to Docker repository.

    YAML 

     steps:
 - name: 'gcr.io/cloud-builders/docker'
   entrypoint: 'bash'
   args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
   secretEnv: ['USERNAME', 'PASSWORD']
 - name: 'gcr.io/cloud-builders/docker'
   entrypoint: 'bash'
   args: ['-c', 'docker build -t $$USERNAME/REPOSITORY:TAG .']
   secretEnv: ['USERNAME']
 - name: 'gcr.io/cloud-builders/docker'
   entrypoint: 'bash'
   args: ['-c', 'docker push $$USERNAME/REPOSITORY:TAG']
   secretEnv: ['USERNAME']
 availableSecrets:
   secretManager:
   - versionName: projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION
     env: 'PASSWORD'
   - versionName: projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION
     env: 'USERNAME'

    JSON 

    {
  "steps": [
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker login --username=$$USERNAME --password=$$PASSWORD"
    ],
    "secretEnv": [
      "USERNAME",
      "PASSWORD"
    ]
  },
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker build -t $$USERNAME/REPOSITORY:TAG ."
     ],
     "secretEnv": [
      "USERNAME"
    ]
  },
  {
    "name": "gcr.io/cloud-builders/docker",
    "entrypoint": "bash",
    "args": [
      "-c",
      "docker push $$USERNAME/REPOSITORY:TAG"
     ],
     "secretEnv": [
      "USERNAME"
    ]
  }
  ],
  "availableSecrets": {
    "secretManager": [{
      "versionName": "projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION",
      "env": "PASSWORD"
  }, {
    "versionName": "projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION",
    "env": "USERNAME"
     }]
  }
}

    Reemplaza los valores de marcador de posición en los comandos anteriores por la siguiente información:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud en el que almacenaste tus secretos.
    • DOCKER_USERNAME_SECRET_NAME: Es el nombre secreto correspondiente a tu nombre de usuario de Docker.
    • DOCKER_USERNAME_SECRET_VERSION: Es la versión del secreto de tu nombre de usuario de Docker.
    • DOCKER_PASSWORD_SECRET_NAME: Es el nombre del secreto correspondiente a tu contraseña de Docker.
    • DOCKER_PASSWORD_SECRET_VERSION: Es la versión del secreto de tu contraseña de Docker.
    • REPOSITORY: Es el nombre de tu repositorio de Docker al que envías la imagen.
    • TAG: Es el nombre de la etiqueta de la imagen.

  3. Usa el archivo de configuración de compilación para iniciar una compilación de forma manual o automatizar compilaciones mediante activadores.

Cómo trabajar con versiones cliente de Docker

gcr.io/cloud-builders/docker, el compilador de Docker compatible con Cloud Build, usa Docker 20.10.14. Con esta versión, si no especificas una etiqueta cuando envías una imagen a Docker, Docker envía solo la imagen con la etiqueta latest. Si la etiqueta latest no existe, el envío falla.

Para enviar una imagen con una etiqueta específica a Docker, especifica la etiqueta en el paso de compilación docker push. En el siguiente ejemplo, se envía una imagen con la etiqueta prod:

YAML 

steps:
...
- name: 'gcr.io/cloud-builders/docker'
  args: ['docker', 'push', '$$USERNAME/myrepo:prod']
...

JSON 

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker",
    "args": [
      "docker",
      "push", 
      "$$USERNAME/myrepo:prod"
      ],
  }
  ...
}

Para enviar todas las etiquetas de una imagen a Docker, agrega la marca -a a la lista de argumentos en el paso de compilación docker push:

YAML 

steps:
...
- name: 'gcr.io/cloud-builders/docker'
  args: ['docker', 'push', '-a', '$$USERNAME/myrepo']
...

JSON 

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker",
    "args": [
      "docker",
      "push",
      "-a",
      "$$USERNAME/myrepo"
      ],
  }
  ...
}

Puedes usar el cliente de Docker 19.03.9 si etiquetas la versión en el compilador de Docker:

YAML 

steps:
...
- name: 'gcr.io/cloud-builders/docker:19.03.9'
  args: ['docker', 'push', '$$USERNAME/myrepo:prod']
...

JSON 

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker:19.03.9",
    "args": [
      "docker",
      "push",
      "$$USERNAME/myrepo:prod"
      ],
  }
  ...
}

¿Qué sigue?