1.8. 빌드 트리거 및 수정

다음 섹션에서는 빌드 후크를 사용하여 빌드를 트리거하고 수정하는 방법을 간략하게 설명합니다.

1.8.1. 빌드 트리거

BuildConfig를 정의할 때 BuildConfig를 실행해야 하는 상황을 제어하기 위해 트리거를 정의할 수 있습니다. 다음과 같은 빌드 트리거를 사용할 수 있습니다.

  • Webhook
  • 이미지 변경
  • 구성 변경

1.8.1.1. Webhook 트리거

Webhook 트리거를 사용하면 OpenShift Container Platform API 끝점에 요청을 전송하여 새 빌드를 트리거할 수 있습니다. 이러한 트리거는 GitHub, GitLab, Bitbucket 또는 Generic Webhook를 사용하여 정의할 수 있습니다.

현재는 OpenShift Container Platform Webhook에서 Git 기반 SCM(소스 코드 관리) 시스템 각각에 대해 유사한 버전의 내보내기 이벤트만 지원합니다. 기타 모든 이벤트 유형은 무시됩니다.

내보내기 이벤트가 처리되면 OpenShift Container Platform 마스터 호스트에서 이벤트 내부의 분기 참조가 해당 BuildConfig의 분기 참조와 일치하는지 확인합니다. 일치하는 경우 OpenShift Container Platform 빌드의 Webhook 이벤트에 언급된 커밋 참조가 정확한지 확인합니다. 일치하지 않는 경우에는 빌드가 트리거되지 않습니다.

참고

oc new-appoc new-build는 GitHub 및 Generic Webhook 트리거를 자동으로 생성하지만 필요한 다른 Webhook 트리거는 수동으로 추가해야 합니다. 트리거 설정을 통해 트리거를 수동으로 추가할 수 있습니다.

모든 Webhook에 대해 WebHookSecretKey라는 키와 Webhook를 호출할 때 제공할 값이 되는 값을 사용하여 보안을 정의해야 합니다. 그런 다음 Webhook 정의에서 보안을 참조해야 합니다. 보안을 사용하면 URL의 고유성이 보장되어 다른 사용자가 빌드를 트리거할 수 없습니다. 키 값은 Webhook 호출 중 제공되는 보안과 비교됩니다.

예를 들면 아래 예제에는 mysecret이라는 보안에 대한 참조가 포함된 GitHub Webhook가 있습니다.

type: "GitHub"
github:
  secretReference:
    name: "mysecret"

그런 다음 보안이 다음과 같이 정의됩니다. 보안 값은 Secret 오브젝트의 data 필드에 필요하므로 base64로 인코딩됩니다.

- kind: Secret
  apiVersion: v1
  metadata:
    name: mysecret
    creationTimestamp:
  data:
    WebHookSecretKey: c2VjcmV0dmFsdWUx
1.8.1.1.1. GitHub Webhook 사용

GitHub Webhook는 리포지토리를 업데이트할 때 GitHub에서 생성하는 호출을 처리합니다. 트리거를 정의할 때는 보안을 지정해야 하는데, 보안은 Webhook를 구성할 때 GitHub에 제공하는 URL의 일부입니다.

GitHub Webhook 정의의 예:

type: "GitHub"
github:
  secretReference:
    name: "mysecret"
참고

Webhook 트리거 구성에 사용되는 보안은 GitHub UI에서 Webhook를 구성할 때 표시되는 secret 필드와 동일하지 않습니다. 전자는 Webhook URL을 고유하고 예측하기 어렵게 만들고, 후자는 X-Hub-Signature 헤더로 전송되는 본문의 HMAC 16진수 다이제스트를 생성하는 데 사용되는 선택적 문자열 필드입니다.

페이로드 URL은 oc describe 명령에 의해 GitHub Webhook URL로 반환되고(Webhook URL 표시 참조) 다음과 같이 구성됩니다.

출력 예

https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github

