Descripción general de la configuración de compilación

En esta página, se explica la estructura del archivo de configuración de compilación de Cloud Build.

Dockerfile y archivo de configuración de compilación

Si ejecutas compilaciones que no son Docker en Cloud Build con la herramienta de línea de comandos de gcloud o un activador de compilación, debes proporcionar un archivo de configuración de compilación. Un archivo de configuración de compilación contiene instrucciones para que Cloud Build realice tareas en función de tus especificaciones. Por ejemplo, tu archivo de configuración de compilación puede contener instrucciones para compilar, insertar y empaquetar imágenes de Docker.

Si ejecutas compilaciones de Docker con la herramienta de gcloud o activadores de compilaciones, puedes usar un Dockerfile o un archivo de configuración de compilación para compilar la imagen. Para obtener instrucciones sobre cómo crear una imagen de Docker con un Dockerfile, consulta Guías de inicio rápido con Docker.

Estructura de un archivo de configuración de compilación

Los archivos de configuración de compilación se modelan mediante el recurso Build de la API de Cloud Build.

Puedes escribir el archivo de configuración de compilación con la sintaxis de YAML o JSON. Si envías solicitudes de compilación mediante herramientas http de terceros como curl, usa la sintaxis de JSON. Debes crear el archivo de configuración de compilación en el directorio raíz de tu proyecto y Cloud Build lo leerá cada vez que inicie una compilación.

Un archivo de configuración de compilación tiene la siguiente estructura:

YAML

steps:
- name: string
  args: [string, string, ...]
  env: [string, string, ...]
  dir: string
  id: string
  waitFor: string
  entrypoint: string
  secretEnv: string
  volumes: object(Volume)
  timeout: string (Duration format)
- name: string
  ...
- name: string
  ...
timeout: string (Duration format)
logsBucket: string
options:
 sourceProvenanceHash: enum(HashType)
 machineType: enum(MachineType)
 diskSizeGb: string (int64 format)
 substitutionOption: enum(SubstitutionOption)
 logStreamingOption: enum(LogStreamingOption)
 logging: enum(LoggingMode)
substitutions: map (key: string, value: string)
tags: [string, string, ...]
secrets: object(Secret)
images:
- [string, string, ...]
artifacts: object (Artifacts)

JSON

{
    "steps": [
    {
        "name": "string",
        "args": [
        [
            "string",
            "string",
            "..."
        ]
        ],
        "env": [
        [
            "string",
            "string",
            "..."
        ]
        ],
        "dir": "string",
        "id": "string",
        "waitFor": "string",
        "entrypoint": "string",
        "secretEnv": "string",
        "volumes": "object(Volume)",
        "timeout": "string (Duration format)"
    },
    {
        "name": "string"
        ...
    },
    {
        "name": "string"
        ...
    }
    ],
    "timeout": "string (Duration format)",
    "logsBucket": "string",
    "options": {
        "sourceProvenanceHash": "enum(HashType)",
        "machineType": "enum(MachineType)",
        "diskSizeGb": "string (int64 format)",
        "substitutionOption": "enum(SubstitutionOption)",
        "logStreamingOption": "enum(LogStreamingOption)",
        "logging": "enum(LoggingMode)"
    },
    "substitutions": "map (key: string, value: string)",
    "tags": [
    [
        "string",
        "string",
        "..."
    ]
    ],
    "secrets": "object(Secret)",
    "images": [
    [
        "string",
        "string",
        "..."
    ]
    ],
    "artifacts": "object(Artifacts)"
}

En cada una de las secciones del archivo de configuración de compilación, se define una parte de la tarea que quieres que ejecute Cloud Build:

Pasos de la compilación

Un paso de compilación especifica una acción que deseas que realice Cloud Build. Para cada paso de compilación, Cloud Build ejecuta un contenedor de Docker como una instancia de docker run. Los pasos de la compilación son similares a los comandos en una secuencia de comandos y te proporcionan la flexibilidad de ejecutar instrucciones arbitrarias en tu compilación. Si puedes empaquetar una herramienta de compilación en un contenedor, Cloud Build puede ejecutarla como parte de tu compilación.

