변수 값 치환

빌드 시 특정 변수를 대체하려면 빌드 구성 파일에 substitutions를 사용합니다.

대체 항목은 빌드할 때까지 값을 알 수 없는 변수에 유용하며 다른 변수 값을 사용하여 기존 빌드 요청을 다시 사용하는 데 유용합니다.

Cloud Build가 기본 제공하는 대체 항목을 사용하거나 사용자가 직접 대체 항목을 정의할 수 있습니다. 빌드 시 해당 값을 확인하려면 빌드의 stepsimages에서 substitutions를 사용합니다.

이 페이지에서는 기본 대체 항목을 사용하거나 고유한 substitutions를 정의하는 방법을 설명합니다.

기본 대체 항목 사용

Cloud Build는 모든 빌드에 다음과 같은 기본 대체 항목을 제공합니다.

  • $PROJECT_ID: 클라우드 프로젝트의 ID입니다.
  • $BUILD_ID: 빌드의 ID입니다.
  • $PROJECT_NUMBER: 프로젝트 번호

Cloud Build는 트리거로 호출되는 빌드에 다음과 같은 기본 대체 항목을 제공합니다.

  • $TRIGGER_NAME: 트리거와 연결된 이름입니다.
  • $COMMIT_SHA: 빌드와 연결된 커밋 ID입니다.
  • $REVISION_ID: 빌드와 연결된 커밋 ID입니다.
  • $SHORT_SHA: COMMIT_SHA의 처음 7개 문자입니다.
  • $REPO_NAME: 저장소 이름입니다.
  • $BRANCH_NAME: 분기 이름입니다.
  • $TAG_NAME: 태그 이름입니다.
  • $TRIGGER_BUILD_CONFIG_PATH: 빌드 실행 중에 사용된 빌드 구성 파일의 경로입니다. 그렇지 않으면 빌드가 트리거에 인라인으로 구성되었거나 Dockerfile 또는 Buildpack으로 사용된 경우 빈 문자열입니다.

Cloud Build는 pull 요청 트리거에 사용할 수 있는 다음과 같은 GitHub용 기본 대체 항목을 제공합니다.

  • $_HEAD_BRANCH: pull 요청의 헤드 분기
  • $_BASE_BRANCH: pull 요청의 베이스 분기
  • $_HEAD_REPO_URL: pull 요청의 헤드 repo
  • $_PR_NUMBER: pull 요청 수

기본 대체 항목을 사용할 수 없는 경우(예: 소스가 없는 빌드 또는 스토리지 소스를 사용하는 빌드) 누락된 변수가 빈 문자열로 바뀝니다.

gcloud builds submit을 사용하는 빌드를 시작할 때는 --substitutions 인수를 사용하여 트리거된 빌드에서 일반적으로 제공되는 변수를 지정할 수 있습니다. 구체적으로 다음에 대한 값을 수동으로 제공할 수 있습니다.

  • $TRIGGER_NAME
  • $COMMIT_SHA
  • $REVISION_ID
  • $SHORT_SHA
  • $REPO_NAME
  • $BRANCH_NAME
  • $TAG_NAME
  • $TRIGGER_BUILD_CONFIG_PATH

예를 들어 다음 명령어는 TAG_NAME 대체 항목을 사용합니다.

gcloud builds submit --config=cloudbuild.yaml \
    --substitutions=TAG_NAME="test"

다음 예시에서는 기본 대체 항목 $BUILD_ID, $PROJECT_ID, $PROJECT_NUMBER, $REVISION_ID를 사용합니다.

YAML

steps:
# Uses the ubuntu build step:
# to run a shell script; and
# set env variables for its execution
- name: 'ubuntu'
  args: ['bash', './myscript.sh']
  env:
  - 'BUILD=$BUILD_ID'
  - 'PROJECT_ID=$PROJECT_ID'
  - 'PROJECT_NUMBER=$PROJECT_NUMBER'
  - 'REV=$REVISION_ID'

# Uses the docker build step to build an image called my-image
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-image', '.']

# my-image is pushed to Container Registry
images:
- 'gcr.io/$PROJECT_ID/my-image'

