Envoyer un build via la CLI et l'API

Cette page explique comment démarrer manuellement une compilation dans Cloud Build à l'aide de Google Cloud CLI et de l'API Cloud Build.

Avant de commencer

  • Si vous voulez vous servir des exemples de ligne de commande de ce guide, installez Google Cloud CLI.
  • Pour compiler à l'aide de la configuration de compilation Cloud Build, créez un fichier de configuration de compilation.
  • Pour compiler à l'aide d'un fichier Dockerfile, gardez votre fichier Dockerfile à portée de main.
  • Si votre compilation nécessite un code source, gardez-le à portée de main.

Autorisations IAM requises

Pour obtenir des instructions sur l'attribution de rôles IAM, consultez la page Configurer l'accès aux ressources Cloud Build.

Exécuter des compilations

Vous pouvez spécifier la source de votre compilation à l'aide du champ Build source (Source de la compilation). Le champ de la source de compilation est l'un des suivants: storage_source, repo_source, git_source et connected_repository.

Envoyer des builds avec storage_source

gcloud

Utiliser un fichier Dockerfile :

Votre fichier Dockerfile contient toutes les informations nécessaires à la compilation d'une image Docker à l'aide de Cloud Build.

Pour exécuter une requête de compilation à l'aide de votre fichier Dockerfile, exécutez la commande suivante à partir du répertoire contenant votre code d'application, votre fichier Dockerfile et toutes les autres ressources :

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

Où :

  • PROJECT_ID est le nom de votre projet Google Cloud.
  • IMAGE_NAME est l'image à compiler.
  • . indique que le code source se trouve dans le répertoire de travail actuel.

Le nom complet de l'image à compiler est gcr.ioPROJECT_ID/IMAGE_NAME. Les images envoyées vers Container Registry utilisent le format du nom de registre.

La commande gcloud builds submit :

  • compresse le code de l'application, le fichier Dockerfile et toutes les autres ressources contenues dans le répertoire courant, comme indiqué par . ;
  • importe les fichiers dans un bucket Cloud Storage ;
  • lance une compilation à l'emplacement us-west2 en utilisant les fichiers importés en entrée ;
  • marque l'image à l'aide du nom fourni ;
  • envoie l'image compilée vers Container Registry.

Au fur et à mesure de la compilation, les résultats s'affichent dans la fenêtre de votre interface système ou de votre terminal. Une fois la compilation terminée, un résultat semblable aux lignes suivantes doit s'afficher :

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

où $BUILD_ID correspond à l'identifiant unique de la compilation.

Utiliser le fichier de configuration de compilation Cloud Build :

Pour envoyer une compilation à l'aide de la configuration de compilation, exécutez la commande suivante :

    gcloud builds submit --region=us-west2 --config BUILD_CONFIG SOURCE

Où :

  • BUILD_CONFIG est le chemin d'accès du fichier de configuration de compilation
  • SOURCE est le code source du chemin d'accès ou de l'URL

Lorsque vous exécutez gcloud builds submit pour la première fois dans un projet Google Cloud, Cloud Build crée un bucket Cloud Storage nommé [YOUR_PROJECT_NAME]_cloudbuild dans ce projet. Cloud Build utilise ce bucket pour stocker tout code source pouvant servir pour vos builds. Cloud Build ne supprime pas automatiquement le contenu de ce bucket. Pour supprimer les objets que vous n'utilisez plus pour les builds, vous pouvez soit définir la configuration du cycle de vie sur le bucket, soit supprimer les objets manuellement.

La commande suivante montre comment envoyer une requête de compilation cloudbuild.yaml à l'aide d'un code source stocké dans un bucket Cloud Storage.

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

Où :

  • BUCKET est le nom du bucket Cloud Storage contenant le code source à compiler.
  • SOURCE est le nom de votre fichier de code source compressé.

Vous pouvez utiliser . pour spécifier que le code source se trouve dans le répertoire de travail courant :

    gcloud builds submit --region=us-west2 --config=cloudbuild.yaml .

API

