HelmBlueGreenDeploy

The HelmBlueGreenDeploy step implements a Blue/Green strategy to deploy a Docker image to a Kubernetes cluster using a Helm chart.

The Helm chart used to deploy the image through this native step can be either:

A HelmChart resource that identifies a Helm chart stored in an Artifactory repository by HelmPublish.
A Helm chart in a source code repository identified by a GitRepo resource.

When properly configured, the HelmBlueGreenDeploy step also performs a replace_envs operation on all files specified under the blueValueFilePaths or greenValueFilePaths tag to replace all environment variables in those files with their values. This enables the step to derive information from a resource, such as the image name and tag from an Image, and use it to perform the deployment.

The HelmBlueGreenDeploy step uses the helm upgrade command to perform the deployment.

Blue/Green Deployment Strategy

Blue/Green deployment is a strategy for releasing new software that uses two production environments, as identical as possible, where they take turns in serving user requests and performing final stages of testing.

The HelmBlueGreenDeploy step refers to those two environments as blue and green. Those environments can play either Idle or Live roles, depending on which environment the users' requests are being forwarded to. The environment that is currently handling user requests is considered Live while the other one is considered Idle. To rollout a new release, it is first deployed to the environment playing the Idle role. There we can validate the new version to check if it is good to become available to users. If that is true, the environment roles can be flipped so that the previously Idle environment becomes Live and starts handling user requests, while the previously Live environment becomes Idle. One of the main advantages of this strategy is that rolling back new releases is as easy as flipping the environments roles again.

Both blue and green environments are represented in the context of Helm as two individual releases that co-exist in the same namespace. The HelmBlueGreenDeploy step assign Idle or Live roles to those releases by creating copies of their public Services dedicated to each role. By doing that we can easily change the release's role by updating those Services to be a copy of the Services from a specific environment. Those role Services created by Pipelines can be used to provision additional entrypoint components like DNS Records, Ingress Rules or Service Meshes.

To implement the complete Blue/Green deployment strategy workflow, Pipelines provides three native steps:

HelmBlueGreenDeploy: From runtime, this step discovers which release is playing Idle role, deploys the chart to it and creates or updates Idle role Services.
elmBlueGreenRoleSwitch: From runtime, this step discovers which release is playing each role and flips them by creating or updating the role Services.
HelmBlueGreenCleanup: From runtime, this step discovers which release is playing Idle role and uninstalls it.

YAML Schema

The YAML schema for HelmBlueGreenDeploy native step is as follows:

HelmBlueGreenDeploy

pipelines:
  - name:   <string>
    steps:
      - name: <string>
        type: HelmBlueGreenDeploy
        configuration:
          #inherits all the tags from bash
          helmVersion:                  <2 | 3>         # optional, defaults to 3
          namespace:                    <string>
          blueReleaseName:              <string>
          blueFlags:                    <string>        # optional
          blueValueFilePaths:                           # optional
            - <path and filename>          
          greenReleaseName:             <string>
          greenFlags:                   <string>        # optional
          greenValueFilePaths:                      # optional
            - <path and filename>          
          roleServices:
            - liveName:             <string>
              liveCustomProperties: <string>        # optional
              idleName:             <string>
              idleCustomProperties: <string>        # optional
              blueReferenceName:    <string>
                          greenReferenceName:   <string>              
          chartPath:                    <path string>   # optional, may be required for certain input resources
                  chartName:                <path string>   # optional, may be required for certain input resources
                  chartVersion:             <path string>   # optional, may be required for certain input resources
          dryRun:                   <true | false>  # optional, only deploys if the dryrun is success
          lint:                     <true | false>  # lints chart before upgrade, default false
          lintFlags: “--strict”
          test:                     <true | false>  # runs helm test after upgrade, default false
          testFlags: “--parallel”

          integrations:
            - name:         <kubernetes integration>                         # required
          inputResources:
            - name:         <HelmChart, GitRepo, FileSpec or BuildInfo resource>        # required, only one input resource is allowed

        execution:
          onStart:
            - echo "Preparing for work..."
          onSuccess:
            - echo "Job well done!"
          onFailure:
            - echo "uh oh, something went wrong"
          onComplete: #always
            - echo "Cleaning up some stuff"

