Build über die Befehlszeile und die API einreichen

Auf dieser Seite wird beschrieben, wie Sie mit der Google Cloud CLI und der Cloud Build API manuell einen Build in Cloud Build starten.

Hinweis

Erforderliche IAM-Berechtigungen

Damit die erforderlichen Berechtigungen zum Senden von Builds hat, bitten Sie Ihren Administrator, die folgenden IAM-Rollen für Ihr Dienstkonto zuzuweisen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Ihr Administrator kann die erforderlichen Berechtigungen möglicherweise auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erteilen.

Builds ausführen

Sie können die Quelle Ihres Builds im Feld Build-Quelle angeben. Das Feld **Build-Quelle** kann einen der folgenden Werte haben: storage_source, repo_source, git_source und connected_repository.

Builds mit storage_source senden

gcloud

Dockerfile verwenden:

Ihr Dockerfile enthält alle Informationen, die Sie zum Erstellen eines Docker-Images mit Cloud Build benötigen.

Führen Sie zum Erstellen mit einem Dockerfile den folgenden Befehl aus dem Verzeichnis aus, das Ihren Quellcode und das Dockerfile enthält:

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

Wobei:

  • LOCATION: der regionale oder multiregionale Speicherort Ihres Docker-Repositorys in Artifact Registry.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.
  • REPOSITORY: der Name Ihres Artifact Registry-Repositorys.
  • IMAGE_NAME: der Name des zu erstellenden Container-Images.

Der vollständige Name des zu erstellenden Images ist LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME. In Artifact Registry übertragene Images verwenden die Artifact Registry-Namenskonvention.

Der Befehl gcloud builds submit:

  • komprimiert Ihren Anwendungscode, das Dockerfile und alle anderen Assets im aktuellen Verzeichnis wie durch . angegeben.
  • initiiert einen Build am Speicherort LOCATION unter Verwendung der hochgeladenen Dateien als Eingabe.
  • taggt das Image mit dem bereitgestellten Namen.
  • überträgt das erstellte Image in Artifact Registry.

Der Fortschritt des Builds wird währenddessen im Shell- oder Terminalfenster ausgegeben. Nach Abschluss des Builds sollten Sie in etwa folgende Ausgabe sehen:

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

Dabei ist $BUILD_ID die eindeutige Kennung Ihres Builds.

Build-Konfigurationsdatei für Cloud Build verwenden:

Führen Sie den folgenden Befehl aus, um einen Build mit der Build-Konfiguration zu übertragen:

    gcloud builds submit --config BUILD_CONFIG SOURCE

Wobei:

  • BUILD_CONFIG ist der Pfad zur Build-Konfigurationsdatei.
  • SOURCE ist der Pfad oder die URL zum Quellcode.

Wenn Sie gcloud builds submit zum ersten Mal in einem Google Cloud Projekt ausführen, erstellt Cloud Build einen Cloud Storage-Bucket mit dem Namen [YOUR_PROJECT_NAME]_cloudbuild in diesem Projekt. Cloud Build verwendet diesen Bucket, um Quellcode zu speichern, den Sie für Ihre Builds verwenden können. Cloud Build löscht Inhalte in diesem Bucket nicht automatisch. Um Objekte zu löschen, die Sie nicht mehr für Builds verwenden, können Sie entweder die Lebenszykluskonfiguration für den Bucket einrichten oder die Objekte manuell löschen.

Der folgende Befehl zeigt, wie Sie eine cloudbuild.yaml-Build-Anfrage mit Quellcode senden, der in einem Cloud Storage-Bucket gespeichert ist.

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

Wobei:

  • BUCKET der Name Ihres Buckets in Cloud Storage ist, der den Quellcode für den Build enthält.
  • SOURCE der Name Ihrer komprimierten Quellcodedatei ist.

Sie können mit . angeben, dass sich der Quellcode im aktuellen Arbeitsverzeichnis befindet:

    gcloud builds submit --config=cloudbuild.yaml .

API

So senden Sie die Build-Anfrage mit curl:

  1. Erstellen Sie eine Datei mit dem Namen request.json und mit folgendem Inhalt:

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

    Wobei:

    • BUCKET der Name Ihres Cloud Storage-Buckets ist, der den Quellcode für den Build enthält.
    • SOURCE der Name Ihrer komprimierten Quellcodedatei ist.
    • IMAGE_NAME der Name des zu erstellenden Images ist.
    • LOCATION: der regionale oder multiregionale Speicherort Ihres Docker-Repositorys in Artifact Registry.
    • PROJECT_ID: Ihre Google Cloud Projekt-ID.
    • REPOSITORY der Name Ihres Docker-Repositorys in Artifact Registry ist.

    In dieser Build-Anfrage ruft Cloud Build den docker Build-Schritt mit den Argumenten build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY . auf.

    Der vollständige Name des zu erstellenden Images ist LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY.

    In Artifact Registry übertragene Images verwenden die Artifact Registry-Namenskonvention.

  2. Führen Sie den folgenden Befehl aus. Dabei ist PROJECT_ID Ihre Google Cloud Projekt-ID und REGION eine der unterstützten Regionen:

    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 diesem Befehl sendet curl request.json in einem POST-Aufruf für die API-Methode projects.builds.create an den builds Endpunkt.

    Mit dem Befehl werden im Shell- oder Terminalfenster Details zum Build angezeigt. Als Ausgabe erhalten Sie in etwa die folgende JSON-Antwort:

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

    Die JSON-Antwort wird mithilfe der Operation-Ressource in der Cloud Build API modelliert. Das Feld metadata wird mithilfe der Build-Ressource modelliert. Der Status QUEUED zeigt an, dass der Build auf seine Ausführung wartet.

