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 fromcontainerRegistryUrl
yourImageName
,yourImageTag
will be retrieved fromimage
dockerSecret
will be calculated with a call tokubectl 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 | |
additionalParameters | no | |
apiServer | no | |
appTemplate | no | |
containerCommand | no | |
containerRegistryPassword | no | dockerCredentialsId ) |
containerRegistrySecret | no | |
containerRegistryUser | no | dockerCredentialsId ) |
containerShell | no | |
createDockerRegistrySecret | no | |
deployTool | no | |
dockerEnvVars | no | |
dockerImage | no | |
dockerName | no | |
dockerOptions | no | |
dockerPullImage | no | |
dockerVolumeBind | no | |
dockerWorkspace | no | |
forceUpdates | no | |
helmDeployWaitSeconds | no | |
helmValues | no | |
ingressHosts | no | |
keepFailedDeployments | no | |
kubeConfig | no | kubeConfigFileCredentialsId ) |
kubeContext | no | |
kubeToken | no | kubeTokenCredentialsId ) |
namespace | no | |
stashContent | no | |
tillerNamespace | no | |
verbose | no | activates debug output |
Details¶
additionalParameters¶
Defines additional parameters for \"helm install\" or \"kubectl apply\" command.
Scope | Details |
---|---|
Aliases | helmDeploymentParameters |
Type | []string |
Mandatory | no |
Default | $PIPER_additionalParameters (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
apiServer¶
Defines the Url of the API Server of the Kubernetes cluster.
Scope | Details |
---|---|
Aliases | k8sAPIServer |
Type | string |
Mandatory | no |
Default | $PIPER_apiServer (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
appTemplate¶
Defines the filename for the kubernetes app template (e.g. k8s_apptemplate.yaml)
Scope | Details |
---|---|
Aliases | k8sAppTemplate |
Type | string |
Mandatory | no |
Default | $PIPER_appTemplate (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
chartPath¶
Defines the chart path for deployments using helm.
Scope | Details |
---|---|
Aliases | helmChartPath |
Type | string |
Mandatory | yes |
Default | $PIPER_chartPath (if set) |
Secret | no |
Configuration scope |
|
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).
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
containerRegistryPassword¶
Password for container registry access - typically provided by the CI/CD environment.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_containerRegistryPassword (if set) |
Secret | yes |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | regsecret |
Secret | no |
Configuration scope |
|
Resource references | none |
containerRegistryUrl¶
http(s) url of the Container registry where the image to deploy is located.
Scope | Details |
---|---|
Aliases | dockerRegistryUrl |
Type | string |
Mandatory | yes |
Default | $PIPER_containerRegistryUrl (if set) |
Secret | no |
Configuration scope |
|
Resource references | commonPipelineEnvironment: reference to: container/registryUrl |
containerRegistryUser¶
Username for container registry access - typically provided by the CI/CD environment.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_containerRegistryUser (if set) |
Secret | yes |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
createDockerRegistrySecret¶
Only for deployTool:kubectl
: Toggle to turn on containerRegistrySecret
creation.
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
deployTool¶
Defines the tool which should be used for deployment.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | kubectl |
Possible values | - kubectl - helm - helm3 |
Secret | no |
Configuration scope |
|
Resource references | none |
deploymentName¶
Defines the name of the deployment.
Scope | Details |
---|---|
Aliases | helmDeploymentName |
Type | string |
Mandatory | yes |
Default | $PIPER_deploymentName (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerEnvVars¶
Jenkins-specific: Used for proper environment setup.
Environment variables to set in the container, e.g. [http_proxy: "proxy:8080"].
Scope | Details |
---|---|
Aliases | - |
Type | map[string]string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
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.
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 |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerOptions¶
Jenkins-specific: Used for proper environment setup.
Docker options to be set when starting the container.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | deployTool=helm3 : [{-u 0}] deployTool= helm : [{-u 0}] deployTool= kubectl : [{-u 0}] |
Secret | no |
Configuration scope |
|
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.
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 |
|
Resource references | none |
dockerVolumeBind¶
Jenkins-specific: Used for proper environment setup.
Volumes that should be mounted into the docker container.
Scope | Details |
---|---|
Aliases | - |
Type | map[string]string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
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
.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | deployTool=helm3 : /config deployTool= helm : /config deployTool= kubectl : /config |
Secret | no |
Configuration scope |
|
Resource references | none |
forceUpdates¶
Helm only: force resource updates with helm parameter --force
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
helmDeployWaitSeconds¶
Number of seconds before helm deploy returns.
Scope | Details |
---|---|
Aliases | - |
Type | int |
Mandatory | no |
Default | 300 |
Secret | no |
Configuration scope |
|
Resource references | none |
helmValues¶
List of helm values as YAML file reference or URL (as per helm parameter description for -f
/ --values
)
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | $PIPER_helmValues (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
image¶
Full name of the image to be deployed.
Scope | Details |
---|---|
Aliases | deployImage |
Type | string |
Mandatory | yes |
Default | $PIPER_image (if set) |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | $PIPER_ingressHosts (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
keepFailedDeployments¶
Defines whether a failed deployment will be purged
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
kubeConfig¶
Defines the path to the \"kubeconfig\" file.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_kubeConfig (if set) |
Secret | yes |
Configuration scope |
|
Resource references | Jenkins credential id: id: kubeConfigFileCredentialsId |
kubeContext¶
Defines the context to use from the \"kubeconfig\" file.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_kubeContext (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
kubeToken¶
Contains the id_token used by kubectl for authentication. Consider using kubeConfig parameter instead.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_kubeToken (if set) |
Secret | yes |
Configuration scope |
|
Resource references | Jenkins credential id: id: kubeTokenCredentialsId |
namespace¶
Defines the target Kubernetes namespace for the deployment.
Scope | Details |
---|---|
Aliases | - helmDeploymentNamespace - k8sDeploymentNamespace |
Type | string |
Mandatory | no |
Default | default |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | Jenkins Script |
Mandatory | yes |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
stashContent¶
Jenkins-specific: Used for proper environment setup.
Specific stashes that should be considered for the step execution.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | - deployDescriptor |
Secret | no |
Configuration scope |
|
Resource references | none |
tillerNamespace¶
Defines optional tiller namespace for deployments using helm.
Scope | Details |
---|---|
Aliases | helmTillerNamespace |
Type | string |
Mandatory | no |
Default | $PIPER_tillerNamespace (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
verbose¶
verbose output
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | kubeCredentialsId (deprecated) |
Type | string |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | k8sTokenCredentialsId (deprecated) |
Type | string |
Configuration scope |
|
dockerCredentialsId¶
Jenkins-specific: Used for proper environment setup. See using credentials for details.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Configuration scope |
|
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'