Puedes incluir uno o más pasos de la compilación en tu archivo de configuración.

Usa el campo steps en el archivo de configuración de compilación para especificar un paso de compilación. A continuación, se muestra un fragmento del tipo de configuración que puedes establecer en el campo steps:

YAML

steps:
- name: 'gcr.io/cloud-builders/git'
  args: ['clone', 'https://github.com/GoogleCloudPlatform/cloud-builders']
  env: ['PROJECT_ROOT=hello']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project-id/myimage', '.']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/git",
        "args": [
            "clone",
            "https://github.com/GoogleCloudPlatform/cloud-builders"
        ],
        "env": [
            "PROJECT_ROOT=hello"
        ]
    },
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/my-project-id/myimage",
            "."
        ]
    }
    ]
}

name

Usa el campo name de un paso de compilación para especificar un compilador en la nube, que es una imagen de contenedor que ejecuta herramientas comunes. Debes usar un compilador en un paso de compilación para ejecutar tus tareas.

En el siguiente fragmento, se muestran pasos de la compilación que llaman a los compiladores de bazel, gcloud, y docker:

YAML

steps:
- name: 'gcr.io/cloud-builders/bazel'
...

- name: 'gcr.io/cloud-builders/gcloud'
...

- name: 'gcr.io/cloud-builders/docker'
...

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/bazel"
        ...
    },
    {
        "name": "gcr.io/cloud-builders/gcloud"
        ...
    },
    {
        "name": "gcr.io/cloud-builders/docker"
        ...
    }
    ]
}

args

El campo args de un paso de compilación toma una lista de argumentos y los pasa al compilador al que hace referencia el campo name. Los argumentos que se pasan al compilador se pasan a la herramienta que se ejecuta en el compilador, lo que te permite invocar cualquier comando que admita la herramienta. Si el compilador usado en el paso de compilación tiene un punto de entrada, se usarán args como argumentos para ese punto de entrada. Si el compilador no define un punto de entrada, el primer elemento en args se usará como punto de entrada y el resto se usará como argumento.

En el siguiente fragmento, se invoca el comando docker build y se instalan dependencias de Maven:

YAML

steps:
- name: 'gcr.io/cloud-builders/mvn'
  args: ['install']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project-id/myimage', '.']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/mvn",
        "args": [
            "install"
        ]
    },
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/my-project-id/myimage",
            "."
        ]
    }
    ]
}

env

El campo env de un paso de compilación toma una lista de variables de entorno que se usarán cuando se ejecute el paso. Las variables están en formato KEY=VALUE.

En la siguiente configuración de compilación, el campo env del paso de compilación establece la zona de Compute Engine y el clúster de GKE antes de ejecutar kubectl:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
- name: 'gcr.io/cloud-builders/kubectl'
  args: ['set', 'image', 'deployment/myimage', 'frontend=gcr.io/myproject/myimage']
  env:
  - 'CLOUDSDK_COMPUTE_ZONE=us-east1-b'
  - 'CLOUDSDK_CONTAINER_CLUSTER=node-example-cluster'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    },
    {
        "name": "gcr.io/cloud-builders/kubectl",
        "args": [
            "set",
            "image",
            "deployment/myimage",
            "frontend=gcr.io/myproject/myimage"
        ],
        "env": [
            "CLOUDSDK_COMPUTE_ZONE=us-east1-b",
            "CLOUDSDK_CONTAINER_CLUSTER=node-example-cluster"
        ]
    }
    ]
}

dir

Usa el campo dir en un paso de compilación a fin de configurar un directorio de trabajo para usar cuando se ejecute el paso. De forma predeterminada, Cloud Build usa un directorio llamado /workspace como un directorio de trabajo. Si tu archivo de configuración tiene más de un paso de compilación, los recursos que produce un paso se pueden pasar al siguiente a través de la persistencia del directorio /workspace, que te permite configurar una canalización de pasos de la compilación que comparten recursos. Si configuras el campo dir en el paso de compilación, el directorio de trabajo se establece en /workspace/<dir>. Si este valor es una ruta relativa, es relativa al directorio de trabajo de la compilación. Si este valor es absoluto, puede estar fuera del directorio de trabajo de la compilación, en ese caso, el contenido de la ruta no puede persistir en las ejecuciones de los pasos de la compilación (a menos que se especifique un volumen para esa ruta).

