Schema der Build-Konfigurationsdatei

Eine Build-Konfigurationsdatei enthält eine Anleitung, die Cloud Build zur Ausführung von Aufgaben gemäß Ihren Spezifikationen verwendet. Zum Beispiel kann Ihre Build-Konfigurationsdatei Anweisungen zum Erstellen, Packen und Hochladen von Docker-Images enthalten.

Auf dieser Seite wird das Schema der Cloud Build-Konfigurationsdatei erläutert. Anleitungen zum Erstellen und Verwenden einer Build-Konfigurationsdatei finden Sie unter Einfache Build-Konfigurationsdatei erstellen.

Struktur einer Build-Konfigurationsdatei

Build-Konfigurationsdateien werden mit der Ressource Build der Cloud Build API modelliert.

Sie können die Build-Konfigurationsdatei mit der YAML- oder der JSON-Syntax schreiben. Verwenden Sie die JSON-Syntax, wenn Sie Build-Anfragen mithilfe von HTTP-Tools eines Drittanbieters wie "curl" senden.

Hinweis: Wenn Sie VS Code- oder IntelliJ-IDEs verwenden, können Sie Cloud Code verwenden, um Ihre YAML-Konfigurationsdateien zu erstellen. Cloud Code ist in den Cloud Shell-Editor eingebunden und erfordert keine Einrichtung. Weitere Informationen finden Sie unter Cloud Code für VS Code und Cloud Code für IntelliJ.

Eine Build-Konfigurationsdatei hat folgende Struktur:

YAML

steps:
- name: string
  args: [string, string, ...]
  env: [string, string, ...]
  allowFailure: boolean
  allowExitCodes: [string (int64 format), string (int64 format), ...]
  dir: string
  id: string
  waitFor: [string, string, ...]
  entrypoint: string
  secretEnv: string
  volumes: object(Volume)
  timeout: string (Duration format)
  script: string
  automapSubstitutions: boolean
- name: string
  ...
- name: string
  ...
timeout: string (Duration format)
queueTtl: string (Duration format)
logsBucket: string
options:
 env: [string, string, ...]
 secretEnv: string
 volumes: object(Volume)
 sourceProvenanceHash: enum(HashType)
 machineType: enum(MachineType)
 diskSizeGb: string (int64 format)
 substitutionOption: enum(SubstitutionOption)
 dynamicSubstitutions: boolean
 automapSubstitutions: boolean
 logStreamingOption: enum(LogStreamingOption)
 logging: enum(LoggingMode)
 defaultLogsBucketBehavior: enum(DefaultLogsBucketBehavior)
 pool: object(PoolOption)
 requestedVerifyOption: enum(RequestedVerifyOption)
substitutions: map (key: string, value: string)
tags: [string, string, ...]
serviceAccount: string
secrets: object(Secret)
availableSecrets: object(Secrets)
artifacts: object(Artifacts)
  mavenArtifacts: [object(MavenArtifact), ...]
  pythonPackages: [object(PythonPackage), ...]
  npmPackages: [object(npmPackage), ...]
images:
- [string, string, ...]

JSON

{
    "steps": [
    {
        "name": "string",
        "args": [
            "string",
            "string",
            "..."
        ],
        "env": [
            "string",
            "string",
            "..."
        ],
        "allowFailure": "boolean",
        "allowExitCodes: [
            "string (int64 format)",
            "string (int64 format)",
            "..."
        ],
        "dir": "string",
        "id": "string",
        "waitFor": [
            "string",
            "string",
            "..."
        ],
        "entrypoint": "string",
        "secretEnv": "string",
        "volumes": "object(Volume)",
        "timeout": "string (Duration format)",
        "script" : "string",
        "automapSubstitutions" : "boolean"
    },
    {
        "name": "string"
        ...
    },
    {
        "name": "string"
        ...
    }
    ],
    "timeout": "string (Duration format)",
    "queueTtl": "string (Duration format)",
    "logsBucket": "string",
    "options": {
        "sourceProvenanceHash": "enum(HashType)",
        "machineType": "enum(MachineType)",
        "diskSizeGb": "string (int64 format)",
        "substitutionOption": "enum(SubstitutionOption)",
        "dynamicSubstitutions": "boolean",
        "automapSubstitutions": "boolean",
        "logStreamingOption": "enum(LogStreamingOption)",
        "logging": "enum(LoggingMode)"
        "defaultLogsBucketBehavior": "enum(DefaultLogsBucketBehavior)"
        "env": [
            "string",
            "string",
            "..."
        ],
        "secretEnv": "string",
        "volumes": "object(Volume)",
        "pool": "object(PoolOption)"
        "requestedVerifyOption": "enum(RequestedVerifyOption)"
    },
    "substitutions": "map (key: string, value: string)",
    "tags": [
        "string",
        "string",
        "..."
    ],
    "serviceAccount": "string",
    "secrets": "object(Secret)",
    "availableSecrets": "object(Secrets)",
    "artifacts": "object(Artifacts)",
      "mavenArtifacts": ["object(MavenArtifact)", ...],
      "pythonPackages": ["object(PythonPackage)", ...],
      "npmPackages": ["object(npmPackage)", ...],
    "images": [
        "string",
        "string",
        "..."
    ]
}