JSON

{
  "steps": [{
      "name": "ubuntu",
      "args": [
        "bash",
        "./myscript.sh"
      ],
      "env": [
        "BUILD=$BUILD_ID",
        "PROJECT_ID=$PROJECT_ID",
        "PROJECT_NUMBER=$PROJECT_NUMBER",
        "REV=$REVISION_ID"
      ]
    }, {
      "name": "gcr.io/cloud-builders/docker",
      "args": ["build", "-t", "gcr.io/$PROJECT_ID/my-image", "."]
    }],
  "images": [
    "gcr.io/$PROJECT_ID/my-image"
  ]
}

아래의 예시는 docker 빌드 단계를 사용하여 이미지를 빌드한 다음 기본 $PROJECT_ID 대체 항목을 사용하여 이미지를 Container Registry로 푸시하는 빌드 요청을 보여줍니다.

예를 들면 다음과 같습니다.

  • 빌드 요청에는 gcr.io/cloud-buildersdocker 빌드 단계를 사용하여 Docker 이미지를 빌드하는 빌드 단계가 하나 있습니다.
    • 단계의 args 필드는 docker 명령어에 전달할 인수를 지정합니다. 이 경우 build -t gcr.io/my-project/cb-demo-img .를 호출합니다($PROJECT_ID가 프로젝트 ID로 대체된 후).
  • images 필드에는 이미지의 이름이 있습니다. 빌드가 성공하면 생성된 이미지가 Container Registry로 푸시됩니다. 빌드에서 이미지를 성공적으로 생성하지 않으면 빌드가 실패하게 됩니다.

YAML

steps:
- name: gcr.io/cloud-builders/docker
  args: ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."]
images:
- gcr.io/$PROJECT_ID/cb-demo-img

JSON

{
  "steps": [{
      "name": "gcr.io/cloud-builders/docker",
      "args": ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."]
    }],
  "images": [
    "gcr.io/$PROJECT_ID/cb-demo-img"
  ]
}

사용자 정의 대체 항목 사용

사용자 정의 대체 항목을 정의할 수도 있습니다. 사용자 정의 대체 항목은 다음 규칙을 따라야 합니다.

  • 대체 항목은 밑줄(_)로 시작하고 대문자 및 숫자만 사용해야 합니다(정규 표현식 _[A-Z0-9_]+ 고려). 이렇게 하면 기본 제공 대체 항목과의 충돌을 방지할 수 있습니다. $로 시작하는 표현식을 사용하려면 $$를 사용해야 합니다. 따라서 다음과 같습니다.
    • $FOO은 기본 제공 대체 항목이 아니기 때문에 잘못되었습니다.
    • $$FOO은 리터럴 문자열 $FOO으로 평가됩니다.
  • 매개변수의 수는 100개로 제한됩니다. 매개변수 키 길이는 100바이트로 제한되고 매개변수 값 길이는 4,000바이트로 제한됩니다.

$_FOO 또는 ${_FOO}의 두 방법 중 하나로 변수를 지정할 수 있습니다.

  • $_FOO${_FOO}은 모두 _FOO 값으로 확인됩니다. 하지만 ${}는 주위 공백 없이 대체 항목이 작동할 수 있으므로 ${_FOO}BAR와 같은 대체 항목이 허용됩니다.
  • $$는 템플릿에서 리터럴 $를 포함하도록 허용합니다. 따라서 다음과 같습니다.
    • $_FOO_FOO의 값으로 평가됩니다.
    • $$_FOO은 리터럴 문자열 $_FOO으로 평가됩니다.
    • $$$_FOO_FOO 값이 뒤에 오는 리터럴 문자열 $로 평가됩니다. .

대체 항목을 사용하려면 --substitutions 인수gcloud 명령어에 사용하거나 구성 파일에 지정하세요.

다음 예시에서는 _NODE_VERSION_1_NODE_VERSION_2라는 두 가지 사용자 정의 대체 항목이 있는 빌드 구성을 보여줍니다.

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build',
         '--build-arg',
         'node_version=${_NODE_VERSION_1}',
         '-t',
         'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}',
         '.']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build',
         '--build-arg',
         'node_version=${_NODE_VERSION_2}',
         '-t',
         'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}',
         '.']