En el siguiente fragmento, se establece el directorio de trabajo como examples/hello_world:

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
  env: ['PROJECT_ROOT=hello']
  dir: 'examples/hello_world'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ],
        "env": [
            "PROJECT_ROOT=hello"
        ],
        "dir": "examples/hello_world"
    }
    ]
}

timeout

Usa el campo timeout en un paso de compilación a fin de establecer un límite de tiempo para ejecutar el paso. Si no configuras este campo, el paso no tiene límite de tiempo y podrá ejecutarse hasta que se complete o hasta que el tiempo de espera de la compilación se agote. El timeout debe especificarse en segundos con hasta nueve dígitos decimales, que terminan con “s”. Ejemplo: “3.5s”.

En la siguiente configuración de compilación, el tiempo de espera del paso ubuntu se agota después de 500 segundos:

YAML

steps:
- name: 'ubuntu'
  args: ['sleep', '600']
  timeout: 500s
- name: 'ubuntu'
  args: ['echo', 'hello world, after 600s']

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "sleep",
            "600"
        ],
        "timeout": "500s"
    },
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "hello world, after 600s"
        ]
    }
    ]
}

id

Usa el campo id a fin de establecer un identificador único para un paso de compilación. id se usa con el campo waitFor a fin de configurar el orden en que deben ejecutarse los pasos de la compilación. Para obtener instrucciones sobre cómo usar id y waitFor, consulta Configura el orden de los pasos de la compilación.

waitFor

Usa el campo waitFor en un paso de compilación para especificar los pasos que se deben ejecutar antes de que se ejecute el paso de compilación. Si no se proporcionan valores para waitFor, el paso de compilación espera a que todos los pasos de la compilación anteriores en la solicitud de compilación se completen con éxito antes de ejecutarse. Para obtener instrucciones sobre cómo usar id y waitFor, consulta Configura el orden de los pasos de la compilación.

entrypoint

Usa el entrypoint en un paso de compilación para especificar un punto de entrada si no deseas usar el punto de entrada predeterminado del compilador. Si no configuras este campo, Cloud Build usará el punto de entrada del compilador. En el siguiente fragmento, se establecen los puntos de entrada para el paso de compilación npm:

YAML

steps:
- name: 'gcr.io/cloud-builders/npm'
  entrypoint: 'node'
  args: ['--version']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/npm",
        "entrypoint": "node",
        "args": [
            "--version"
        ]
    }
    ]
}

secretEnv

Una lista de variables de entorno que se encriptan con una clave criptográfica de Cloud KMS. Estos valores se deben especificar en los secretos de la compilación. Para obtener información sobre el uso de este campo, consulta Uso de la variable encriptada en las solicitudes de compilación.

volumes

Un Volumen es un contenedor de Docker que se activa en los pasos de la compilación para conservar archivos en los pasos de la compilación. Cuando Cloud Build ejecuta un paso de compilación, activa de manera automática un volumen de workspace en /workspace. Puedes especificar volúmenes adicionales a fin de que se activen en tus contenedores de los pasos de la compilación mediante el campo volumes para tus pasos.

Por ejemplo, el siguiente archivo de configuración de compilación escribe un archivo en un volumen en el primer paso y lo lee en el segundo paso. Si estos pasos no especificaron la ruta /persistent_volume como un volumen persistente, el primer paso escribirá el archivo en esa ruta, entonces ese archivo se descartará antes de que se ejecute el segundo paso. Cuando se especifica el volumen con el mismo nombre en ambos pasos, los contenidos de /persistent_volume en el primer paso se conservan en el segundo.

YAML

steps:
- name: 'ubuntu'
  volumes:
  - name: 'vol1'
    path: '/persistent_volume'
  entrypoint: 'bash'
  args:
  - '-c'
  - |
        echo "Hello, world!" > /persistent_volume/file
