Canary-deploy an application to a target

This quickstart shows you how to use Cloud Deploy to deliver a sample application image in a canary deployment to either Google Kubernetes Engine or to Cloud Run. (You can also run a canary deployment to GKE attached clusters, but only GKE and Cloud Run are shown in this quickstart.)

A canary deployment splits traffic between an already-deployed version of the application and the new version. Cloud Run apportions traffic based on the percentages you configure in the delivery pipeline. GKE deploys the new version to a proportion of pods. This quickstart deploys to 50% first, then to 100%.

In this quickstart, there is only one target, (prod). So we create only one GKE cluster or one Cloud Run service to run your application.

In this quickstart, you'll do the following:

  1. Create one GKE cluster or define one Cloud Run service.

    You can canary deploy to GKE attached clusters too, but this quickstart uses GKE and Cloud Run only.

  2. Create a Skaffold configuration and a Kubernetes manifest to specify the (pre-built) container image to deploy.

  3. Define your Cloud Deploy delivery pipeline and deployment target.

  4. Invoke your delivery pipeline by creating a release, which automatically deploys to one target.

    This first release skips the canary phase.

  5. View the delivery pipeline and release in the Google Cloud console.

  6. Create a second release, this time executing the canary stage to deploy the application to 50%.

  7. Advance the release to deploy to 100%.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Cloud Deploy, Cloud Build, GKE, Cloud Run, and Cloud Storage APIs.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. Install the Google Cloud CLI.

  6. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  7. To initialize the gcloud CLI, run the following command: 

    gcloud init

  8. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  9. Verify that billing is enabled for your Google Cloud project.

  10. Enable the Cloud Deploy, Cloud Build, GKE, Cloud Run, and Cloud Storage APIs.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  11. Install the Google Cloud CLI.

  12. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  13. To initialize the gcloud CLI, run the following command: 

    gcloud init

    14. If you already have the CLI installed, make sure you're running the latest version:

    gcloud components update

  14. Make sure the default Compute Engine service account has sufficient permissions.

    The service account might already have the necessary permissions. These steps are included for projects that disable automatic role grants for default service accounts.

    1. First add the clouddeploy.jobRunner role: 

      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:$(gcloud projects describe PROJECT_ID \
    --format="value(projectNumber)")-compute@developer.gserviceaccount.com \
    --role="roles/clouddeploy.jobRunner"

    2. Add the developer role for your specific runtime.
      • For GKE, and GKE with Gateway API: 

        gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:$(gcloud projects describe PROJECT_ID \
    --format="value(projectNumber)")-compute@developer.gserviceaccount.com \
    --role="roles/container.developer"

      • For Cloud Run: 

        gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:$(gcloud projects describe PROJECT_ID \
    --format="value(projectNumber)")-compute@developer.gserviceaccount.com \
    --role="roles/run.developer"

    3. Add the iam.serviceAccountUser role, which includes the actAspermission to deploy to the runtime:

      gcloud iam service-accounts add-iam-policy-binding $(gcloud projects describe PROJECT_ID \
    --format="value(projectNumber)")-compute@developer.gserviceaccount.com \
    --member=serviceAccount:$(gcloud projects describe PROJECT_ID \
    --format="value(projectNumber)")-compute@developer.gserviceaccount.com \
    --role="roles/iam.serviceAccountUser" \
    --project=PROJECT_ID

Create your runtime environment

GKE

Create one GKE Autopilot cluster:

 gcloud container clusters create-auto canary-quickstart-cluster \
                  --project=PROJECT_ID \
                  --region=us-central1

GKE + Gateway API

  1. Create one GKE cluster, with recommended settings to support using with Istio:

    gcloud container clusters create canary-quickstart-cluster \
       --machine-type=n1-standard-1 \
       --num-nodes 4 \
       --region=us-central1 \
       --project=PROJECT_ID

  2. Get the cluster credentials:

    gcloud container clusters get-credentials canary-quickstart-cluster \
       --project=PROJECT_ID \
       --region=us-central1

  3. Install the Kubernetes Gateway API CRDs if not already present on the cluster.

    kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.6.2/standard-install.yaml

  4. Enable Istio's Gateway controller implementation by installing Istio.

    curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.17.2 sh - \
&& ./istio-1.17.2/bin/istioctl install --set profile=minimal -y

Cloud Run

If you're using Cloud Run, you can skip this command, you don't need to do anything here.

Prepare your Skaffold configuration and application manifest

Cloud Deploy uses Skaffold to provide the details for what to deploy and how to deploy it properly to your target.

In this quickstart, you create a skaffold.yaml file, which identifies the Kubernetes manifest or Cloud Run service configuration to be deployed.

  1. Open a terminal window.

  2. Create a new directory and navigate into it.

    GKE 

    mkdir deploy-canary-quickstart-gke
cd deploy-canary-quickstart-gke

    GKE + Gateway API 

    mkdir deploy-canary-quickstart-gke-gatewayapi
cd deploy-canary-quickstart-gke-gatewayapi

    Cloud Run 

    mkdir deploy-canary-quickstart-run
cd deploy-canary-quickstart-run

  3. Create a file named skaffold.yaml with the following contents:

    GKE 

    apiVersion: skaffold/v4beta7
kind: Config
manifests:
  rawYaml:
  - kubernetes.yaml
deploy:
  kubectl: {}

    GKE + Gateway API 

    apiVersion: skaffold/v4beta7
kind: Config
manifests:
  rawYaml:
  - kubernetes.yaml
deploy:
  kubectl: {}

    Cloud Run 

    apiVersion: skaffold/v4beta7
kind: Config
manifests:
  rawYaml:
  - run.yaml
deploy:
  cloudrun: {}

    This file is a minimal Skaffold config, identifying your manifest. For this quickstart, you create the file. But you can also have Cloud Deploy create one for you, for simple, non-production applications.

    See the skaffold.yaml reference for more information about this file.

  4. Create your application manifest.

    GKE

    Create a file named kubernetes.yaml, in the deploy-canary-quickstart-gke directory, with the following contents:

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  labels:
    app: my-app
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: nginx
        image: my-app-image
---
apiVersion: v1
kind: Service
metadata:
  name: my-service
  namespace: default
spec:
  selector:
    app: my-app
  ports:
    - protocol: TCP
      port: 80

    This file is a Kubernetes manifest, which is applied to the cluster to deploy the application. This manifest includes the Service and Deployment resources required for canary deployment, plus an HTTPRoute and the Gateway resource needed for using Gateway API.

    The container image to deploy is set here as a placeholder, my-app-image, which is replaced with the specific image when you create the release.

    GKE + Gateway API

    Create a file named kubernetes.yaml, in the deploy-canary-quickstart-gke-gatewayapi directory, with the following contents:

    kind: Gateway
apiVersion: gateway.networking.k8s.io/v1beta1
metadata:
  name: my-gateway
  annotations:
    networking.istio.io/service-type: "ClusterIP"
spec:
  gatewayClassName: istio
  listeners:
  - name: default
    hostname: "*.example.com"
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces: