Skip to content

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.

library('piper-lib-os')

gitopsUpdateDeployment script: this
piper gitopsUpdateDeployment

Parameters

Overview - Step

Name Mandatory Additional information
containerImageNameTag yes
containerRegistryUrl yes
filePath yes
password (yes) Vault Secret pass via ENV, Vault or Jenkins credentials (gitHttpsCredentialsId)
script (yes) Jenkins only reference to Jenkins main pipeline script
username (yes) Vault Secret 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 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

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

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