사전 요구 사항

  • GitHub 리포지토리에서 BuildConfig를 생성합니다.

프로세스

  1. GitHub Webhook를 구성하려면 다음을 수행합니다.

    1. GitHub 리포지토리에서 BuildConfig를 생성한 후 다음을 실행합니다.

      $ oc describe bc/<name-of-your-BuildConfig>

      그러면 다음과 같은 Webhook GitHub URL이 생성됩니다.

      출력 예

      <https://api.starter-us-east-1.openshift.com:443/oapi/v1/namespaces/nsname/buildconfigs/bcname/webhooks/<secret>/github>.

    2. GitHub 웹 콘솔에서 이 URL을 잘라내어 GitHub에 붙여넣습니다.
    3. GitHub 리포지토리의 설정 → Webhook에서 Webhook 추가를 선택합니다.
    4. URL 출력을 페이로드 URL 필드에 붙여넣습니다.
    5. GitHub의 기본 application/x-www-form-urlencoded에서 콘텐츠 유형application/json으로 변경합니다.
    6. Webhook 추가를 클릭합니다.

      GitHub에서 Webhook가 성공적으로 구성되었음을 알리는 메시지가 표시됩니다.

      이제 GitHub 리포지토리에 변경 사항을 내보내면 새 빌드가 자동으로 시작되고 빌드가 성공하면 새 배포가 시작됩니다.

      참고

      Gogs는 GitHub와 동일한 Webhook 페이로드 형식을 지원합니다. 따라서 Gogs 서버를 사용하는 경우 BuildConfig에 GitHub Webhook 트리거를 정의하고 Gogs 서버에서도 트리거할 수 있습니다.

  2. payload.json과 같이 유효한 JSON 페이로드가 포함된 파일의 경우 curl을 사용하여 Webhook를 수동으로 트리거할 수 있습니다.

    $ curl -H "X-GitHub-Event: push" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github

    -k 인수는 API 서버에 올바르게 서명된 인증서가 없는 경우에만 필요합니다.

추가 리소스

1.8.1.1.2. GitLab Webhook 사용

GitLab Webhook는 리포지토리를 업데이트할 때 GitLab에서 생성하는 호출을 처리합니다. GitHub 트리거와 마찬가지로 보안을 지정해야 합니다. 다음 예제는 BuildConfig 내의 트리거 정의 YAML입니다.

type: "GitLab"
gitlab:
  secretReference:
    name: "mysecret"

페이로드 URL은 oc describe 명령을 통해 GitLab Webhook URL로 반환되고 다음과 같이 구조화됩니다.

출력 예

https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/gitlab

프로세스

  1. GitLab Webhook를 구성하려면 다음을 수행합니다.

    1. Webhook URL을 가져오도록 BuildConfig를 지정합니다.

      $ oc describe bc <name>
    2. Webhook URL을 복사하여 <secret>을 보안 값으로 교체합니다.
    3. GitLab 설정 지침에 따라 Webhook URL을 GitLab 리포지토리 설정에 붙여넣습니다.
  2. payload.json과 같이 유효한 JSON 페이로드가 포함된 파일의 경우 curl을 사용하여 Webhook를 수동으로 트리거할 수 있습니다.

    $ curl -H "X-GitLab-Event: Push Hook" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/gitlab

    -k 인수는 API 서버에 올바르게 서명된 인증서가 없는 경우에만 필요합니다.

1.8.1.1.3. Bitbucket Webhook 사용

추가 리소스

Bitbucket Webhook는 리포지토리가 업데이트될 때 Bitbucket에서 만든 호출을 처리합니다. 이전 트리거와 유사하게 보안을 지정해야 합니다. 다음 예제는 BuildConfig 내의 트리거 정의 YAML입니다.

type: "Bitbucket"
bitbucket:
  secretReference:
    name: "mysecret"

페이로드 URL은 oc describe 명령을 통해 Bitbucket Webhook URL로 반환되고 다음과 같이 구조화됩니다.

출력 예

