Cloud customer?
Start for Free >
Upgrade in MyJFrog >
What's New in Cloud >

Search





Overview

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:

  • 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.

Page Contents


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; https://www.jfrog.com/confluence/display/JFROG/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"

Tags

name 

An alphanumeric string (underscores are permitted) that identifies the step.

type 

Must be HelmBlueGreenDeploy for this step type.

configuration

Specifies all configuration selections for the step's execution environment. This step inherits the Bash/PowerShell step configuration tags, including these pertinent tags:

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 HelmChartGitRepo, FileSpec, BuildInfo, or ReleaseBundle resource that contains a Helm chart.

Required


In addition, these tags can be defined to support the step's native operation:

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
helmVersionA number representing the major version of Helm to use. Can be either 2 or 3. Defaults to 3.Optional
namespaceTarget 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
blueFlagsA flag string to be included in the Helm command when deploying the blue release. For example: --set key=’value’ -f myTestValues.yamlOptional
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
greenFlagsA flag string to be included in the Helm command when deploying the green release. For example: --set key=’value’ -f myTestValues.yamlOptional
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.

TagDescription of usageRequired/Optional
liveNameName of the Service that points to the environment playing Live role.Required
liveCustomPropertiesjq 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
idleNameName of the Service that points to the environment playing Idle role.Required
idleCustomPropertiesjq 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
blueReferenceNameName 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
greenReferenceNameName 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.

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.

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.

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
lintFlagsFlag 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
testFlagsFlag 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
onStartCommands to execute in advance of the native operationOptional
onSuccessCommands to execute on successful completionOptional
onFailureCommands to execute on failed completionOptional
onCompleteCommands to execute on any completionOptional

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 chartName and chartVersion configuration 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 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
          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:

NameTypeValue
app.kubernetes.io/managed-byLabel"Pipelines"
pipelines.jfrog.com/pipelineAnnotationPipeline name
pipelines.jfrog.com/deploy-stepAnnotationStep name
pipelines.jfrog.com/runAnnotationNumber of the last run to update the Service
pipelines.jfrog.com/referenceAnnotationReference Service name
pipelines.jfrog.com/environmentAnnotationEnvironment currently playing that role
  • No labels
Copyright © 2021 JFrog Ltd.