Jeder Abschnitt der Build-Konfigurationsdatei definiert einen Teil der Aufgabe, die Cloud Build ausführen soll:

Build-Schritte

Ein Build-Schritt gibt eine Aktion an, die Cloud Build ausführen soll. Cloud Build führt für jeden Build-Schritt einen Docker-Container als Instanz von docker runaus. Build-Schritte sind mit Befehlen in einem Skript vergleichbar und ermöglichen die flexible Ausführung beliebiger Anweisungen in einem Build. Wenn Sie ein Build-Tool in einen Container packen, kann Cloud Build dieses Tool als Teil des Builds ausführen. Standardmäßig führt Cloud Build alle Schritte eines Builds seriell auf demselben Computer aus. Wenn Sie Schritte haben, die gleichzeitig ausgeführt werden können, verwenden Sie die Option waitFor.

Sie können bis zu 300 Build-Schritte in Ihre Konfigurationsdatei aufnehmen.

Verwenden Sie das Feld steps in der Build-Konfigurationsdatei, um einen Build-Schritt anzugeben. Nachfolgend sehen Sie ein Snippet für die Art der Konfigurationsanweisung, die Sie im Feld steps angeben können:

YAML

steps:
- name: 'gcr.io/cloud-builders/kubectl'
  args: ['set', 'image', 'deployment/mydepl', 'my-image=gcr.io/my-project/myimage']
  env:
  - 'CLOUDSDK_COMPUTE_ZONE=us-east4-b'
  - 'CLOUDSDK_CONTAINER_CLUSTER=my-cluster'
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project-id/myimage', '.']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/kubectl",
        "args": [
            "set",
            "image"
            "deployment/mydepl"
            "my-image=gcr.io/my-project/myimage"
        ],
        "env": [
            "CLOUDSDK_COMPUTE_ZONE=us-east4-b",
            "CLOUDSDK_CONTAINER_CLUSTER=my-cluster"
        ]
    },
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/my-project-id/myimage",
            "."
        ]
    }
    ]
}

name

Geben Sie im Feld name eines Build-Schritts einen Cloud-Builder an. Dies ist ein Container-Image, das häufig genutzte Tools ausführt. Mit einem Builder werden die Aufgaben in einem Build-Schritt ausgeführt.

Das folgende Snippet zeigt Build-Schritte, die die Builder bazel, gcloud und docker aufrufen:

YAML

steps:
- name: 'gcr.io/cloud-builders/bazel'
...

- name: 'gcr.io/cloud-builders/gcloud'
...

- name: 'gcr.io/cloud-builders/docker'
...

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/bazel"
        ...
    },
    {
        "name": "gcr.io/cloud-builders/gcloud"
        ...
    },
    {
        "name": "gcr.io/cloud-builders/docker"
        ...
    }
    ]
}

args

Im Feld args eines Build-Schritts wird eine Liste von Argumenten abgerufen und an den Builder übergeben, auf den im Feld name verwiesen wird. An den Builder übergebene Argumente werden wiederum an das im Builder ausgeführte Tool übergeben, mit dem Sie alle vom Tool unterstützten Befehle aufrufen können. Wenn der im Build-Schritt verwendete Builder einen Einstiegspunkt hat, werden "args" als Argumente für diesen Einstiegspunkt verwendet. Wenn der Builder keinen Einstiegspunkt definiert, wird das erste Element in "args" als Einstiegspunkt verwendet. Alle weiteren Elemente werden als Argumente verwendet.

Sie können bis zu 100 Argumente pro Schritt erstellen. Die maximale Länge des Arguments beträgt 10.000 Zeichen.

Das folgende Snippet ruft den Befehl docker build auf und installiert Maven-Abhängigkeiten:

YAML

steps:
- name: 'gcr.io/cloud-builders/mvn'
  args: ['install']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project-id/myimage', '.']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/mvn",
        "args": [
            "install"
        ]
    },
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/my-project-id/myimage",
            "."
        ]
    }
    ]
}

env

Im Feld env eines Build-Schritts wird eine Liste von Umgebungsvariablen abgerufen, die beim Ausführen des Schritts verwendet werden sollen. Die Variablen haben die Form KEY=VALUE.

In der folgenden Build-Konfiguration legt das Feld env des Build-Schrittes die Compute Engine-Zone und den GKE-Cluster vor der Ausführung von kubectl fest:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
- name: 'gcr.io/cloud-builders/kubectl'
  args: ['set', 'image', 'deployment/myimage', 'frontend=gcr.io/myproject/myimage']
  env:
  - 'CLOUDSDK_COMPUTE_ZONE=us-east1-b'
  - 'CLOUDSDK_CONTAINER_CLUSTER=node-example-cluster'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    },
    {
        "name": "gcr.io/cloud-builders/kubectl",
        "args": [
            "set",
            "image",
            "deployment/myimage",
            "frontend=gcr.io/myproject/myimage"
        ],
        "env": [
            "CLOUDSDK_COMPUTE_ZONE=us-east1-b",
            "CLOUDSDK_CONTAINER_CLUSTER=node-example-cluster"
        ]
    }
    ]
}

