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 obtener los permisos que necesitas para enviar compilaciones, pídele a tu administrador que te otorgue los siguientes roles de IAM 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.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Ejecuta compilaciones

Puedes especificar la fuente de tu compilación con el campo Build source. El campo de 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: El Google Cloud ID de tu 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 aplicación, Dockerfile y cualquier otro elemento del directorio actual, como lo indica .;
  • inicia una compilación en la ubicación LOCATION con los archivos subidos como entrada;
  • etiqueta la imagen con el nombre proporcionado;
  • 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 proyecto de Google Cloud , 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. Para 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 que se 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 que se 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: El Google Cloud ID de tu 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 la fuente de compilación de un recurso de repositorio de 2ª gen., 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 Cloud Build de 2ª gen., 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, el comando anterior sube todos los archivos del directorio especificado a Google Cloudpara 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 genera un archivo .gcloudignore compatible con Git que respeta tus archivos .gitignore-ed. Para obtener más información, consulta la documentación de gcloudignore.

Si no tienes un código fuente para pasar a tu compilación, usa la marca --no-source, 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 Cloud Build de 2ª gen., 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: El Google Cloud ID de tu 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 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": {
                    "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?