https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/bitbucket

프로세스

  1. Bitbucket Webhook를 구성하려면 다음을 수행합니다.

    1. Webhook URL을 가져오도록 'BuildConfig'를 지정합니다.

      $ oc describe bc <name>
    2. Webhook URL을 복사하여 <secret>을 보안 값으로 교체합니다.
    3. Bitbucket 설정 지침에 따라 Webhook URL을 Bitbucket 리포지토리 설정에 붙여넣습니다.
  2. payload.json과 같이 유효한 JSON 페이로드가 포함된 파일의 경우 curl을 사용하여 Webhook를 수동으로 트리거할 수 있습니다.

    $ curl -H "X-Event-Key: repo:push" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/bitbucket

    -k 인수는 API 서버에 올바르게 서명된 인증서가 없는 경우에만 필요합니다.

1.8.1.1.4. 일반 Webhook 사용

일반 Webhook는 웹 요청을 수행할 수 있는 모든 시스템에서 호출합니다. 다른 Webhook와 마찬가지로 보안을 지정해야 하는데 보안은 호출자가 빌드를 트리거하는 데 사용해야 하는 URL의 일부입니다. 보안을 사용하면 URL의 고유성이 보장되어 다른 사용자가 빌드를 트리거할 수 없습니다. 다음은 BuildConfig 내 트리거 정의 YAML의 예입니다.

type: "Generic"
generic:
  secretReference:
    name: "mysecret"
  allowEnv: true 1
1
일반 Webhook에서 환경 변수를 전달하도록 허용하려면 true로 설정합니다.

프로세스

  1. 호출자를 설정하기 위해 빌드에 대한 일반 Webhook 끝점의 URL을 호출 시스템에 제공합니다.

    출력 예

    https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic

    호출자는 Webhook를 POST 작업으로 호출해야 합니다.

  2. Webhook를 수동으로 호출하려면 curl을 사용하면 됩니다.

    $ curl -X POST -k https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic

    HTTP 동사를 POST로 설정해야 합니다. 비보안 -k 플래그는 인증서 검증을 무시하도록 지정됩니다. 클러스터에 올바르게 서명된 인증서가 있는 경우 이 두 번째 플래그는 필요하지 않습니다.

    끝점은 다음 형식을 사용하여 선택적 페이로드를 허용할 수 있습니다.

    git:
      uri: "<url to git repository>"
      ref: "<optional git reference>"
      commit: "<commit hash identifying a specific git commit>"
      author:
        name: "<author name>"
        email: "<author e-mail>"
      committer:
        name: "<committer name>"
        email: "<committer e-mail>"
      message: "<commit message>"
    env: 1
       - name: "<variable name>"
         value: "<variable value>"
    1
    BuildConfig 환경 변수와 유사하게 여기에 정의된 환경 변수도 빌드에 사용할 수 있습니다. 이러한 변수가 BuildConfig 환경 변수와 충돌하는 경우 해당 변수가 우선합니다. 기본적으로 Webhook에서 전달하는 환경 변수는 무시됩니다. 이 동작을 활성화하려면 Webhook 정의에서 allowEnv 필드를 true로 설정합니다.
  3. curl을 사용하여 이 페이로드를 전달하려면 payload_file.yaml이라는 파일에 페이로드를 정의하고 다음을 실행합니다.

    $ curl -H "Content-Type: application/yaml" --data-binary @payload_file.yaml -X POST -k https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic

    인수는 위 예제와 동일하고 헤더와 페이로드가 추가되었습니다. -H 인수는 페이로드 형식에 따라 Content-Type 헤더를 application/yaml 또는 application/json으로 설정합니다. --data-binary 인수는 POST 요청을 사용하여 온전한 새 줄로 바이너리 페이로드를 보내는 데 사용됩니다.

참고