dir

Verwenden Sie in einem Build-Schritt das Feld dir, um ein Arbeitsverzeichnis festzulegen, das beim Ausführen des Containers des Schritts verwendet werden soll. Wenn Sie das Feld dir im Build-Schritt festlegen, wird das Arbeitsverzeichnis auf /workspace/<dir> festgelegt. Wenn dieser Wert ein relativer Pfad ist, ist er relativ zum Arbeitsverzeichnis des Builds. Wenn es sich um einen absoluten Wert handelt, befindet er sich möglicherweise außerhalb des Build-Arbeitsverzeichnisses. In diesem Fall wird der Inhalt des Pfads möglicherweise nicht über die Ausführung von Build-Schritten hinweg beibehalten (es sei denn, für diesen Pfad ist ein Volume angegeben).

Das folgende Code-Snippet legt das Arbeitsverzeichnis für den Build-Schritt als /workspace/examples/hello_world fest:

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
  env: ['PROJECT_ROOT=hello']
  dir: 'examples/hello_world'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ],
        "env": [
            "PROJECT_ROOT=hello"
        ],
        "dir": "examples/hello_world"
    }
    ]
}

timeout

Verwenden Sie das Feld timeout in einem Build-Schritt, um ein Zeitlimit für die Ausführung des Schritts festzulegen. Wenn Sie dieses Feld nicht festlegen, hat der Schritt kein Zeitlimit und kann ausgeführt werden, bis er abgeschlossen ist oder das Zeitlimit des Builds überschritten wird. Das Feld timeout in einem Build-Schritt darf den für einen Build angegebenen Wert timeout nicht überschreiten. timeout muss in Sekunden mit bis zu neun Nachkommastellen mit einem "s" am Ende angegeben werden. Beispiel: 3.5s

In der folgenden Build-Konfiguration wird der Schritt ubuntu nach 500 Sekunden beendet:

YAML

steps:
- name: 'ubuntu'
  args: ['sleep', '600']
  timeout: 500s
- name: 'ubuntu'
  args: ['echo', 'hello world, after 600s']

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "sleep",
            "600"
        ],
        "timeout": "500s"
    },
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "hello world, after 600s"
        ]
    }
    ]
}

Hinweis: Das Feld "timeout" existiert sowohl für den Build-Schritt als auch für den Build. Das Feld "timeout" eines Build-Schritts gibt an, wie lange der Schritt ausgeführt werden darf. Das Feld timeout eines Builds legt fest, wie lange der Build ausgeführt werden darf.

Skript

Verwenden Sie das Feld script in einem Build-Schritt, um ein Shell-Skript anzugeben, in dem es ausgeführt werden soll Schritt. Wenn Sie script in einem Buildschritt angeben, können Sie im selben Schritt nicht args oder entrypoint angeben. Eine Anleitung zur Verwendung des Felds script finden Sie unter Bash-Scripts ausführen.

automapSubstitutions

Wenn true festgelegt ist, werden alle Substitutionen automatisch zugeordnet und in einem einzigen Schritt als Umgebungsvariablen verfügbar gemacht. Wenn false festgelegt ist, ignorieren Substitutionen für diesen Schritt. Beispiele finden Sie unter Variablenwerte ersetzen.

id

Verwenden Sie das Feld id, um eine eindeutige ID für einen Build-Schritt festzulegen. id wird mit dem Feld waitFor verwendet, um die Reihenfolge festzulegen, in der Build-Schritte ausgeführt werden sollen. Weitere Informationen zur Verwendung von waitFor und id finden Sie unter Reihenfolge der Build-Schritte konfigurieren.

waitFor

Geben Sie in einem Build-Schritt mit dem Feld waitFor an, welche Schritte vor dem Ausführen des Build-Schritts ausgeführt werden müssen. Wenn Sie für waitFor keine Werte angeben, wartet der Build-Schritt erst auf die erfolgreiche Ausführung aller vorherigen Build-Schritte in der Build-Anfrage. Weitere Informationen zur Verwendung von waitFor und id finden Sie unter Reihenfolge der Build-Schritte konfigurieren.

entrypoint

Verwenden Sie entrypoint in einem Build-Schritt, um einen Einstiegspunkt anzugeben, wenn Sie nicht den Standardeinstiegspunkt des Builders verwenden möchten. Wenn Sie dieses Feld nicht angeben, verwendet Cloud Build den Einstiegspunkt des Builders. Das folgende Snippet legt die Einstiegspunkte für den Build-Schritt npm fest:

YAML

steps:
- name: 'gcr.io/cloud-builders/npm'
  entrypoint: 'node'
  args: ['--version']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/npm",
        "entrypoint": "node",
        "args": [
            "--version"
        ]
    }
    ]
}

secretEnv

