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.

Nota: Cuando extraes una imagen de contenedor pública de Docker Hub para usarla en tu archivo de configuración de compilación, Cloud Build verifica de forma automática el proxy de almacenamiento en caché mirror.gcr.io en busca de una copia almacenada en caché de la imagen de contenedor. Si una copia almacenada en caché no está disponible, Cloud Build extrae la imagen solicitada de Docker Hub y el proxy de almacenamiento en caché puede almacenarla en caché para usarla en el futuro. Para obtener más información, consulta Extrae imágenes almacenadas en caché.

En el siguiente ejemplo, Cloud Build extrae la imagen de Docker para que maven ejecute el comando mvn, que se especifica 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.

A fin de otorgar la función de IAM de Administrador y descriptor de acceso a secretos para la cuenta de servicio de Cloud Build, sigue estos pasos:

1. Abre la página 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 cuadro de texto Nuevos principales, ingresa la dirección de correo electrónico de la cuenta de servicio de Cloud Build con el formato [e-mail], en el que PROJECT_NUMBER es el número del proyecto en el que ejecutas compilaciones. Puedes encontrar el número de proyecto en la página de configuración del proyecto.

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, especifícalo con la variable de entorno con el prefijo $$.

   En el siguiente archivo de configuración de compilación, se muestra cómo acceder a Docker con el nombre de usuario y la contraseña de Docker almacenados en Secret Manager y ejecutar una imagen privada.

   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"
        }]
     }
   }
   

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

   • PROJECT_ID: 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 desde el que extraes 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.

Envía imágenes a Docker Hub

Para enviar imágenes públicas y privadas a Docker Hub, haz lo siguiente:

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, especifícalo con la variable de entorno con el prefijo $$.

   En el siguiente archivo de configuración de compilación de ejemplo, se muestra cómo acceder a Docker, compilar una imagen con código fuente almacenado de forma local y, luego, enviarla al repositorio de Docker.

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

Trabaja con versiones cliente de Docker

gcr.io/cloud-builders/docker, el compilador de Docker compatible para 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 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?

• Obtén más información sobre cómo escribir un archivo de configuración de compilación básico.
• Obtén más información sobre cómo ejecutar las compilaciones de forma manual o automatizar las compilaciones mediante activadores de compilación.