Skip to content

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.

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) Jenkins only reference to Jenkins main pipeline script
sourceImageTag (yes) mandatory in case of:
- pushLocalDockerImage=false
sourceImages (yes) mandatory in case of:
- pushLocalDockerImage=false
sourceRegistryPassword (yes) Vault Secret pass via ENV, Vault or Jenkins credentials
mandatory in case of:
- pushLocalDockerImage=false
sourceRegistryUrl (yes) mandatory in case of:
- pushLocalDockerImage=false
sourceRegistryUser (yes) Vault Secret pass via ENV, Vault or Jenkins credentials
mandatory in case of:
- pushLocalDockerImage=false
targetImageTag (yes) mandatory in case of:
- tagLatest=false
targetRegistryPassword (yes) Vault Secret pass via ENV, Vault or Jenkins credentials
targetRegistryUrl yes
targetRegistryUser (yes) Vault Secret pass via ENV, Vault or Jenkins credentials
dockerConfigJSON no Vault Secret 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 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

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