Enviar una compilación mediante la CLI y la API

En esta página se describe cómo iniciar una compilación en Cloud Build manualmente mediante la CLI de Google Cloud y la API Cloud Build.

Antes de empezar

Permisos de gestión de identidades y accesos necesarios

Para obtener los permisos que necesitas para enviar compilaciones, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu cuenta de servicio:

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Ejecutar compilaciones

Puede especificar el origen de su compilación mediante el campo Origen de compilación. El campo "Origen de la compilación" es uno de los siguientes: storage_source, repo_source, git_source y connected_repository.

Enviar compilaciones con storage_source

gcloud

Usar un Dockerfile:

Tu Dockerfile contiene toda la información necesaria para crear una imagen de Docker con Cloud Build.

Para compilar con un Dockerfile, ejecuta el siguiente comando desde el directorio que contiene el código fuente y el Dockerfile:

gcloud builds submit --tag LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME

Donde:

  • LOCATION: la ubicación regional o multirregional de tu repositorio Docker en Artifact Registry.
  • PROJECT_ID: tu ID de proyecto Google Cloud .
  • REPOSITORY: el nombre de tu repositorio de Artifact Registry.
  • IMAGE_NAME: el nombre de la imagen de contenedor que se va a compilar.

El nombre completo de la imagen que se va a compilar es LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME. Las imágenes insertadas en Artifact Registry usan la convención de nomenclatura de Artifact Registry.

El comando gcloud builds submit:

  • comprime el código de tu aplicación, Dockerfile, y cualquier otro recurso del directorio actual, tal como se indica en ..
  • inicia una compilación en la ubicación LOCATION usando los archivos subidos como entrada.
  • etiqueta la imagen con el nombre proporcionado.
  • Envía la imagen creada a Artifact Registry.

A medida que avanza la compilación, su resultado se muestra en la ventana de shell o terminal. Cuando se haya completado la compilación, debería ver un resultado similar al siguiente:

    DONE
    ---------------------------------------------------------------------------------
    ID                                    CREATE_TIME                DURATION STATUS
    $BUILD_ID                             2023-10-28T15:21:18+00:00  12S      SUCCESS

donde $BUILD_ID es el identificador único de tu compilación.

Usar el archivo de configuración de compilación de Cloud Build:

Para enviar una compilación con la configuración de compilación, ejecuta el siguiente comando:

    gcloud builds submit --config BUILD_CONFIG SOURCE

Donde:

  • BUILD_CONFIG es la ruta al archivo de configuración de compilación.
  • SOURCE es la ruta o el código fuente de la URL.

Cuando ejecutas gcloud builds submit por primera vez en un proyecto Google Cloud , Cloud Build crea un segmento de Cloud Storage llamado [YOUR_PROJECT_NAME]_cloudbuild en ese proyecto. Cloud Build usa este segmento para almacenar el código fuente que puedas usar en tus compilaciones. Cloud Build no elimina automáticamente el contenido de este segmento. Para eliminar los objetos que ya no uses en las compilaciones, puedes configurar el ciclo de vida del bucket o eliminar los objetos manualmente.

El siguiente comando muestra cómo enviar una solicitud de compilación cloudbuild.yaml con código fuente almacenado en un segmento de Cloud Storage.

    gcloud builds submit --config cloudbuild.yaml \
        gs://BUCKET/SOURCE.tar.gz

Donde:

  • BUCKET es el nombre del segmento de Cloud Storage que contiene el código fuente que quieres compilar.
  • SOURCE es el nombre del archivo de código fuente comprimido.

Puedes usar . para especificar que el código fuente se encuentra en el directorio de trabajo actual:

    gcloud builds submit --config=cloudbuild.yaml .

API