- name: 'ubuntu'
  volumes:
  - name: 'vol1'
    path: '/persistent_volume'
  args: ['cat', '/persistent_volume/file']

JSON

  {
    "steps": [
      {
        "name": "ubuntu",
        "volumes": [
          {
            "name": "vol1",
            "path": "/persistent_volume"
          }
        ],
        "entrypoint": "bash",
        "args": [
          "-c",
          "echo \"Hello, world!\" > /persistent_volume/file\n"
        ]
      },
      {
        "name": "ubuntu",
        "volumes": [
          {
            "name": "vol1",
            "path": "/persistent_volume"
          }
        ],
        "args": [
          "cat",
          "/persistent_volume/file"
        ]
     }
    ]
  }

timeout

Usa el campo timeout para que una compilación especifique la cantidad de tiempo en que se debe permitir que se ejecute, hasta el segundo nivel de detalle. Si transcurre este tiempo, cesará el trabajo en la compilación y el estado de la compilación será TIMEOUT. Si no se establece timeout, se aplicará un tiempo de espera predeterminado de 10 minutos a la compilación. El timeout se debe especificar en segundos con hasta nueve dígitos decimales, que termina con “s”. Ejemplo: “3.5s”.

En el siguiente fragmento, timeout se establece en 660 segundos para evitar que se agote el tiempo de espera de la compilación debido a la suspensión:

YAML

steps:
- name: 'ubuntu'
  args: ['sleep', '600']
timeout: 660s

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "sleep",
            "600"
        ]
    }
    ],
    "timeout": "660s"
}

logsBucket

Establece el campo logsBucket para que una compilación especifique un depósito de Cloud Storage en el que se deben escribir los registros. Si no configuras este campo, Cloud Build usará un depósito predeterminado para almacenar tus registros de compilación.

En el siguiente fragmento, se establece un depósito de registros para almacenar registros de compilación:

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
logsBucket: 'gs://mybucket'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ]
    }
    ],
    "logsBucket": "gs://mybucket"
}

options

Usa el campo options a fin de especificar los siguientes argumentos opcionales para tu compilación:

sourceProvenanceHash: configura la opción sourceProvenanceHash a fin de especificar el algoritmo hash para la fuente de origen. En el siguiente fragmento, se especifica que el algoritmo hash es SHA256:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
    sourceProvenanceHash: ['SHA256']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "sourceProvenanceHash": ["SHA256"]
    }
}

machineType: Cloud Build proporciona dos tipos de máquina virtual con capacidad de CPU alta para ejecutar tus compilaciones: 8 CPU y 32 CPU. El tipo de máquina predeterminado es de 1 CPU. La solicitud de una máquina virtual con capacidad de CPU alta puede aumentar el tiempo de inicio de tu compilación. Agrega la opción machineType para solicitar una máquina virtual con una capacidad de CPU más alta:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 machineType: 'N1_HIGHCPU_8'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    },
    ],
    "options": {
        "machineType": "N1_HIGHCPU_8"
    }
}

Para obtener más información sobre el uso de la opción machineType, consulta Acelera compilaciones.

diskSizeGb: usa la opción diskSizeGb a fin de solicitar un tamaño de disco personalizado para tu compilación. El tamaño máximo que puedes solicitar es de 1,000 GB.

En el siguiente fragmento, se solicita un tamaño de disco de 200 GB:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 diskSizeGb: 200

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "diskSizeGb": 200
    }
}

logStreamingOption: usa esta opción para especificar si deseas transmitir los registros de compilación a Cloud Storage. De forma predeterminada, Cloud Build recopila los registros de compilación cuando finaliza la compilación; esta opción especifica si deseas transmitir los registros de compilación en tiempo real a través del proceso de compilación. En el siguiente fragmento, se especifica que los registros de compilación se transmiten a Cloud Storage:

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
options:
 logStreamingOption: STREAM_ON

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ]
    }
    ],
    "options": {
        "logStreamingOption": "STREAM_ON"
    }
}