Tag	Description of usage	Required/Optional
`integrations`	Must specify a Kubernetes Integration. and Must specify an Artifactory Integration when `ReleaseBundle` is the `inputResource`for the step.	Required May be required
`inputResources`	Must specify HelmChart, GitRepo, FileSpec, BuildInfo, or ReleaseBundle resource that contains a Helm chart.	Required

Tags derived from Bash

All native steps derive from the Bash step. This means that all steps share the same base set of tags from Bash, while native steps have their own additional tags as well that support the step's particular function. So it's important to be familiar with the Bash step definition, since it's the core of the definition of all other steps.

Tag

Description of usage

Required/Optional

helmVersion

A number representing the major version of Helm to use. Can be either 2 or 3. Defaults to 3.

Optional

namespace

Target kubernetes namespace for the deployment.

Required

blueReleaseName

The release name for the blue environment. Equivalent to the --name (-n) option of the helm install command.

Required

blueFlags

A flag string to be included in the Helm command when deploying the blue release. For example: --set key=’value’ -f myTestValues.yaml

Optional

blueValueFilePaths

Specifies values YAML file(s) for use with a --values (-f) option of the helm install command when deploying the blue release.

All environment variables referenced in the specified file(s) are automatically replaced with the values of matching runtime environment variables.

Optional

greenReleaseName

The release name for the green environment. Equivalent to the --name (-n) option of the helm install command.

Required

greenFlags

A flag string to be included in the Helm command when deploying the green release. For example: --set key=’value’ -f myTestValues.yaml

Optional

greenValueFilePaths

Specifies values YAML file(s) for use with a --values (-f) option of the helm install command when deploying the green release.

All environment variable referenced in the specified file(s) are automatically replaced with values of matching runtime environment variables.

Optional

roleServices

List of services that should be created by Pipelines to assign Idle and Live roles to the releases.

Tag	Description of usage	Required/Optional
`liveName`	Name of the Service that points to the environment playing Live role.	Required
`liveCustomProperties`	`jq` expression to be executed on the Live Service after the content is copied from the reference Service and before applying it to the kubernetes cluster. Can be used to customize the Live Service content. For instance, to assign a custom label use the following expression: `".metadata.labels.my-label = my-value".`	Optional
`idleName`	Name of the Service that points to the environment playing Idle role.	Required
`idleCustomProperties`	`jq` expression to be executed on this Idle Service after the content is copied from the reference Service and before applying it to the kubernetes cluster. Can be used to customize the Idle Service content. For instance, to assign a custom label use the following expression: `". metadata.labels.my-label = my-value".`	Optional
`blueReferenceName`	Name of the Service deployed by the blue release that will be used as reference when creating or updating this role Service. When blue is playing Live role, `liveName` will be a copy of this Service. If blue is playing Idle role, `idleName` will be a copy of this Service.	Required
`greenReferenceName`	Name of the Service deployed by the green release that will be used as reference when creating or updating this role Service. When green is playing Live role, `liveName` will be a copy of this Service. If green is playing Idle role, `idleName` will be a copy of this Service.

Required

chartPath

The path to the Helm chart in the GitRepo/FileSpec/BuildInfo/ReleaseBundle resource specified in inputResources.

Note

Do not use when a HelmChart resource is specified.

May be required

chartName

The name of the Helm chart in the FileSpec/BuildInfo/ReleaseBundle resource specified in inputResources.

Note

Do not use when a HelmChart/GitRepo resource is specified or when your input resource is not an Artifactory Helm repository.

May be required

chartVersion

The name of the Helm chart in the FileSpec/BuildInfo/ReleaseBundle resource specified in inputResources.