OpenShift Container Platform에서는 유효하지 않은 요청 페이로드(예: 유효하지 않은 콘텐츠 유형, 구문 분석할 수 없거나 유효하지 않은 콘텐츠 등)가 제공되는 경우에도 일반 Webhook에서 빌드를 트리거할 수 있습니다. 이 동작은 이전 버전과의 호환성을 위해 유지됩니다. 유효하지 않은 요청 페이로드가 제공되면 OpenShift Container Platform에서 HTTP 200 OK 응답의 일부로 JSON 형식의 알림을 반환합니다.

1.8.1.1.5. Webhook URL 표시

다음 명령을 사용하여 빌드 구성과 관련된 Webhook URL을 표시할 수 있습니다. 이 명령에서 Webhook URL을 표시하지 않으면 해당 빌드 구성에 Webhook 트리거가 정의되지 않습니다.

프로세스

  • BuildConfig와 관련된 Webhook URL을 표시하려면 다음을 실행합니다.
$ oc describe bc <name>

1.8.1.2. 이미지 변경 트리거 사용

이미지 변경 트리거를 사용하면 새 버전의 업스트림 이미지가 준비될 때 빌드가 자동으로 호출됩니다. 예를 들어 빌드가 RHEL 이미지를 기반으로 하는 경우 RHEL 이미지가 변경될 때마다 해당 빌드를 트리거하여 실행할 수 있습니다. 결과적으로 애플리케이션 이미지는 항상 최신 RHEL 기본 이미지에서 실행됩니다.

참고

v1 컨테이너 레지스트리의 컨테이너 이미지를 가리키는 이미지 스트림은 이미지 스트림 태그를 사용할 수 있을 때 빌드를 한 번만 트리거하고 후속 이미지 업데이트에서는 빌드를 트리거하지 않습니다. 이는 v1 컨테이너 레지스트리에서 고유하게 확인할 수 있는 이미지가 없기 때문입니다.

프로세스

이미지 변경 트리거를 구성하려면 다음 작업을 수행해야 합니다.

  1. 트리거하려는 업스트림 이미지를 가리키는 ImageStream을 정의합니다.

    kind: "ImageStream"
    apiVersion: "v1"
    metadata:
      name: "ruby-20-centos7"

    이는 <system-registry>_/<namespace>/ruby-20-centos7에 있는 컨테이너 이미지 리포지토리에 연결된 이미지 스트림을 정의합니다. <system-registry>는 OpenShift Container Platform에서 실행 중인 docker-registry라는 이름을 사용하여 서비스로 정의됩니다.

  2. 이미지 스트림이 빌드의 기본 이미지인 경우 빌드 전략의 from 필드를 ImageStream을 가리키도록 설정합니다.

    strategy:
      sourceStrategy:
        from:
          kind: "ImageStreamTag"
          name: "ruby-20-centos7:latest"

    이 경우 sourceStrategy 정의에서는 이 네임스페이스 내에 있는 ruby-20-centos7이라는 이미지 스트림의 latest 태그를 사용합니다.

  3. ImageStreams를 가리키는 하나 이상의 트리거를 사용하여 빌드를 정의합니다.

    type: "imageChange" 1
    imageChange: {}
    type: "imageChange" 2
    imageChange:
      from:
        kind: "ImageStreamTag"
        name: "custom-image:latest"
    1
    빌드 전략의 from 필드에 정의된 ImageStreamTag를 모니터링하는 이미지 변경 트리거입니다. 여기에서 imageChange 오브젝트는 비어 있어야 합니다.
    2
    임의의 이미지 스트림을 모니터링하는 이미지 변경 트리거입니다. 이 경우 imageChange 부분에 모니터링할 ImageStreamTag를 참조하는 from 필드를 포함해야 합니다.

전략 이미지 스트림에 이미지 변경 트리거를 사용하는 경우 생성된 빌드에 해당 태그와 일치하는 최신 이미지를 가리키는 변경 불가능한 Docker 태그가 제공됩니다. 이 새 이미지 참조는 빌드에 대해 실행할 때 전략에서 사용합니다.