logging: usa esta opción para especificar si deseas almacenar registros en Stackdriver Logging o Cloud Storage. Si no configuras esta opción, Cloud Build almacena los registros en Stackdriver Logging y Cloud Storage. Puedes configurar la opción logging en GCS_ONLY para almacenar los registros solo en Cloud Storage. En el siguiente fragmento, se especifica que los registros se almacenan en Cloud Storage:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 logging: GCS_ONLY

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "logging": "GCS_ONLY"
    }
}

substitutionOption: configurarás esta opción junto con el campo substitutions que se encuentra a continuación, para especificar el comportamiento cuando hay un error en las verificaciones de sustitución.

substitutions

Usa sustituciones en tu archivo de configuración de compilación para sustituir variables específicas en el momento de la compilación. Las sustituciones son útiles para las variables cuyo valor no se conoce hasta el momento de la compilación o si quieres volver a usar una solicitud de compilación existente con diferentes valores de variable. De forma predeterminada, la compilación muestra un error si falta una sustitución o una variable de sustitución. Sin embargo, puedes usar la opción ALLOW_LOOSE para omitir esta verificación.

En el siguiente fragmento, se usan sustituciones para imprimir “hello world”. La opción de sustitución ALLOW_LOOSE está establecida, lo que significa que la compilación no mostrará un error si falta una sustitución o una variable de sustitución.

YAML

steps:
- name: 'ubuntu'
  args: ['echo', 'hello ${_SUB_VALUE}']
substitutions:
    _SUB_VALUE: world
options:
    substitution_option: 'ALLOW_LOOSE'

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "hello ${_SUB_VALUE}"
        ]
    }
    ],
    "substitutions": {
        "_SUB_VALUE": "world"
},
    "options": {
        "substitution_option": "ALLOW_LOOSE"
    }
}

Para obtener instrucciones adicionales sobre el uso de substitutions, consulta Sustitución de valores de variables.

tags

Usa el campo tags para organizar tus compilaciones en grupos y filtrarlas. La siguiente configuración establece dos etiquetas llamadas mytag1 y mytag2:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  ...
- name: 'ubuntu'
  ...
tags: ['mytag1', 'mytag2']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker"
    },
    {
        "name": "ubuntu"
    }
    ],
    "tags": [
        "mytag1",
        "mytag2"
    ]
}

secretos

Secreto empareja un conjunto de variables de entorno secretas que contienen valores encriptados con la clave de Cloud KMS que se puede usar para desencriptar el valor. Usa el campo secrets a fin de definir secretos para desencriptar mediante Cloud KMS. Si quieres ver un ejemplo de cómo usar este campo, consulta Usa secretos y credenciales encriptados.

images

El campo images en el archivo de configuración de compilación especifica una o más imágenes de Docker para que Cloud Build envíe a Container Registry. Es posible que tengas una compilación que realice tareas sin producir ninguna imagen de Docker, pero si compilas imágenes y no las envías a Container Registry, las imágenes se descartan cuando finaliza la compilación. Si durante la compilación no se produce una imagen especificada, la compilación fallará. Para obtener más información sobre el almacenamiento de imágenes, consulta Almacenamiento de imágenes y artefactos.

La siguiente configuración de compilación establece el campo images para almacenar la imagen de compilación:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
images: ['gcr.io/myproject/myimage']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "images": [
        "gcr.io/myproject/myimage"
    ]
}

artifacts

El campo artifacts en el archivo de configuración de compilación especifica uno o más artefactos no contenedores para almacenar en Cloud Storage. Para obtener más información sobre el almacenamiento de artefactos no contenedores, consulta Almacena imágenes y artefactos.

La siguiente configuración de compilación establece el campo artifacts para que almacene el paquete compilado de Go en gs://mybucket/:

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['build', 'my-package']
artifacts:
  objects:
    location: 'gs://mybucket/'
    paths: ['my-package']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "build",
            "my-package"
        ]
    }
    ],
    "artifacts": {
      "objects": {
        "location": "gs://mybucket/",
        "paths": [
            "my-package"
        ]
      }
    }
}

Pasos siguientes

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...