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.

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

Skript

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

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 festlegen und der Build-Schritt fehlschlägt, ist der Build erfolgreich, solange alle anderen Build-Schritte in diesem Build erfolgreich sind.

Wenn allowFailure für alle Build-Schritte in einem Build auf true gesetzt ist und alle Build-Schritte fehlschlagen, ist der Build-Status immer noch Successful.

allowExitCodes hat Vorrang vor diesem Feld.

Das folgende Code-Snippet sorgt dafür, dass der Build erfolgreich ist, 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

Geben Sie im Feld allowExitCodes an, dass ein fehlgeschlagener Build-Schritt ignoriert werden kann, wenn bei diesem Schritt ein bestimmter Exit-Code zurückgegeben wird.

Wenn ein Build-Schritt mit einem Exit-Code fehlschlägt, der mit dem Wert in allowExitCodes übereinstimmt, schlägt 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 beendet wird, den Sie im Feld allowExitCodes angegeben haben, ist der Build trotzdem erfolgreich.

Wenn der Build-Schritt jedoch fehlschlägt und ein weiterer Exit-Code generiert wird, der nicht mit dem Wert in allowExitCodes übereinstimmt, schlägt der gesamte Build fehl.

Die für Ihren Build relevanten Exit-Codes hängen von Ihrer Software ab. „1“ ist beispielsweise ein gängiger Exit-Code unter Linux. Sie können in Ihren Skripts auch eigene Exit-Codes definieren. In das Feld allowExitCodes können Zahlen bis zu 255 eingegeben werden.

Dieses Feld hat Vorrang vor allowFailure.

Das folgende Code-Snippet ermöglicht den Build, wenn der erste Schritt mit einem der angegebenen Exit-Codes 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 timeout nicht festgelegt ist, gilt ein Standard-timeout von 60 Minuten auf den Build. 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"
}

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 bei createTime. queueTtl muss in Sekunden mit bis zu neun Nachkommastellen mit einem „s“ am Ende angegeben werden, z. B. 3.5s.

Im folgenden Snippet ist timeout auf 20s und queueTtl auf 10s festgelegt. queueTtl beginnt um createTime (die Uhrzeit, zu der der Build angefordert wird) und timeout beginnt um startTime (die Startzeit des Builds). Daher läuft queueTtl bei createTime + 10s ab, es sei denn, der Build beginnt zu diesem Zeitpunkt.

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 außerdem 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 verlängern. 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 maximale Größe, die Sie anfordern können, beträgt 2.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 Projekt in derselben Region wie Ihr Build erstellt wird. Weitere Informationen finden Sie unter Build-Logs in einem nutzereigenen und regionalisierten Bucket speichern.

Die folgende Build-Konfiguration legt das Feld defaultLogsBucketBehavior auf den Wert REGIONAL_USER_OWNED_BUCKET fest:

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

dynamic_substitutions: 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 dynamic_substitutions immer auf "True" gesetzt und muss nicht in der Build-Konfigurationsdatei angegeben werden. Wenn Ihr Build manuell aufgerufen wird, müssen Sie das Feld dynamic_substitutions auf "True" setzen, damit die Bash-Parametererweiterungen beim Ausführen des Builds interpretiert werden.

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: Legen Sie den Wert von requestedVerifyOption auf VERIFIED fest, um die Generierung von attestations und Herkunftsmetadaten für Ihren Build zu prüfen. Diese Option aktiviert auch Attestierungen und Herkunftsmetadaten für regionale Builds und Builds in privaten Pools. Wenn Sie requestedVerifyOption: VERIFIED nicht hinzufügen, generiert Cloud Build die Herkunft nur für globale Builds.

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.

Im folgenden Snippet werden Substitutionen verwendet, um "Hello World" auszugeben. Die Substitutionsoption ALLOW_LOOSE ist festgelegt. Das bedeutet, dass der Build keinen Fehler zurückgibt, 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"
    }
}

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.

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 ein oder mehrere Linux Docker-Images an, die von Cloud Build an Artifact Registry oder Container Registry übertragen werden (eingestellt). Möglicherweise haben Sie einen Build, der Aufgaben ausführt, ohne Linux-Docker-Images zu erstellen. Wenn Sie jedoch Images erstellen und diese nicht in die Registry hochladen, 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 zum Speichern von Images 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 zum Speichern von Artefakten ohne Container 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.

Mit der folgenden Build-Konfiguration wird das Feld mavenArtifacts so festgelegt, 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.

Mit 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

Verwenden Sie das Feld npmPackages, um Cloud Build so zu konfigurieren, dass Ihre erstellten npm-Pakete in unterstützte Repositories in Artifact Registry hochgeladen werden. Sie müssen Werte für repository und packagePath angeben.

Das Feld repository gibt das Artifact Registry-Repository zum Speichern Ihrer Pakete an. Das Feld packagePath gibt das lokale Verzeichnis an, das das hochzuladende npm-Paket enthält. Dieses Verzeichnis muss eine package.json-Datei enthalten.

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

Mit 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 über die gcloud CLI oder Build-Trigger ausführen, können Sie einen Dockerfile ohne separate Build-Konfigurationsdatei verwenden. Wenn Sie weitere Anpassungen an Ihren Docker-Builds vornehmen möchten, können Sie zusätzlich zu Dockerfile eine Build-Konfigurationsdatei angeben. Eine Anleitung zum Erstellen eines Docker-Images mit einem Dockerfile finden Sie in der 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 ADC einem darunter liegenden Container anbieten möchten oder gsutil oder gcloud in einem docker-Schritt verwenden möchten, verwenden Sie das Flag --network in Ihrem Docker-build-Schritt

YAML

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

JSON

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

Nächste Schritte