PipeCD – Examples

Docs-V0.56.x: Canary deployment for Kubernetes app with Istio

Mon, 01 Jan 0001 00:00:00 +0000

Canary release is a technique to reduce the risk of introducing a new software version in production by slowly rolling out the change to a small subset of users before rolling it out to the entire infrastructure and making it available to everybody. – martinfowler.com/canaryrelease

With Istio, we can accomplish this goal by configuring a sequence of rules that route a percentage of traffic to each variant of the application. And with PipeCD, you can enable and automate the canary strategy for your Kubernetes application even easier.

In this guide, we will show you how to configure the application configuration file to send 10% of traffic to the new version and keep 90% to the primary variant. Then after waiting for manual approval, you will complete the migration by sending 100% of traffic to the new version.

Complete source code for this example is hosted in pipe-cd/examples repository.

Before you begin

Add a new Kubernetes application by following the instructions in this guide
Ensure having pipecd.dev/variant: primary label and selector in the workload template
Ensure having at least one Istio’s DestinationRule and defining the needed subsets (primary and canary) with pipecd.dev/variant label

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: mesh-istio-canary
spec:
  host: mesh-istio-canary.default.svc.cluster.local
  subsets:
  - name: primary
    labels:
      pipecd.dev/variant: primary
  - name: canary
    labels:
      pipecd.dev/variant: canary

Ensure having at least one Istio’s VirtualService manifest and all traffic is routed to the primary

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: mesh-istio-canary
spec:
  hosts:
    - mesh-istio-canary.pipecd.dev
  gateways:
    - mesh-istio-canary
  http:
    - route:
      - destination:
          host: mesh-istio-canary.default.svc.cluster.local
          subset: primary
        weight: 100

Enabling canary strategy

Add the following application configuration file into the application directory in Git.

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      - name: K8S_CANARY_ROLLOUT
        with:
          replicas: 50%
      - name: K8S_TRAFFIC_ROUTING
        with:
          canary: 10
          primary: 90
      - name: WAIT_APPROVAL
      - name: K8S_PRIMARY_ROLLOUT
      - name: K8S_TRAFFIC_ROUTING
        with:
          primary: 100
      - name: K8S_CANARY_CLEAN
  trafficRouting:
    method: istio
    istio:
      host: mesh-istio-canary.default.svc.cluster.local

Send a PR to update the container image version in the Deployment manifest and merge it to trigger a new deployment. PipeCD will plan the deployment with the specified canary strategy.

Deployment Details Page

Now you have an automated canary deployment for your application. 🎉

Understanding what happened

In this example, you configured the application configuration file to migrate traffic from an old to a new version of the application using Istio’s weighted routing feature.

Stage 1: K8S_CANARY_ROLLOUT ensures that the workloads of canary variant (new version) should be deployed. But at this time, they still handle nothing, all traffic are handled by workloads of primary variant. The number of workloads (e.g. pod) for canary variant is configured to be 50% of the replicas number of primary varant.

Stage 2: K8S_TRAFFIC_ROUTING ensures that 10% of traffic should be routed to canary variant and 90% to primary variant. Because the trafficRouting is configured to use Istio, PipeCD will find Istio’s VirtualService resource of this application to control the traffic percentage.

Stage 3: WAIT_APPROVAL waits for a manual approval from someone in your team.
Stage 4: K8S_PRIMARY_ROLLOUT ensures that all resources of primary variant will be updated to the new version.

Stage 5: K8S_TRAFFIC_ROUTING ensures that all traffic should be routed to primary variant. Now primary variant is running the new version so it means all traffic is handled by the new version.

Stage 6: K8S_CANARY_CLEAN ensures all created resources for canary variant should be destroyed.

Docs-V0.56.x: BlueGreen deployment for Kubernetes app with Istio

Mon, 01 Jan 0001 00:00:00 +0000

Similar to canary deployment, PipeCD allows you to enable and automate the blue-green deployment strategy for your application based on Istio’s weighted routing feature.

In both canary and blue-green strategies, the old version and the new version of the application get deployed at the same time. But while the canary strategy slowly routes the traffic to the new version, the blue-green strategy quickly routes all traffic to one of the versions.

In this guide, we will show you how to configure the application configuration file to apply the blue-green strategy.

Complete source code for this example is hosted in pipe-cd/examples repository.

Before you begin

Add a new Kubernetes application by following the instructions in this guide
Ensure having pipecd.dev/variant: primary label and selector in the workload template
Ensure having at least one Istio’s DestinationRule and defining the needed subsets (primary and canary) with pipecd.dev/variant label

apiVersion: networking.istio.io/v1beta1
kind: DestinationRule
metadata:
  name: mesh-istio-bluegreen
spec:
  host: mesh-istio-bluegreen
  subsets:
  - name: primary
    labels:
      pipecd.dev/variant: primary
  - name: canary
    labels:
      pipecd.dev/variant: canary
  trafficPolicy:
    tls:
      mode: ISTIO_MUTUAL

Ensure having at least one Istio’s VirtualService manifest and all traffic is routed to the primary

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: mesh-istio-bluegreen
spec:
  hosts:
    - mesh-istio-bluegreen.pipecd.dev
  gateways:
    - mesh-istio-bluegreen
  http:
    - route:
      - destination:
          host: mesh-istio-bluegreen
          subset: primary
        weight: 100

Enabling blue-green strategy