Eine Liste von Umgebungsvariablen, die mit einem Cloud KMS-Crypto-Schlüssel verschlüsselt werden. Diese Werte müssen in den Secrets des Builds festgelegt werden. Informationen zur Verwendung dieses Feldes finden Sie unter Verschlüsselte Variablen in Build-Anfragen verwenden.

volumes

Ein Volume ist ein Docker-Container, der in Build-Schritte eingebunden wird, um Dateien über Build-Schritte hinweg beizubehalten. Wenn Cloud Build einen Build-Schritt ausführt, wird automatisch das Volume workspace in /workspace bereitgestellt. Sie können zusätzliche Volumes angeben, die in den Containern der Build-Schritte bereitgestellt werden sollen. Verwenden Sie für die Schritte das Feld volumes.

Die folgende Build-Konfigurationsdatei schreibt beispielsweise im ersten Schritt eine Datei in ein Volume und liest sie im zweiten Schritt. Wenn der Pfad /persistent_volume in den Schritten nicht als persistentes Volume angegeben ist, wird die Datei im ersten Schritt in den Pfad geschrieben und vor der Ausführung des zweiten Schritts verworfen. Wenn Sie das Volume in beiden Schritten mit demselben Namen angeben, werden die Inhalte von /persistent_volume aus dem ersten Schritt im zweiten Schritt beibehalten.

YAML

steps:
- name: 'ubuntu'
  volumes:
  - name: 'vol1'
    path: '/persistent_volume'
  entrypoint: 'bash'
  args:
  - '-c'
  - |
        echo "Hello, world!" > /persistent_volume/file
- name: 'ubuntu'
  volumes:
  - name: 'vol1'
    path: '/persistent_volume'
  args: ['cat', '/persistent_volume/file']

JSON

  {
    "steps": [
      {
        "name": "ubuntu",
        "volumes": [
          {
            "name": "vol1",
            "path": "/persistent_volume"
          }
        ],
        "entrypoint": "bash",
        "args": [
          "-c",
          "echo \"Hello, world!\" > /persistent_volume/file\n"
        ]
      },
      {
        "name": "ubuntu",
        "volumes": [
          {
            "name": "vol1",
            "path": "/persistent_volume"
          }
        ],
        "args": [
          "cat",
          "/persistent_volume/file"
        ]
     }
    ]
  }

allowFailure

Wenn Sie in einem Build-Schritt den Wert des Felds allowFailure auf true setzen und der Build-Schritt fehlschlägt, ist der Build erfolgreich, solange alle anderen Build-Schritte in diesem Build erfolgreich sind.

Wenn für alle Build-Schritte in einem Build allowFailure auf true festgelegt ist und alle Build-Schritte fehlschlagen, bleibt der Status des Builds Successful.

allowExitCodes hat Vorrang vor diesem Feld.

Mit dem folgenden Code-Snippet kann der Build erfolgreich abgeschlossen werden, wenn der erste Schritt fehlschlägt:

YAML

steps:
- name: 'ubuntu'
  args: ['-c', 'exit 1']
  allowFailure: true
steps:
- name: 'ubuntu'
  args: ['echo', 'Hello World']

JSON

{
  "steps": [
    {
        "name": "ubuntu",
        "args": [
            "-c",
            "exit -1"
        ],
        "allowFailure": true,
    },
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "Hello World"
        ]
    }
  ]
}

allowExitCodes

Mit dem Feld allowExitCodes können Sie angeben, dass ein Fehler bei einem Buildschritt ignoriert werden kann, wenn dieser Schritt einen bestimmten Exit-Code zurückgibt.

Wenn ein Build-Schritt mit einem Exit-Code fehlschlägt, der mit dem Wert übereinstimmt, den Sie in allowExitCodes angegeben haben, lässt Cloud Build diesen Build-Schritt fehl, ohne dass der gesamte Build fehlschlägt.

Wenn 100 % Ihrer Build-Schritte fehlschlagen, aber jeder Schritt mit einem Code endet, den Sie im Feld allowExitCodes angegeben haben, ist der Build trotzdem erfolgreich.

Wenn der Buildschritt jedoch fehlschlägt und ein anderer Exit-Code ausgegeben wird, der nicht mit dem in allowExitCodes angegebenen Wert übereinstimmt, schlägt der gesamte Build fehl.

Der oder die für Ihren Build relevanten Exit-Code hängen von Ihrer Software ab. „1“ ist beispielsweise ein gängiger Beendigungscode unter Linux. Sie können auch eigene Beendigungscodes in Ihren Scripts definieren. Das Feld allowExitCodes akzeptiert Zahlen mit maximal 255 Stellen.

Dieses Feld hat Vorrang vor allowFailure.

Mit dem folgenden Code-Snippet kann der Build erfolgreich abgeschlossen werden, wenn der erste Schritt mit einem der angegebenen Exitcodes fehlschlägt:

YAML

steps:
- name: 'ubuntu'
  args: ['-c', 'exit 1']
  allowExitCodes: [1]
steps:
- name: 'ubuntu'
  args: ['echo', 'Hello World']

JSON

