이 문서에서는 Cloud Deploy를 사용하여 모든 대상 유형에 애플리케이션을 배포하기 위해 커스텀 카나리아 배포를 구성하고 사용하는 방법을 설명합니다.
커스텀 카나리아 배포의 작동 방식
맞춤 카나리아 배포 전략을 사용하여 배포할 때 Cloud Deploy는 선택한 트래픽 균형 조정 구성을 용이하게 하기 위해 매니페스트를 수정하지 않습니다. 대신 각 카나리아 단계의 타겟 런타임에 적용되는 매니페스트를 제공해야 합니다.
필수 권한 필요
Cloud Deploy를 사용하는 데 필요한 다른 Identity and Access Management 권한 외에도 카나리아 배포에 필요할 수 있는 추가 작업을 수행하기 위해 다음 권한이 필요합니다.
clouddeploy.rollouts.advance
clouddeploy.rollouts.ignoreJob
clouddeploy.rollouts.cancel
clouddeploy.rollouts.retryJob
clouddeploy.jobRuns.get
clouddeploy.jobRuns.list
clouddeploy.jobRuns.terminate
이러한 권한이 포함된 사용 가능한 역할에 대한 자세한 내용은 IAM 역할 및 권한을 참조하세요.
skaffold.yaml 준비
skaffold.yaml 파일은 매니페스트가 렌더링되고 배포되는 방식을 정의합니다.
맞춤 카나리아 배포의 경우 선택한 트래픽 균형 조정 구성을 용이하게 하기 위해 각 카나리아 단계와 연결된 프로필을 정의해야 합니다. 이러한 프로필은 전달 파이프라인 전략 구성의 단계에 매핑됩니다.
완전 자동화된 카나리아에서 Cloud Deploy는 단계 이름을 지정합니다(예: canary-25, canary-75, stable). 그러나 커스텀 카나리아를 사용하면 이 카나리아 단계의 모든 단계에서 고유하고 리소스 ID 제한을 준수하는 한 각 단계에 이름을 지정할 수 있습니다. 하지만 최종(100%) 단계 이름은 stable이어야 합니다.
단계별 백분율 목표
단계별로 별도로 백분율을 지정합니다.
단계에 사용할 Skaffold 프로필
각 단계 또는 동일한 프로필 또는 모든 조합에 대해 별도의 Skaffold 프로필을 사용할 수 있습니다. 각 프로필은 서로 다른 Cloud Run 서비스 정의를 사용할 수 있습니다. 또한 지정된 단계에 대해 하나를 초과하는 프로필을 사용할 수 있습니다. Cloud Deploy는 이를 결합합니다.
배포 전 또는 배포 후 작업을 사용 설정할 경우 이러한 작업의 skaffold.yaml을 구성해야 합니다.
커스텀 카나리아 구성 요소
다음 YAML에서는 완전 커스텀 카나리아 배포 단계 구성을 보여줍니다.
strategy:canary:# Custom configuration for each canary phasecustomCanaryDeployment:phaseConfigs:-phaseId:"PHASE1_NAME"percentage:PERCENTAGE1profiles:["PROFILE_NAME"]verify:true | falsepredeploy:actions:"PREDEPLOY_ACTION"postdeploy:actions:"POSTDEPLOY_ACTION"-…-phaseId:"stable"percentage:100profiles:["LAST_PROFILE_NAME"]verify:true|falsepredeploy:actions:"PREDEPLOY_ACTION"postdeploy:actions:"POSTDEPLOY_ACTION"
이 YAML에서
PHASE1_NAME
단계 이름입니다. 각 단계 이름은 고유해야 합니다.
[ "PROFILE_NAME" ]
단계에 사용할 프로필의 이름입니다. 각 단계에 동일한 프로필을 사용하거나 단계마다 다른 프로필을 사용하거나 이를 조합하여 사용할 수 있습니다. 또한 프로필을 하나 넘게 지정할 수 있습니다. Cloud Deploy는 지정된 모든 프로필과 함께 전체 단계에서 사용되는 프로필 또는 매니페스트를 사용합니다.
stable
마지막 단계의 이름은 stable이어야 합니다.
PERCENTAGE1
첫 번째 단계에 배포할 백분율입니다. 각 단계에는 고유한 백분율 값이 있어야 하며 해당 값은 전체 백분율(예: 10.5 아님)이어야 하며 단계는 오름차순이어야 합니다.
verify: true|false
단계에 대해 확인 작업을 포함할지 여부를 Cloud Deploy에 알려줍니다.
확인을 사용할 각 단계에 대해 Scaffold는 해당 단계에 대해 렌더링 및 배포에 지정된 동일한 프로파일을 확인에 사용합니다.
PREDEPLOY_ACTION
skaffold.yaml에서 배포 전에 실행할 맞춤 액션을 정의하는 데 사용한 ACTION_NAME과 동일합니다.
POSTDEPLOY_ACTION
skaffold.yaml에서 배포 후 실행할 맞춤 액션을 정의하는 데 사용한 ACTION_NAME과 동일합니다.
마지막 단계의 백분율은 100이어야 합니다. 이 customCanaryDeployment 스탠자에서 구성한 순서에 따라 단계가 실행되지만 백분율 값이 오름차순이 아닌 경우 배포 파이프라인을 등록하는 명령어가 실패하고 오류가 발생합니다.
커스텀 카나리아 구성에는 runtimeConfig 스탠자가 포함되지 않습니다. runtimeConfig를 포함하면 커스텀 자동 카나리아로 간주됩니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-03(UTC)"],[],[],null,["# Custom Canary Deployments\n\nThis document describes how to configure and use custom canary deployments to\ndeploy your applications to [all target types](/deploy/docs/deploying-application#set_up_for_the_runtime_environment_of_your_choice)\nusing Cloud Deploy.\n\nHow custom canary deployments work\n----------------------------------\n\nWhen you deploy using a custom canary deployment strategy,\nCloud Deploy does not modify your manifests in order to facilitate the\nchosen traffic-balancing configuration. Instead you are responsible for\nproviding manifests that are applied to your target runtime for each canary\nphase.\n\n### Make sure you have the required permissions\n\nIn addition to other Identity and Access Management permissions you need for using\nCloud Deploy, you need the following permissions in order to\nperform additional actions that might be needed for a canary deployment:\n\n- `clouddeploy.rollouts.advance`\n- `clouddeploy.rollouts.ignoreJob`\n- `clouddeploy.rollouts.cancel`\n- `clouddeploy.rollouts.retryJob`\n- `clouddeploy.jobRuns.get`\n- `clouddeploy.jobRuns.list`\n- `clouddeploy.jobRuns.terminate`\n\nSee [IAM roles and permissions](/deploy/docs/iam-roles-permissions)\nfor more information about what available roles include these permissions.\n\n### Prepare your `skaffold.yaml`\n\nYour `skaffold.yaml` file defines how your manifests are rendered and deployed.\nFor a custom canary deployment you are responsible for defining profiles that\nare associated with each canary phase in order to facilitate the chosen\ntraffic-balancing configuration. These profiles are mapped to phases in the\ndelivery pipeline strategy configuration.\n\nThe following is an example `skaffold.yaml` configuration used by a custom\ncanary: \n\n apiVersion: skaffold/v4beta7\n kind: Config\n profiles:\n - name: canary-25\n manifests:\n rawYaml:\n - canary-25-resources.yaml\n - name: canary-50\n manifests:\n rawYaml:\n - canary-50-resources.yaml\n - name: stable\n manifests:\n rawYaml:\n - stable-resources.yaml\n\n### Configure a custom canary\n\nWith custom canary configuration, you specify the following, in your delivery\npipeline definition:\n\n- Rollout phase names\n\n In a fully-automated canary, Cloud Deploy names the phases for you\n (`canary-25`, `canary-75`, `stable`, for example). With a custom canary,\n however, you can give each phase any name, as long as it's unique among all\n phases for this canary stage, and it honors\n [resource ID restrictions](/apis/design/resource_names#resource-id-segments). But the final\n (100%) phase name must be `stable`.\n- Percentage goals for each phase\n\n Specify the percentages separately, per phase.\n- Skaffold profiles to use for the phase\n\n You can use a separate Skaffold profile for each phase, or the same profile,\n or any combination. And each profile can use a different Cloud Run service definition. You can also use more than\n one profile for a given phase. Cloud Deploy combines them.\n- Whether there is a verify job for the phase\n\n Remember that if you're enabling verify, you need to\n [configure](/deploy/docs/verify-deployment) your `skaffold.yaml` for\n verification also.\n- Whether there are predeploy or postdeploy jobs for the phase\n\n If you're enabling predeploy or postdeploy jobs, you need to\n [configure](/deploy/docs/hooks) your `skaffold.yaml` for those jobs.\n\n#### Custom canary configuration elements\n\nThe following YAML shows the configuration for the phases of fully custom canary\ndeployment: \n\n strategy:\n canary:\n # Custom configuration for each canary phase\n customCanaryDeployment:\n phaseConfigs:\n - phaseId: \"\u003cvar label=\"phase 1\" translate=\"no\"\u003ePHASE1_NAME\u003c/var\u003e\"\n percentage: \u003cvar label=\"percent1\" translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003ePERCENTAGE1\u003c/span\u003e\u003c/var\u003e\n profiles: [ \"\u003cvar label=\"profile\" translate=\"no\"\u003ePROFILE_NAME\u003c/var\u003e\" ]\n verify: true | false\n predeploy:\n actions: \"\u003cvar translate=\"no\"\u003ePREDEPLOY_ACTION\u003c/var\u003e\"\n postdeploy:\n actions: \"\u003cvar translate=\"no\"\u003ePOSTDEPLOY_ACTION\u003c/var\u003e\"\n - ...\n - phaseId: \"stable\"\n percentage: 100\n profiles: [ \"\u003cvar label=\"profile n\" translate=\"no\"\u003eLAST_PROFILE_NAME\u003c/var\u003e\" ]\n verify: true|false\n predeploy:\n actions: \"\u003cvar translate=\"no\"\u003ePREDEPLOY_ACTION\u003c/var\u003e\"\n postdeploy:\n actions: \"\u003cvar translate=\"no\"\u003ePOSTDEPLOY_ACTION\u003c/var\u003e\"\n\nIn this YAML\n\n- \u003cvar label=\"phase 1\" translate=\"no\"\u003ePHASE1_NAME\u003c/var\u003e\n\n Is the name of the phase. Each phase name must be unique.\n- `[ \"`\u003cvar label=\"profile 1\" translate=\"no\"\u003ePROFILE_NAME\u003c/var\u003e`\" ]`\n\n Is the name of the profile to use for the phase. You can use the same profile\n for each phase, or a different one for each, or any combination. Also, you can\n specify more than one profile. Cloud Deploy uses all of the\n profiles you specify, *plus* the profile or manifest used by the overall\n stage.\n- `stable`\n\n The final phase must be named `stable`.\n- \u003cvar label=\"percent1\" translate=\"no\"\u003ePERCENTAGE1\u003c/var\u003e\n\n Is the percentage to deploy for the first phase. Each phase must have a unique\n percentage value, and that value must be a whole percentage (not `10.5`, for\n example), and the phases must be in ascending order.\n- `verify: true|false`\n\n Tells Cloud Deploy whether to include a verify job for the phase.\n Note that for each phase to use verify, Skaffold uses the same profile for\n verify that is specified for render and deploy for that phase.\n- \u003cvar translate=\"no\"\u003ePREDEPLOY_ACTION\u003c/var\u003e\n\n Is the same as the \u003cvar translate=\"no\"\u003eACTION_NAME\u003c/var\u003e that you used in your\n `skaffold.yaml` to define the custom action you want to run before deploying.\n- \u003cvar translate=\"no\"\u003ePOSTDEPLOY_ACTION\u003c/var\u003e\n\n Is the same as the \u003cvar translate=\"no\"\u003eACTION_NAME\u003c/var\u003e that you used in your\n `skaffold.yaml` to define the custom action you want to run after deploying.\n\nThe percentage for the last phase must be `100`. Phases are executed according\nin the order you configure them in this `customCanaryDeployment` stanza, but if\nthe percentage values are not in ascending order, the command to\n[register the delivery pipeline](/deploy/docs/create-pipeline-targets#register_the_delivery_pipeline_and_targets)\nfails with an error.\n\nNote that the configuration for a custom canary doesn't include a\n`runtimeConfig` stanza. If you include `runtimeConfig`, it's considered a\n[custom-automated canary](/deploy/docs/deployment-strategies/canary#types_of_canary).\n\nWhat's next\n-----------\n\n- Try the [canary deployment quickstart](/deploy/docs/deploy-app-canary).\n\n- Find out how to [manage the lifecycle of your canary's rollouts](/deploy/docs/deployment-strategies/manage-rollout).\n\n- Learn more about [parallel deployment](/deploy/docs/parallel).\n\n- Learn more about [Cloud Deploy deployment strategies](/deploy/docs/deployment-strategies)."]]