substitutions:
    _NODE_VERSION_1: v6.9.1 # default value
    _NODE_VERSION_2: v6.9.2 # default value
images: [
    'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}',
    'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}'
]

JSON

{
    "steps": [{
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "--build-arg",
            "node_version=${_NODE_VERSION_1}",
            "-t",
            "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
            "."
        ]
    }, {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "--build-arg",
            "node_version=${_NODE_VERSION_2}",
            "-t",
            "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}",
            "."
        ]
    }],
    "substitutions": {
        "_NODE_VERSION_1": "v6.9.1"
        "_NODE_VERSION_1": "v6.9.2"
    },
    "images": [
        "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
        "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}"
    ]
}

빌드 구성 파일에 지정한 대체 값을 재정의하려면 gcloud builds submit 명령어에 --substitutions 플래그를 사용하세요. 대체 항목은 배열이나 시퀀스가 아닌 값과 변수의 매핑입니다. $PROJECT_ID$BUILD_ID를 제외하고 기본 대체 변수 값을 재정의할 수 있습니다. 다음 명령어는 위의 빌드 구성 파일에 지정된 _NODE_VERSION_1의 기본값을 재정의합니다.

gcloud builds submit --config=cloudbuild.yaml \
  --substitutions=_NODE_VERSION_1="v6.9.4",_NODE_VERSION_2="v6.9.5" .

기본적으로 누락된 대체 변수 또는 누락된 대체 항목이 있으면 빌드가 오류를 반환합니다. 그러나 ALLOW_LOOSE 옵션을 설정하여 이 검사를 건너뛸 수 있습니다.

다음 스니펫은 'hello world'를 출력하고 사용되지 않는 대체 항목을 정의합니다. ALLOW_LOOSE 대체 항목 옵션이 설정되었으므로 대체 항목 누락에 관계없이 빌드가 성공하게 됩니다.

YAML

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

JSON

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

빌드가 트리거에 의해 호출되면 ALLOW_LOOSE 옵션이 기본적으로 설정됩니다. 이 경우 대체 변수 또는 대체 항목이 누락되면 빌드가 오류를 반환하지 않습니다. 트리거에 의해 호출된 빌드에 ALLOW_LOOSE 옵션을 재정의할 수 없습니다.

ALLOW_LOOSE 옵션이 지정되지 않은 경우 대체 항목 매핑 또는 빌드 요청에 일치하지 않는 키가 있으면 오류가 발생합니다. 예를 들어 빌드 요청에 $_FOO이 포함되고 대체 매핑이 _FOO을 정의하지 않는 경우, 트리거에 대체 변수가 포함되어 있으면 빌드 실행 또는 트리거 호출 후 오류가 수신됩니다.

대체 변수를 정의할 때는 정적 문자열로 제한되지 않습니다. 또한 트리거를 호출한 이벤트 페이로드에 액세스할 수 있습니다. 이것들은 페이로드 바인딩으로 제공됩니다. 또한 대체 변수에 bash 매개변수 확장을 적용하고 결과 문자열을 새로운 대체 변수로 저장할 수 있습니다. 자세한 내용은 대체 항목에서 페이로드 바인딩 및 bash 매개변수 확장 사용을 참조하세요.

동적 대체 항목

빌드 구성 파일에서 dynamic_substitutions 옵션을 true로 설정하여 사용자 정의 대체 내 다른 변수의 값을 참조할 수 있습니다. 빌드가 트리거로 호출되는 경우 dynamic_substitutions 필드는 항상 true로 설정되며, 빌드 구성 파일에 지정될 필요가 없습니다. 빌드를 수동으로 호출하는 경우 빌드를 실행할 때 bash 매개변수 확장이 해석되도록 dynamic_substitutions 필드를 true로 설정해야 합니다. 자세한 내용은 bash 매개변수 확장 적용을 참조하세요.

다음 단계