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 command line tool and Helm Charts.
• kubectl and kubectl apply command.

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 generic <containerRegistrySecret> --from-file=.dockerconfigjson=<dockerConfigJson> --type=kubernetes.io/dockerconfigjson --insecure-skip-tls-verify=true --dry-run=client --output=json

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.

JenkinsCommand Line

library('piper-lib-os')

kubernetesDeploy script: this

piper kubernetesDeploy

Parameters

Overview - Step

Name	Mandatory	Additional information
containerRegistryUrl	yes
image	yes
script	(yes)	reference to Jenkins main pipeline script
additionalParameters	no
apiServer	no
appTemplate	no
chartPath	no
containerImageName	no
containerImageTag	no
containerRegistryPassword	no	pass via ENV or Jenkins credentials (dockerCredentialsId)
containerRegistrySecret	no
containerRegistryUser	no	pass via ENV or Jenkins credentials (dockerCredentialsId)
createDockerRegistrySecret	no
deployCommand	no
deployTool	no
deploymentName	no
dockerConfigJSON	no	pass via ENV, Vault or Jenkins credentials (dockerConfigJsonCredentialsId)
forceUpdates	no
helmDeployWaitSeconds	no
helmValues	no
imageDigests	no
imageNameTags	no
imageNames	no
ingressHosts	no
keepFailedDeployments	no
kubeConfig	no	pass via ENV, Vault or Jenkins credentials (kubeConfigFileCredentialsId)
kubeContext	no
kubeToken	no	pass via ENV or Jenkins credentials (kubeTokenCredentialsId)
namespace	no
runHelmTests	no
showTestLogs	no
tillerNamespace	no
valuesMapping	no
verbose	no	activates debug output

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
containerShell	no
dockerEnvVars	no
dockerImage	no
dockerName	no
dockerOptions	no
dockerPullImage	no
dockerVolumeBind	no
dockerWorkspace	no
stashContent	no

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

There are two supported ways for the template rendering:

1. For a deployments using single image, you can use a placeholder <image-name>, which will be replaced with the image GUN.

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: app
     labels:
       app: app
   spec:
     replicas: 3
     selector:
       matchLabels:
         app: app
     template:
       metadata:
         labels:
           app: app
       spec:
         containers:
         - name: app
           image: <image-name>
   

2. Helm styled templates, with the support for multi-image deployments.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
  labels:
    app: app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: app
  template:
    metadata:
      labels:
        app: app
    spec:
      containers:
      - name: app-1
        image: "{{ .Values.image.repository}}:{{ .Values.image.tag }}"
      - name: app-2
        image: "{{ .Values.image.app_2.repository}}:{{ .Values.image.app_2.tag }}"

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. It is a mandatory parameter when deployTool:helm or deployTool:helm3.

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

containerImageName

Name of the container which will be built - will be used together with containerImageTag instead of parameter containerImage

back to overview

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

containerImageTag

Tag of the container which will be built - will be used together with containerImageName instead of parameter containerImage

back to overview

Scope	Details
Aliases	artifactVersion
Type	string
Mandatory	no
Default	$PIPER_containerImageTag (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: artifactVersion

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 commonPipelineEnvironment:   reference to: container/repositoryPassword commonPipelineEnvironment:   reference to: custom/repositoryPassword

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.

For deployTool: kubectl:
If containerRegistryUser and containerRegistryPassword are provided, a secret with the given name will be created 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.

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 commonPipelineEnvironment:   reference to: container/repositoryUsername commonPipelineEnvironment:   reference to: custom/repositoryUsername

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

deployCommand

Only for deployTool: kubectl: defines the command apply or replace. The default is apply.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	apply
Possible values	- apply - replace
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. It is a mandatory parameter when deployTool:helm or deployTool:helm3.

back to overview

Scope	Details
Aliases	helmDeploymentName
Type	string
Mandatory	no
Default	$PIPER_deploymentName (if set)
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	.pipeline/docker/config.json
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	Jenkins credential id:   id: dockerConfigJsonCredentialsId 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	deployTool=helm3: dtzar/helm-kubectl:3.8.1 deployTool=helm: dtzar/helm-kubectl:2.17.0 deployTool=kubectl: dtzar/helm-kubectl:2.17.0
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

Adds --force flag to a helm resource update command or to a kubectl replace command

back to overview

Scope	Details
Aliases	force
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

imageDigests

List of image digests of the images to be deployed, in the format sha256:<hash>. If provided, image digests will be appended to the image tag, e.g. <repository>/<name>:<tag>@<digest>

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	$PIPER_imageDigests (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: container/imageDigests

imageNameTags

List of full names (registry and tag) of the images to be deployed.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	$PIPER_imageNameTags (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: container/imageNameTags

imageNames

List of names of the images to be deployed.

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	no
Default	$PIPER_imageNames (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: container/imageNames

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

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

runHelmTests

Defines whether or not to run helm tests against the recently deployed release

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

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

showTestLogs

Defines whether to print the pod logs after running helm tests

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

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

valuesMapping

Mapping of values provided by Piper onto custom paths in format [custom-path]: [piper-value]

Example:

valuesMapping:
  subchart.image.tag:        image.debug.tag
  subchart.image.repository: image.debug.repository
  subchart.image.pullsecret: secret.dockerconfigjson

back to overview

Scope	Details
Aliases	-
Type	map[string]interface{}
Mandatory	no
Default	$PIPER_valuesMapping (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

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

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'