변수 값 치환

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

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

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

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

기본 대체 항목 사용

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

• $PROJECT_ID: 클라우드 프로젝트의 ID입니다.
• $BUILD_ID: 빌드의 ID입니다.
• $PROJECT_NUMBER: 프로젝트 번호
• $LOCATION: 빌드와 연결된 리전

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

• $TRIGGER_NAME: 트리거와 연결된 이름입니다.
• $COMMIT_SHA: 빌드와 연결된 커밋 ID입니다.
• $REVISION_ID: 빌드와 연결된 커밋 ID입니다.
• $SHORT_SHA: COMMIT_SHA의 처음 7개 문자입니다.
• $REPO_NAME: 저장소 이름입니다.
• $REPO_FULL_NAME: 사용자 또는 조직을 포함한 저장소의 전체 이름입니다.
• $BRANCH_NAME: 분기 이름입니다.
• $TAG_NAME: 태그 이름입니다.
• $REF_NAME: 브랜치 또는 태그의 이름입니다.
• $TRIGGER_BUILD_CONFIG_PATH: 빌드 실행 중에 사용된 빌드 구성 파일의 경로입니다. 그렇지 않으면 빌드가 트리거에 인라인으로 구성되었거나 Dockerfile 또는 Buildpack으로 사용된 경우 빈 문자열입니다.
• $SERVICE_ACCOUNT_EMAIL: 빌드에 사용 중인 서비스 계정의 이메일입니다. 기본 서비스 계정 또는 사용자 지정 서비스 계정입니다.
• $SERVICE_ACCOUNT: 서비스 계정의 리소스 이름이며 형식은 projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL입니다.

참고: $COMMIT_SHA 및 $REVISION_ID는 빌드와 연결된 커밋 ID를 나타냅니다. 두 대체 항목에 대한 지원은 제공됩니다.

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
• $REPO_FULL_NAME
• $BRANCH_NAME
• $TAG_NAME
• $REF_NAME
• $TRIGGER_BUILD_CONFIG_PATH
• $SERVICE_ACCOUNT_EMAIL
• $SERVICE_ACCOUNT

예를 들어 다음 명령어는 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-builders의 docker 빌드 단계를 사용하여 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으로 평가됩니다.
• 매개변수의 수는 200개로 제한됩니다. 매개변수 키 길이는 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:
    substitutionOption: '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을 정의하지 않는 경우, 트리거에 대체 변수가 포함되어 있으면 빌드 실행 또는 트리거 호출 후 오류가 수신됩니다.

ALLOW_LOOSE 옵션을 설정하지 않더라도 다음 대체 변수에는 항상 기본 빈 문자열 값이 포함됩니다.

• $REPO_NAME
• $REPO_FULL_NAME
• $BRANCH_NAME
• $TAG_NAME
• $COMMIT_SHA
• $SHORT_SHA

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

동적 대체 항목

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

다음 빌드 구성 파일은 ${PROJECT_ID} 변수를 참조하는 대체 변수 ${_IMAGE_NAME}을 보여줍니다. dynamicSubstitutions 필드는 true로 설정되므로 빌드를 수동으로 호출할 때 참조가 적용됩니다.

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', '${_IMAGE_NAME}', '.']
substitutions:
    _IMAGE_NAME: 'gcr.io/${PROJECT_ID}/test-image'
options:
    dynamicSubstitutions: true

JSON

{
   "steps": [
      {
         "name": "gcr.io/cloud-builders/docker",
         "args": [
            "build",
            "-t",
            "${_IMAGE_NAME}",
            "."
         ]
      }
   ],
   "substitutions": {
      "_IMAGE_NAME": "gcr.io/${PROJECT_ID}/test-image"
   },
   "options": {
      "dynamic_substitutions": true
   }
}

자세한 내용은 bash 매개변수 확장 적용을 참조하세요.

환경 변수에 대체 항목 매핑

스크립트는 대체 항목을 직접 지원하지 않지만 환경 변수를 지원합니다. 모든 환경 변수를 직접 정의하여 대체 항목을 환경 변수에 자동으로 모두 한 번에 또는 수동으로 매핑할 수 있습니다.

