Schema del file di configurazione di compilazione

Un file di configurazione di compilazione contiene istruzioni che consentono a Cloud Build di eseguire attività basate sulle tue specifiche. Ad esempio, il file di configurazione della build può contenere istruzioni per creare, pacchettizzare ed eseguire il push delle immagini Docker.

Questa pagina spiega lo schema del file di configurazione di Cloud Build. Per istruzioni sulla creazione e sull'utilizzo di un file di configurazione di compilazione, consulta Creazione di un file di configurazione di compilazione di base.

Struttura di un file di configurazione della build

I file di configurazione di compilazione vengono modellati utilizzando la risorsa Build dell'API Cloud Build.

Puoi scrivere il file di configurazione della build utilizzando la sintassi YAML o JSON. Se invii richieste di build utilizzando strumenti HTTP di terze parti come curl, utilizza la sintassi JSON.

Nota: se usi VS Code o IDE IntelliJ, puoi usare Cloud Code per creare i file di configurazione YAML. Cloud Code è integrato nell'editor di Cloud Shell e non richiede alcuna configurazione. Per ulteriori informazioni, consulta Cloud Code for VS Code e Cloud Code for IntelliJ.

Un file di configurazione di compilazione ha la seguente struttura:

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

Ognuna delle sezioni del file di configurazione della build definisce una parte dell'attività che vuoi che Cloud Build esegua:

Passi build

Un passaggio di build specifica un'azione che vuoi che venga eseguita da Cloud Build. Per ogni passaggio di build, Cloud Build esegue un container Docker come istanza di docker run. I passaggi di build sono simili ai comandi in uno script e ti offrono la flessibilità necessaria per eseguire istruzioni arbitrarie nella build. Se puoi pacchettizzare uno strumento di creazione in un container, Cloud Build può eseguirlo come parte della tua build. Per impostazione predefinita, Cloud Build esegue in serie tutti i passaggi di una build sulla stessa macchina. Se sono presenti passaggi che possono essere eseguiti contemporaneamente, utilizza l'opzione waitFor.

Nel file di configurazione puoi includere fino a 300 passi di build.

Utilizza il campo steps nel file di configurazione della build per specificare un passaggio di build. Di seguito è riportato uno snippet del tipo di configurazione che potresti impostare nel campo steps:

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

Utilizza il campo name di un passaggio di build per specificare un cloud builder, ovvero un'immagine container che esegue strumenti comuni. Per eseguire le tue attività, utilizzi un builder in un passaggio di build.

Lo snippet seguente mostra i passaggi di build che chiamano i builder bazel, gcloud e docker:

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

Il campo args di un passaggio di build accetta un elenco di argomenti e li passa al generatore a cui fa riferimento il campo name. Gli argomenti passati al builder vengono passati allo strumento in esecuzione nel builder, il che consente di richiamare qualsiasi comando supportato dallo strumento. Se il generatore utilizzato nel passaggio di build ha un punto di ingresso, gli argomenti verranno utilizzati come argomenti per tale punto di ingresso. Se il builder non definisce un punto di ingresso, il primo elemento degli argomenti verrà utilizzato come punto di ingresso, mentre il resto verrà usato come argomenti.

Puoi creare fino a 100 argomenti per passaggio. La lunghezza massima dell'argomento è di 10.000 caratteri.

Lo snippet seguente richiama il comando docker build e installa le dipendenze Maven:

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

Il campo env di un passaggio di build richiede un elenco di variabili di ambiente da utilizzare durante l'esecuzione del passaggio. Le variabili sono nel formato KEY=VALUE.

Nella seguente configurazione di compilazione, il campo env del passaggio di build imposta la zona Compute Engine e il cluster GKE prima dell'esecuzione kubectl:

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

Utilizza il campo dir in un passaggio della build per impostare una directory di lavoro da utilizzare per l'esecuzione del container del passaggio. Se imposti il campo dir nel passaggio della build, la directory di lavoro è impostata su /workspace/<dir>. Se questo valore è un percorso relativo, sarà relativo alla directory di lavoro della build. Se questo valore è assoluto, potrebbe essere esterno alla directory di lavoro della build, nel qual caso i contenuti del percorso potrebbero non essere resi persistenti nelle esecuzioni dei passaggi della build (a meno che non venga specificato un volume per quel percorso).

Il seguente snippet di codice imposta la directory di lavoro per il passaggio della build come /workspace/examples/hello_world:

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

