Envía una compilación con la CLI y la API

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

Antes de comenzar

Permisos de IAM obligatorios

Para asegurarte de que `gcloud` tenga los permisos necesarios para enviar compilaciones, pídele a tu administrador que otorgue las siguientes funciones de IAM a `gcloud` en tu cuenta de servicio:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Es posible que tu administrador también pueda otorgar los permisos necesarios a través de funciones personalizadas o de otras funciones predefinidas .

Ejecuta compilaciones

Puedes especificar el origen de tu compilación con el campo Origen de compilación. El campo Origen de compilación es uno de los siguientes: storage_source, repo_source, git_source y connected_repository.

Envía compilaciones con storage_source

gcloud

Usa un Dockerfile:

Tu Dockerfile contiene toda la información necesaria para compilar una imagen de Docker mediante 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

Aquí:

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

El nombre completo de la imagen que se compilará es LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME. En las imágenes enviadas a Artifact Registry, se usa la convención de nombres de Artifact Registry.

Con el comando gcloud builds submit, se realiza lo siguiente:

  • Se comprime tu código de la aplicación, Dockerfile y cualquier otro elemento del directorio actual, como lo indica ..
  • Se inicia una compilación en la ubicación LOCATION con los archivos subidos como entrada.
  • Se etiqueta la imagen mediante el nombre provisto;
  • Se envía la imagen compilada a Artifact Registry.

A medida que la compilación avanza, su resultado se muestra en tu shell o ventana de terminal. Cuando se completa la compilación, debes ver un resultado similar al siguiente:

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

En el ejemplo anterior, $BUILD_ID es el identificador único de la compilación.

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

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

    gcloud builds submit --config BUILD_CONFIG SOURCE

Aquí:

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

Cuando ejecutas gcloud builds submit por primera vez en un Google Cloud proyecto, Cloud Build crea un bucket de Cloud Storage llamado [YOUR_PROJECT_NAME]_cloudbuild en ese proyecto. Cloud Build usa este bucket para almacenar cualquier código fuente que puedas usar en tus compilaciones. Cloud Build no borra automáticamente el contenido de este bucket. A fin de borrar los objetos que ya no utilizas para las compilaciones, puedes establecer la configuración del ciclo de vida en el bucket o borrar los objetos de forma manual.

En el siguiente comando, se muestra cómo enviar una solicitud de compilación cloudbuild.yaml con el código fuente almacenado en un bucket de Cloud Storage.

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

Aquí:

  • BUCKET es el nombre de tu bucket en Cloud Storage que contiene el código fuente para compilar.
  • SOURCE es el nombre de tu 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, haz lo siguiente:

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

    Aquí:

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

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

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

    En las imágenes enviadas a Artifact Registry, se usa la convención de nombres de Artifact Registry.

  2. Ejecuta el siguiente comando, en el que PROJECT_ID es el ID de tu Google Cloud proyecto 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 extremo builds para el método de la API projects.builds.create.

    El comando muestra detalles sobre tu compilación en tu shell o ventana de terminal. El resultado es una respuesta JSON con un aspecto similar al 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 en la API de Cloud Build. El campo metadata se modela mediante el recurso Build. El estado QUEUED indica que la compilación se encuentra a la espera de la ejecución.

Envía 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

Aquí:

  • 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 recuperará del repositorio de Git, como una rama, una etiqueta, un SHA de confirmación o cualquier referencia de Git.
  • BUILD_CONFIG es la ruta de acceso al archivo de configuración de compilación.

A medida que la compilación avanza, su resultado se muestra en tu shell o ventana de terminal. Cuando se completa la compilación, debes ver un resultado similar al siguiente:

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

En el ejemplo anterior, $BUILD_ID es el identificador único de la compilación.

gcloudignore: Cuando se incluye el código fuente para la compilación, con el comando anterior se suben todos los archivos del directorio especificado a Google Cloud para compilar. Si deseas excluir ciertos archivos del directorio, puedes incluir un archivo con el nombre .gcloudignore en el directorio de carga de nivel superior. Los archivos que este especifique se ignorarán. Si .gcloudignore no está presente en el directorio de carga de nivel superior, pero sí un archivo .gitignore, gcloud CLI generará un archivo .gcloudignore compatible con Git que respeta tus archivos .gitignore. Para obtener más información, consulta la gcloudignore documentación.

Si no tienes el código fuente para pasar a tu compilación, usa la --no-source marca, en la que BUILD_CONFIG es la ruta de acceso al archivo de configuración de compilación:

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY

API

Para enviar la solicitud de compilación mediante curl, haz lo siguiente:

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

    Aquí:

    • 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 recuperará 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 compilará.
    • LOCATION: Es la ubicación regional o multirregional de tu repositorio de Docker en Artifact Registry.
    • PROJECT_ID: Es el ID del Google Cloud proyecto.

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

    El nombre completo de la imagen que se compilará es LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME. En las imágenes enviadas a Artifact Registry, se usa la convención de nombres de Artifact Registry.

  2. Ejecuta el siguiente comando, en el que PROJECT_ID es el Google Cloud ID del proyecto 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 extremo builds para el método de la API projects.builds.create.

    El comando muestra detalles sobre tu compilación en tu shell o ventana de terminal. El resultado es una respuesta JSON con un aspecto similar al 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 en la API de Cloud Build. El campo metadata se modela mediante el recurso Build. El estado QUEUED indica que la compilación se encuentra a la espera de la ejecución.

¿Qué sigue?