빌드 구성 파일에는 Cloud Build가 사양에 따라 태스크를 수행하는 방법에 대한 안내가 포함되어 있습니다. 예를 들어 빌드 구성 파일에 Docker 이미지를 빌드하고, 패키징하고, 내보내는 안내가 포함될 수 있습니다.
이 페이지에서는 Cloud Build 구성 파일의 스키마를 설명합니다. 빌드 구성 파일 만들기 및 사용에 대한 자세한 내용은 기본 빌드 구성 파일 만들기를 참조하세요.
빌드 구성 파일의 구조
빌드 구성 파일은 Cloud Build API의 Build
리소스를 사용하여 모델링됩니다.
빌드 구성 파일은 YAML 또는 JSON 문법을 사용하여 작성할 수 있습니다. curl과 같은 타사 http 도구를 사용하여 빌드 요청을 제출하는 경우 JSON 문법을 사용하세요.
빌드 구성 파일의 구조는 다음과 같습니다.
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",
"..."
]
}
빌드 구성 파일의 각 섹션은 Cloud Build에서 실행할 작업의 일부를 정의합니다.
빌드 단계
빌드 단계는 Cloud Build가 수행해야 하는 작업을 가리킵니다. 각 빌드 단계에서 Cloud Build는 docker run
의 인스턴스로 Docker 컨테이너를 실행합니다. 빌드 단계는 스크립트의 명령어와 유사하며, 빌드에서 임의의 명령을 실행할 수 있는 유연성을 제공합니다. 빌드 도구를 컨테이너에 패키징할 수 있으면 Cloud Build가 빌드의 일부로 이를 실행할 수 있습니다. 기본적으로 Cloud Build는 동일한 머신에서 빌드의 모든 단계를 순차적으로 실행합니다.
동시에 실행할 수 있는 단계가 있는 경우 waitFor 옵션을 사용하세요.
구성 파일에는 최대 300개의 빌드 단계를 포함할 수 있습니다.
빌드 구성 파일의 steps
필드를 사용하여 빌드 단계를 지정합니다. 다음은 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
일반적인 도구를 실행하는 컨테이너 이미지인 클라우드 빌더를 지정하려면 빌드 단계의 name
필드를 사용합니다. 빌드 단계에서 빌더를 사용하여 작업을 실행합니다.
다음 스니펫은 bazel
, gcloud
, 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
빌드 단계의 args
필드는 인수 목록을 가져오고 name
필드로 참조되는 빌더에 전달합니다. 빌더에 전달된 인수는 빌더에서 실행 중인 도구에 전달되고, 이 도구에서 지원하는 모든 명령어를 호출하는 데 사용할 수 있습니다. 빌드 단계에서 사용된 빌더에 진입점이 있으면 args가 해당 진입점에 대한 인수로 사용됩니다. 빌더가 진입점을 정의하지 않으면 args의 첫 번째 요소가 진입점으로 사용되며 나머지는 인수로 사용됩니다.
단계당 최대 100개의 인수를 만들 수 있습니다. 최대 인수 길이는 10,000자(영문 기준)입니다.
다음 스니펫은 docker build
명령어를 호출하고 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
빌드 단계의 env
필드는 단계를 실행할 때 사용할 환경 변수 목록을 가져옵니다. 변수의 형식은 KEY=VALUE
입니다.
다음 빌드 구성에서 빌드 단계의 env
필드는 kubectl
을 실행하기 전에 Compute Engine 영역과 GKE 클러스터를 설정합니다.
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
단계 컨테이너를 실행할 때 사용할 작업 디렉터리를 설정하려면 빌드 단계의 dir
필드를 사용합니다. 빌드 단계에 dir
필드를 설정하면 작업 디렉터리가 /workspace/<dir>
로 설정됩니다. 이 값이 상대 경로이면 빌드의 작업 디렉터리와 상대적 관계를 갖습니다. 이 값이 절대 경로이면 빌드 작업 디렉터리 외부에 있을 수 있습니다. 이 경우 경로의 내용이 빌드 단계가 실행되는 동안 지속되지 않을 수 있습니다(해당 경로의 볼륨이 지정되지 않은 경우).
다음 코드 스니펫은 빌드 단계의 작업 디렉터리를 /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
단계 실행에 대한 시간 제한을 설정하려면 빌드 단계의 timeout
필드를 사용합니다. 이 필드를 설정하지 않으면 단계에 시간 제한이 적용되지 않으며 단계가 완료되거나 빌드 자체가 제한 시간을 초과할 때까지 실행이 허용됩니다. 빌드 단계의 timeout
필드는 빌드에 지정된 timeout
값을 초과하지 않아야 합니다. timeout
은 최대 9자리 소수의 초 단위로 지정되고 's'로 끝나야 합니다. 예시: 3.5s
다음 빌드 구성에서는 500초 후에 ubuntu
단계의 제한 시간이 초과됩니다.
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"
]
}
]
}
스크립트
빌드 단계에서 실행할 셸 스크립트를 지정하려면 그 단계의 script
필드를 사용합니다. 빌드 단계에서 script
를 지정하면 동일한 단계에서 args
또는 entrypoint
를 지정할 수 없습니다. script
필드 사용에 대한 자세한 내용은 bash 스크립트 실행을 참조하세요.
automapSubstitutions
true
로 설정하면 모든 대체 항목을 자동으로 매핑하고 한 번에 환경 변수로 사용할 수 있게 됩니다. false
로 설정하면 해당 단계에 대한 대체를 무시합니다. 예시는 대체 변수 값을 참고하세요.
id
빌드 단계의 고유 식별자를 설정하려면 id
필드를 사용합니다. id
는 waitFor
필드와 함께 사용되어 빌드 단계 실행 순서를 구성합니다. waitFor
및 id
를 사용하는 방법은 빌드 단계 순서 구성을 참조하세요.
waitFor
빌드 단계의 waitFor
필드를 사용하여 이 단계보다 먼저 실행해야 하는 단계를 지정합니다. waitFor
에 지정된 값이 없으면 빌드 단계는 빌드 요청의 모든 이전 빌드 단계가 완료될 때까지 기다린 후에 실행됩니다. waitFor
및 id
를 사용하는 방법은 빌드 단계 순서 구성을 참조하세요.
entrypoint
빌더의 기본 진입점을 사용하지 않으려면 빌드 단계의 entrypoint
를 사용하여 진입점을 지정합니다. 이 필드를 설정하지 않으면 Cloud 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
Cloud KMS 암호화 키를 사용하여 암호화된 환경 변수 목록. 이러한 값은 빌드의 비밀번호에 지정되어야 합니다. 이 필드를 사용하는 방법에 대한 자세한 내용은 빌드 요청에 암호화된 변수 사용을 참조하세요.
volumes
볼륨은 빌드 단계에서 파일을 유지하고자 빌드 단계에 마운트되는 Docker 컨테이너 볼륨입니다. Cloud Build가 빌드 단계를 실행하면 workspace
볼륨을 /workspace
에 자동으로 마운트합니다. 단계에 volumes
필드를 사용하여 빌드 단계의 컨테이너에 마운트할 추가 볼륨을 지정할 수 있습니다.
예를 들어 다음 빌드 구성 파일은 첫 번째 단계의 볼륨에 파일을 쓰고 두 번째 단계에서 읽습니다. 이 단계에서 /persistent_volume
경로를 영구 볼륨으로 지정하지 않으면 첫 번째 단계에서 해당 경로에 파일을 쓰고 두 번째 단계가 실행되기 전에 해당 파일이 삭제됩니다. 두 단계에 동일한 이름의 볼륨을 지정하면 첫 번째 단계에서 /persistent_volume
의 내용이 두 번째 단계에서도 유지됩니다.
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
빌드 단계에서 allowFailure
필드의 값을 true
로 설정했는데 빌드 단계가 실패하는 경우, 해당 빌드의 다른 모든 빌드 단계가 성공하는 한 빌드도 성공합니다.
빌드의 모든 빌드 단계에 allowFailure
가 true
로 설정되어 있고 모든 빌드 단계가 실패한 경우에도 빌드 상태는 Successful
입니다.
allowExitCodes
가 이 필드보다 우선합니다.
다음 코드 스니펫을 사용하면 첫 번째 단계가 실패할 때 빌드가 성공할 수 있습니다.
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
allowExitCodes
필드를 사용하여 빌드 단계에서 특정 종료 코드를 반환하면 해당 단계의 실패가 무시되도록 지정합니다.
allowExitCodes
에 제공한 값과 일치하는 종료 코드로 빌드 단계가 실패하면 Cloud Build는 전체 빌드에 실패하지 않고 이 빌드 단계를 실패하도록 할 수 있습니다.
빌드 단계가 100% 실패했지만 모든 단계가 allowExitCodes
필드에 지정한 코드로 종료되면 빌드가 계속 성공합니다.
그러나 빌드 단계가 실패하여 다른 종료 코드(allowExitCodes
에 지정한 값과 일치하지 않는 코드)가 생성되면 전체 빌드가 실패합니다.
빌드와 관련된 종료 코드는 소프트웨어에 따라 다릅니다. 예: '1'은 Linux에서 일반적인 종료 코드입니다. 또한 스크립트에서 고유한 종료 코드를 정의할 수도 있습니다. allowExitCodes
입력란에는 최대 255자의 숫자를 입력할 수 있습니다.
이 필드는 allowFailure
보다 우선 적용됩니다.
다음 코드 스니펫을 사용하면 첫 번째 단계가 제공된 종료 코드 중 하나로 실패할 때 빌드가 성공할 수 있습니다.
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
빌드를 실행할 수 있는 시간을 초 단위로 지정하려면 빌드에 timeout
필드를 사용합니다. 이 시간이 지나면 빌드에 대한 작업이 중단되고 빌드 상태가 TIMEOUT
이 됩니다. timeout
이 설정되지 않으면 기본 60분의 timeout
이 빌드에 적용됩니다. timeout
에 적용할 수 있는 최댓값은 24시간입니다. timeout
은 최대 9자리 소수의 초 단위로 지정되고 's'로 끝나야 합니다. 예시: 3.5s
다음 스니펫에서 timeout
은 빌드가 절전 시간 때문에 제한 시간을 초과하지 않도록 660초로 설정됩니다.
YAML
steps:
- name: 'ubuntu'
args: ['sleep', '600']
timeout: 660s
JSON
{
"steps": [
{
"name": "ubuntu",
"args": [
"sleep",
"600"
]
}
],
"timeout": "660s"
}
queueTtl
queueTtl
필드를 사용하여 빌드를 큐에 넣을 수 있는 시간을 지정합니다. 빌드가 queueTtl
에 설정된 값보다 오래 동안 큐에 있으면 빌드가 만료되고 빌드 상태가 EXPIRED
로 설정됩니다. 값을 제공하지 않으면 Cloud Build는 기본값 3600s
(1시간)을 사용합니다. queueTtl
은 createTime
에서 틱을 시작합니다. queueTtl
은 최대 9자리 소수의 초 단위로 지정되고 's'로 끝나야 합니다(예: 3.5s
).
다음 스니펫에서 timeout
은 20s
로 설정되고 queueTtl
은 10s
로 설정됩니다.
queueTtl
이 빌드가 요청된 시간인 createTime
에 틱을 시작하고, timeout
은 빌드가 시작되는 시간인 startTime
에 틱을 시작합니다. 따라서 그 때까지 빌드가 시작되지 않으면 queueTtl
은 createTime
+ 10s
에 만료됩니다.
YAML
steps:
- name: 'ubuntu'
args: ['sleep', '5']
timeout: 20s
queueTtl: 10s
JSON
{
"steps": [
{
"name": "ubuntu",
"args": [
"sleep",
"5"
]
}
],
"timeout": "20s",
"queueTtl": "10s"
}
logsBucket
로그를 작성해야 하는 Cloud Storage 버킷을 지정하려면 빌드에 logsBucket
필드를 설정합니다. 이 필드를 설정하지 않으면 Cloud 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
빌드에 다음과 같은 선택적 인수를 지정하려면 options
필드를 사용합니다.
env
:
이 빌드의 모든 빌드 단계에 존재하는 전역 환경 변수 정의의 목록입니다. 변수가 전역적으로도 빌드 단계에도 모두 정의되어 있으면 변수는 빌드 단계 값을 사용합니다. 요소는 값 VALUE
가 지정된 환경 변수 KEY
의 경우 KEY=VALUE
형식입니다.
secretEnv
:
Cloud Key Management Service 암호화 키를 사용하여 암호화된 전역 환경 변수 목록으로, 이 빌드의 모든 빌드 단계에서 사용할 수 있습니다.
이러한 값은 빌드의 Secret
에 지정되어야 합니다.
volumes
:
모든 빌드 단계에 전역적으로 마운트할 볼륨 목록입니다. 각 볼륨은 빌드 프로세스를 시작하기 전에 빈 볼륨으로 생성됩니다. 빌드가 완료되면 볼륨과 그 내용이 삭제됩니다. 전역 볼륨 이름과 경로는 빌드 단계가 정의된 볼륨과 중복되어서는 안 됩니다. 단계가 하나뿐인 빌드에서 전역 볼륨을 사용하는 것은 구성이 잘못된 빌드 요청을 나타내므로 유효하지 않습니다.
sourceProvenanceHash
:
소스 출처에 해시 알고리즘을 지정하려면 sourceProvenanceHash
옵션을 설정합니다. 다음 스니펫은 해시 알고리즘이 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는 빌드를 실행하기 위해 4가지의 고성능 CPU 가상 머신 유형, 즉 8 CPU 머신 유형 2가지와 32 CPU 머신 유형 2가지를 제공합니다. 또한 Cloud Build는 1개의 CPU와 2개의 CPU를 사용하여 빌드를 실행할 수 있는 두 가지 추가 가상 머신 유형을 제공합니다. 기본 머신 유형은 CPU가 2개인 e2-standard-2
입니다.
고성능 CPU 가상 머신을 요청하면 빌드 시작 시간이 길어질 수 있습니다. 고성능 CPU 가상 머신을 요청하려면 machineType
옵션을 추가하세요.
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"
}
}
machineType
옵션 사용에 대한 자세한 내용은 빌드 속도 향상을 참조하세요.
diskSizeGb
:
빌드의 커스텀 디스크 크기를 요청하려면 diskSizeGb
옵션을 사용합니다. 요청 가능한 최대 크기는 4,000GB입니다.
다음 스니펫은 200GB의 디스크 크기를 요청합니다.
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
:
Cloud Storage로 빌드 로그를 스트리밍할지를 지정하려면 이 옵션을 사용합니다. 기본적으로 Cloud Build는 빌드 완료 시 빌드 로그를 수집합니다. 이 옵션은 빌드 프로세스를 통해 실시간으로 빌드 로그를 스트리밍할지 여부를 지정합니다. 다음 스니펫은 빌드 로그가 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
: Cloud Logging 또는 Cloud Storage 중 로그를 저장할 위치를 지정하려면 이 옵션을 사용합니다. 이 옵션을 설정하지 않으면 Cloud Build는 Cloud Logging과 Cloud Storage 모두에 로그를 저장합니다. logging
옵션을 GCS_ONLY
로 설정하여 Cloud Storage에만 로그를 저장할 수 있습니다. 다음 스니펫은 로그가 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
:
defaultLogsBucketBehavior
옵션을 사용하면 빌드와 동일한 리전에 있는 자체 프로젝트 내에 기본 로그 버킷을 만들도록 Cloud Build를 구성할 수 있습니다. 자세한 내용은 사용자가 소유하고 리전화된 버킷에 빌드 로그 저장을 참조하세요.
다음 빌드 구성은 defaultLogsBucketBehavior
필드를 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"
}
}
dynamicSubstitutions
: 이 옵션을 사용하여 대체 항목으로 bash 매개변수 확장을 명시적으로 사용 설정하거나 중지하세요. 빌드가 트리거에 의해 호출되는 경우 dynamicSubstitutions
필드는 항상 true로 설정되며 빌드 구성 파일에 지정할 필요가 없습니다. 빌드를 수동으로 호출하는 경우 빌드를 실행할 때 bash 매개변수 확장이 해석되도록 dynamicSubstitutions
필드를 true로 설정해야 합니다.
automapSubstitutions
: 모든 대체 항목을 전체 빌드에서 사용할 수 있는 환경 변수에 자동으로 매핑합니다. 예시는 대체 변수 값을 참고하세요.
substitutionOption
:
아래의 substitutions
필드와 이 옵션을 함께 설정하여 대체 검사 오류 발생 시 동작을 지정할 수 있습니다.
pool
:
이 필드의 값을 빌드를 실행할 비공개 풀의 리소스 이름으로 설정합니다. 비공개 풀에서 빌드를 실행하는 방법은 비공개 풀에서 빌드 실행을 참조하세요.
requestedVerifyOption
:
빌드에 대한 증명 및 출처 메타데이터 생성을 사용 설정하고 확인하려면 requestedVerifyOption
값을 VERIFIED
로 설정하세요. 설정이 완료되면 증명 및 출처가 생성된 경우에만 빌드가 SUCCESS
로 표시됩니다.
substitutions
빌드 시 특정 변수를 대체하려면 빌드 구성 파일에 substitutions를 사용합니다. substitutions는 빌드 시간까지 값을 알 수 없는 변수에 또는 다른 변수 값을 사용하여 기존 빌드 요청을 다시 사용하는 데 유용합니다. 기본적으로 누락된 대체 변수나 누락된 대체 항목이 있으면 빌드가 오류를 반환합니다. 그러나 ALLOW_LOOSE
옵션을 사용하여 이 검사를 건너뛸 수 있습니다.
다음 스니펫은 substitutions를 사용하여 'hello world'를 인쇄합니다. ALLOW_LOOSE
대체 옵션이 설정됩니다. 이는 누락된 대체 변수 또는 누락된 대체 항목이 있으면 빌드가 오류를 반환하지 않음을 의미합니다.
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"
}
}
substitutions
사용에 대한 추가 지침은 변수 값 치환을 참조하세요.
tags
빌드를 그룹별로 정리하고 빌드를 필터링하려면 tags
필드를 사용합니다. 다음 구성은 mytag1
과 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
Cloud Build에 Secret Manager의 보안 비밀을 사용하려면 이 필드를 사용합니다. 자세한 내용은 보안 비밀 사용을 참조하세요.
secrets
secret은 암호화된 값이 포함된 보안 비밀 환경 변수 세트와 값을 해독하는 데 사용할 Cloud KMS 키를 페어링합니다.
serviceAccount
이 필드를 사용하여 빌드 시 사용할 IAM 서비스 계정을 지정합니다. 자세한 내용은 사용자 지정 서비스 계정 구성을 참조하세요.
images
빌드 구성 파일의 images
필드는 Cloud Build가 Artifact Registry 또는 Container Registry(지원 중단됨)로 푸시할 하나 이상의 Linux Docker 이미지를 지정합니다. Linux Docker 이미지를 생성하지 않고 작업을 수행하는 빌드가 있을 수 있지만 이미지를 빌드하고 레지스트리로 푸시하지 않으면 빌드가 완료될 때 이미지가 삭제됩니다. 빌드 중에 지정된 이미지가 생성되지 않으면 빌드가 실패합니다. 이미지 저장에 대한 자세한 내용은 Artifact Registry에 아티팩트 저장을 참조하세요.
다음 빌드 구성은 빌드된 이미지를 저장하도록 images
필드를 설정합니다.
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
빌드 구성 파일의 artifacts
필드는 Cloud Storage에 저장될 하나 이상의 컨테이너가 아닌 아티팩트를 지정합니다. 컨테이너가 아닌 아티팩트를 저장하는 방법에 대한 자세한 내용은 Cloud Storage에 빌드 아티팩트 저장을 참조하세요.
다음 빌드 구성은 빌드된 Go 패키지를 gs://mybucket/
에 저장하도록 artifacts
필드를 설정합니다.
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
mavenArtifacts
필드를 사용하면 비컨테이너 자바 아티팩트를 Artifact Registry의 Maven 저장소에 업로드할 수 있습니다. 자세한 내용은 자바 애플리케이션 빌드 및 테스트를 참조하세요.
다음 빌드 구성은 패키지 파일 my-app-1.0-SNAPSHOT.jar
을 Artifact Registry 저장소 https://us-central1-maven.pkg.dev/my-project-id/my-java-repo
에 업로드하도록 mavenArtifacts
필드를 설정합니다.
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
pythonPackages
필드를 사용하면 Python 패키지를 Artifact Registry에 업로드할 수 있습니다. 자세한 내용은 Python 애플리케이션 빌드 및 테스트를 참조하세요.
다음 빌드 구성은 Python 패키지 dist/my-pkg.whl
을 Artifact Registry 저장소 https://us-east1-python.pkg.dev/my-project/my-repo
에 업로드하도록 pythonPackages
필드를 설정합니다.
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
npmPackages
필드를 사용하여 Artifact Registry의 지원되는 저장소에 npm 패키지를 업로드하도록 Cloud Build를 구성하세요. repository
및 packagePath
에 대한 값을 제공해야 합니다.
repository
필드는 패키지를 저장할 Artifact Registry 저장소를 지정합니다. packagePath
필드는 업로드할 npm 패키지를 포함하는 로컬 디렉터리를 지정합니다. 이 디렉터리에는 package.json
파일이 포함되어야 합니다.
packagePath
값에는 절대 경로를 사용하는 것이 좋습니다. 현재 작업 디렉터리를 가리키기 위해 .
를 사용할 수 있지만, 이 필드는 생략하거나 비워둘 수 없습니다. npmPackages
사용에 관한 자세한 안내는 Node.js 애플리케이션 빌드 및 테스트를 참조하세요.
다음 빌드 구성은 /workspace/my-pkg
디렉터리의 npm 패키지를 Artifact Registry 저장소 https://us-east1-npm.pkg.dev/my-project/my-repo
에 업로드하도록 npmPackages
필드를 설정합니다.
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"
}
]
}
}
Dockerfile 사용
gcloud CLI 또는 빌드 트리거를 사용하여 Cloud Build에서 Docker 빌드를 실행하는 경우 별도의 빌드 구성 파일 없이 Dockerfile
을 사용할 수 있습니다. Docker 빌드를 더 조정하려면 Dockerfile
외에도 빌드 구성 파일을 제공하면 됩니다. Dockerfile
을 사용하여 Docker 이미지를 만드는 방법은 빠른 시작: 빌드를 참조하세요.
Cloud Build 네트워크
Cloud Build가 각 빌드 단계를 실행할 때 단계의 컨테이너를 cloudbuild
라는 로컬 Docker 네트워크에 연결합니다. cloudbuild
네트워크는 Google Cloud 서비스에서 사용자 인증 정보를 자동으로 찾는 데 사용할 수 있는 애플리케이션 기본 사용자 인증 정보(ADC)를 호스팅합니다. 중첩된 Docker 컨테이너를 실행 중이고 ADC를 기본 컨테이너에 노출하거나 docker
단계에서 gcloud
를 사용하려면 docker build
단계에서 --network
플래그를 사용하세요.
YAML
steps:
- name: 'gcr.io/cloud-builders/docker'
args: ['build', '--network=cloudbuild', '.']
JSON
{
"steps": [
{
"name": "gcr.io/cloud-builders/docker",
"args": [
"build",
"--network=cloudbuild",
"."
]
}
]
}
다음 단계
- 기본 빌드 구성 파일을 만들어 Cloud Build용 빌드를 구성하는 방법 알아보기.
- 수동으로 빌드 시작을 읽어 Cloud Build에서 빌드를 실행하는 방법 확인하기