Utilizza il campo timeout in un passaggio della build per impostare un limite di tempo per l'esecuzione del passaggio. Se non imposti questo campo, il passaggio non ha limiti di tempo e potrà essere eseguito fino al completamento o fino al timeout della build. Il campo timeout in un passaggio di build non deve superare il valore timeout specificato per una build. timeout deve essere specificato in secondi con un massimo di nove cifre frazionarie, terminate con una "s". Esempio: 3.5s

Nella configurazione di build seguente, il passaggio ubuntu scade dopo 500 secondi:

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

Nota: il campo timeout esiste sia per il passaggio di build sia per la build: il campo timeout di un passaggio di build specifica per quanto tempo può essere eseguito il passaggio, mentre il campo timeout di una build specifica il tempo per cui la build può essere eseguita.

copione

Utilizza il campo script in un passaggio di build per specificare uno script shell da eseguire nel passaggio. Se specifichi script in un passaggio di build, non puoi specificare args o entrypoint nello stesso passaggio. Per istruzioni sull'utilizzo del campo script, consulta la sezione Esecuzione di script bash.

id

Utilizza il campo id per impostare un identificatore univoco per un passaggio di build. id viene utilizzato con il campo waitFor per configurare l'ordine in cui devono essere eseguiti i passi di build. Per istruzioni sull'utilizzo di waitFor e id, consulta Configurazione dell'ordine dei passaggi di build.

waitFor

Utilizza il campo waitFor in un passaggio di build per specificare quali passaggi devono essere eseguiti prima dell'esecuzione del passaggio. Se non vengono forniti valori per waitFor, il passaggio di build attende che tutti i passaggi di build precedenti nella richiesta di build vengano completati correttamente prima dell'esecuzione. Per istruzioni sull'utilizzo di waitFor e id, consulta Configurazione dell'ordine dei passaggi di build.

entrypoint

Usa entrypoint in un passaggio di build per specificare un punto di ingresso se non vuoi utilizzare quello predefinito del builder. Se non imposti questo campo, Cloud Build utilizzerà il punto di ingresso del builder. Lo snippet seguente imposta gli entry point per il passaggio di build npm:

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

Un elenco di variabili di ambiente criptate con una chiave di crittografia Cloud KMS. Questi valori devono essere specificati nei secret della build. Per informazioni sull'utilizzo di questo campo, consulta Utilizzo della variabile criptata nelle richieste di build.

volumes

Un volume è un volume di container Docker montato nei passaggi di build per rendere persistenti i file in tutti i passaggi di build. Quando Cloud Build esegue un passaggio di build, monta automaticamente un volume workspace in /workspace. Puoi specificare volumi aggiuntivi da montare nei container dei passaggi di build utilizzando il campo volumes per i passaggi.

Ad esempio, il seguente file di configurazione di compilazione scrive un file in un volume nel primo passaggio e lo legge nel secondo. Se in questi passaggi non è stato specificato il percorso /persistent_volume come volume permanente, il primo passaggio scriverebbe il file in quel percorso, quindi il file verrà ignorato prima dell'esecuzione del secondo passaggio. Specificando il volume con lo stesso nome in entrambi i passaggi, i contenuti di /persistent_volume nel primo passaggio vengono mantenuti fino al secondo passaggio.

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

In un passaggio di build, se imposti il valore del campo allowFailure su true e il passaggio di build non va a buon fine, la build ha esito positivo purché tutti gli altri passaggi della build abbiano esito positivo.

Se tutti i passaggi di build in una build hanno allowFailure impostato su true e tutti i passaggi hanno esito negativo, lo stato della build è ancora Successful.

allowExitCodes ha la precedenza su questo campo.

Lo snippet di codice riportato di seguito consente la riuscita della build quando il primo passaggio non va a buon fine:

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

Utilizza il campo allowExitCodes per specificare che un errore del passaggio di build può essere ignorato quando questo passaggio restituisce un particolare codice di uscita.

Se un passaggio di build non va a buon fine con un codice di uscita corrispondente al valore fornito in allowExitCodes, Cloud Build consentirà un errore di questo passaggio senza causare errori nell'intera build.

Se il 100% dei passaggi della build non riesce, ma ogni passaggio termina con un codice che hai specificato nel campo allowExitCodes, la build ha esito positivo.

Tuttavia, se il passaggio di build non va a buon fine e produce un altro codice di uscita (uno che non corrisponde al valore specificato in allowExitCodes), la build complessiva avrà esito negativo.