{
  "steps": [
    {
        "name": "ubuntu",
        "args": [
            "-c",
            "exit 1"
        ],
        "allowExitCodes": [1],
    },
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "Hello World"
        ]
    }
  ]
}

timeout

Verwenden Sie das Feld timeout für einen Build, um die Zeitspanne bis zum zweiten Detaillierungsgrad anzugeben, in der der Build ausgeführt werden darf. Wenn diese Zeitspanne verstrichen ist, wird die Arbeit am Build beendet und der Build-Status ändert sich in TIMEOUT. Wenn kein timeout festgelegt wurde, gilt für den Build standardmäßig ein timeout von 60 Minuten. Für timeout kann ein Höchstwert von 24  Stunden angewendet werden. timeout muss in Sekunden mit bis zu neun Nachkommastellen mit einem "s" am Ende angegeben werden. Beispiel: 3.5s

Im folgenden Snippet wurde timeout auf 660 Sekunden eingestellt, um zu verhindern, dass der Build aufgrund des Ruhemodus die Zeit überschreitet:

YAML

steps:
- name: 'ubuntu'
  args: ['sleep', '600']
timeout: 660s

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "sleep",
            "600"
        ]
    }
    ],
    "timeout": "660s"
}

Hinweis: Das Feld "timeout" existiert sowohl für den Build-Schritt als auch für den Build. Das Feld timeout eines Build-Schritts gibt an, wie lange der Schritt ausgeführt werden darf. Das Feld timeout eines Builds legt fest, wie lange der Build ausgeführt werden darf.

queueTtl

Mit dem Feld queueTtl geben Sie an, wie lange ein Build in die Warteschlange gestellt wird. Wenn sich ein Build in der Warteschlange länger als der in queueTtl festgelegte Wert befindet, läuft der Build ab und der Build-Status stellt sich auf EXPIRED. Wenn kein Wert angegeben ist, verwendet Cloud Build den Standardwert 3600s (1 Stunde). queueTtl beginnt mit dem Ticken von createTime. queueTtl muss kann in Sekunden mit bis zu neun Nachkommastellen angegeben werden, gefolgt von "s", z. B. 3.5s.

Im folgenden Snippet ist timeout auf 20s und queueTtl auf 10s gesetzt. queueTtl beginnt mit dem Ticken bei createTime, also dem Zeitpunkt, zu dem der Build angefordert wird, und timeout beginnt mit startTime. Dies ist der Zeitpunkt, zu dem der Build gestartet wird. Daher läuft queueTtl um createTime + 10s ab, es sei denn, bis dahin beginnt.

YAML

steps:
- name: 'ubuntu'
  args: ['sleep', '5']
timeout: 20s
queueTtl: 10s

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "sleep",
            "5"
        ]
    }
    ],
    "timeout": "20s",
    "queueTtl": "10s"
}

logsBucket

Legen Sie das Feld logsBucket für einen Build fest, um einen Cloud Storage-Bucket anzugeben, in den Logs geschrieben werden müssen. Wenn Sie dieses Feld nicht festlegen, verwendet Cloud Build einen Standard-Bucket, um Ihre Build-Logs zu speichern.

Das folgende Snippet legt einen Log-Bucket zum Speichern der Build-Logs fest:

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
logsBucket: 'gs://mybucket'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ]
    }
    ],
    "logsBucket": "gs://mybucket"
}

options

Verwenden Sie das Feld options, um die folgenden optionalen Argumente für den Build anzugeben:

env: Eine Liste globaler Definitionen von Umgebungsvariablen, die für alle Build-Schritte in dem Build vorhanden sind. Wenn eine Variable sowohl global als auch in einem Build-Schritt definiert ist, verwendet die Variable den Build-Schrittwert. Die Elemente haben die Form KEY=VALUE für die Umgebungsvariable KEY, die den Wert VALUE erhält.

secretEnv: Eine Liste globaler Umgebungsvariablen, die mit einem Kryptoschlüssel des Cloud Key Management Service verschlüsselt wurden und für alle Build-Schritte in diesem Build verfügbar sind. Diese Werte müssen im Secret des Builds festgelegt werden.

volumes: Eine Liste von Volumes, die global für ALLE Build-Schritte bereitgestellt werden sollen. Die neu erstellten Volumes sind vor Beginn des Build-Verfahrens leer. Nach Abschluss des Builds werden die Volumes und deren Inhalte verworfen. Die Namen und Pfade globaler Volumes dürfen nicht mit den in einem Build-Schritt definierten Volumes in Konflikt stehen. Die Verwendung eines globalen Volumes in einem Build mit nur einem Schritt ist nicht zulässig. Es deutet auf eine falsch konfigurierte Build-Anfrage hin.

sourceProvenanceHash: Legen Sie mit der Option sourceProvenanceHash den Hash-Algorithmus für die Quellenherkunft fest. Das folgende Snippet gibt als Hash-Algorithmus SHA256 an:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
    sourceProvenanceHash: ['SHA256']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "sourceProvenanceHash": ["SHA256"]
    }
}

