Skip to content

helmExecute

Executes helm3 functionality as the package manager for Kubernetes.

Description

Alpha version: please expect incompatible changes

Executes helm functionality as the package manager for Kubernetes.

  • Helm is the package manager for Kubernetes.
  • Helm documentation and best practices
  • Helm Charts
    Available Commands:
    `upgrade`, `lint`, `install`, `test`, `uninstall`, `dependency`, `publish`
    
      upgrade       upgrade a release
      lint          examine a chart for possible issues
      install       install a chart
      test          run tests for a release
      uninstall     uninstall a release
      dependency    package a chart directory into a chart archive
      publish       package and publish a release
    

Note: piper supports only helm3 version, since helm2 is deprecated.

Usage

We recommend to define values of step parameters via .pipeline/config.yml file.
In this case, calling the step is essentially reduced to defining the step name.
Calling the step can be done either in an orchestrator specific way (e.g. via a Jenkins library step) or on the command line.

library('piper-lib-os')

helmExecute script: this
piper helmExecute

Outputs

Output type Details
commonPipelineEnvironment
  • custom/helmChartUrl

Parameters

Overview - Step

Name Mandatory Additional information
image yes
script (yes) Jenkins only reference to Jenkins main pipeline script
additionalParameters no
appVersion no
chartPath no
customTlsCertificateLinks no
dependency no
dockerConfigJSON no Vault Secret pass via ENV, Vault or Jenkins credentials (dockerConfigJsonCredentialsId)
dumpLogs no
filterTest no
helmCommand no
helmDeployWaitSeconds no
helmValues no
keepFailedDeployments no
kubeConfig no Vault Secret pass via ENV, Vault or Jenkins credentials (kubeConfigFileCredentialsId)
kubeContext no
namespace no
packageDependencyUpdate no
publish no
renderSubchartNotes no
renderValuesTemplate no
sourceRepositoryName no
sourceRepositoryPassword no Vault Secret pass via ENV, Vault or Jenkins credentials (sourceRepositoryCredentialsId)
sourceRepositoryURL no
sourceRepositoryUser no Vault Secret pass via ENV, Vault or Jenkins credentials (sourceRepositoryCredentialsId)
targetRepositoryName no
targetRepositoryPassword no Vault Secret pass via ENV, Vault or Jenkins credentials (targetRepositoryCredentialsId)
targetRepositoryURL no
targetRepositoryUser no Vault Secret pass via ENV, Vault or Jenkins credentials (targetRepositoryCredentialsId)
templateEndDelimiter no
templateStartDelimiter no
verbose no activates debug output
version no

Overview - Execution Environment

Orchestrator-specific only

These parameters are relevant for orchestrator usage and not considered when using the command line option.

Name Mandatory Additional information
containerCommand no Jenkins only
containerShell no Jenkins only
dockerEnvVars no
dockerImage no
dockerName no
dockerOptions no
dockerPullImage no
dockerVolumeBind no Jenkins only
dockerWorkspace no Jenkins only
stashContent no Jenkins only

Details

additionalParameters

Defines additional parameters for Helm like "helm install [NAME] [CHART] [flags]".

back to overview