Note

Do not use when a HelmChart/GitRepo resource is specified or when your input resource is not an Artifactory Helm repository.

May be required

dryRun

When true, only deploys if the --dry-run install simulation is successful.

Defaults to false.

Optional

lint

When set to true, performs a lint to examine a chart for possible issues.

Defaults to false.

Optional

lintFlags

Flag string to pass to the helm lint command.

Optional

test

When set to true, performs a test to run the tests for release.

Defaults to false.

Optional

testFlags

Flag string to pass to the helm test command.

Optional

execution

Declares collections of shell command sequences to perform for pre- and post-execution phases:

Tag	Description of usage	Required/Optional
`onStart`	Commands to execute in advance of the native operation	Optional
`onSuccess`	Commands to execute on successful completion	Optional
`onFailure`	Commands to execute on failed completion	Optional
`onComplete`	Commands to execute on any completion	Optional

The actions performed for the onExecute phase are inherent to this step type and may not be overridden.

Examples

The following examples show how to configure a HelmBlueGreenDeploy step.

Helm 3 and HelmChart Resource Input

A HelmBlueGreenDeploy step using Helm 3 and a HelmChart resource input.

HelmBlueGreenDeploy

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmBlueGreenDeploy
        configuration: 
          helmVersion: 3
          namespace: app-namespace
          blueReleaseName: app-blue
          greenReleaseName: app-green
          roleServices:
            - blueReferenceName: app-blue-service
              greenReferenceName: app-green-service 
              idleName: app-idle-service
              liveName: app-service
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: helmChartResource

Dry Run

A HelmBlueGreenDeploy step using Helm 3 and a HelmChart resource input with values files and a dry run before the deployment.

HelmBlueGreenDeploy

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmBlueGreenDeploy
        configuration: 
          helmVersion: 3
          namespace: app-namespace
          blueReleaseName: app-blue
          blueValueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          greenReleaseName: app-green
          greenValueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          roleServices:
            - blueReferenceName: app-blue-service
              greenReferenceName: app-green-service 
              idleName: app-idle-service
              liveName: app-service
          dryRun: true          
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: helmChartResource

GitRepo Input

A HelmBlueGreenDeploy step with a GitRepo input instead of a HelmChart, lint and test commands.

HelmBlueGreenDeploy

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmBlueGreenDeploy
        configuration: 
          helmVersion: 3
          namespace: app-namespace
          blueReleaseName: app-blue
          blueFlags: "--set key=value"
          greenReleaseName: app-green
          greenFlags: "--set key=value"
          roleServices:
            - blueReferenceName: app-blue-service
              greenReferenceName: app-green-service 
              idleName: app-idle-service
              liveName: app-service
          chartPath: "./myChart"
          lint: true
          lintFlags: "--strict"
          test: true
          testFlags: "--parallel"
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: gitRepoResource

FileSpec Input

A HelmBlueGreenDeploy step with a FileSpec input resource. When using the FileSpec input resource, use the chartPath property to specify where the Helm chart file is in the FileSpec resource. If the FileSpec represents a Generic repository in Artifactory that contains the Helm chart, use the following configuration as a reference:

HelmBlueGreenDeploy

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmBlueGreenDeploy
        configuration: 
          helmVersion: 3
          namespace: app-namespace
          blueReleaseName: app-blue
          greenReleaseName: app-green
          roleServices:
            - blueReferenceName: app-blue-service
              greenReferenceName: app-green-service 
              idleName: app-idle-service
              liveName: app-service
          chartPath: "./myChart"          
          lint: true
          lintFlags: "--strict"
          test: true
          testFlags: "--parallel"
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: fileSpecResource

If the FileSpec input resource represents a Helm repository in Artifactory, you will also need to provide the chartNameandchartVersionconfiguration properties:

