imagePushToRegistry

Allows you to copy a Docker image from a source container registry to a destination container registry.

Description

In case you want to pull an existing image from a remote container registry, a source image and source registry needs to be specified.
This makes it possible to move an image from one registry to another.

The imagePushToRegistry is not similar in functionality to containerPushToRegistry (which is currently a groovy based step and only be used in jenkins). Currently the imagePushToRegistry only supports copying a local image or image from source remote registry to destination registry.

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

imagePushToRegistry script: this

piper imagePushToRegistry

Parameters

Overview - Step

Name	Mandatory	Additional information
localDockerImagePath	(yes)	mandatory in case of: - pushLocalDockerImage=true
script	(yes)	reference to Jenkins main pipeline script
sourceImageTag	(yes)	mandatory in case of: - pushLocalDockerImage=false
sourceImages	(yes)	mandatory in case of: - pushLocalDockerImage=false
sourceRegistryPassword	(yes)	pass via ENV, Vault or Jenkins credentials mandatory in case of: - pushLocalDockerImage=false
sourceRegistryUrl	(yes)	mandatory in case of: - pushLocalDockerImage=false
sourceRegistryUser	(yes)	pass via ENV, Vault or Jenkins credentials mandatory in case of: - pushLocalDockerImage=false
targetImageTag	(yes)	mandatory in case of: - tagLatest=false
targetRegistryPassword	(yes)	pass via ENV, Vault or Jenkins credentials
targetRegistryUrl	yes
targetRegistryUser	(yes)	pass via ENV, Vault or Jenkins credentials
dockerConfigJSON	no	pass via ENV, Vault or Jenkins credentials
pushLocalDockerImage	no
sourceImageNameTags	no
tagLatest	no
targetArchitecture	no
targetImageNameTags	no
targetImages	no
useImageNameTags	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

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	/busybox/tail -f /dev/null
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

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	/busybox/sh
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	$PIPER_dockerConfigJSON (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	Vault resource:   name: dockerConfigFileVaultSecretName   default value: docker-config 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	map[container:docker]
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	gcr.io/go-containerregistry/crane:debug
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	[{-u 0} {--entrypoint }]
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	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
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

localDockerImagePath

If the localDockerImagePath is a directory, it will be read as an OCI image layout. Otherwise, localDockerImagePath is assumed to be a docker-style tarball.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	mandatory in case of: - pushLocalDockerImage=true
Default	$PIPER_localDockerImagePath (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	none

pushLocalDockerImage

Defines if the local image should be pushed to registry

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

sourceImageNameTags

List of full names (registry and tag) of the images to be copied. Works in combination with useImageNameTags.

back to overview

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

sourceImageTag

Tag of the sourceImages

back to overview

Scope	Details
Aliases	- artifactVersion - containerImageTag
Type	string
Mandatory	mandatory in case of: - pushLocalDockerImage=false
Default	$PIPER_sourceImageTag (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: artifactVersion

sourceImages

Defines the names of the images that will be pulled from source registry. This is helpful for moving images from one location to another. Please ensure that targetImages and sourceImages correspond to each other: the first image in sourceImages should be mapped to the first image in the targetImages parameter.

  sourceImages:
    - image-1
    - image-2
  targetImages:
    image-1: target-image-1
    image-2: target-image-2

back to overview

Scope	Details
Aliases	-
Type	[]string
Mandatory	mandatory in case of: - pushLocalDockerImage=false
Default	$PIPER_sourceImages (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: container/imageNames

sourceRegistryPassword

Password of the source registry where the image should be pulled from.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	mandatory in case of: - pushLocalDockerImage=false
Default	$PIPER_sourceRegistryPassword (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: container/repositoryPassword Vault resource:   name: registryCredentialsVaultSecretName   default value: docker-registry Vault paths: $(vaultPath)/docker-registry $(vaultBasePath)/$(vaultPipelineName)/docker-registry $(vaultBasePath)/GROUP-SECRETS/docker-registry

sourceRegistryUrl

Defines a registry url from where the image should optionally be pulled from, incl. the protocol like https://my.registry.com*"

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	mandatory in case of: - pushLocalDockerImage=false
Default	$PIPER_sourceRegistryUrl (if set)
Secret	no
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: container/registryUrl

sourceRegistryUser

Username of the source registry where the image should be pulled from.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	mandatory in case of: - pushLocalDockerImage=false
Default	$PIPER_sourceRegistryUser (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: container/repositoryUsername Vault resource:   name: registryCredentialsVaultSecretName   default value: docker-registry Vault paths: $(vaultPath)/docker-registry $(vaultBasePath)/$(vaultPipelineName)/docker-registry $(vaultBasePath)/GROUP-SECRETS/docker-registry

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	- source
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

tagLatest

Defines if the image should be tagged as latest. The parameter is true if targetImageTag is not specified.

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

targetArchitecture

Specifies the targetArchitecture in the form os/arch[/variant][:osversion] (e.g. linux/amd64). All OS and architectures of the specified image will be copied if it is a multi-platform image. To only push a single platform to the target registry use this parameter

back to overview

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

targetImageNameTags

List of full names (registry and tag) of the images to be deployed. Works in combination with useImageNameTags. If not set, the value will be the sourceImageNameTags with the targetRegistryUrl incorporated.

back to overview

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

targetImageTag

Tag of the targetImages

back to overview

Scope	Details
Aliases	- artifactVersion - containerImageTag
Type	string
Mandatory	mandatory in case of: - tagLatest=false
Default	$PIPER_targetImageTag (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: artifactVersion

targetImages

Defines the names of the images that will be pushed to the target registry. If empty, names of sourceImages will be used. Please ensure that targetImages and sourceImages correspond to each other: the first image in sourceImages should be mapped to the first image in the targetImages parameter.

sourceImages:
  - image-1
  - image-2
targetImages:
  image-1: target-image-1
  image-2: target-image-2

back to overview

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

targetRegistryPassword

Password of the target registry where the image should be pushed to.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_targetRegistryPassword (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	Vault resource:   name: registryCredentialsVaultSecretName   default value: docker-registry Vault paths: $(vaultPath)/docker-registry $(vaultBasePath)/$(vaultPipelineName)/docker-registry $(vaultBasePath)/GROUP-SECRETS/docker-registry

targetRegistryUrl

Defines a registry url from where the image should optionally be pushed to, incl. the protocol like https://my.registry.com*"

back to overview

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

targetRegistryUser

Username of the target registry where the image should be pushed to.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	yes
Default	$PIPER_targetRegistryUser (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	Vault resource:   name: registryCredentialsVaultSecretName   default value: docker-registry Vault paths: $(vaultPath)/docker-registry $(vaultBasePath)/$(vaultPipelineName)/docker-registry $(vaultBasePath)/GROUP-SECRETS/docker-registry

useImageNameTags

Will use the sourceImageNameTags and targetImageNameTags parameters, instead of sourceImages and targetImages. sourceImageNameTags can be set by a build step, e.g. kanikoExecute, and is then available in the pipeline environment.

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

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