전략 이미지 스트림을 참조하지 않는 다른 이미지 변경 트리거의 경우 새 빌드가 시작되지만 빌드 전략은 고유 이미지 참조로 업데이트되지 않습니다.

이 예제에는 전략에 대한 이미지 변경 트리거가 있으므로 결과 빌드는 다음과 같습니다.

strategy:
  sourceStrategy:
    from:
      kind: "DockerImage"
      name: "172.30.17.3:5001/mynamespace/ruby-20-centos7:<immutableid>"

그 결과 트리거된 빌드는 리포지토리로 방금 푸시된 새 이미지를 사용하고 동일한 입력을 사용하여 빌드를 다시 실행할 수 있습니다.

이미지 변경 트리거를 일시 정지하여 빌드를 시작하기 전에 참조 이미지 스트림에 대한 다양한 변경 사항을 허용할 수 있습니다. 처음에 ImageChangeTriggerBuildConfig에 추가할 때 빌드가 즉시 트리거되지 않도록 paused 특성을 true로 설정할 수도 있습니다.

type: "ImageChange"
imageChange:
  from:
    kind: "ImageStreamTag"
    name: "custom-image:latest"
  paused: true

모든 Strategy 유형의 이미지 필드를 설정하는 것 외에 사용자 지정 빌드의 경우 OPENSHIFT_CUSTOM_BUILD_BASE_IMAGE 환경 변수도 확인합니다. 존재하지 않는 경우 변경 불가능한 이미지 참조를 사용하여 생성됩니다. 존재하는 경우 변경 불가능한 이미지 참조를 사용하여 업데이트됩니다.

Webhook 트리거 또는 수동 요청으로 인해 빌드가 트리거되는 경우 생성된 빌드는 Strategy에서 참조한 ImageStream의 확인된 <immutableid>를 사용합니다. 그러면 쉽게 재현할 수 있도록 일관된 이미지 태그를 사용하여 빌드를 수행할 수 있습니다.

1.8.1.3. 구성 변경 트리거

구성 변경 트리거를 사용하면 새 BuildConfig가 생성되는 즉시 빌드가 자동으로 호출됩니다.

다음은 BuildConfig 내 트리거 정의 YAML의 예입니다.

  type: "ConfigChange"
참고

구성 변경 트리거는 현재 새 BuildConfig를 생성할 때만 작동합니다. 향후 릴리스에서는 BuildConfig가 업데이트될 때마다 구성 변경 트리거도 빌드를 시작할 수 있습니다.

1.8.1.3.1. 트리거 수동 설정

oc set triggers를 사용하여 빌드 구성에서 트리거를 추가 및 제거할 수 있습니다.

프로세스

  • 빌드 구성에 GitHub Webhook 트리거를 설정하려면 다음을 사용합니다.

    $ oc set triggers bc <name> --from-github
  • 이미지 변경 트리거를 설정하려면 다음을 사용합니다.

    $ oc set triggers bc <name> --from-image='<image>'
  • 트리거를 제거하려면 --remove를 추가합니다.

    $ oc set triggers bc <name> --from-bitbucket --remove
참고

Webhook 트리거가 이미 있는 경우 해당 트리거를 다시 추가하면 Webhook 보안이 다시 생성됩니다.

자세한 내용은 다음을 실행하여 도움말 문서를 참조하십시오.

$ oc set triggers --help

1.8.2. 빌드 후크

빌드 후크를 사용하면 빌드 프로세스에 동작을 삽입할 수 있습니다.

BuildConfig 오브젝트의 postCommit 필드는 빌드 출력 이미지를 실행하는 임시 컨테이너 내에서 명령을 실행합니다. 후크는 이미지의 마지막 계층을 커밋한 직후 그리고 이미지를 레지스트리로 푸시되기 전에 실행됩니다.

현재 작업 디렉터리는 이미지의 WORKDIR로 설정되어 있으며 이는 컨테이너 이미지의 기본 작업 디렉터리입니다. 대부분의 이미지에서 이 디렉터리는 소스 코드가 있는 위치입니다.