HelmBlueGreenDeploy

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmBlueGreenDeploy
        configuration: 
          helmVersion: 3
          namespace: app-namespace
          blueReleaseName: app-blue
          greenReleaseName: app-green
          roleServices:
            - blueReferenceName: app-blue-service
              greenReferenceName: app-green-service 
              idleName: app-idle-service
              liveName: app-service
          chartPath: "./myChart"
                  chartName: "myChartName"
                  chartVersion: 0.0.1          
          lint: true
          lintFlags: "--strict"
          test: true
          testFlags: "--parallel"
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: fileSpecResource

BuildInfo Input

A HelmBlueGreenDeploy step with a BuildInfo input resource. When using the BuildInfo input resource, use the chartPath property to specify where the Helm chart file is in the BuildInfo resource. If the BuildInfo represents a Generic repository in Artifactory that contains the Helm chart, use the following configuration as a reference:

HelmBlueGreenDeploy

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmBlueGreenDeploy
        configuration: 
          helmVersion: 3
          namespace: app-namespace
          blueReleaseName: app-blue
          blueValueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          greenReleaseName: app-green
          greenValueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          roleServices:
            - blueReferenceName: app-blue-service
              greenReferenceName: app-green-service 
              idleName: app-idle-service
              liveName: app-service
          chartPath: "./myChart"          
          lint: true
          lintFlags: "--strict"
          test: true
          testFlags: "--parallel"          
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: buildInfoResource

If the BuildInfo input resource represents a Helm repository in Artifactory, you will also need to provide the chartName and chartVersionconfiguration properties:

HelmBlueGreenDeploy

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmBlueGreenDeploy
        configuration: 
          helmVersion: 3
          namespace: app-namespace
          blueReleaseName: app-blue
          blueValueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          greenReleaseName: app-green
          greenValueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          roleServices:
            - blueReferenceName: app-blue-service
              greenReferenceName: app-green-service 
              idleName: app-idle-service
              liveName: app-service
          chartPath: "./myChart"
                  chartName: "myChartName"
                  chartVersion: 0.0.1
          lint: true
          lintFlags: "--strict"
          test: true
          testFlags: "--parallel"          
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: buildInfoResource

ReleaseBundle Input

A HelmBlueGreenDeploy step with a ReleaseBundle input resource. When using the ReleaseBundle input resource you will need to specify where the Helm chart file is in the ReleaseBundle resource using the chartPath property.

If the ReleaseBundle represents a Generic repository in Artifactory that contains the Helm chart, please use the following configuration as a reference:

Artifactory integration is required

You must specify an Artifactory Integration when ReleaseBundle is the inputResource to HelmBlueGreenDeploy step. This integration will point to the Artifactory that will be the source to download the ReleaseBundle that will be used in this step.

HelmBlueGreenDeploy

pipelines:
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmBlueGreenDeploy
        configuration:
          helmVersion: 3
          namespace: app-namespace
          blueReleaseName: app-blue
          blueValueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          greenReleaseName: app-green
          greenValueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          roleServices:
            - blueReferenceName: app-blue-service
              greenReferenceName: app-green-service 
              idleName: app-idle-service
              liveName: app-service
          chartPath: "./myChart"          
          lint: true
          lintFlags: "--strict"
          test: true
          testFlags: "--parallel"
          integrations:
            - name: kubernetes_integration
            - name: artifactory_integration
          inputResources:
            - name: releaseBundleResource

If the ReleaseBundle input resource represents a Helm repository in Artifactory, you will also have to specify chartName and chartVersion configuration properties:

HelmBlueGreenDeploy

pipelines:
  - name: helmDeployPipeline   
    steps:
      - name: helmDeployStep
        type: HelmBlueGreenDeploy
        configuration:
          helmVersion: 3
          namespace: app-namespace
          blueReleaseName: app-blue
          blueValueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          greenReleaseName: app-green
          greenValueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          roleServices:
            - blueReferenceName: app-blue-service
              greenReferenceName: app-green-service 
              idleName: app-idle-service
              liveName: app-service
          chartPath: "./myChart"
          chartName: "myChartName"
          chartVersion: 0.0.1          
          lint: true
          lintFlags: "--strict"
          test: true
          testFlags: "--parallel"
          integrations:
            - name: kubernetes_integration
                        - name: artifactory_integration 
          inputResources:
            - name: releaseBundleResource