Il codice o i codici di uscita pertinenti alla build dipendono dal software. Ad esempio, "1" è un codice di uscita comune in Linux. Puoi anche definire codici di uscita personalizzati negli script. Il campo allowExitCodes accetta numeri fino a un massimo di 255.

Questo campo ha la precedenza su allowFailure.

Lo snippet di codice riportato di seguito consente la riuscita della build quando il primo passaggio non va a buon fine con uno dei codici di uscita forniti:

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

Utilizza il campo timeout per una build per specificare per quanto tempo deve essere consentita l'esecuzione della build, al secondo livello di granularità. Se questo tempo scade, il lavoro sulla build verrà interrotto e lo stato della build sarà TIMEOUT. Se timeout non è impostato, alla build verrà applicato un valore predefinito di timeout di 60 minuti. Il valore massimo che può essere applicato a timeout è 24 ore. timeout deve essere specificato in secondi con un massimo di nove cifre frazionarie, terminate con una "s". Esempio: 3.5s

Nel seguente snippet, l'elemento timeout è impostato su 660 secondi per evitare il timeout della build a causa del sonno:

YAML

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

JSON

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

Nota: il campo timeout esiste sia per il passaggio di build che per la build: il campo timeout di un passaggio di build specifica la quantità di tempo per cui il passaggio può essere eseguito, mentre il campo timeout di una build specifica il tempo di esecuzione della build.

queueTtl

Utilizza il campo queueTtl per specificare per quanto tempo una build può essere messa in coda. Se una build rimane in coda per un tempo maggiore rispetto al valore impostato in queueTtl, la build scade e lo stato della build è impostato su EXPIRED. Se non viene fornito alcun valore, Cloud Build utilizza il valore predefinito di 3600s (1 ora). queueTtl inizia a spuntare dal giorno createTime. queueTtl deve essere specificato in secondi con un massimo di nove cifre frazionarie, terminate con una "s", ad esempio 3.5s.

Nello snippet seguente, timeout è impostato su 20s e queueTtl è impostato su 10s. Il valore di queueTtl inizia alle ore createTime, ossia l'ora in cui viene richiesta la build, mentre timeout inizia alle ore startTime, ovvero il momento in cui viene avviata la build. Di conseguenza, queueTtl scadrà il giorno createTime + 10s, a meno che la build non inizi entro questa data.

YAML

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

JSON

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

logsBucket

Imposta il campo logsBucket per una build per specificare un bucket Cloud Storage in cui devono essere scritti i log. Se non imposti questo campo, Cloud Build utilizzerà un bucket predefinito per archiviare i log di build.

Lo snippet seguente imposta un bucket di log per l'archiviazione dei log di build:

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

Utilizza il campo options per specificare i seguenti argomenti facoltativi per la build:

env: un elenco di definizioni delle variabile di ambiente globali che saranno disponibili per tutti i passaggi di build di questa build. Se viene definita una variabile sia a livello globale sia in un passaggio di build, la variabile utilizzerà il valore del passaggio di build. Gli elementi sono nel formato KEY=VALUE per la variabile di ambiente KEY con il valore VALUE.

secretEnv: un elenco di variabili di ambiente globali, criptate mediante una chiave di crittografia di Cloud Key Management Service, che sarà disponibile per tutti i passaggi della build in questa build. Questi valori devono essere specificati nel Secret della build.

volumes: un elenco di volumi da montare a livello globale per TUTTI i passaggi della build. Ogni volume viene creato come volume vuoto prima di iniziare il processo di compilazione. Al completamento della build, i volumi e i relativi contenuti vengono eliminati. I nomi e i percorsi dei volumi globali non possono essere in conflitto con i volumi definiti in un passaggio di build. L'utilizzo di un volume globale in una build con un solo passaggio non è valido, in quanto indica una richiesta di build con una configurazione non corretta.

sourceProvenanceHash: imposta l'opzione sourceProvenanceHash per specificare l'algoritmo hash per la provenienza dell'origine. Il seguente snippet specifica che l'algoritmo hash è SHA256:

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 offre quattro tipi di macchine virtuali con CPU elevata per eseguire le tue build: due tipi di macchine con 8 CPU e due tipi di macchine con 32 CPU. Cloud Build fornisce inoltre due tipi di macchine virtuali aggiuntivi con 1 CPU e 2 CPU per eseguire le tue build. Il tipo di macchina predefinito è e2-standard-2 con 2 CPU. La richiesta di una macchina virtuale con CPU elevata può aumentare il tempo di avvio della tua build. Aggiungi l'opzione machineType per richiedere una macchina virtuale con una CPU più elevata:

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

