커스텀 대상 정보

이 문서에서는 커스텀 대상이 Cloud Deploy에서 작동하는 방식을 설명합니다.

Cloud Deploy에는 대상으로 다양한 런타임 환경에 대한 지원이 기본 제공됩니다. 하지만 지원되는 대상 유형 목록은 유한합니다. 커스텀 대상을 사용하면 지원되는 런타임 이외의 다른 시스템에 배포할 수 있습니다.

커스텀 대상은 Cloud Deploy에서 지원하는 런타임 이외의 임의 출력 환경을 나타내는 대상입니다.

커스텀 대상 만들기 페이지에서는 커스텀 대상 유형을 정의하고 배포 파이프라인에서 대상으로 구현하는 프로세스를 설명합니다.

커스텀 대상은 어떻게 되나요?

각 커스텀 대상은 다음 구성요소로 구성됩니다.

• skaffold.yaml에 정의된 커스텀 작업

  이는 배포 후크를 정의하는 방법과 비슷합니다. skaffold.yaml 파일에서 customActions를 정의합니다. 여기서 각 커스텀 작업은 사용할 컨테이너 이미지와 해당 컨테이너에서 실행할 명령어를 식별합니다.

  이러한 방식으로 커스텀 대상은 단순히 커스텀 정의 작업이거나 작업 집합입니다.

  모든 커스텀 대상 유형에 커스텀 렌더링 작업과 커스텀 배포 작업을 구성합니다. 이러한 작업은 Cloud Deploy에서 제공하는 값을 사용하며 필수 출력 집합을 충족해야 합니다.

  커스텀 렌더링 작업은 선택사항이지만 Cloud Deploy의 기본값인 skaffold render으로 렌더링되면 커스텀 대상이 올바르게 작동하지 않는 한 커스텀 렌더링 작업을 만들어야 합니다.

• 커스텀 대상 유형 정의

  CustomTargetType은 이 유형의 대상에서 출시 버전 렌더링 및 출시 버전 배포 활동에 사용하는 커스텀 작업(skaffold.yaml에서 별도로 정의됨)을 식별하는 Cloud Deploy 리소스입니다.

• 대상 정의

  커스텀 대상의 대상 정의는 해당 값이 CustomTargetType 이름인 customTarget 속성을 포함한다는 점을 제외하고 모든 대상 유형과 동일합니다.

이러한 구성요소를 사용하면 모든 대상과 마찬가지로 대상을 사용하고 배포 파이프라인 진행에서 이를 참조하며 승격 및 승인 및 롤백과 같은 Cloud Deploy 기능을 최대한 활용할 수 있습니다.

예시

빠른 시작: 커스텀 대상 유형 정의 및 사용에서는 컨테이너 이미지에서 실행할 간단한 명령어(렌더링을 위한 명령어 하나 및 배포를 위한 명령어 하나)가 포함된 커스텀 대상 유형을 만듭니다. 이 경우 명령어는 렌더링 및 배포에 필요한 출력 파일에 텍스트를 추가하기만 합니다.

더 많은 예시는 커스텀 대상 예시를 참조하세요.

필수 입력 및 출력

Cloud Deploy에 정의된 모든 커스텀 대상 유형은 렌더링 및 배포 모두의 입력 및 출력 요구사항을 충족해야 합니다. 이 섹션에는 필요한 입력과 출력 및 제공되는 방식이 나열되어 있습니다.

Cloud Deploy는 렌더링과 배포 모두에 필요한 입력을 환경 변수로 제공합니다. 다음 섹션에는 이러한 입력뿐만 아니라 커스텀 렌더링 및 배포 작업에서 반환해야 하는 출력이 나열되어 있습니다.

파라미터를 환경 변수로 배포

Cloud Deploy는 이 섹션에 나열된 환경 변수 외에도 설정한 배포 매개변수를 커스텀 컨테이너에 전달할 수 있습니다.

자세히 알아보기

렌더링 작업에 대한 입력

커스텀 렌더링 작업의 경우 Cloud Deploy는 다음 필수 입력을 환경 변수로 제공합니다. 멀티 단계 출시(카나리아 배포)의 경우 Cloud Deploy는 단계마다 이러한 변수를 제공합니다.

• CLOUD_DEPLOY_PROJECT

  커스텀 대상 유형이 생성되는 Google Cloud 프로젝트입니다.