Pour envoyer la requête de compilation à l'aide de curl :

  1. Créez un fichier nommé request.json avec le contenu suivant :

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

    Où :

    • BUCKET est le nom du bucket Cloud Storage contenant le code source à compiler.
    • SOURCE est le nom de votre fichier de code source compressé.
    • IMAGE_NAME est le nom de l'image à compiler.

    Dans cette requête de compilation, Cloud Build appelle l'étape de compilation docker avec les arguments build -t gcr.io/$PROJECT_ID/IMAGE-NAME ..

    Le nom complet de l'image à compiler est gcr.io/$PROJECT_ID/IMAGE_NAME.

    Les images envoyées vers Container Registry utilisent le format du nom de registre.

  2. Exécutez la commande suivante, où PROJECT_ID est l'ID de votre projet Google Cloud et REGION est l'une des régions disponibles:

    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

    Dans cette commande, curl envoie le fichier request.json dans une requête POST au point de terminaison builds pour la méthode API projects.builds.create.

    La commande affiche des détails sur la compilation dans la fenêtre d'interface système ou de terminal. Le résultat est une réponse JSON et ressemble à ce qui suit :

        {
        "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 réponse JSON est modélisée sous la forme de ressource Operation dans l'API Cloud Build. Le champ metadata est modélisé sous la forme de ressource Build. L'état QUEUED indique que la compilation est en attente d'exécution.

Envoyer des builds avec connected_repository

gcloud

Pour exécuter une requête de compilation avec une source de compilation à partir d'une ressource de dépôt de 2e génération, exécutez la commande suivante:

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

Où :

  • REPOSITORY est le nom du dépôt Google Cloud Build 2e génération, au format projects/*/locations/*/connections/*repositories/*.
  • REVISION est la révision à extraire du dépôt Git, comme une branche, un tag, un SHA de commit ou toute référence Git.
  • BUILD_CONFIG est le chemin d'accès du fichier de configuration de compilation

Au fur et à mesure de la compilation, les résultats s'affichent dans la fenêtre de votre interface système ou de votre terminal. Une fois la compilation terminée, un résultat semblable aux lignes suivantes doit s'afficher :

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

où $BUILD_ID correspond à l'identifiant unique de la compilation.

gcloudignore : lors de l'inclusion du code source dans la compilation, la commande ci-dessus importe tous les fichiers du répertoire spécifié vers Google Cloud Platform pour compiler. Si vous souhaitez exclure certains fichiers du répertoire, vous pouvez inclure un fichier nommé .gcloudignore dans le répertoire d'importation de premier niveau. Les fichiers spécifiés seront ignorés. Si le répertoire d'importation de premier niveau ne contient pas de fichier .gcloudignore, mais qu'un fichier .gitignore l'est, la gcloud CLI génère un fichier .gcloudignore compatible avec Git qui respecte vos fichiers .gitignore. Pour en savoir plus, consultez la documentation de gcloudignore.

Si vous n'avez pas de code source à transmettre à votre compilation, utilisez l'option --no-source, où BUILD_CONFIG est le chemin d'accès du fichier de configuration de compilation :

    gcloud builds submit --region=us-west2 --config=BUILD_CONFIG --no-source

API

Pour envoyer la requête de compilation à l'aide de curl :

  1. Créez un fichier nommé request.json avec le contenu suivant :

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

    Où :

    • REPOSITORY est le nom du dépôt Google Cloud Build 2e génération, au format projects/*/locations/*/connections/*repositories/*.
    • REVISION est la révision à extraire du dépôt Git, comme une branche, un tag, un SHA de commit ou toute référence Git.
    • IMAGE_NAME est le nom de l'image à compiler.

    Dans cette requête de compilation, Cloud Build appelle l'étape de compilation docker avec les arguments build -t gcr.io/PROJECT_ID/IMAGE_NAME ..

    Le nom complet de l'image à compiler est gcr.io/PROJECT_ID/IMAGE_NAME. Les images envoyées vers Container Registry utilisent le format du nom de registre.

  2. Exécutez la commande suivante, où PROJECT_ID est l'ID de votre projet Google Cloud et REGION est l'une des régions disponibles:

    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

    Dans cette commande, curl envoie le fichier request.json dans une requête POST au point de terminaison builds pour la méthode API projects.builds.create.

    La commande affiche des détails sur la compilation dans la fenêtre d'interface système ou de terminal. Le résultat est une réponse JSON et ressemble à ce qui suit :

        {
        "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 réponse JSON est modélisée sous la forme de ressource Operation dans l'API Cloud Build. Le champ metadata est modélisé sous la forme de ressource Build. L'état QUEUED indique que la compilation est en attente d'exécution.

Étapes suivantes