Overview

The HelmDeploy step deploys 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 HelmDeploy step also performs a replace_envs operation on all files specified under the valueFilePaths 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 HelmDeploy step uses the helm upgrade command to perform the deployment.

YAML Schema

The YAML schema for HelmDeploy native step is as follows:

pipelines:
  - name:   <string>
    steps:
      - name: <string>
        type: HelmDeploy
        configuration:
          #inherits all the tags from bash; https://www.jfrog.com/confluence/display/JFROG/Bash
          helmVersion:         <2 | 3>          # optional, defaults to 2
          namespace:               <string>     # optional, namespace to which to deploy
          flags:               <string>         # optional
          valueFilePaths:                       # optional
            - <path and filename>
          releaseName:         <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, BuildInfo or ReleaseBundle resource>    # required, one input resource from this list is required
																						           # HelmChart and GitRepo input resources are allowed together       
        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 HelmDeploy 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.

or

Must specify an Artifactory Integration when ReleaseBundle is the inputResource to the step.

Required


May be required

inputResources 

Must specify HelmChart, GitRepo, FileSpec ,BuildInfo or ReleaseBundle resource that contains a Helm chart.
Can also specify a second input resource of type GitRepo containing Helm values files, if HelmChart was provided as the other input resource.

Required


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

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 2 or 3. Defaults to 2.Optional
namespaceThe namespace to which to deploy. This will be added to the deploy command as a --namespace parameter.Optional
flagsA flag string to be included in the Helm command. For example: "--set key=’value’ -f myTestValues.yaml"Optional
valueFilePaths

Specifies values YAML file(s) for use with a--values (-f) option of the  command.

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

Optional
releaseName

The release name. Equivalent to the --name (-n) option of the  command.

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  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  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 HelmDeploy step.

Helm 3 and HelmChart Resource Input

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

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmDeploy
        configuration: 
          helmVersion: 3
          namespace: my-namespace
          releaseName: myHelmRelease
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: helmChartResource

Dry Run

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

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmDeploy
        configuration: 
          helmVersion: 3
          namespace: my-namespace
          releaseName: myHelmRelease
          dryRun: true
          valueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: helmChartResource

GitRepo Input

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

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmDeploy
        configuration: 
          helmVersion: 3
          namespace: my-namespace
          chartPath: "./myChart"
          releaseName: myHelmRelease
          lint: true
          lintFlags: "--strict"
          test: true
          testFlags: "--parallel"
          valueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: gitRepoResource

FileSpec Input

A HelmDeploy 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:

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmDeploy
        configuration: 
          helmVersion: 3
          namespace: my-namespace
          chartPath: "./myChart"
          releaseName: myHelmRelease
          lint: true
          lintFlags: "--strict"
          test: true
          testFlags: "--parallel"
          valueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          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:

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmDeploy
        configuration: 
          helmVersion: 3
          namespace: my-namespace
          chartPath: "./myChart"
		  chartName: "myChartName"
		  chartVersion: 0.0.1
          releaseName: myHelmRelease
          lint: true
          lintFlags: "--strict"
          test: true
          testFlags: "--parallel"
          valueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: fileSpecResource

BuildInfo Input

A HelmDeploy 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:

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmDeploy
        configuration: 
          helmVersion: 3
          namespace: my-namespace
          chartPath: "./myChart"
          releaseName: myHelmRelease
          lint: true
          lintFlags: "--strict"
          test: true
          testFlags: "--parallel"
          valueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          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:

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmDeploy
        configuration: 
          helmVersion: 3
          namespace: my-namespace
          chartPath: "./myChart"
		  chartName: "myChartName"
		  chartVersion: 0.0.1
          releaseName: myHelmRelease
          lint: true
          lintFlags: "--strict"
          test: true
          testFlags: "--parallel"
          valueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: buildInfoResource

ReleaseBundle Input

A HelmDeploy 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:

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

pipelines:
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmDeploy
        configuration:
          helmVersion: 3
          namespace: my-namespace
          chartPath: "./myChart"
          releaseName: myHelmRelease
          lint: true
          lintFlags: "--strict"
          test: true
          testFlags: "--parallel"
          valueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          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:

pipelines:
  - name: helmDeployPipeline   
    steps:
      - name: helmDeployStep
        type: HelmDeploy
        configuration:
          helmVersion: 3
          namespace: my-namespace
          chartPath: "./myChart"
          chartName: "myChartName"
          chartVersion: 0.0.1
          releaseName: myHelmRelease
          lint: true
          lintFlags: "--strict"
          test: true
          testFlags: "--parallel"
          valueFilePaths:
            - values/values1.yaml
            - values/values2.yaml
          integrations:
            - name: kubernetes_integration
			- name: artifactory_integration	
          inputResources:
            - name: releaseBundleResource

Helm 2

A HelmDeploy step using Helm 2. 

pipelines: 
  - name: helmDeployPipeline
    steps:
      - name: helmDeployStep
        type: HelmDeploy
        configuration: 
          helmVersion: 2
          namespace: my-namespace
          releaseName: myHelmRelease
          integrations:
            - name: kubernetes_integration
          inputResources:
            - name: helmChartResource

How it Works

When you use the HelmDeploy 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 )
  • 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)
  • helm test (if test is true)