machineType: Cloud Build bietet vier virtuelle Maschinentypen mit hoher CPU-Leistung zum Ausführen Ihrer Builds: zwei Maschinentypen mit 8 CPUs und zwei Maschinentypen mit 32 CPUs. Cloud Build bietet zwei zusätzliche VM-Typen mit 1 CPU und 2 CPUs zum Ausführen Ihrer Builds. Der Standardmaschinentyp ist e2-standard-2 mit 2 CPUs. Das Anfordern einer virtuellen Maschine mit hoher CPU-Anzahl kann die Startzeit Ihres Builds erhöhen. Fügen Sie die Option machineType hinzu, um eine virtuelle Maschine mit einer höheren CPU-Anzahl anzufordern:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 machineType: 'E2_HIGHCPU_8'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    },
    ],
    "options": {
        "machineType": "E2_HIGHCPU_8"
    }
}

Weitere Informationen zur Verwendung der Option machineType finden Sie unter Best Practices zur Beschleunigung von Builds.

diskSizeGb: Verwenden Sie die Option diskSizeGb, um eine benutzerdefinierte Laufwerkgröße für Ihren Build anzufordern. Die Die maximale Größe, die Sie anfordern können, beträgt 4.000 GB.

Das folgende Snippet fordert eine Laufwerkgröße von 200 GB an:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 diskSizeGb: '200'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "diskSizeGb": '200'
    }
}

logStreamingOption: Mit dieser Option geben Sie an, ob Sie Build-Logs in Cloud Storage streamen möchten. Standardmäßig erfasst Cloud Build nach Abschluss des Builds die Build-Logs. Diese Option gibt an, ob Sie Build-Logs in Echtzeit während des Build-Vorgangs streamen möchten. Das folgende Snippet gibt an, dass Build-Logs an Cloud Storage gestreamt werden:

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
options:
 logStreamingOption: STREAM_ON

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ]
    }
    ],
    "options": {
        "logStreamingOption": "STREAM_ON"
    }
}

logging: Verwenden Sie diese Option, um festzulegen, ob Sie Logs in Cloud Logging oder Cloud Storage speichern möchten. Wenn Sie diese Option nicht festlegen, speichert Cloud Build die Logs sowohl in Cloud Logging als auch in Cloud Storage. Sie können die Option logging auf GCS_ONLY setzen, damit die Logs nur in Cloud Storage gespeichert werden. Das folgende Snippet gibt an, dass die Logs in Cloud Storage gespeichert werden:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 logging: GCS_ONLY

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "logging": "GCS_ONLY"
    }
}

defaultLogsBucketBehavior: Mit der Option defaultLogsBucketBehavior können Sie Cloud Build so konfigurieren, dass ein Standard-Log-Bucket in Ihrem eigenen Projekt in derselben Region wie Ihr Build erstellt wird. Weitere Informationen finden Sie unter Build-Logs in einem nutzereigenen und regionalisierten Bucket speichern.

Mit der folgenden Build-Konfiguration wird das Feld defaultLogsBucketBehavior auf den Wert REGIONAL_USER_OWNED_BUCKET festgelegt:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'us-central1-docker.pkg.dev/myproject/myrepo/myimage', '.' ]
options:
  defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET

JSON

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/docker",
      "args": [
        "build",
        "-t",
        "us-central1-docker.pkg.dev/myproject/myrepo/myimage",
        "."
      ]
    }
    ],
    "options": {
      "defaultLogsBucketBehavior": "REGIONAL_USER_OWNED_BUCKET"
    }
}

dynamicSubstitutions: Mit dieser Option können Sie die Bash-Parametererweiterung explizit als Substitution aktivieren oder deaktivieren. Wenn Ihr Build von einem Trigger aufgerufen wird, ist das Feld dynamicSubstitutions immer auf "True" gesetzt und muss nicht in der Build-Konfigurationsdatei angegeben werden. Wenn Ihr Build manuell aufgerufen wird, müssen Sie das Feld dynamicSubstitutions auf "True" setzen, damit die Bash-Parametererweiterungen beim Ausführen des Builds interpretiert werden.

automapSubstitutions: Ordnen Sie alle Substitutionen automatisch Umgebungsvariablen zu, die während des gesamten Builds verfügbar sind. Beispiele finden Sie unter Ersetzen Sie Variablenwerte.

substitutionOption: In Verbindung mit dem Feld substitutions wird mit dieser Option das Verhalten für den Fall eines Fehlers bei den Substitutionsprüfungen festgelegt.

pool: Legen Sie den Wert dieses Felds auf den Ressourcennamen des privaten Pools fest, in dem der Build ausgeführt werden soll. Eine Anleitung zum Ausführen von Builds in einem privaten Pool finden Sie unter Builds in einem privaten Pool ausführen.

requestedVerifyOption: Setzen Sie den Wert von requestedVerifyOption auf VERIFIED, um die Generation von Attestierungen und Herkunftsmetadaten für Ihren Build. Nach dem Festlegen werden deine Builds nur mit SUCCESS gekennzeichnet wenn Attestierungen und Herkunft generiert werden.

substitutions

