Configure a Blue/Green Deployment Strategy
What a blue/green strategy does
A blue/green strategy shifts traffic from the running version of your software (blue) to a new version of your software (green) based on conditions you set. You specify conditions that must be met prior to routing traffic to the new version and before shutting down the old version. See the Strategies Overview for details on the advantages of using a blue/green deployment strategy.
How CD-as-a-Service implements blue/green
- CD-as-a-Service deploys a new version of your software without exposing it to external traffic.
- CD-as-a-Service executes one or more user-defined steps in parallel. These steps are pre-conditions for exposing the new version of your software to traffic. For example, you may want to run automated metric analysis or wait for manual approval.
- After all pre-conditions complete successfully, CD-as-a-Service redirects all traffic to the new software version. At this stage of the deployment, the old version of your software is still running but is not receiving external traffic.
- Next, CD-as-a-Service executes one or more user-defined steps in parallel. These steps are pre-conditions for tearing down the old version of your software. For example, you may want to pause for an hour or wait for an additional automated metric analysis.
- After all pre-conditions complete successfully, CD-as-a-Service tears down the old version of your software.
Before you begin
Before configuring a blue/green strategy in your deployment, you should have the following:
Kubernetes Deployment object
Your Kubernetes Deployment object tells Kubernetes how to create and update your app.
Kubernetes Service object
Your Kubernetes Service object sends traffic to the current green version of your app. This active Service can already exist in your cluster, or you can deploy it along with your app. You declare the name of this service in the
trafficManagement.kubernetes.activeServicefield in the deployment config file.
Show me an example Service object
apiVersion: v1 kind: Service metadata: name: <your-app-service> labels: app: <your-app-name> spec: selector: app: <your-app-name> ports: - name: http port: 80 targetPort: 9001 protocol: TCP
Define a blue/green deployment strategy
Declare your strategy
You define your blue/green strategy in the root-level
strategies section of your CD-as-a-Service deployment config file. The strategy has two required fields:
strategies: <name-for-your-blue-green-strategy>: blueGreen: redirectTrafficAfter: shutDownOldVersionAfter:
redirectTrafficAfter: Define the conditions for exposing the new blue version of your app to the active Service. You can add multiple steps, which are all executed in parallel. After all the steps complete successfully, CD-as-a-Service exposes the new version to the active Service.
pause: Pause until a condition is true. You can pause for a set amount of time or until you approve a manual judgment in the UI. When you configure a manual judgment, it’s a good idea to include
approvalExpirationso your deployment cancels if nobody issues a manual approval.Time
redirectTrafficAfter: - pause: duration: <integer> unit: <seconds|minutes|hours>Manual Judgment
redirectTrafficAfter: - pause: untilApproved: true approvalExpiration: duration: <integer> unit: <seconds|minutes|hours>
shutDownOldVersionAfter: Set the conditions for shutting down the old version of your app. You can add multiple steps, which are all executed in parallel. After all the steps complete successfully, CD-as-a-Services shuts down the old version of your app.
pause: Pause until a condition is true. You have the same config choices here as you do in the
Configure your active Service
You also need to configure your active Service in a root-level
trafficManagement section so CD-as-a-Service knows where to route traffic.
trafficManagement: kubernetes: - activeService: <your-app-service>
activeService: This is the name of the Kubernetes Service object you created to route traffic to the current version of your app.
Add your strategy to your deployment target
After you configure your strategy, you need to add it to your deployment targets:
targets: staging: ... strategy: <name-for-your-blue-green-strategy> prod: ... strategy: <name-for-your-blue-green-strategy>
You can define different blue/green strategies for different deployment targets.
Example deployment config file
In this basic example, you deploy an app called “sample-app” with a Service called “sample-app-svc” to two deployment targets.
version: v1 kind: kubernetes application: sample-app targets: staging: account: staging-cluster namespace: staging-ns strategy: sample-app-blue-green prod: account: prod-cluster namespace: prod-ns strategy: sample-app-blue-green manifests: - path: manifests/<your-app>.yaml # the path to and name of your app manifest strategies: sample-app-blue-green: blueGreen: redirectTrafficAfter: - pause: duration: 2 unit: hours shutDownOldVersionAfter: - pause: untilApproved: true approvalDuration: duration: 8 unit: hours trafficManagement: kubernetes: - activeService: sample-app-svc
Show me the app manifest
apiVersion: apps/v1 kind: Deployment metadata: name: sample-app annotations: "app": "sample-app" spec: revisionHistoryLimit: 1 replicas: 2 strategy: type: RollingUpdate rollingUpdate: maxSurge: 2 maxUnavailable: 1 selector: matchLabels: app: sample-app template: metadata: labels: app: sample-app annotations: "app": "sample-app" spec: containers: - image: demoimages/bluegreen:v3 #v5, v4, v3 imagePullPolicy: Always name: sample-app resources: limits: cpu: "100m" # this is to ensure the above busy wait cannot DOS a low CPU cluster. memory: "70Mi" requests: cpu: "10m" # this is to ensure the above busy wait cannot DOS a low CPU cluster. memory: "70Mi" #ports: # - containerPort: 8086 restartPolicy: Always --- apiVersion: v1 kind: Service metadata: name: sample-app-svc labels: app: sample-app annotations: linkerd.io/inject: enabled spec: selector: app: sample-app ports: - name: http port: 80 targetPort: 8000 protocol: TCP
You can programmatically or manually observe the new version of your software before exposing it to traffic. You can accomplish this by defining a preview Service in the
As with the active Service, you need to create a Kubernetes Service object as the preview Service, which sends traffic to the new, blue version of your app. The preview Service must be a different Service object than the active Service. The preview Service needs to exist on your cluster, or you can deploy it alongside your app.
When creating the ReplicaSet for the new version, CD-as-a-Service injects the labels into the preview Service, so that the preview Service points to the new version of app.
Show me an example preview Service
apiVersion: v1 kind: Service metadata: name: <your-new-app-service> labels: app: <your-new-app-name> spec: selector: app: <your-new-app-name> ports: - name: gate-tcp port: 80 protocol: TCP targetPort: 9001
previewService in the
... trafficManagement: kubernetes: - activeService: <your-app-service> previewService: <your-new-app-service> # optional
Target-specific traffic management
You can apply the traffic management settings to specific targets with the
... trafficManagement: - targets: ['staging'] # optionally apply this to only one target, if you have multiple targets kubernetes: - activeService: <your-app-service>
You can add canary analysis as a step in the
shutdownOldVersionAfter blocks. You use the
analysis step to run a set of queries against your deployment. Based on the results of the queries, the deployment can (automatically or manually) roll forward or roll back.
redirectTrafficAfter: - analysis: metricProviderName: <metricProviderName> context: keyName: <value> keyName: <value> interval: <integer> unit: <seconds|minutes|hours> numberOfJudgmentRuns: <integer> rollBackMode: <manual|automatic> rollForwardMode: <manual|automatic> queries: - <queryName> - <queryName>
Expose service resources
The section enables exposing deployed
service resources via a temporary, internet-facing, randomly generated link for testing purposes.
... - exposeServices: services: - <service-name-1> - <service-name-2> - <service-name-n> ttl: duration: <integer> unit: <seconds|minutes|hours>
services: List of one-to-many services to expose
- Each service name must match an existing service deployed in the target cluster.
- Each service must be in the same namespace as the app you are deploying.
- Each service must define a single HTTP port.
ttl: (Optional) The lifetime of the exposed service preview
- Minimum: 1 minute (60 seconds)
- Maximum: 24 hours
- Default: 5 minutes
Each link automatically expires after the configured amount of time. The exposed link is not secure.
You can configure multiple
exposeServices entries, each having a different expiration time.
You can use exposed service links elsewhere in your deploy config, such as in your webhook definitions. The naming convention is
In this example, the snippet instructs Armory CD-as-a-Service to create a public URL to the deployed services service-name-1 and service-name-2. Both automatically expire after 2 hours.
... - exposeServices: services: - service-name-1 - service-name-2 ttl: duration: 2 unit: hours
You can use a webhook-based approval as a step in the
redirectTrafficAfter section. See External Automation Approval Using Webhooks Overview for details on incorporating external automation in your blue/green strategy.
- See the Deployment File Reference for detailed field explanations.
- The Blue/Green Deployment Tutorial shows you how to deploy an app using a blue/green strategy.
Was this page helpful?
Thank you for letting us know!
Sorry to hear that. Please tell us how we can improve.
Last modified August 3, 2023: (10324ed)