Per ulteriori informazioni sull'utilizzo dell'opzione machineType, consulta la sezione Velocizzare le build.

diskSizeGb: utilizza l'opzione diskSizeGb per richiedere una dimensione del disco personalizzata per la tua build. La dimensione massima che puoi richiedere è 2000 GB.

Lo snippet seguente richiede una dimensione disco di 200 GB:

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: utilizza questa opzione per specificare se vuoi trasmettere i log di build a Cloud Storage. Per impostazione predefinita, Cloud Build raccoglie i log di build al completamento della build. Questa opzione specifica se vuoi trasmettere i log di build in tempo reale durante il processo di compilazione. Lo snippet seguente specifica che i log di build vengono trasmessi in flussi a Cloud Storage:

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: utilizza questa opzione per specificare se vuoi archiviare i log in Cloud Logging o Cloud Storage. Se non imposti questa opzione, Cloud Build archivia i log sia in Cloud Logging che in Cloud Storage. Puoi impostare l'opzione logging su GCS_ONLY per archiviare i log solo in Cloud Storage. Lo snippet seguente specifica che i log vengono archiviati in Cloud Storage:

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: l'opzione defaultLogsBucketBehavior consente di configurare Cloud Build per creare un bucket di log predefinito all'interno del tuo progetto nella stessa regione della build. Per saperne di più, vedi Archiviare i log di build in un bucket di proprietà dell'utente e a livello di regione.

La seguente configurazione di compilazione imposta il campo defaultLogsBucketBehavior sul valore REGIONAL_USER_OWNED_BUCKET:

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: Utilizza questa opzione per attivare o disattivare esplicitamente l'espansione dei parametri bash nelle sostituzioni. Se la build viene richiamata da un trigger, il campo dynamic_substitutions è sempre impostato su true e non deve essere specificato nel file di configurazione della build. Se la build viene richiamata manualmente, devi impostare il campo dynamic_substitutions su true affinché le espansioni dei parametri bash vengano interpretate durante l'esecuzione della build.

substitutionOption: Imposta questa opzione insieme al campo substitutions di seguito per specificare il comportamento in caso di errore nei controlli di sostituzione.

pool: Imposta il valore di questo campo sul nome della risorsa del pool privato per l'esecuzione della build. Per istruzioni sull'esecuzione di una build su un pool privato, consulta Esecuzione di build in un pool privato.

requestedVerifyOption: imposta il valore di requestedVerifyOption su VERIFIED per verificare la generazione di attestazioni e metadati di prova per la build. Questa opzione abilita inoltre attestazioni e metadati di provenienza per build e build a livello di regione in pool privati. Se non aggiungi requestedVerifyOption: VERIFIED, Cloud Build genera la provenienza solo per le build globali.

substitutions

Utilizza sostituzioni nel file di configurazione della build per sostituire variabili specifiche in fase di compilazione. Le sostituzioni sono utili per le variabili il cui valore non è noto fino alla fase di compilazione o per riutilizzare una richiesta di build esistente con valori di variabili diversi. Per impostazione predefinita, la build restituisce un errore se manca una variabile di sostituzione o una sostituzione mancante. Tuttavia, puoi utilizzare l'opzione ALLOW_LOOSE per saltare questo controllo.

Lo snippet seguente utilizza le sostituzioni per stampare "hello world". L'opzione di sostituzione ALLOW_LOOSE è impostata, il che significa che la build non restituirà un errore in caso di variabile di sostituzione mancante o mancante.

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

Nota: se la build viene richiamata da un trigger, l'opzione ALLOW_LOOSE è impostata per impostazione predefinita. In questo caso, la tua build non restituirà un errore se manca una variabile di sostituzione o una sostituzione mancante. Non puoi eseguire l'override dell'opzione ALLOW_LOOSE per le build richiamate dai trigger.

Per ulteriori istruzioni sull'utilizzo di substitutions, consulta Sostituzione dei valori delle variabili.

tags

Utilizza il campo tags per organizzare le build in gruppi e per filtrare le build. La configurazione seguente imposta due tag denominati mytag1 e mytag2:

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

Utilizza questo campo per utilizzare un secret di Secret Manager con Cloud Build. Per ulteriori informazioni, vedi Utilizzare i secret.

secrets

