Envía una compilación a través de 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

  • Si deseas usar los ejemplos de la línea de comandos de esta guía, instala Google Cloud CLI.
  • Si quieres usar la configuración de compilación de Cloud Build, crea un archivo de configuración de compilación.
  • Para compilar mediante un Dockerfile, ten listo tu Dockerfile.
  • Si tu compilación requiere código fuente, ten listo tu código fuente.

Permisos de IAM obligatorios

Si deseas obtener instrucciones para otorgar funciones de IAM, consulta Configura el acceso a los recursos de Cloud Build.

Ejecuta compilaciones

Puedes especificar el origen de la compilación en el campo Fuente de la compilación. El campo de fuente 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 ejecutar una solicitud de compilación mediante tu Dockerfile, ejecuta el siguiente comando desde el directorio que contiene Dockerfile, tu código de la aplicación y cualquier otro elemento:

gcloud builds submit --region=us-west2 --tag gcr.io/PROJECT_ID/IMAGE_NAME .

Aquí:

  • PROJECT_ID es el nombre del proyecto de Google Cloud.
  • IMAGE_NAME es la imagen que se compilará.
  • . especifica que el código fuente se encuentra en el directorio de trabajo actual.

El nombre completo de la imagen que se compilará es gcr.ioPROJECT_ID/IMAGE_NAME. En las imágenes enviadas a Container Registry, se usa el formato de nombre de registro.

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 .;
  • sube los archivos a un bucket de Cloud Storage;
  • inicia una compilación en la ubicación us-west2 usando los archivos subidos como entrada;
  • etiqueta la imagen mediante el nombre provisto; y
  • envía la imagen compilada a Container 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 --region=us-west2 --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. 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 --region=us-west2 --config cloudbuild.yaml \
        gs://BUCKET/SOURCE.tar.gz

Aquí:

  • BUCKET es el nombre del bucket en Cloud Storage que contiene el código fuente que deseas 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 --region=us-west2 --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",
            "gcr.io/PROJECT_ID/IMAGE_NAME",
            "."
        ]
    }],
    "images": [
        "gcr.io/PROJECT_ID/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á.

    En esta solicitud de compilación, Cloud Build llama al paso de compilación docker con los argumentos build -t gcr.io/$PROJECT_ID/IMAGE-NAME ..

    El nombre completo de la imagen que se compilará es gcr.io/$PROJECT_ID/IMAGE_NAME.

    En las imágenes enviadas a Container Registry, se usa el formato de nombre de registro.

  2. Ejecuta el siguiente comando, en el que PROJECT_ID es el ID de tu proyecto de 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 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",
                        "gcr.io/PROJECT_ID/IMAGE_NAME",
                        "."
                    ]
                }
                ],
                "timeout": "600s",
                "images": [
                    "gcr.io/$PROJECT_ID/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 desde un recurso de repositorio de 2a gen., ejecuta el siguiente comando:

gcloud builds submit REPOSITORY --revision=REVISION --config=BUILD_CONFIG --region=us-west2

Aquí:

  • REPOSITORY es el nombre del repositorio de 2a gen. de Google 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, el comando anterior sube todos los archivos del directorio especificado a Google Cloud Platform con el fin de 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 no se muestra ningún archivo .gcloudignore presente en el directorio de carga de nivel superior, pero un archivo .gitignore sí, el gcloud CLI generará 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 el 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 --region=us-west2 --config=BUILD_CONFIG --no-source

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",
            "gcr.io/PROJECT_ID/IMAGE_NAME",
            "."
        ]
    }],
    "images": [
        "gcr.io/PROJECT_ID/IMAGE_NAME"
    ]
}

    Aquí:

    • REPOSITORY es el nombre del repositorio de 2a gen. de Google 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á.

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

    El nombre completo de la imagen que se compilará es gcr.io/PROJECT_ID/IMAGE_NAME. En las imágenes enviadas a Container Registry, se usa el formato de nombre de registro.

  2. Ejecuta el siguiente comando, en el que PROJECT_ID es tu ID del proyecto de Google Cloud y REGION es uno de los 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",
                        "gcr.io/PROJECT_ID/IMAGE_NAME",
                        "."
                    ]
                }
                ],
                "timeout": "600s",
                "images": [
                    "gcr.io/PROJECT_ID/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?