Invia una build utilizzando l'interfaccia a riga di comando e l'API

Questa pagina descrive come avviare manualmente una build in Cloud Build utilizzando Google Cloud CLI e l'API Cloud Build.

Prima di iniziare

Autorizzazioni IAM richieste

Per ottenere le autorizzazioni necessarie per inviare build, chiedi all'amministratore di concederti i seguenti ruoli IAM sul tuo account di servizio:

Per ulteriori informazioni sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Esecuzione delle build

Puoi specificare l'origine della build utilizzando il campo Origine build. Il campo Origine build è uno dei seguenti: storage_source, repo_source, git_source e connected_repository.

Inviare build con storage_source

gcloud

Utilizzo di un Dockerfile:

Il tuo Dockerfile contiene tutte le informazioni necessarie per creare un'immagine Docker utilizzando Cloud Build.

Per eseguire la build utilizzando un Dockerfile, esegui il seguente comando dalla directory contenente il codice sorgente e il Dockerfile:

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

Dove:

  • LOCATION: la posizione regionale o multiregionale del repository Docker in Artifact Registry.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • REPOSITORY: il nome del repository Artifact Registry.
  • IMAGE_NAME: il nome dell'immagine container da creare.

Il nome completo dell'immagine da creare è LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME. Le immagini sottoposte a push ad Artifact Registry utilizzano la convenzione di denominazione di Artifact Registry.

Il comando gcloud builds submit:

  • comprime il codice dell'applicazione, Dockerfile e qualsiasi altro asset nella directory corrente, come indicato da .;
  • avvia una build nella località LOCATION utilizzando i file caricati come input;
  • assegna un tag all'immagine utilizzando il nome fornito.
  • esegue il push dell'immagine creata in Artifact Registry.

Man mano che la build procede, il relativo output viene visualizzato nella finestra della shell o del terminale. Al termine della build, dovresti visualizzare un output simile al seguente:

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

dove $BUILD_ID è l'identificatore univoco della build.

Utilizzo del file di configurazione della build di Cloud Build:

Per inviare una build utilizzando la configurazione della build, esegui il seguente comando:

    gcloud builds submit --config BUILD_CONFIG SOURCE

Dove:

  • BUILD_CONFIG è il percorso del file di configurazione della build.
  • SOURCE è il percorso o il codice sorgente dell'URL.

Quando esegui gcloud builds submit per la prima volta in un progetto Google Cloud , Cloud Build crea un bucket Cloud Storage denominato [YOUR_PROJECT_NAME]_cloudbuild in quel progetto. Cloud Build utilizza questo bucket per archiviare il codice sorgente che potresti utilizzare per le tue build. Cloud Build non elimina automaticamente i contenuti di questo bucket. Per eliminare gli oggetti che non utilizzi più per le build, puoi configurare il ciclo di vita nel bucket o eliminarli manualmente.

Il seguente comando mostra come inviare una richiesta di build cloudbuild.yaml utilizzando il codice sorgente archiviato in un bucket Cloud Storage.

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

Dove:

  • BUCKET è il nome del bucket in Cloud Storage contenente il codice sorgente da compilare.
  • SOURCE è il nome del file di codice sorgente compresso.

Puoi utilizzare . per specificare che il codice sorgente si trova nella directory di lavoro corrente:

    gcloud builds submit --config=cloudbuild.yaml .

API