Add the following application configuration file into the application directory in the Git repository.

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      - name: K8S_CANARY_ROLLOUT
        with:
          replicas: 100%
      - name: K8S_TRAFFIC_ROUTING
        with:
          all: canary
      - name: WAIT_APPROVAL
      - name: K8S_PRIMARY_ROLLOUT
      - name: K8S_TRAFFIC_ROUTING
        with:
          all: primary
      - name: K8S_CANARY_CLEAN
  trafficRouting:
    method: istio
    istio:
      host: mesh-istio-bluegreen

Send a PR to update the container image version in the Deployment manifest and merge it to trigger a new deployment. PipeCD will plan the deployment with the specified blue-green strategy.

Deployment Details Page

Now you have an automated blue-green deployment for your application. 🎉

Understanding what happened

In this example, you configured the application configuration file to switch all traffic from an old to a new version of the application using Istio’s weighted routing feature.

Stage 1: K8S_CANARY_ROLLOUT ensures that the workloads of canary variant (new version) should be deployed. But at this time, they still handle nothing, all traffic is handled by workloads of primary variant. The number of workloads (e.g. pod) for canary variant is configured to be 100% of the replicas number of primary varant.

Stage 2: K8S_TRAFFIC_ROUTING ensures that all traffic should be routed to canary variant. Because the trafficRouting is configured to use Istio, PipeCD will find Istio’s VirtualService resource of this application to control the traffic percentage. (You can add an ANALYSIS stage after this to validate the new version. When any negative impacts are detected, an auto-rollback stage will be executed to switch all traffic back to the primary variant.)

Stage 3: WAIT_APPROVAL waits for a manual approval from someone in your team.
Stage 4: K8S_PRIMARY_ROLLOUT ensures that all resources of primary variant will be updated to the new version.

Stage 5: K8S_TRAFFIC_ROUTING ensures that all traffic should be routed to primary variant. Now primary variant is running the new version so it means all traffic is handled by the new version.

Stage 6: K8S_CANARY_CLEAN ensures all created resources for canary variant should be destroyed.

Docs-V0.56.x: Canary deployment for Kubernetes app with PodSelector

Mon, 01 Jan 0001 00:00:00 +0000

Using service mesh like Istio helps you doing canary deployment easier with many powerful features, but not all teams are ready to use service mesh in their environment. This page will walk you through using PipeCD to enable canary deployment for Kubernetes application running in a non-mesh environment.

Basically, the idea behind is described as this Kubernetes document; the Service resource uses the common label set to route the traffic to both canary and primary workloads, and percentage of traffic for each variant is based on their replicas number.

Enabling canary strategy

Assume your application has the following Service and Deployment manifests:

service.yaml

apiVersion: v1
kind: Service
metadata:
  name: helloworld
spec:
  selector:
    app: helloworld
  ports:
    - protocol: TCP
      port: 9085

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: helloworld
  labels:
    app: helloworld
    pipecd.dev/variant: primary
spec:
  replicas: 30
  revisionHistoryLimit: 2
  selector:
    matchLabels:
      app: helloworld
      pipecd.dev/variant: primary
  template:
    metadata:
      labels:
        app: helloworld
        pipecd.dev/variant: primary
    spec:
      containers:
      - name: helloworld
        image: gcr.io/pipecd/helloworld:v0.1.0
        args:
          - server
        ports:
          - containerPort: 9085

In PipeCD context, manifests defined in Git are the manifests for primary variant, so please note to ensure that your deployment manifest contains pipecd.dev/variant: primary label and selector in the spec.

To enable canary strategy for this Kubernetes application, you will update your application configuration file to be as below:

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  pipeline:
    stages:
      # Deploy the workloads of CANARY variant. In this case, the number of
      # workload replicas of CANARY variant is 50% of the replicas number of PRIMARY variant.
      - name: K8S_CANARY_ROLLOUT
        with:
          replicas: 50%
      - name: WAIT_APPROVAL
        with:
          duration: 10s
      # Update the workload of PRIMARY variant to the new version.
      - name: K8S_PRIMARY_ROLLOUT
      # Destroy all workloads of CANARY variant.
      - name: K8S_CANARY_CLEAN

That is all, now let try to send a PR to update the container image version in the Deployment manifest and merge it to trigger a new deployment. Then, PipeCD will plan the deployment with the specified canary strategy.

Deployment Details Page

Complete source code for this example is hosted in pipe-cd/examples repository.

Understanding what happened

In this example, you configured your application to be deployed with a canary strategy using a native feature of Kubernetes: pod selector. The traffic will be routed to both canary and primary workloads because they are sharing the same label: app: helloworld. The percentage of traffic for each variant is based on the respective number of pods.

Here are what happened in details:

Before deploying, all traffic gets routed to primary workloads.

Stage 1: K8S_CANARY_ROLLOUT ensures that the workloads of canary variant (new version) should be deployed. The number of workloads (e.g. pod) for canary variant is configured to be 50% of the replicas number of primary variant. It means 15 canary pods will be started, and they receive 33.3% traffic while primary workloads receive the remaining 66.7% traffic.

Stage 2: WAIT_APPROVAL waits for a manual approval from someone in your team.
Stage 3: K8S_PRIMARY_ROLLOUT ensures that all resources of primary variant will be updated to the new version.

Stage 4: K8S_CANARY_CLEAN ensures all created resources for canary variant should be destroyed. After that, the primary workloads running in with the new version will receive all traffic.

Docs-V0.56.x: BlueGreen deployment for Kubernetes app with PodSelector

Mon, 01 Jan 0001 00:00:00 +0000

TBA

For applications that are not deployed on a service mesh, PipeCD can enable blue-green deployment with Kubernetes L4 networking.