gitopsUpdateDeployment

Updates Kubernetes Deployment Manifest in an Infrastructure Git Repository

Description

This step allows you to update the deployment manifest for Kubernetes in a git repository.

It can for example be used for GitOps scenarios where the update of the manifests triggers an update of the corresponding deployment in Kubernetes.

As of today, it supports the update of deployment yaml files via kubectl patch, update a whole helm template and kustomize.

For kubectl the container inside the yaml must be described within the following hierarchy: {"spec":{"template":{"spec":{"containers":[{...}]}}}} For helm the whole template is generated into a single file (filePath) and uploaded into the repository. For kustomize the images section will be update with the current image.

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

gitopsUpdateDeployment script: this

piper gitopsUpdateDeployment

Parameters

Overview - Step

Name	Mandatory	Additional information
containerImageNameTag	yes
containerRegistryUrl	yes
filePath	yes
password	(yes)	pass via ENV, Vault or Jenkins credentials (gitHttpsCredentialsId)
script	(yes)	reference to Jenkins main pipeline script
username	(yes)	pass via ENV, Vault or Jenkins credentials (gitHttpsCredentialsId)
branchName	no
chartPath	no
commitMessage	no
containerName	no
customTlsCertificateLinks	no
deploymentName	no
forcePush	no
helmValues	no
serverUrl	no
tool	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

branchName

The name of the branch where the changes should get pushed into.

back to overview

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

chartPath

Defines the chart path for deployments using helm. Globbing is supported to merge multiple charts into one resource.yaml that will be commited.

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

commitMessage

If the commit message is empty a default message in the form "Updated containerName to version containerImage" will be used.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_commitMessage (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

containerImageNameTag

Container image name with version tag to annotate in the deployment configuration.

back to overview

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

containerName

The name of the container to update

back to overview

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

containerRegistryUrl

http(s) url of the Container registry where the image 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

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

customTlsCertificateLinks

List containing download links of custom TLS certificates. This is required to ensure trusted connections to registries with custom certificates.

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

deploymentName

Defines the name of the deployment. In case of kustomize this is the name or alias of the image in the kustomization.yaml

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

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	tool=helm: dtzar/helm-kubectl:3.8.0 tool=kubectl: dtzar/helm-kubectl:3.8.0 tool=kustomize: nekottyo/kustomize-kubeval:kustomizev4
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	tool=helm: [{-u 0}] tool=kubectl: [{-u 0}] tool=kustomize: [{-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	tool=helm: true tool=kubectl: true tool=kustomize: 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	tool=helm: /config tool=kubectl: /config tool=kustomize: /config
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

filePath

Relative path in the git repository to the deployment descriptor file that shall be updated. For different tools this has different semantics:

• kubectl - path to the deployment.yaml that should be patched. Supports globbing.
• helm - path where the helm chart will be generated into. Here no globbing is supported.
• kustomize - path to the kustomization.yaml. Supports globbing.

back to overview

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

forcePush

To bypass branch-protections the git push command can be forced.

Example:

steps:
  gitopsUpdateDeployment:
    forcePush: true

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

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

password

Password/token for git authentication.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_password (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	Jenkins credential id:   id: gitHttpsCredentialsId   reference to: password Vault resource:   name: gitHttpsCredentialVaultSecretName   default value: gitHttpsCredential Vault paths: $(vaultPath)/gitHttpsCredential $(vaultBasePath)/$(vaultPipelineName)/gitHttpsCredential $(vaultBasePath)/GROUP-SECRETS/gitHttpsCredential

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

serverUrl

GitHub server url to the repository.

back to overview

Scope	Details
Aliases	githubServerUrl
Type	string
Mandatory	no
Default	https://github.com
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

tool

Defines the tool which should be used to update the deployment description.

back to overview

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

username

User name for git authentication

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_username (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	Jenkins credential id:   id: gitHttpsCredentialsId   reference to: username Vault resource:   name: gitHttpsCredentialVaultSecretName   default value: gitHttpsCredential Vault paths: $(vaultPath)/gitHttpsCredential $(vaultBasePath)/$(vaultPipelineName)/gitHttpsCredential $(vaultBasePath)/GROUP-SECRETS/gitHttpsCredential

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

gitHttpsCredentialsId

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

Jenkins 'Username with password' credentials ID containing username/password for http access to your git repository.

back to overview

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