Il secret accoppia un insieme di variabili di ambiente secret contenenti valori criptati con la chiave Cloud KMS da utilizzare per decriptare il valore.

Nota: utilizza availableSecrets anziché secrets. Per maggiori informazioni, vedi Utilizzare i secret e Utilizzare le credenziali criptate.

serviceAccount

Utilizza questo campo per specificare l'account di servizio IAM da utilizzare al momento della compilazione. Per saperne di più, consulta Configurazione degli account di servizio specificati dall'utente.

images

Il campo images nel file di configurazione della build specifica una o più immagini Docker Linux di cui Cloud Build deve eseguire il push ad Artifact Registry o Container Registry (deprecato). Potresti avere una build che esegue attività senza generare immagini Docker di Linux, ma se crei le immagini e non le esegui nel registro, le immagini vengono eliminate al completamento della build. Se durante la build non viene prodotta un'immagine specificata, la build avrà esito negativo. Per ulteriori informazioni sull'archiviazione delle immagini, consulta Archiviare gli artefatti in Artifact Registry.

La seguente configurazione di build imposta il campo images per archiviare l'immagine creata:

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

Il campo artifacts nel file di configurazione della build specifica uno o più artefatti non containerizzati da archiviare in Cloud Storage. Per ulteriori informazioni sull'archiviazione di artefatti non containerizzati, consulta Archiviare gli artefatti delle build in Cloud Storage.

La seguente configurazione di compilazione imposta il campo artifacts per archiviare il pacchetto Go creato su gs://mybucket/:

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

Il campo mavenArtifacts consente di caricare artefatti Java non containerizzati nei repository Maven in Artifact Registry. Per saperne di più, vedi Creare e testare applicazioni Java.

La seguente configurazione di compilazione imposta il campo mavenArtifacts per caricare il file in pacchetto my-app-1.0-SNAPSHOT.jar nel repository di Artifact Registry https://us-central1-maven.pkg.dev/my-project-id/my-java-repo:

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

Il campo pythonPackages consente di caricare pacchetti Python in Artifact Registry. Per saperne di più, vedi Creare e testare le applicazioni Python.

La seguente configurazione di compilazione imposta il campo pythonPackages per caricare il pacchetto Python dist/my-pkg.whl nel repository di Artifact Registry https://us-east1-python.pkg.dev/my-project/my-repo:

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

Utilizza il campo npmPackages per configurare Cloud Build in modo da caricare i pacchetti npm creati nei repository supportati in Artifact Registry. Devi fornire valori per repository e packagePath.

Il campo repository specifica il repository Artifact Registry in cui archiviare i pacchetti. Il campo packagePath specifica la directory locale che contiene il pacchetto npm da caricare. Questa directory deve contenere un file package.json.

Ti consigliamo di utilizzare un percorso assoluto per il valore di packagePath. Puoi utilizzare . per fare riferimento alla directory di lavoro attuale, ma il campo non può essere omesso o lasciato vuoto. Per ulteriori istruzioni sull'utilizzo di npmPackages, vedi Creare e testare le applicazioni Node.js.

La seguente configurazione di compilazione imposta il campo npmPackages per caricare il pacchetto npm nella directory /workspace/my-pkg nel repository Artifact Registry https://us-east1-npm.pkg.dev/my-project/my-repo.

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

Utilizzo dei Dockerfile

Se esegui build Docker in Cloud Build utilizzando l'interfaccia alla gcloud CLI o i trigger di build, puoi utilizzare una Dockerfile senza un file di configurazione della build separato. Se vuoi apportare ulteriori modifiche alle build Docker, puoi fornire un file di configurazione della build oltre a Dockerfile. Per istruzioni su come creare un'immagine Docker utilizzando un Dockerfile, consulta la Guida rapida: build.

Rete Cloud Build

Quando Cloud Build esegue ogni passaggio di build, collega il container del passaggio a una rete Docker locale denominata cloudbuild. La rete cloudbuild ospita le credenziali predefinite dell'applicazione (ADC) che i servizi Google Cloud possono utilizzare per trovare automaticamente le tue credenziali. Se esegui container Docker nidificati e vuoi esporre l'ADC a un container sottostante o utilizzare gsutil o gcloud in un passaggio docker, utilizza il flag --network nel passaggio build Docker:

YAML

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

JSON

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

Passaggi successivi

• Scopri come creare un file di configurazione delle build di base per configurare le build per Cloud Build.
• Consulta la pagina Avvio manuale di una build per le istruzioni su come eseguire le build in Cloud Build.