Para enviar la solicitud de compilación mediante curl, sigue estos pasos:

  1. Crea un archivo llamado request.json con el siguiente contenido:

    {
    "source": {
        "storageSource": {
            "bucket": "BUCKET",
            "object": "SOURCE.tar.gz"
        }
    },
    "steps": [{
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
            "."
        ]
    }],
    "images": [
        "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"
    ]
}

    Donde:

    • BUCKET es el nombre del segmento de Cloud Storage que contiene el código fuente que quieres compilar.
    • SOURCE es el nombre del archivo de código fuente comprimido.
    • IMAGE_NAME es el nombre de la imagen que se va a compilar.
    • LOCATION: la ubicación regional o multirregional de tu repositorio Docker en Artifact Registry.
    • PROJECT_ID: tu ID de proyecto Google Cloud .
    • REPOSITORY: el nombre de tu repositorio de Docker en Artifact Registry.

    En esta solicitud de compilación, Cloud Build llama al docker paso de compilación con los argumentos build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY ..

    El nombre completo de la imagen que se va a compilar es LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY.

    Las imágenes insertadas en Artifact Registry usan la convención de nomenclatura de Artifact Registry.

  2. Ejecuta el siguiente comando, donde PROJECT_ID es el ID de tu proyecto y REGION es una de las regiones admitidas:Google Cloud 

    curl -X POST -T request.json -H "Authorization: Bearer $(gcloud config config-helper \
    --format='value(credential.access_token)')" \
    https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/builds

    En este comando, curl envía request.json en una llamada POST al endpoint builds del método de API projects.builds.create.

    El comando muestra detalles sobre tu compilación en la ventana de shell o de terminal. La salida es una respuesta JSON similar a la siguiente:

        {
        "name": "operations/build/$PROJECT-ID/NmZhZW...",
        "metadata": {
            "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata",
            "build": {
                "id": $BUILD-ID,
                "status": "QUEUED",
                "source": {
                    "storageSource": {
                        "bucket": "BUCKET",
                        "object": "SOURCE.tar.gz"
                    }
                },
                "createTime": "2017-05-12T18:58:07.341526Z",
                "steps": [
                {
                    "name": "gcr.io/cloud-builders/docker",
                    "args": [
                        "build",
                        "-t",
                        "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
                        "."
                    ]
                }
                ],
                "timeout": "600s",
                "images": [
                    "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"
                ],
                "projectId": $PROJECT-ID,
                "logsBucket": "gs://...",
                "sourceProvenance": {
                    "resolvedStorageSource": {
                        "bucket": "BUCKET",
                        "object": "SOURCE.tar.gz"
                        "generation": "..."
                    }
                },
                "logUrl": "https://console.cloud.google.com/cloud-build/builds/...?project=$PROJECT_ID"
            }
        }
    }

    La respuesta JSON se modela mediante el recurso Operation de la API Cloud Build. El campo metadata se modela con el recurso Build. El estado QUEUED indica que la compilación está pendiente de ejecución.

Enviar compilaciones con connected_repository

gcloud

Para ejecutar una solicitud de compilación con una fuente de compilación de un recurso de repositorio de segunda generación, ejecuta el siguiente comando:

gcloud builds submit REPOSITORY --revision=REVISION --config=BUILD_CONFIG LOCATION