Builds mit connected_repository senden

gcloud

Führen Sie den folgenden Befehl aus, um eine Build-Anfrage mit einer Build-Quelle aus einer Repository-Ressource der 2. Generation auszuführen:

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

Wobei:

  • LOCATION: der regionale oder multiregionale Speicherort Ihres Docker-Repositorys in Artifact Registry.
  • REPOSITORY der Name des Cloud Build-Repositorys der 2. Generation im Format projects/*/locations/*/connections/*/repositories/* ist.
  • REVISION die Revision ist, die aus dem Git-Repository abgerufen werden soll, z. B. ein Zweig, ein Tag, eine Commit-SHA oder eine beliebige Git-Referenz.
  • BUILD_CONFIG der Pfad zur Build-Konfigurationsdatei ist.

Der Fortschritt des Builds wird währenddessen im Shell- oder Terminalfenster ausgegeben. Nach Abschluss des Builds sollten Sie in etwa folgende Ausgabe sehen:

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

Dabei ist $BUILD_ID die eindeutige Kennung Ihres Builds.

gcloudignore: Wenn Sie auch den Quellcode für den Build angeben, werden mit dem vorherigen Befehl alle Dateien im angegebenen Verzeichnis für den Build-Vorgang auf Google Cloud hochgeladen. Wenn Sie bestimmte Dateien aus dem Verzeichnis ausschließen möchten, können Sie im übergeordneten Upload-Verzeichnis eine Datei mit dem Namen .gcloudignore einfügen. Die darin angegebenen Dateien werden ignoriert. Wenn im übergeordneten Upload-Verzeichnis keine .gcloudignore-Datei vorhanden ist, dafür aber eine .gitignore-Datei, generiert die gcloud CLI eine mit Git kompatible .gcloudignore-Datei, in der die von Ihnen in .gitignore ignorierten Dateien berücksichtigt werden. Weitere Informationen finden Sie in der gcloudignore Dokumentation.

Wenn Sie keinen Quellcode haben, der an den Build übergeben werden soll, verwenden Sie das --no-source Flag. Dabei ist BUILD_CONFIG der Pfad zur Build Konfigurationsdatei:

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY

API

So senden Sie die Build-Anfrage mit curl:

  1. Erstellen Sie eine Datei mit dem Namen request.json und mit folgendem Inhalt:

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

    Wobei:

    • REPOSITORY der Name des Cloud Build-Repositorys der 2. Generation im Format projects/*/locations/*/connections/*repositories/* ist.
    • REVISION die Revision ist, die aus dem Git-Repository abgerufen werden soll, z. B. ein Zweig, ein Tag, eine Commit-SHA oder eine beliebige Git-Referenz.
    • IMAGE_NAME der Name des zu erstellenden Images ist.
    • LOCATION: der regionale oder multiregionale Speicherort Ihres Docker-Repositorys in Artifact Registry.
    • PROJECT_ID: Ihre Google Cloud Projekt-ID.

    In dieser Build-Anfrage ruft Cloud Build den docker Build-Schritt mit den Argumenten build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME . auf.

    Der vollständige Name des zu erstellenden Images ist LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME. In Artifact Registry übertragene Images verwenden die Artifact Registry-Namenskonvention.

  2. Führen Sie den folgenden Befehl aus. Dabei ist PROJECT_ID Ihre Google Cloud Projekt-ID und REGION eine der unterstützten Regionen:

    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 diesem Befehl sendet curl request.json in einem POST-Aufruf für die API-Methode projects.builds.create an den builds Endpunkt.

    Mit dem Befehl werden im Shell- oder Terminalfenster Details zum Build angezeigt. Als Ausgabe erhalten Sie in etwa die folgende JSON-Antwort:

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

    Die JSON-Antwort wird mithilfe der Operation-Ressource in der Cloud Build API modelliert. Das Feld metadata wird mithilfe der Build-Ressource modelliert. Der Status QUEUED zeigt an, dass der Build auf seine Ausführung wartet.

Nächste Schritte