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"
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 |
---|---|---|
| Must specify a Kubernetes Integration. and Must specify an Artifactory Integration when | Required May be required |
| Must specify HelmChart, GitRepo, 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 | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| A number representing the major version of Helm to use. Can be either 2 or 3. Defaults to 3. | Optional | |||||||||||||||||||||
| Target kubernetes namespace for the deployment. | Required | |||||||||||||||||||||
| The release name for the blue environment. Equivalent to the --name (-n) option of the helm install command. | Required | |||||||||||||||||||||
| A flag string to be included in the Helm command when deploying the blue release. For example: | Optional | |||||||||||||||||||||
| Specifies values YAML file(s) for use with a All environment variables referenced in the specified file(s) are automatically replaced with the values of matching runtime environment variables. | Optional | |||||||||||||||||||||
| The release name for the green environment. Equivalent to the | Required | |||||||||||||||||||||
| A flag string to be included in the Helm command when deploying the green release. For example: | Optional | |||||||||||||||||||||
| Specifies values YAML file(s) for use with a All environment variable referenced in the specified file(s) are automatically replaced with values of matching runtime environment variables. | Optional | |||||||||||||||||||||
| List of services that should be created by Pipelines to assign Idle and Live roles to the releases.
| Required | |||||||||||||||||||||
| The path to the Helm chart in the NoteDo not use when a HelmChart resource is specified. | May be required | |||||||||||||||||||||
| The name of the Helm chart in the NoteDo not use when a HelmChart/GitRepo resource is specified or when your input resource is not an Artifactory Helm repository. | May be required | |||||||||||||||||||||
| The name of the Helm chart in the NoteDo not use when a HelmChart/GitRepo resource is specified or when your input resource is not an Artifactory Helm repository. | May be required | |||||||||||||||||||||
| When true, only deploys if the --dry-run install simulation is successful. Defaults to | Optional | |||||||||||||||||||||
| When set to true, performs a lint to examine a chart for possible issues. Defaults to | Optional | |||||||||||||||||||||
| Flag string to pass to the | Optional | |||||||||||||||||||||
| When set to true, performs a test to run the tests for release. Defaults to | Optional | |||||||||||||||||||||
| Flag string to pass to the | Optional |
execution
Declares collections of shell command sequences to perform for pre- and post-execution phases:
Tag | Description of usage | Required/Optional |
---|---|---|
| Commands to execute in advance of the native operation | Optional |
| Commands to execute on successful completion | Optional |
| Commands to execute on failed completion | Optional |
| 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 chartName
andchartVersion
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 andjq
andConvertFrom-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 |