Donde:

  • LOCATION es la ubicación regional o multirregional de tu repositorio de Docker en Artifact Registry.
  • REPOSITORY es el nombre del repositorio de segunda generación de Cloud Build, con el formato projects/*/locations/*/connections/*repositories/*.
  • REVISION es la revisión que se va a obtener del repositorio de Git, como una rama, una etiqueta, un SHA de confirmación o cualquier referencia de Git.
  • BUILD_CONFIG es la ruta al archivo de configuración de compilación.

A medida que avanza la compilación, su resultado se muestra en la ventana de shell o terminal. Cuando se haya completado la compilación, debería ver un resultado similar al siguiente:

    DONE
    ---------------------------------------------------------------------------------
    ID                                    CREATE_TIME                DURATION STATUS
    $BUILD_ID                             2023-10-28T15:21:18+00:00  12S      SUCCESS

donde $BUILD_ID es el identificador único de tu compilación.

gcloudignore al incluir el código fuente para la compilación, el comando anterior sube todos los archivos del directorio especificado a Google Cloudpara compilar. Si quieres excluir determinados archivos del directorio, puedes incluir un archivo llamado .gcloudignore en el directorio de subida de nivel superior. Los archivos que especifique se ignorarán. Si .gcloudignore no está presente en el directorio de subida de nivel superior, pero sí lo está el archivo .gitignore, la CLI de gcloud genera un archivo .gcloudignore compatible con Git que respeta los archivos .gitignore. Para obtener más información, consulta la documentación de gcloudignore.

Si no tienes código fuente para incluir en tu compilación, usa la marca --no-source donde BUILD_CONFIG es la ruta al archivo de configuración de la compilación:

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY

API

Para enviar la solicitud de compilación mediante curl, sigue estos pasos:

  1. Crea un archivo llamado request.json con el siguiente contenido:

    {
    "source": {
        "connectedRepository": {
            "repository": "REPOSITORY",
            "revision": "REVISION"
        }
    },
    "steps": [{
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
            "."
        ]
    }],
    "images": [
        "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"
    ]
}

    Donde:

    • REPOSITORY es el nombre del repositorio de segunda generación de Cloud Build, con el formato projects/*/locations/*/connections/*repositories/*.
    • REVISION es la revisión que se va a obtener del repositorio de Git, como una rama, una etiqueta, un SHA de confirmación o cualquier referencia de Git.
    • IMAGE_NAME es el nombre de la imagen que se va a compilar.
    • LOCATION: la ubicación regional o multirregional de tu repositorio Docker en Artifact Registry.
    • PROJECT_ID: tu ID de proyecto Google Cloud .

    En esta solicitud de compilación, Cloud Build llama al docker paso de compilación con los argumentos build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME ..

    El nombre completo de la imagen que se va a compilar es LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME. Las imágenes insertadas en Artifact Registry usan la convención de nomenclatura de Artifact Registry.

  2. Ejecuta el siguiente comando, donde PROJECT_ID es el ID de tu proyecto Google Cloud y REGION es una de las regiones admitidas:

    curl -X POST -T request.json -H "Authorization: Bearer $(gcloud config config-helper \
    --format='value(credential.access_token)')" \
    https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/builds

    En este comando, curl envía request.json en una llamada POST al endpoint builds del método de API projects.builds.create.

    El comando muestra detalles sobre tu compilación en la ventana de shell o de terminal. La salida es una respuesta JSON similar a la siguiente:

        {
        "name": "operations/build/$PROJECT-ID/NmZhZW...",
        "metadata": {
            "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata",
            "build": {
                "id": $BUILD-ID,
                "status": "QUEUED",
                "source": {
                    "connectedRepository": {
                        "repository": "REPOSITORY",
                        "revision": "REVISION"
                    }
                },
                "createTime": "2017-05-12T18:58:07.341526Z",
                "steps": [
                {
                    "name": "gcr.io/cloud-builders/docker",
                    "args": [
                        "build",
                        "-t",
                        "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
                        "."
                    ]
                }
                ],
                "timeout": "600s",
                "images": [
                    "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"
                ],
                "projectId": PROJECT_ID,
                "logsBucket": "gs://...",
                "sourceProvenance": {
                    "resolvedConnectedRepository": {
                        "repository": "REPOSITORY",
                        "revision": "REVISION.tar.gz"
                        "generation": "..."
                    }
                },
                "logUrl": "https://console.cloud.google.com/cloud-build/builds/...?project=PROJECT_ID"
            }
        }
    }

    La respuesta JSON se modela mediante el recurso Operation de la API Cloud Build. El campo metadata se modela con el recurso Build. El estado QUEUED indica que la compilación está pendiente de ejecución.

Siguientes pasos