serialPipeline:stages:-targetId:cloudrun-prodprofiles:[]strategy:canary:# Include runtimeConfig for automatic traffic managementruntimeConfig:cloudRun:automaticTrafficControl:true# Include customCanaryDeployment for phase customizationcustomCanaryDeployment:phaseConfigs:-phaseId:"warmup-cr"percentage:10profiles:["base-config"]# Profile rendering service def (no traffic stanza)verify:true-phaseId:"scaling-cr"percentage:50profiles:["base-config"]# Can use the same profileverify:true-phaseId:"stable"percentage:100profiles:["base-config"]verify:true
[[["容易理解","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 (世界標準時間)。"],[],[],null,["# Canary Deployments to Cloud Run\n\nThis document describes how to configure and use canary deployments to deploy\nyour applications to Cloud Run (services only---not jobs) using Cloud Deploy.\n\nA canary deployment is a progressive rollout of a new version of your application,\nwhere you gradually increase the percentage of traffic sent to the new version,\nwhile monitoring the application's performance. This helps you to catch potential\nproblems early and minimize the impact on your users.\n\nHow canary deployments work for Cloud Run\n-----------------------------------------\n\nWhen you deploy to Cloud Run using a canary deployment strategy,\nCloud Deploy updates your existing service with a new revision. The\nnew revision receives a specified percentage of traffic, and the old revision\ncontinues to receive the remainder. You gradually increase the traffic split to\nthe new revision over time.\n\nUsing Cloud Deploy, you can configure canary deployments to\nCloud Run in a single stage or in multiple stages.\n\nThe instructions here include only what is specific to canary configuration. The\ndocument [Deploy a Cloud Run service or job](/deploy/docs/run-targets) has the\ngeneral instructions for configuring and executing your deployment pipeline.\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 Cloud Run service definitions are rendered and deployed. For a canary deployment to Cloud Run, ensure it correctly points to your service definition file(s) and defines any necessary build artifacts (like container images). No special canary-specific configuration is required within `skaffold.yaml` itself beyond what's needed for a [standard deployment](/deploy/docs/using-skaffold). You might use Skaffold profiles to manage different service definition variations for [custom canary phases](#custom-automated).\n\n### Prepare your service definition\n\nYour normal Cloud Run service definition file is sufficient, but\nwithout a `traffic` stanza. Cloud Deploy manages splitting\ntraffic for you between the last successful revision and the new revision.\n\nExample `service.yaml` (without `traffic` stanza): \n\n apiVersion: serving.knative.dev/v1\n kind: Service\n metadata:\n name: my-cloudrun-service\n spec:\n template:\n spec:\n containers:\n - image: gcr.io/my-project/my-cloudrun-app\n ports:\n - containerPort: 8080\n\n### Configure an automated canary\n\nConfigure an automated canary directly within your delivery pipeline definition for a specific Cloud Run stage. Cloud Deploy automatically instructs Cloud Run to split traffic between the last stable revision and the new revision according to the specified percentages. \n\n serialPipeline:\n stages:\n - targetId: prod\n profiles: []\n strategy:\n canary:\n runtimeConfig:\n cloudRun:\n automaticTrafficControl: true\n canaryDeployment:\n percentages: [\u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-nv\"\u003ePERCENTAGES\u003c/span\u003e\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 configuration:\n\n- \u003cvar translate=\"no\"\u003ePERCENTAGES\u003c/var\u003e is a comma-separated list of percentage\n values representing your canary increments, for example `[25, 50, 75]`. Note\n that this doesn't include `100`, because 100% percent deployment is\n *assumed* in the canary, and is handled by the\n `stable` phase.\n\n- You can enable [deployment verification](/deploy/docs/verify-deployment)\n (`verify: true`). If you do so, a `verify` job is added to each\n canary phase.\n\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\n 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\n deploying.\n\n### Configure a custom-automated canary\n\nThis combines custom phase definition (names, percentages, profiles, verify, hooks) with Cloud Deploy's automatic traffic management for Cloud Run. You define the phases, but Cloud Deploy handles instructing Cloud Run to shift traffic based on the percentages.\n\nTo configure this, include both the `runtimeConfig.cloudRun.automaticTrafficControl: true` setting and the `customCanaryDeployment` section (defining `phaseConfigs`) within the `strategy.canary` block. Cloud Deploy will use the specified Skaffold profiles for rendering the service definition (which still shouldn't have a `traffic` stanza) but will automatically manage traffic according to the phase percentages. \n\n serialPipeline:\n stages:\n - targetId: cloudrun-prod\n profiles: []\n strategy:\n canary:\n # Include runtimeConfig for automatic traffic management\n runtimeConfig:\n cloudRun:\n automaticTrafficControl: true\n # Include customCanaryDeployment for phase customization\n customCanaryDeployment:\n phaseConfigs:\n - phaseId: \"warmup-cr\"\n percentage: 10\n profiles: [\"base-config\"] # Profile rendering service def (no traffic stanza)\n verify: true\n - phaseId: \"scaling-cr\"\n percentage: 50\n profiles: [\"base-config\"] # Can use the same profile\n verify: true\n - phaseId: \"stable\"\n percentage: 100\n profiles: [\"base-config\"]\n verify: true\n\nExecute the Cloud Run canary\n----------------------------\n\n1. Register Pipeline and Targets: Apply your delivery pipeline and Cloud Run target configuration files.\n\n\n gcloud deploy apply --file=delivery-pipeline.yaml --region=\u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e\n gcloud deploy apply --file=cloudrun-targets.yaml --region=\u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e\n\n The delivery pipeline includes the automated or custom canary configuration,\n for your chosen runtime.\n2. Create a Release: Start the deployment, providing the image name.\n\n\n gcloud deploy releases create \u003cvar translate=\"no\"\u003eRELEASE_NAME\u003c/var\u003e \\\n --delivery-pipeline=\u003cvar translate=\"no\"\u003ePIPELINE_NAME\u003c/var\u003e \\\n --region=\u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e\n\n The delivery pipeline identified by \u003cvar translate=\"no\"\u003ePIPELINE_NAME\u003c/var\u003e\n contains the automated or custom canary configuration described in this\n document.\n3. Advance the canary:\n\n ### gcloud CLI\n\n gcloud deploy rollouts advance \u003cvar translate=\"no\"\u003eROLLOUT_NAME\u003c/var\u003e \\\n --release=\u003cvar translate=\"no\"\u003eRELEASE_NAME\u003c/var\u003e \\\n --delivery-pipeline=\u003cvar translate=\"no\"\u003ePIPELINE_NAME\u003c/var\u003e \\\n --region=\u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e\n\n Where:\n\n \u003cvar translate=\"no\"\u003eROLLOUT_NAME\u003c/var\u003e is the name of the current rollout\n which you're advancing to the next phase.\n\n \u003cvar translate=\"no\"\u003eRELEASE_NAME\u003c/var\u003e is the name of the release that\n this rollout is part of.\n\n \u003cvar translate=\"no\"\u003ePIPELINE_NAME\u003c/var\u003e is the name of the delivery\n pipeline you're using to manage deployment of this release.\n\n \u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e is the name of the region in which the\n release was created, for example `us-central1`. This is required.\n\n See the Google Cloud SDK reference for more information about the\n [`gcloud deploy rollouts advance` command](/sdk/gcloud/reference/deploy/rollouts/advance).\n\n ### Google Cloud console\n\n 1. [Open the Delivery\n pipelines page](https://console.cloud.google.com/deploy/delivery-pipelines).\n\n 2. Click your pipeline shown in the list of delivery pipelines.\n\n The Delivery pipeline details page shows a graphical representation of\n your delivery pipeline's progress.\n 3. On the **Rollouts** tab, under **Delivery pipeline details**, click\n the name of your rollout.\n\n The rollout details page is shown, for that rollout.\n\n Notice that in this example, the rollout has a `canary-50` phase and a\n `stable` phase. Your rollout might have more phases or different\n phases.\n 4. Click **Advance rollout**.\n\n The rollout is advanced to the next phase.\n\n### Skipped phases\n\nIf you deploy a canary and your application has not been deployed to that\nruntime yet, Cloud Deploy skips the canary phase and runs the stable\nphase. See [Skipping phases the first time](/deploy/docs/deployment-strategies#skip_phases)\nto find out why this happens.\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).\n\n- Learn more about [Cloud Run](/run/docs)."]]