Per inviare la richiesta di build utilizzando curl:

  1. Crea un file denominato request.json con i seguenti contenuti:

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

    Dove:

    • BUCKET è il nome del tuo bucket Cloud Storage contenente il codice sorgente da compilare.
    • SOURCE è il nome del file di codice sorgente compresso.
    • IMAGE_NAME è il nome dell'immagine da creare.
    • LOCATION: la posizione regionale o multiregionale del repository Docker in Artifact Registry.
    • PROJECT_ID: il tuo ID progetto Google Cloud .
    • REPOSITORY: il nome del repository Docker in Artifact Registry.

    In questa richiesta di build, Cloud Build chiama il passaggio di build docker con gli argomenti build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY ..

    Il nome completo dell'immagine da creare è LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY.

    Le immagini sottoposte a push ad Artifact Registry utilizzano la convenzione di denominazione di Artifact Registry.

  2. Esegui questo comando, dove PROJECT_ID è il tuo ID progettoGoogle Cloud e REGION è una delle regioni supportate:

    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

    In questo comando, curl invia request.json in una chiamata POST all'endpoint builds per il metodo API projects.builds.create.

    Il comando mostra i dettagli della build nella finestra della shell o del terminale. L'output è una risposta JSON e appare simile alla seguente:

        {
        "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 risposta JSON è modellata utilizzando la risorsa Operation nell'API Cloud Build. Il campo metadata è modellato utilizzando la risorsa Build. Lo stato QUEUED indica che la build è in attesa di esecuzione.

Inviare build con connected_repository

gcloud

Per eseguire una richiesta di build con l'origine build da una risorsa repository di seconda generazione, esegui questo comando:

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

Dove:

  • LOCATION è la località regionale o multiregionale del repository Docker in Artifact Registry.
  • REPOSITORY è il nome del repository Cloud Build di 2ª gen., formattato come projects/*/locations/*/connections/*repositories/*.
  • REVISION è la revisione da recuperare dal repository Git, ad esempio un branch, un tag, una SHA di commit o qualsiasi riferimento Git.
  • BUILD_CONFIG è il percorso del file di configurazione della build.

Man mano che la build procede, il relativo output viene visualizzato nella finestra della shell o del terminale. Al termine della build, dovresti visualizzare un output simile al seguente:

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

dove $BUILD_ID è l'identificatore univoco della build.

gcloudignore: quando includi il codice sorgente per la build, il comando precedente carica tutti i file nella directory specificata in Google Cloud per la build. Se vuoi escludere determinati file nella directory, puoi includere un file denominato .gcloudignore nella directory di caricamento di primo livello; i file specificati verranno ignorati. Se .gcloudignore non è presente nella directory di caricamento di primo livello, ma è presente un file .gitignore, la gcloud CLI genera un file .gcloudignore compatibile con Git che rispetta i file .gitignore. Per saperne di più, consulta la documentazione di gcloudignore.

Se non hai il codice sorgente da passare alla build, utilizza il flag --no-source, dove BUILD_CONFIG è il percorso del file di configurazione della build:

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY

API

Per inviare la richiesta di build utilizzando curl:

  1. Crea un file denominato request.json con i seguenti contenuti:

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

    Dove:

    • REPOSITORY è il nome del repository Cloud Build di 2ª gen., formattato come projects/*/locations/*/connections/*repositories/*.
    • REVISION è la revisione da recuperare dal repository Git, ad esempio un branch, un tag, una SHA di commit o qualsiasi riferimento Git.
    • IMAGE_NAME è il nome dell'immagine da creare.
    • LOCATION: la posizione regionale o multiregionale del repository Docker in Artifact Registry.
    • PROJECT_ID: il tuo ID progetto Google Cloud .

    In questa richiesta di build, Cloud Build chiama il passaggio di build docker con gli argomenti build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME ..

    Il nome completo dell'immagine da creare è LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME. Le immagini sottoposte a push ad Artifact Registry utilizzano la convenzione di denominazione di Artifact Registry.

  2. Esegui questo comando dove PROJECT_ID è l'ID del tuo progettoGoogle Cloud e REGION è una delle regioni supportate:

    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

    In questo comando, curl invia request.json in una chiamata POST all'endpoint builds per il metodo API projects.builds.create.

    Il comando mostra i dettagli della build nella finestra della shell o del terminale. L'output è una risposta JSON e appare simile alla seguente:

        {
        "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 risposta JSON è modellata utilizzando la risorsa Operation nell'API Cloud Build. Il campo metadata è modellato utilizzando la risorsa Build. Lo stato QUEUED indica che la build è in attesa di esecuzione.

Passaggi successivi