Verwenden Sie das Feld "substitutions" in Ihrer Build-Konfigurationsdatei dazu, bestimmte Variablen zum Build-Zeitpunkt zu ersetzen. Substitutionen sind für Variablen geeignet, deren Wert bis zur Erstellung des Builds nicht bekannt ist. Mit Substitutionen können Sie auch eine vorhandene Build-Anfrage mit anderen Variablenwerten wiederverwenden. Standardmäßig gibt der Build einen Fehler zurück, wenn eine Substitutionsvariable oder eine Substitution fehlt. Sie können aber diese Überprüfung mit der Option ALLOW_LOOSE überspringen.

Das folgende Snippet verwendet Substitutionen für die Ausgabe von "Hello World". Dabei ist die Substitutionsoption ALLOW_LOOSE festgelegt, d. h., der Build gibt keinen Fehler aus, wenn eine Substitutionsvariable oder eine Substitution fehlt.

YAML

steps:
- name: 'ubuntu'
  args: ['echo', 'hello ${_SUB_VALUE}']
substitutions:
    _SUB_VALUE: world
options:
    substitution_option: 'ALLOW_LOOSE'

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "hello ${_SUB_VALUE}"
        ]
    }
    ],
    "substitutions": {
        "_SUB_VALUE": "world"
},
    "options": {
        "substitution_option": "ALLOW_LOOSE"
    }
}

Hinweis: Wenn Ihr Build von einem Trigger aufgerufen wird, ist die Option ALLOW_LOOSE standardmäßig festgelegt. In diesem Fall gibt der Build keinen Fehler zurück, wenn eine Substitutionsvariable oder eine Substitution fehlt. Sie können die Option ALLOW_LOOSE für Builds, die durch Trigger aufgerufen werden, nicht überschreiben.

Weitere Anleitungen zur Verwendung von substitutions finden Sie unter Variablenwerte ersetzen.

tags

Verwenden Sie das Feld tags, um Ihre Builds in Gruppen zu organisieren und die Builds zu filtern. Mit der folgenden Konfiguration werden zwei Tags namens mytag1 und mytag2 festgelegt:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  ...
- name: 'ubuntu'
  ...
tags: ['mytag1', 'mytag2']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker"
    },
    {
        "name": "ubuntu"
    }
    ],
    "tags": [
        "mytag1",
        "mytag2"
    ]
}

availableSecrets

Verwenden Sie dieses Feld, um mit Cloud Build ein Secret aus Secret Manager zu verwenden. Weitere Informationen finden Sie unter Secrets verwenden.

secrets

Secret koppelt einen Satz geheimer Umgebungsvariablen, die verschlüsselte Werte enthalten, mit dem Cloud KMS-Schlüssel, der zum Entschlüsseln der Werte verwendet werden soll.

Hinweis: Verwenden Sie availableSecrets anstelle von secrets. Weitere Informationen finden Sie unter Secrets verwenden und Verschlüsselte Anmeldedaten verwenden.

serviceAccount

Geben Sie in diesem Feld das IAM-Dienstkonto an, das zum Build-Zeitpunkt verwendet werden soll. Weitere Informationen finden Sie unter Benutzerdefinierte Dienstkonten konfigurieren.

images

Das Feld images in der Build-Konfigurationsdatei gibt mindestens einen Linux-Docker an. Images, die von Cloud Build an Artifact Registry oder Container Registry übertragen werden (Eingestellt). Unter Umständen haben Sie einen Build, der Aufgaben ausführt, ohne Linux Docker-Images zu erstellen. Wenn Sie jedoch Images erstellen und diese nicht an das Registry übergeben, werden die Images nach Abschluss des Builds verworfen. Wenn ein angegebenes Image während des Build-Prozesses nicht erstellt wird, schlägt der Build fehl. Weitere Informationen Informationen zum Speichern von Bildern finden Sie unter Artefakte in Artifact Registry speichern.

Die folgende Build-Konfiguration legt das Feld imagesso fest, dass das Build-Image gespeichert wird:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
images: ['gcr.io/myproject/myimage']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "images": [
        "gcr.io/myproject/myimage"
    ]
}

artifacts

Das Feld artifacts in der Build-Konfigurationsdatei gibt mindestens ein Artefakt ohne Container an, das in Cloud Storage gespeichert werden soll. Weitere Informationen zu Nicht-Container-Artefakte speichern, finden Sie unter Build-Artefakte in Cloud Storage speichern.

Mit der folgenden Build-Konfiguration wird das Feld artifacts zum Speichern des erstellten Go-Pakets auf gs://mybucket/ festgelegt:

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['build', 'my-package']
artifacts:
  objects:
    location: 'gs://mybucket/'
    paths: ['my-package']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "build",
            "my-package"
        ]
    }
    ],
    "artifacts": {
      "objects": {
        "location": "gs://mybucket/",
        "paths": [
            "my-package"
        ]
      }
    }
}

mavenArtifacts

Mit dem Feld mavenArtifacts können Sie Java-Artefakte ohne Container in Maven-Repositories in Artifact Registry hochladen. Weitere Informationen finden Sie unter Java-Anwendungen erstellen und testen.

