빌드 구성 파일에는 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
- 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",
"..."
]
}
빌드 구성 파일의 각 섹션은 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 필드를 사용합니다. 빌드 단계에서 script를 지정하면 동일한 단계에서 args 또는 entrypoint를 지정할 수 없습니다. script 필드 사용에 대한 자세한 내용은 bash 스크립트 실행을 참조하세요.
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에 생성되면 전체 빌드가 실패합니다.
빌드와 관련된 종료 코드는 소프트웨어에 따라 다릅니다. 예를 들어 Linux에서 일반적인 종료 코드는 '1'입니다. 스크립트에서 자체 종료 코드를 정의할 수도 있습니다. 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는 빌드 실행을 위해 CPU 1개와 CPU 2개가 있는 2개의 추가 가상 머신 유형을 제공합니다. 기본 머신 유형은 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 옵션을 사용합니다. 요청 가능한 최대 크기는 2,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"
}
}
dynamic_substitutions: 이 옵션을 사용하여 대체 항목으로 bash 매개변수 확장을 명시적으로 사용 설정하거나 중지하세요. 빌드가 트리거에 의해 호출되는 경우 dynamic_substitutions 필드는 항상 true로 설정되며 빌드 구성 파일에 지정할 필요가 없습니다. 빌드를 수동으로 호출하는 경우 빌드를 실행할 때 bash 매개변수 확장이 해석되도록 dynamic_substitutions 필드를 true로 설정해야 합니다.
substitutionOption:
아래의 substitutions 필드와 이 옵션을 함께 설정하여 대체 검사 오류 발생 시 동작을 지정할 수 있습니다.
pool:
이 필드의 값을 빌드를 실행할 비공개 풀의 리소스 이름으로 설정합니다. 비공개 풀에서 빌드를 실행하는 방법은 비공개 풀에서 빌드 실행을 참조하세요.
requestedVerifyOption:
requestedVerifyOption 값을 VERIFIED로 설정하여 빌드에 대한 증명 및 출처 메타데이터 생성을 확인합니다. 또한 이 옵션을 사용하면 리전 빌드 및 비공개 풀의 빌드에 대한 증명 및 출처 메타데이터도 사용 설정됩니다. requestedVerifyOption: VERIFIED를 추가하지 않으면 Cloud Build가 전역 빌드에 대해서만 출처를 생성합니다.
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 필드를 사용하여 빌드된 npm 패키지를 Artifact Registry의 지원되는 저장소에 업로드하도록 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 단계에서 gsutil 또는 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에서 빌드를 실행하는 방법 확인하기