대체 항목 자동 매핑

• 빌드 수준에서. 모든 대체 항목을 전체 빌드에서 사용할 수 있는 환경 변수에 자동으로 매핑하려면 빌드 수준의 옵션으로 automapSubstitutions를 true로 설정합니다. 예를 들어 다음 빌드 구성 파일은 환경 변수에 매핑된 사용자 정의된 대체 항목 $_USER 및 기본 대체 항목 $PROJECT_ID를 보여줍니다.

  YAML

  steps:
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Hello $_USER"
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Your project ID is $PROJECT_ID"
  options:
    automapSubstitutions: true
  substitutions:
    _USER: "Google Cloud"
  

  JSON

  {
    "steps": [
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
      },
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'"
      }
    ],
    "options": {
      "automap_substitutions": true
    },
    "substitutions": {
      "_USER": "Google Cloud"
    }
  }
  

• 단계 수준에서. 모든 대체 항목을 자동으로 매핑하고 한 번에 환경 변수로 사용할 수 있게 하려면 해당 단계에서 automapSubstitutions 필드를 true로 설정합니다. 다음 예시에서는 자동 대체 항목 매핑이 사용 설정된 유일한 항목이므로 두 번째 단계에서만 대체 항목이 올바르게 표시됩니다.

  YAML

  steps:
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Hello $_USER"
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Your project ID is $PROJECT_ID"
    automapSubstitutions: true
  substitutions:
    _USER: "Google Cloud"
  

  JSON

  {
    "steps": [
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
      },
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'",
        "automap_substitutions": true
      }
    ],
    },
    "substitutions": {
      "_USER": "Google Cloud"
    }
  

  또한 전체 빌드에서 대체 항목을 환경 변수로 사용할 수 있게 설정한 후 한 번에 무시해도 됩니다. 빌드 수준에서 automapSubstitutions를 true로 설정한 후 대체 항목을 무시하려는 단계에서 동일한 필드를 false로 설정합니다. 다음 예시에서는 빌드 수준에서 매핑 대체 항목이 사용 설정되어 있더라도 automapSubstitutions가 해당 단계에서 false로 설정되어 있기 때문에 프로젝트 ID가 두 번째 단계에서 출력되지 않습니다.

  YAML

  steps:
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Hello $_USER"
  - name: 'ubuntu'
    script: |
      #!/usr/bin/env bash
      echo "Your project ID is $PROJECT_ID"
    automapSubstitutions: false
  options:
    automapSubstitutions: true
  substitutions:
    _USER: "Google Cloud"
  

  JSON

  {
    "steps": [
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
      },
      {
        "name": "ubuntu",
        "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'",
        "automap_substitutions": false
      }
    ],
    "options": {
      "automap_substitutions": true
    },
    },
    "substitutions": {
      "_USER": "Google Cloud"
    }
  

수동으로 대체 항목 매핑

대체 항목을 환경 변수에 수동으로 매핑할 수 있습니다. 모든 환경 변수는 env 필드를 사용하여 단계 수준에서 정의되며 변수 범위는 변수가 정의된 단계로 제한됩니다. 이 필드에는 키와 값의 목록이 사용됩니다.

다음 예시에서는 대체 항목 $PROJECT_ID을 환경 변수 BAR에 매핑하는 방법을 보여줍니다.

YAML

steps:
- name: 'ubuntu'
  env:
  - 'BAR=$PROJECT_ID'
  script: 'echo $BAR'

JSON

{
  "steps": [
    {
      "name": "ubuntu",
      "env": [
        "BAR=$PROJECT_ID"
      ],
      "script": "echo $BAR"
    }
  ]
}

다음 단계

• 대체 항목에서 페이로드 바인딩 및 bash 매개변수 확장 사용 방법 알아보기
• 기본 빌드 구성 파일 생성 방법 알아보기
• 빌드 트리거 만들기 및 관리 방법 알아보기
• Cloud Build에서 수동 빌드 실행 방법 알아보기