스크립트 또는 명령에서 0이 아닌 종료 코드를 반환하거나 임시 컨테이너를 시작하지 못하는 경우 후크가 실패합니다. 후크가 실패하면 빌드가 실패로 표시되고 이미지를 레지스트리로 푸쉬하지 않습니다. 실패 이유는 빌드 로그를 확인하여 검사할 수 있습니다.

빌드 후크를 사용하면 빌드를 완료로 표시하고 레지스트리에 이미지를 제공하기 전에 단위 테스트를 실행하여 이미지를 확인할 수 있습니다. 모든 테스트를 통과하고 테스트 실행기에서 종료 코드 0을 반환하면 빌드가 성공으로 표시됩니다. 실패한 테스트가 있는 경우 빌드가 실패로 표시됩니다. 어떠한 경우든 빌드 로그에는 테스트 실행기의 출력이 포함되므로 실패한 테스트를 확인할 수 있습니다.

postCommit 후크는 테스트 실행뿐만 아니라 다른 명령에도 사용할 수 있습니다. 이 후크는 임시 컨테이너에서 실행되기 때문에 후크에 의한 변경 사항은 지속되지 않습니다. 즉 후크를 실행해도 최종 이미지에는 영향을 미치지 않습니다. 이러한 동작으로 인해 특히 자동으로 삭제되어 최종 이미지에 존재하지 않는 테스트 종속 항목을 설치하고 사용할 수 있습니다.

1.8.2.1. post-commit 빌드 후크 구성

빌드 후 후크를 구성하는 방법은 다양합니다. 다음 예제에서 모든 양식은 동일하고 bundle exec rake test --verbose를 실행합니다.

프로세스

  • 쉘 스크립트:

    postCommit:
      script: "bundle exec rake test --verbose"

    script 값은 /bin/sh -ic를 사용하여 실행할 쉘 스크립트입니다. 쉘 스크립트가 빌드 후크를 실행하는 데 적합한 경우 이 값을 사용합니다. 예를 들면 위와 같이 단위 테스트를 실행하는 경우입니다. 이미지 항목 지점을 제어하려는 경우 또는 이미지에 /bin/sh가 없는 경우 command 및/또는 args를 사용합니다.

    참고

    추가 -i 플래그는 CentOS 및 RHEL 이미지 작업 환경을 개선하기 위해 도입되었으며 향후 릴리스에서 제거될 수 있습니다.

  • 이미지 진입점으로서의 명령:

    postCommit:
      command: ["/bin/bash", "-c", "bundle exec rake test --verbose"]

    이 양식에서 command는 실행할 명령에 해당하며 Dockerfile 참조에 설명된 exec 형식의 이미지 진입점을 덮어씁니다. 이 명령은 이미지에 /bin/sh가 없거나 쉘을 사용하지 않는 경우 필요합니다. 다른 모든 경우에는 script를 사용하는 것이 더 편리할 수 있습니다.

  • 인수가 있는 명령:

    postCommit:
      command: ["bundle", "exec", "rake", "test"]
      args: ["--verbose"]

    이 형식은 command에 인수를 추가하는 것과 동일합니다.

참고

scriptcommand를 동시에 제공하면 유효하지 않은 빌드 후크가 생성됩니다.

1.8.2.2. CLI를 사용하여 post-commit 빌드 후크 설정

oc set build-hook 명령은 빌드 설정에 빌드 후크를 설정하는 데 사용할 수 있습니다.

프로세스

  1. 명령을 post-commit 빌드 후크로 설정하려면 다음을 실행합니다.

    $ oc set build-hook bc/mybc \
        --post-commit \
        --command \
        -- bundle exec rake test --verbose
  2. 스크립트를 post-commit 빌드 후크로 설정하려면 다음을 실행합니다.

    $ oc set build-hook bc/mybc --post-commit --script="bundle exec rake test --verbose"