• CLOUD_DEPLOY_LOCATION

  커스텀 대상 유형의 Google Cloud 리전입니다.

• CLOUD_DEPLOY_DELIVERY_PIPELINE

  커스텀 대상 유형을 참조하는 Cloud Deploy 배포 파이프라인의 이름입니다.

• CLOUD_DEPLOY_RELEASE

  렌더링 작업이 호출되는 출시 버전의 이름입니다.

• CLOUD_DEPLOY_TARGET

  커스텀 대상 유형을 사용하는 Cloud Deploy 대상의 이름입니다.

• CLOUD_DEPLOY_PHASE

  렌더링에 해당하는 출시 단계입니다.

• CLOUD_DEPLOY_REQUEST_TYPE

  커스텀 렌더링 작업의 경우 항상 RENDER입니다.

• CLOUD_DEPLOY_FEATURES

  커스텀 컨테이너에서 지원해야 하는 쉼표로 구분된 Cloud Deploy 기능 목록입니다. 이 변수는 배포 파이프라인에 구성된 기능을 기반으로 채워집니다.

  구현에서 이 목록의 기능을 지원하지 않으면 렌더링 중에 실패하는 것이 좋습니다.

  표준 배포의 경우에는 비어 있습니다. 카나리아 배포의 경우 값은 CANARY입니다. Cloud Deploy에서 제공하는 값이 CANARY이면 카나리아의 단계마다 렌더링 작업이 호출됩니다. 각 단계의 카나리아 비율은 CLOUD_DEPLOY_PERCENTAGE_DEPLOY 환경 변수에 제공됩니다.

• CLOUD_DEPLOY_PERCENTAGE_DEPLOY

  이 렌더링 작업과 관련된 배포의 비율입니다. CLOUD_DEPLOY_FEATURES 환경 변수가 CANARY로 설정되면 단계마다 커스텀 렌더링 작업이 호출되고 이 변수는 각 단계의 카나리아 비율로 설정됩니다. 표준 배포 및 stable 단계에 도달한 카나리아 배포의 경우에는 100입니다.

• CLOUD_DEPLOY_STORAGE_TYPE

  스토리지 제공업체입니다. 항상 GCS입니다.

• CLOUD_DEPLOY_INPUT_GCS_PATH

  출시 버전이 생성될 때 작성된 렌더링-파일 보관 파일의 Cloud Storage 경로입니다.

• CLOUD_DEPLOY_OUTPUT_GCS_PATH

  커스텀 렌더링 컨테이너에서 배포에 사용할 아티팩트를 업로드할 Cloud Storage 경로입니다. 렌더링 작업에서 이 렌더링 작업의 결과가 포함된 results.json이라는 파일을 업로드해야 합니다. 자세한 내용은 렌더링 작업의 출력을 참조하세요.

렌더링 작업의 출력

커스텀 렌더링 작업은 이 섹션에 설명된 정보를 제공해야 합니다. 정보는 Cloud Deploy에서 제공하는 Cloud Storage 버킷에 있는 results.json이라는 결과 파일에 포함되어야 합니다.

• 렌더링된 구성 파일

• 다음 정보가 포함된 results.json 파일입니다.

  • 커스텀 작업의 성공 또는 실패 상태를 나타냅니다.

    유효한 값은 SUCCEEDED 및 FAILED입니다.

  • (선택사항) 커스텀 작업으로 생성된 오류 메시지입니다.

  • 렌더링된 구성 파일의 Cloud Storage 경로입니다.

    렌더링된 모든 구성 파일의 경로는 전체 URI입니다. Cloud Deploy에서 제공한 CLOUD_DEPLOY_OUTPUT_GCS_PATH 값을 사용하여 부분적으로 채웁니다.

    비어 있는 경우에도 렌더링된 구성 파일을 제공해야 합니다. 커스텀 배포 작업에서 사용할 수 있는 한 파일 콘텐츠는 모든 형식의 콘텐츠일 수 있습니다. 개발자와 조직의 다른 사용자가 출시 버전 검사기에서 이 파일을 볼 수 있도록 이 파일이 사람이 읽을 수 있는 파일인 것이 좋습니다.

  • (선택사항) 포함하려는 메타데이터의 맵

    커스텀 대상에서 이 메타데이터를 만듭니다. 이 메타데이터는 출시 버전의 custom_metadata 필드에 저장됩니다.