Customizing Role Services

A HelmBlueGreenDeploy step with two custom labels assigned to a role Service.

HelmBlueGreenDeploy

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmBlueGreenDeploy
        configuration: 
          helmVersion: 3
          namespace: app-namespace
          blueReleaseName: app-blue
          greenReleaseName: app-green
          roleServices:
            - blueReferenceName: app-blue-service
              greenReferenceName: app-green-service 
              idleName: app-idle-service
              idleCustomProperties: ".metadata.labels.mylabel = \"value\" | .metadata.labels.role = \"idle\""
              liveName: app-service
              liveCustomProperties: ".metadata.labels.mylabel = \"value\" | .metadata.labels.role = \"live\""
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: helmChartResource

Multiple Public Services

A HelmBlueGreenDeploy step that deploys a Helm Chart that exposes two Services.

HelmBlueGreenDeploy

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmBlueGreenDeploy
        configuration: 
          helmVersion: 3
          namespace: app-namespace
          blueReleaseName: app-blue
          greenReleaseName: app-green
          roleServices:
            - blueReferenceName: app-blue-service
              greenReferenceName: app-green-service 
              idleName: app-idle-service              
              liveName: app-service
            - blueReferenceName: app-blue-admin-service
              greenReferenceName: app-green-admin-service 
              idleName: app-idle-admin-service              
              liveName: app-admin-service
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: helmChartResource

Helm 2

A HelmBlueGreenDeploy step using Helm 2.

HelmBlueGreenDeploy

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmBlueGreenDeploy
        configuration: 
          helmVersion: 2
          namespace: app-namespace
          blueReleaseName: app-blue
          greenReleaseName: app-green
          roleServices:
            - blueReferenceName: app-blue-service
              greenReferenceName: app-green-service 
              idleName: app-idle-service
              liveName: app-service          
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: helmChartResource

How it Works

When you use the HelmBlueGreenDeploy native step in a pipeline, it performs the following functions in the background:

helm init --client-only (if the Helm version is 2)
jfrog rt config (if there is a HelmChart resource input, to configure the JFrog CLI with the Artifactory credentials)
jfrog rt use (if there is a HelmChart resource input, to set the current default Artifactory configuration)
kubectl get service (fetch Live Services to read annotations and discover current Idle environment)
helm fetch (if there is a HelmChart resource input and the Helm version is 2, to fetch the chart)
helm pull (if there is a HelmChart resource input and the Helm version is 3, to fetch the chart)
replace_envs (if there are valueFilePaths, to replace variable placeholders)
helm lint (if lint is true)
helm --dry-run (if dryRun is true)
helm (deploy)
kubectl get service (fetch reference Services deployed by helm to create or update role Services)
Cleanup and update role Services definition (uses jq on Bash nodes and jq and ConvertFrom-Json on PowerShell nodes)
kubectl apply (create or update role Services)
add_pipeline_files (saves HelmBlueGreenDeploy configuration to be used by HelmBlueGreenRoleSwitch and HelmBlueGreenCleanup steps later)
helm test (if test is true)

Pipelines Managed Services

The role Services managed by Pipelines can be identified by the following labels and annotations metadata:

Name	Type	Value
app.kubernetes.io/managed-by	Label	"Pipelines"
pipelines.jfrog.com/pipeline	Annotation	Pipeline name
pipelines.jfrog.com/deploy-step	Annotation	Step name
pipelines.jfrog.com/run	Annotation	Number of the last run to update the Service
pipelines.jfrog.com/reference	Annotation	Reference Service name
pipelines.jfrog.com/environment	Annotation	Environment currently playing that role