Die folgende Build-Konfiguration legt das Feld mavenArtifacts so fest, dass die gepackte Datei my-app-1.0-SNAPSHOT.jar in das Artifact Registry-Repository https://us-central1-maven.pkg.dev/my-project-id/my-java-repo hochgeladen wird:

YAML

artifacts:
  mavenArtifacts:
    - repository: 'https://us-central1-maven.pkg.dev/my-project-id/my-java-repo'
      path: '/workspace/my-app/target/my-app-1.0-SNAPSHOT.jar'
      artifactId: 'my-app-1'
      groupId: 'com.mycompany.app'
      version: '1.0.0'

JSON

{
  "artifacts": {
    "mavenArtifacts": [
      {
        "repository": "https://us-central1-maven.pkg.dev/my-project-id/my-java-repo",
        "path": "/workspace/my-app/target/my-app-1.0-SNAPSHOT.jar",
        "artifactId": "my-app-1",
        "groupId": "com.mycompany.app",
        "version": "1.0.0"
      }
    ]
  }
}

pythonPackages

Mit dem Feld pythonPackages können Sie Python-Pakete in Artifact Registry hochladen. Weitere Informationen finden Sie unter Python-Anwendungen erstellen und testen.

In der folgenden Build-Konfiguration wird das Feld pythonPackages so festgelegt, dass das Python-Paket dist/my-pkg.whl in das Artifact Registry-Repository https://us-east1-python.pkg.dev/my-project/my-repo hochgeladen wird:

YAML

artifacts:
  pythonPackages:
   - repository: 'https://us-east1-python.pkg.dev/my-project/my-repo'
     paths: ['dist/my-pkg.whl']

JSON

{
  "artifacts": {
    "pythonPackages": [
      {
        "repository": "https://us-east1-python.pkg.dev/my-project/my-repo",
        "paths": ["dist/my-pkg.whl"]
      }
    ]
  }
}

npmPackages

Mit dem Feld npmPackages können Sie Cloud Build so konfigurieren, dass Ihre erstellten npm-Pakete in unterstützte Repositories in Artifact Registry hochgeladen werden. Du musst geben Sie Werte für repository und packagePath an.

Das Feld repository gibt das Artifact Registry-Repository an, in dem die Datei gespeichert werden soll Pakete. Im Feld packagePath wird das lokale Verzeichnis angegeben, das das hochzuladende npm-Paket. Dieses Verzeichnis muss eine package.json-Datei enthalten.

Wir empfehlen die Verwendung eines absoluten Pfads für den Wert von packagePath. Sie können ., um auf das aktuelle Arbeitsverzeichnis zu verweisen, das Feld darf aber nicht weggelassen werden oder leer gelassen. Weitere Anleitungen zur Verwendung von npmPackages finden Sie unter Node.js-Anwendungen erstellen und testen.

In der folgenden Build-Konfiguration wird das Feld npmPackages so festgelegt, dass das npm-Paket im Verzeichnis /workspace/my-pkg in das Artifact Registry-Repository https://us-east1-npm.pkg.dev/my-project/my-repo hochgeladen wird.

YAML

artifacts:
  npmPackages:
   - repository: 'https://us-east1-npm.pkg.dev/my-project/my-repo'
     packagePath: '/workspace/my-pkg'

JSON

{
  "artifacts": {
    "npmPackages": [
      {
        "repository": "https://us-east1-npm.pkg.dev/my-project/my-repo",
        "packagePath": "/workspace/my-pkg"
      }
    ]
  }
}

Dockerfiles verwenden

Wenn Sie Docker-Builds in Cloud Build mit der gcloud CLI oder Build-Triggern ausführen, können Sie ein Dockerfile ohne separate Build-Konfigurationsdatei verwenden. Wenn Sie weitere Anpassungen an Ihren Docker-Builds vornehmen möchten, können Sie zusätzlich zum Dockerfile eine Build-Konfigurationsdatei bereitstellen. Eine Anleitung zum Erstellen eines Docker-Images mit einem Dockerfile finden Sie unter Kurzanleitung: Build.

Cloud Build-Netzwerk

Wenn Cloud Build jeden Build-Schritt ausführt, hängt es den Container des Schrittes an ein lokales Docker-Netzwerk mit dem Namen cloudbuild an. Das cloudbuild-Netzwerk hostet Standardanmeldedaten für Anwendungen (ADC), damit Google Cloud-Dienste Ihre Anmeldedaten automatisch finden können. Wenn Sie verschachtelte Docker-Container ausführen und an einen zugrunde liegenden Container senden oder gcloud in einem docker-Schritt verwenden, Verwenden Sie das Flag --network im Docker-Schritt build:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '--network=cloudbuild', '.']

JSON

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/docker",
      "args": [
        "build",
        "--network=cloudbuild",
        "."
      ]
   }
  ]
}

Weitere Informationen

• Mehr zum Erstellen einer einfachen Build-Konfigurationsdatei erfahren, um Builds für Cloud Build zu konfigurieren
• Mehr zur Ausführung von Builds in Cloud Build unter Builds manuell starten