디버깅 등을 위해 results.json 파일을 검사해야 하는 경우 Cloud Build 로그에서 Cloud Storage URI를 찾을 수 있습니다.

렌더링 결과 파일 예시

다음은 커스텀 렌더링 작업의 샘플 results.json 파일 출력입니다.

{
  "resultStatus": "SUCCEEDED",
  "manifestFile": "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/manifest.yaml",
  "failureMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

배포 작업을 위한 입력

커스텀 배포 작업의 경우 Cloud Deploy는 다음 필수 입력을 환경 변수로 제공합니다.

• CLOUD_DEPLOY_PROJECT

  커스텀 대상이 생성되는 Google Cloud 프로젝트입니다.

• CLOUD_DEPLOY_LOCATION

  커스텀 대상 유형의 Google Cloud 리전입니다.

• CLOUD_DEPLOY_DELIVERY_PIPELINE

  커스텀 대상 유형을 사용하는 대상을 참조하는 Cloud Deploy 배포 파이프라인의 이름입니다.

• CLOUD_DEPLOY_RELEASE

  배포 작업이 호출되는 출시 버전의 이름입니다.

• CLOUD_DEPLOY_ROLLOUT

  이 배포의 대상 Cloud Deploy 출시 이름입니다.

• CLOUD_DEPLOY_TARGET

  커스텀 대상 유형을 사용하는 Cloud Deploy 대상의 이름입니다.

• CLOUD_DEPLOY_PHASE

  배포에 해당하는 출시 단계입니다.

• CLOUD_DEPLOY_REQUEST_TYPE

  커스텀 배포 작업의 경우 항상 DEPLOY입니다.

• CLOUD_DEPLOY_FEATURES

  커스텀 컨테이너에서 지원해야 하는 쉼표로 구분된 Cloud Deploy 기능 목록입니다. 이 변수는 배포 파이프라인에 구성된 기능을 기반으로 채워집니다.

  구현에서 이 목록의 기능을 지원하지 않으면 렌더링 중에 실패하는 것이 좋습니다.

  표준 배포의 경우에는 비어 있습니다. 카나리아 배포의 경우 값은 CANARY입니다. Cloud Deploy에서 제공하는 값이 CANARY이면 카나리아의 단계마다 렌더링 작업이 호출됩니다. 각 단계의 카나리아 비율은 CLOUD_DEPLOY_PERCENTAGE_DEPLOY 환경 변수에 제공됩니다.

• CLOUD_DEPLOY_PERCENTAGE_DEPLOY

  이 배포 작업과 관련된 배포의 비율입니다. CLOUD_DEPLOY_FEATURES 환경 변수가 CANARY로 설정되면 단계마다 커스텀 배포 작업이 호출되고 이 변수는 각 단계의 카나리아 비율로 설정됩니다. 배포 작업은 단계마다 실행되어야 합니다.

• CLOUD_DEPLOY_STORAGE_TYPE

  스토리지 제공업체입니다. 항상 GCS입니다.

• CLOUD_DEPLOY_INPUT_GCS_PATH

  커스텀 렌더기에서 렌더링된 구성 파일을 작성한 Cloud Storage 경로입니다.

• CLOUD_DEPLOY_SKAFFOLD_GCS_PATH

  렌더링된 Skaffold 구성에 대한 Cloud Storage 경로입니다.

• CLOUD_DEPLOY_MANIFEST_GCS_PATH

  렌더링된 매니페스트 파일의 Cloud Storage 경로입니다.

• CLOUD_DEPLOY_OUTPUT_GCS_PATH

  커스텀 배포 컨테이너가 배포 아티팩트를 업로드할 Cloud Storage 디렉터리의 경로입니다. 자세한 내용은 배포 작업의 출력을 참조하세요.

배포 작업의 출력

커스텀 배포 작업은 results.json 출력 파일을 작성해야 합니다. 이 파일은 Cloud Deploy에서 제공하는 Cloud Storage 버킷(CLOUD_DEPLOY_OUTPUT_GCS_PATH)에 있어야 합니다.

파일에는 다음이 포함되어야 합니다.

• 커스텀 배포 작업의 성공 또는 실패 상태를 나타냅니다.

  유효한 상태는 다음과 같습니다.

  • SUCCEEDED

  • FAILED

  • SKIPPED(stable 단계로 바로 이동하기 위해 카나리아 단계를 건너뛰는 카나리아 배포용)

• (선택사항) Cloud Storage 경로 형식의 배포 아티팩트 파일 목록

  경로는 전체 URI입니다. Cloud Deploy에서 제공한 CLOUD_DEPLOY_OUTPUT_GCS_PATH 값을 사용하여 부분적으로 채웁니다.

  여기에 나열된 파일은 배포 아티팩트로 작업 실행 리소스에 채워집니다.

• (선택사항) 커스텀 배포 작업이 실패한 경우(FAILED 상태 반환)의 실패 메시지

  이 메시지는 이 배포 작업의 작업 실행에서 failure_message를 채우는 데 사용됩니다.

• (선택사항) 작업에서 SKIPPED 상태를 반환하는 경우 추가 정보를 제공하는 건너뛰기 메시지

• (선택사항) 포함하려는 메타데이터의 맵

  커스텀 대상에서 이 메타데이터를 만듭니다. 이 메타데이터는 작업 실행 및 출시의 custom_metadata 필드에 저장됩니다.

디버깅 등을 위해 results.json 파일을 검사해야 하는 경우 Cloud Build 출시 버전 렌더링 로그에서 이 파일에 대한 Cloud Storage URI를 찾을 수 있습니다.

배포 결과 파일 예시

다음은 커스텀 배포 작업의 샘플 results.json 파일 출력입니다.

{
  "resultStatus": "SUCCEEDED",
  "artifactFiles": [
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file1.yaml",
    "gs://bucket/my-pipeline/release-001/rollout-a/01234/custom-output/file2.yaml"
  ],
  "failureMessage": "",
  "skipMessage": "",
  "metadata": {
    "key1": "val",
    "key2": "val"
  }
}

커스텀 작업에 대한 추가 정보

커스텀 대상 유형을 설정하고 사용할 때 유의해야 할 사항은 다음과 같습니다.

커스텀 작업 실행

커스텀 렌더링 및 배포 작업은 Cloud Deploy 실행 환경에서 실행됩니다. Google Kubernetes Engine 클러스터에서 실행되도록 커스텀 작업을 구성할 수 없습니다.

재사용 가능한 원격 Skaffold 구성 사용

이 문서의 설명대로 출시 버전을 만들 때 제공되는 skaffold.yaml 파일에서 커스텀 작업을 구성합니다. 하지만 Git 저장소나 Cloud Storage 버킷에 Skaffold 구성을 저장하고 커스텀 대상 유형 정의에서 이 구성을 참조할 수도 있습니다. 이렇게 하면 각 출시 버전의 skaffold.yaml 파일과 함께 커스텀 작업을 포함하는 대신 단일 공유 위치에서 정의되고 저장된 커스텀 작업을 사용할 수 있습니다.

커스텀 대상 및 배포 전략

커스텀 대상은 표준 배포에서 완전히 지원됩니다.

커스텀 렌더기와 배포자가 카나리아 기능을 지원하는 한 Cloud Deploy는 카나리아 배포를 지원합니다.

커스텀 카나리아 구성을 사용해야 합니다. 자동 및 커스텀 자동화 카나리아는 지원되지 않습니다.

커스텀 대상 및 배포 매개변수

커스텀 대상에서 배포 매개변수를 사용할 수 있습니다. 배포 파이프라인 단계, 커스텀 대상 유형을 사용하는 대상 또는 출시 버전에서 설정할 수 있습니다.

배포 매개변수는 이미 제공된 컨테이너 외에도 커스텀 렌더링 및 배포 컨테이너에 환경 변수로 배포합니다.

커스텀 대상 예시

cloud-deploy-samples 저장소에는 샘플 커스텀 대상 구현 집합이 포함되어 있습니다. 다음 샘플을 사용할 수 있습니다.

• GitOps

• Vertex AI

• Terraform

• Infrastructure Manager

• Helm

각 샘플에는 빠른 시작이 포함되어 있습니다.

이러한 샘플은 지원되는 Google Cloud 제품이 아니며 Google Cloud 지원 계약이 적용되지 않습니다. Google Cloud 제품의 버그를 신고하거나 기능을 요청하려면 Google Cloud 지원팀에 문의하세요.

다음 단계

• 커스텀 대상을 알았으므로 이제 구성 및 사용 방법 알아보기

• 빠른 시작: 커스텀 대상 유형 정의 및 사용 사용해보기

• Cloud Deploy 대상 구성 자세히 알아보기

• Cloud Deploy 실행 환경 알아보기