Scope Details
Aliases helmDeploymentParameters
Type []string
Mandatory no
Default $PIPER_additionalParameters (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

appVersion

set the appVersion on the chart to this version

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_appVersion (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

chartPath

Defines the chart path for helm. chartPath is mandatory for install/upgrade/publish commands.

back to overview

Scope Details
Aliases helmChartPath
Type string
Mandatory no
Default $PIPER_chartPath (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

containerCommand

Jenkins-specific: Used for proper environment setup.

Kubernetes only: Allows to specify start command for container created with dockerImage parameter to overwrite Piper default (/usr/bin/tail -f /dev/null).

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

containerShell

Jenkins-specific: Used for proper environment setup.

Allows to specify the shell to be executed for container with containerName.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

List of download links to custom TLS certificates. This is required to ensure trusted connections to instances with repositories (like nexus) when publish flag is set to true.

back to overview

Scope Details
Aliases -
Type []string
Mandatory no
Default $PIPER_customTlsCertificateLinks (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dependency

manage a chart's dependencies

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_dependency (if set)
Possible values - build
- list
- update
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerConfigJSON

Path to the file .docker/config.json - this is typically provided by your CI/CD system. You can find more details about the Docker credentials in the Docker documentation.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_dockerConfigJSON (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: dockerConfigJsonCredentialsId

Vault resource:
  name: dockerConfigFileVaultSecretName
  default value: docker-config

Vault paths:
  • $(vaultPath)/docker-config
  • $(vaultBasePath)/$(vaultPipelineName)/docker-config
  • $(vaultBasePath)/GROUP-SECRETS/docker-config

dockerEnvVars

Jenkins-specific: Used for proper environment setup.

Environment variables to set in the container, e.g. [http_proxy: "proxy:8080"].

back to overview

Scope Details
Aliases -
Type map[string]string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerImage

Jenkins-specific: Used for proper environment setup.

Name of the docker image that should be used. If empty, Docker is not used and the command is executed directly on the Jenkins system.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default dtzar/helm-kubectl:3
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerName

Jenkins-specific: Used for proper environment setup.

Kubernetes only: Name of the container launching dockerImage. SideCar only: Name of the container in local network.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerOptions

Jenkins-specific: Used for proper environment setup.

Docker options to be set when starting the container.

back to overview

Scope Details
Aliases -
Type []string
Mandatory no
Default [{-u 0}]
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerPullImage

Jenkins-specific: Used for proper environment setup.

Set this to 'false' to bypass a docker image pull. Useful during development process. Allows testing of images which are available in the local registry only.

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default true
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerVolumeBind

Jenkins-specific: Used for proper environment setup.

Volumes that should be mounted into the docker container.

back to overview

Scope Details
Aliases -
Type map[string]string
Mandatory no
Default
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dockerWorkspace

Jenkins-specific: Used for proper environment setup.

Kubernetes only: Specifies a dedicated user home directory for the container which will be passed as value for environment variable HOME.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default /config
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

dumpLogs

dump the logs from test pods (this runs after all tests are complete, but before any cleanup)

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

filterTest

specify tests by attribute (currently name) using attribute=value syntax or !attribute=value to exclude a test (can specify multiple or separate values with commas name=test1,name=test2)

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_filterTest (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

helmCommand

Helm: defines the command upgrade, lint, install, test, uninstall, dependency, publish.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_helmCommand (if set)
Possible values - upgrade
- lint
- install
- test
- uninstall
- dependency
- publish
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

helmDeployWaitSeconds

Number of seconds before helm deploy returns.

back to overview

Scope Details
Aliases -
Type int
Mandatory no
Default 300
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

helmValues

List of helm values as YAML file reference or URL (as per helm parameter description for -f / --values)

back to overview

Scope Details
Aliases -
Type []string
Mandatory no
Default $PIPER_helmValues (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

image

Full name of the image to be deployed.

back to overview

Scope Details
Aliases deployImage
Type string
Mandatory yes
Default $PIPER_image (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references commonPipelineEnvironment:
  reference to: container/imageNameTag

keepFailedDeployments

Defines whether a failed deployment will be purged

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

kubeConfig

Defines the path to the "kubeconfig" file.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_kubeConfig (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: kubeConfigFileCredentialsId

Vault resource:
  name: kubeConfigFileVaultSecretName
  default value: kube-config

Vault paths:
  • $(vaultPath)/kube-config
  • $(vaultBasePath)/$(vaultPipelineName)/kube-config
  • $(vaultBasePath)/GROUP-SECRETS/kube-config

kubeContext

Defines the context to use from the "kubeconfig" file.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_kubeContext (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

namespace

Defines the target Kubernetes namespace for the deployment.

back to overview

Scope Details
Aliases helmDeploymentNamespace
Type string
Mandatory no
Default default
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

packageDependencyUpdate

update dependencies from "Chart.yaml" to dir "charts/" before packaging

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

publish

Configures helm to run the deploy command to publish artifacts to a repository.

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

renderSubchartNotes

If set, render subchart notes along with the parent.

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default true
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

renderValuesTemplate

A flag to turn templating value files on or off.

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default true
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☐ stages
Resource references none

script

Jenkins-specific: Used for proper environment setup.

The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in script: this. This allows the function to access the commonPipelineEnvironment for retrieving, e.g. configuration parameters.

back to overview

Scope Details
Aliases -
Type Jenkins Script
Mandatory yes
Default
Secret no
Configuration scope
  • ☐ parameter
  • ☐ general
  • ☐ steps
  • ☐ stages
Resource references none

sourceRepositoryName

Set the name of the chart repository. The value might be required for fetching dependencies.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_sourceRepositoryName (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

sourceRepositoryPassword

Password for the chart repository for fetching the dependencies.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_sourceRepositoryPassword (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: sourceRepositoryCredentialsId
  reference to: password

Vault resource:
  name: sourceRepositoryPasswordSecret
  default value: dependencies

Vault paths:
  • $(vaultPath)/dependencies
  • $(vaultBasePath)/$(vaultPipelineName)/dependencies
  • $(vaultBasePath)/GROUP-SECRETS/dependencies

sourceRepositoryURL

URL of the source repository where the dependencies can be downloaded.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_sourceRepositoryURL (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

sourceRepositoryUser

Username for the chart repository for fetching the dependencies.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_sourceRepositoryUser (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: sourceRepositoryCredentialsId
  reference to: username

Vault resource:
  name: sourceRepositoryUserSecretName
  default value: dependencies

Vault paths:
  • $(vaultPath)/dependencies
  • $(vaultBasePath)/$(vaultPipelineName)/dependencies
  • $(vaultBasePath)/GROUP-SECRETS/dependencies

stashContent

Jenkins-specific: Used for proper environment setup.

Specific stashes that should be considered for the step execution.

back to overview

Scope Details
Aliases -
Type []string
Mandatory no
Default - deployDescriptor
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

targetRepositoryName

set the chart repository. The value is required for install/upgrade/uninstall commands.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_targetRepositoryName (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

targetRepositoryPassword

Password for the target repository where the compiled helm .tgz archive shall be uploaded - typically provided by the CI/CD environment.

back to overview

Scope Details
Aliases helmRepositoryPassword
Type string
Mandatory no
Default $PIPER_targetRepositoryPassword (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: targetRepositoryCredentialsId
  reference to: password

Vault resource:
  name: targetRepositoryPasswordSecret
  default value: publishing

Vault paths:
  • $(vaultPath)/publishing
  • $(vaultBasePath)/$(vaultPipelineName)/publishing
  • $(vaultBasePath)/GROUP-SECRETS/publishing
commonPipelineEnvironment:
  reference to: custom/helmRepositoryPassword
commonPipelineEnvironment:
  reference to: custom/repositoryPassword

targetRepositoryURL

URL of the target repository where the compiled helm .tgz archive shall be uploaded - typically provided by the CI/CD environment.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_targetRepositoryURL (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references commonPipelineEnvironment:
  reference to: custom/helmRepositoryURL
commonPipelineEnvironment:
  reference to: custom/repositoryUrl

targetRepositoryUser

Username for the chart repository where the compiled helm .tgz archive shall be uploaded - typically provided by the CI/CD environment.

back to overview

Scope Details
Aliases helmRepositoryUsername
Type string
Mandatory no
Default $PIPER_targetRepositoryUser (if set)
Secret yes
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references Jenkins credential id:
  id: targetRepositoryCredentialsId
  reference to: username

Vault resource:
  name: targetRepositoryUserSecretName
  default value: publishing

Vault paths:
  • $(vaultPath)/publishing
  • $(vaultBasePath)/$(vaultPipelineName)/publishing
  • $(vaultBasePath)/GROUP-SECRETS/publishing
commonPipelineEnvironment:
  reference to: custom/helmRepositoryUsername
commonPipelineEnvironment:
  reference to: custom/repositoryUsername

templateEndDelimiter

When templating value files, use this end delimiter.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default }}
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☐ stages
Resource references none

templateStartDelimiter

When templating value files, use this start delimiter.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default {{
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☐ stages
Resource references none

verbose

verbose output

back to overview

Scope Details
Aliases -
Type bool
Mandatory no
Default false
Possible values - true
- false
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

version

Defines the artifact version to use from helm package/publish commands.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default $PIPER_version (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

kubeConfigFileCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

Jenkins 'Secret file' credentials ID containing kubeconfig file. Details can be found in the Kubernetes documentation.

back to overview

Scope Details
Aliases kubeCredentialsId (deprecated)
Type string
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages

dockerConfigJsonCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

Jenkins 'Secret file' credentials ID containing Docker config.json (with registry credential(s)).

back to overview

Scope Details
Aliases -
Type string
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages

sourceRepositoryCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

Jenkins 'Username Password' credentials ID containing username and password for the Helm Repository authentication (source repo)

back to overview

Scope Details
Aliases -
Type string
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages

targetRepositoryCredentialsId

Jenkins-specific: Used for proper environment setup. See using credentials for details.

Jenkins 'Username Password' credentials ID containing username and password for the Helm Repository authentication (target repo)

back to overview

Scope Details
Aliases -
Type string
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages