Skip to content

kubernetesDeploy

Deployment to Kubernetes test or production namespace within the specified Kubernetes cluster.

Description

Deployment to Kubernetes test or production namespace within the specified Kubernetes cluster.

Deployment supports multiple deployment tools

Currently the following are supported:

Helm

Following helm command will be executed by default:

helm upgrade <deploymentName> <chartPath> --install --force --namespace <namespace> --wait --timeout <helmDeployWaitSeconds> --set "image.repository=<yourRegistry>/<yourImageName>,image.tag=<yourImageTag>,secret.dockerconfigjson=<dockerSecret>,ingress.hosts[0]=<ingressHosts[0]>,,ingress.hosts[1]=<ingressHosts[1]>,...
  • yourRegistry will be retrieved from containerRegistryUrl
  • yourImageName, yourImageTag will be retrieved from image
  • dockerSecret will be calculated with a call to kubectl create secret docker-registry regsecret --docker-server=<yourRegistry> --docker-username=<containerRegistryUser> --docker-password=<containerRegistryPassword> --dry-run=true --output=json'

Usage

We recommend to define values of step parameters via config.yml file. In this case, calling the step is reduced to one simple line.
Calling the step can be done either via the Jenkins library step or on the command line.

Jenkins Pipeline

library('piper-lib-os')

kubernetesDeploy script: this

Command Line

piper kubernetesDeploy

Parameters

Overview

Name Mandatory Additional information
chartPath yes
containerRegistryUrl yes
deploymentName yes
image yes
script yes Jenkins only reference to Jenkins main pipeline script
additionalParameters no
apiServer no
appTemplate no
containerCommand no Jenkins only
containerRegistryPassword no Secret pass via ENV or Jenkins credentials (dockerCredentialsId)
containerRegistrySecret no
containerRegistryUser no Secret pass via ENV or Jenkins credentials (dockerCredentialsId)
containerShell no Jenkins only
createDockerRegistrySecret no
deployTool no
dockerEnvVars no Jenkins only
dockerImage no Jenkins only
dockerName no Jenkins only
dockerOptions no Jenkins only
dockerPullImage no Jenkins only
dockerVolumeBind no Jenkins only
dockerWorkspace no Jenkins only
forceUpdates no
helmDeployWaitSeconds no
helmValues no
ingressHosts no
keepFailedDeployments no
kubeConfig no Secret pass via ENV or Jenkins credentials (kubeConfigFileCredentialsId)
kubeContext no
kubeToken no Secret pass via ENV or Jenkins credentials (kubeTokenCredentialsId)
namespace no
stashContent no Jenkins only
tillerNamespace no
verbose no activates debug output

Details

additionalParameters

Defines additional parameters for \"helm install\" or \"kubectl apply\" command.

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

apiServer

Defines the Url of the API Server of the Kubernetes cluster.

back to overview

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

appTemplate

Defines the filename for the kubernetes app template (e.g. k8s_apptemplate.yaml)

back to overview

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

chartPath

Defines the chart path for deployments using helm.

back to overview

Scope Details
Aliases helmChartPath
Type string
Mandatory yes
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

containerRegistryPassword

Password for container registry access - typically provided by the CI/CD environment.

back to overview

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

containerRegistrySecret

Name of the container registry secret used for pulling containers from the registry.

For deployTool: helm/helm3:
If containerRegistryUser and containerRegistryPassword are provided, a secret is created on the fly and the information is passed to the helm template.
Note: the secret will not be persisted in the Kubernetes cluster.

If neither containerRegistryUser nor containerRegistryPassword are provided, it is expected that a secret with the configured name exists in the target Kubernetes cluster.

For deployTool: kubectl:
If createDockerRegistrySecret: true and containerRegistryUser and containerRegistryPassword are provided, a secret with the given name will be created in the Kubernetes cluster unless a secret with the name already exists.

back to overview

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

containerRegistryUrl

http(s) url of the Container registry where the image to deploy is located.

back to overview

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

containerRegistryUser

Username for container registry access - typically provided by the CI/CD environment.

back to overview

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

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

createDockerRegistrySecret

Only for deployTool:kubectl: Toggle to turn on containerRegistrySecret creation.

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

deployTool

Defines the tool which should be used for deployment.

back to overview

Scope Details
Aliases -
Type string
Mandatory no
Default kubectl
Possible values - kubectl
- helm
- helm3
Secret no
Configuration scope
  • ☒ parameter
  • ☐ general
  • ☒ steps
  • ☒ stages
Resource references none

deploymentName

Defines the name of the deployment.

back to overview

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

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 deployTool=helm3: dtzar/helm-kubectl:3.1.2
deployTool=helm: dtzar/helm-kubectl:2.12.1
deployTool=kubectl: dtzar/helm-kubectl:2.12.1
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 deployTool=helm3: [{-u 0}]
deployTool=helm: [{-u 0}]
deployTool=kubectl: [{-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 deployTool=helm3: true
deployTool=helm: true
deployTool=kubectl: 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 deployTool=helm3: /config
deployTool=helm: /config
deployTool=kubectl: /config
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

forceUpdates

Helm only: force resource updates with helm parameter --force

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

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

ingressHosts

DEPRECATED
List of ingress hosts to be exposed via helm deployment.
Host names are passed to helm template via ingress configuration.
This requires a modification to the default helm template, thus it is not recommended.

Recommendation is to use custom values and pass them via parameter helmValues.
Since helm supports multiple files on top of the values.yaml, landscape-specific attributes can be passed via a specific file.

back to overview

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

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

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

kubeToken

Contains the id_token used by kubectl for authentication. Consider using kubeConfig parameter instead.

back to overview

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

namespace

Defines the target Kubernetes namespace for the deployment.

back to overview

Scope Details
Aliases - helmDeploymentNamespace
- k8sDeploymentNamespace
Type string
Mandatory no
Default default
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

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

tillerNamespace

Defines optional tiller namespace for deployments using helm.

back to overview

Scope Details
Aliases helmTillerNamespace
Type string
Mandatory no
Default $PIPER_tillerNamespace (if set)
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

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

kubeTokenCredentialsId

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

Jenkins 'Secret text' credentials ID containing token to authenticate to Kubernetes. This is an alternative way to using a kubeconfig file. Details can be found in the Kubernetes documentation.

back to overview

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

dockerCredentialsId

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

back to overview

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

Exceptions

None

Examples

kubernetesDeploy script: this

// Deploy a helm chart called "myChart" using Helm 3
kubernetesDeploy script: this, deployTool: 'helm3', chartPath: 'myChart', deploymentName: 'myRelease', image: 'nginx', containerRegistryUrl: 'https://docker.io'