cloudFoundryDeploy

Deploys an application to Cloud Foundry

Description

Deploys an application to a test or production space within Cloud Foundry.

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

cloudFoundryDeploy script: this

piper cloudFoundryDeploy

Outputs

Output type	Details
influx	measurement deployment_data artifactUrl deployTime commitHash jobTrigger

Additional Hints

Deployment can be done

• in a standard way
• in a zero-downtime manner (using a blue-green deployment approach)

Deployment supports multiple deployment tools

Currently the following are supported:

• Standard cf push and Bluemix blue-green plugin
• MTA CF CLI Plugin

Blue-Green Deployment with MTA CF CLI Plugin

The Multiapps Plugin offers 2 different strategies:

• Blue-Green Deployment Strategy - where the production environments are called “live” and “idle” during deployment. This strategy is activated with mtaDeployParameters: --strategy blue-green --skip-testing-phase and deployType=standard. After deployment, appnames are not appeneded by any suffix like -live or -idle.
• Legacy Blue-Green Deployment - where the productive environments are called “blue” and “green. Activated by deployType=blue-green. After deployment, appnames are appeneded by suffix like -blue or -green

Note

Due to an incompatible change in the Cloud Foundry CLI, multiple buildpacks are not supported by this step. If your application contains a list of buildpacks instead of a single buildpack, this will be automatically re-written by the step when blue-green deployment is used.

Note

Cloud Foundry supports the deployment of multiple applications using a single manifest file. This option is supported with project "Piper". In this case, define appName: '' since the app name for the individual applications has to be defined via the manifest. You can find details in the Cloud Foundry Documentation

Prerequisites

• Cloud Foundry organization, space and deployment users are available
• Credentials for deployment have been configured in Jenkins or Vault.

Parameters

Overview - Step

Name	Mandatory	Additional information
org	yes
password	(yes)	pass via ENV, Vault or Jenkins credentials (cfCredentialsId)
script	(yes)	reference to Jenkins main pipeline script
space	yes
username	(yes)	pass via ENV, Vault or Jenkins credentials (cfCredentialsId)
apiEndpoint	no
appName	no
artifactVersion	no
buildTool	no
cfHome	no
cfNativeDeployParameters	no
cfPluginHome	no
commitHash	no
deployDockerImage	no
deployTool	no
deployType	no
dockerPassword	no	pass via ENV or Jenkins credentials (dockerCredentialsId)
dockerUsername	no	pass via ENV or Jenkins credentials (dockerCredentialsId)
keepOldInstance	no
loginParameters	no
manifest	no
manifestVariables	no
manifestVariablesFiles	no
mtaDeployParameters	no
mtaExtensionCredentials	no
mtaExtensionDescriptor	no
mtaPath	no
smokeTestScript	no
smokeTestStatusCode	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

Details

apiEndpoint

Cloud Foundry API endpoint

back to overview

Scope	Details
Aliases	- cfApiEndpoint - cloudFoundry/apiEndpoint (deprecated)
Type	string
Mandatory	no
Default	https://api.cf.eu10.hana.ondemand.com
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

appName

Defines the name of the application to be deployed to the Cloud Foundry space

back to overview

Scope	Details
Aliases	- cfAppName - cloudFoundry/appName (deprecated)
Type	string
Mandatory	no
Default	$PIPER_appName (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

artifactVersion

The artifact version, used for influx reporting

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_artifactVersion (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: artifactVersion

buildTool

Defines the tool which is used for building the artifact. If provided, deployTool is automatically derived from it. For MTA projects, deployTool defaults to mtaDeployPlugin. For other projects cf_native will be used.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_buildTool (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: buildTool

cfHome

The cf home folder used by the cf cli. If not provided the default assumed by the cf cli is used.

back to overview

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

cfNativeDeployParameters

Additional parameters passed to cf native deployment command

back to overview

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

cfPluginHome

The cf plugin home folder used by the cf cli. If not provided the default assumed by the cf cli is used.

back to overview

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

commitHash

The commit hash, used for influx reporting

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_commitHash (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: git/headCommitId

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

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

deployDockerImage

Docker image deployments are supported (via manifest file in general)[https://docs.cloudfoundry.org/devguide/deploy-apps/manifest-attributes.html#docker]. If no manifest is used, this parameter defines the image to be deployed. The specified name of the image is passed to the --docker-image parameter of the cf CLI and must adhere it's naming pattern (e.g. REPO/IMAGE:TAG). See (cf CLI documentation)[https://docs.cloudfoundry.org/devguide/deploy-apps/push-docker.html] for details. Note: The used Docker registry must be visible for the targeted Cloud Foundry instance.

back to overview

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

deployTool

Defines the tool which should be used for deployment.

back to overview

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

deployType

Defines the type of deployment, either standard deployment which results in a system downtime or a zero-downtime blue-green deployment. If 'cf_native' as deployTool and 'blue-green' as deployType is used in combination, your manifest.yaml may only contain one application. If this application has the option 'no-route' active the deployType will be changed to 'standard'.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	standard
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	ppiper/cf-cli:latest
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	cfDeploy
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
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

dockerPassword

If the specified image in deployDockerImage is contained in a Docker registry, which requires authorization, this defines the password to be used.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_dockerPassword (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	Jenkins credential id:   id: dockerCredentialsId   reference to: password

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

dockerUsername

If the specified image in deployDockerImage is contained in a Docker registry, which requires authorization, this defines the username to be used.

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_dockerUsername (if set)
Secret	yes
Configuration scope	☒ parameter ☐ general ☒ steps ☒ stages
Resource references	Jenkins credential id:   id: dockerCredentialsId   reference to: username

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

keepOldInstance

In case of a blue-green deployment the old instance will be deleted by default. If this option is set to true the old instance will remain stopped in the Cloud Foundry space.

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

loginParameters

Addition command line options for cf login command. No escaping/quoting is performed. Not recommended for productive environments.

back to overview

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

manifest

Defines the manifest to be used for deployment to Cloud Foundry.

back to overview

Scope	Details
Aliases	- cfManifest - cloudFoundry/manifest (deprecated)
Type	string
Mandatory	no
Default	$PIPER_manifest (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

manifestVariables

Defines a list of variables in the form key=value which are used for variable substitution within the file given by manifest.

This can be used to set variables like it is provided by 'cf push --var key=value'.

Note: variables defined via 'manifestVariables' always win over conflicting variables defined via any file given by 'manifestVariablesFiles' - no matter what is declared before. This is the same behavior as can be observed when using 'cf push --var' in combination with 'cf push --vars-file'."

Example:

...
cloudFoundryDeploy:
  manifestVariables:
    - 'key1=value1'
    - 'key2=value2'
...

back to overview

Scope	Details
Aliases	- cfManifestVariables - cloudFoundry/manifestVariables (deprecated)
Type	[]string
Mandatory	no
Default	$PIPER_manifestVariables (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

manifestVariablesFiles

path(s) of the Yaml file(s) containing the variable values to use as a replacement in the manifest file. The order of the files is relevant in case there are conflicting variable names and values within variable files. In such a case, the values of the last file win.

back to overview

Scope	Details
Aliases	- cfManifestVariablesFiles - cloudFoundry/manifestVariablesFiles (deprecated)
Type	[]string
Mandatory	no
Default	- manifest-variables.yml
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

mtaDeployParameters

Additional parameters passed to mta deployment command

back to overview

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

mtaExtensionCredentials

Defines a map of credentials that need to be replaced in the mtaExtensionDescriptor. This map needs to be created as value-to-be-replaced:id-of-a-credential-in-jenkins. The placeholders in the extension descriptor file(s) looks like: <%= value-to-be-replaced %>. When used outside Jenkins the secret which corresponds to id-of-a-credential-in-jenkins needs to be provided as environment variable in screaming snake case, e.g.: export ID_OF_A_CREDENTIAL_IN_JENKINS=<secret>. id-of-a-credential-in-jenkins needs to be provided in a way so that it can be translated into a valid environment variable name (e.g. don't start with a number). value-to-be-replaced must match this regex: ^[-_A-Za-z0-9]+$.

back to overview

Scope	Details
Aliases	cloudFoundry/mtaExtensionCredentials (deprecated)
Type	map[string]interface{}
Mandatory	no
Default	$PIPER_mtaExtensionCredentials (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

mtaExtensionDescriptor

Defines additional extension descriptor file for deployment with the mtaDeployPlugin

back to overview

Scope	Details
Aliases	cloudFoundry/mtaExtensionDescriptor (deprecated)
Type	string
Mandatory	no
Default	$PIPER_mtaExtensionDescriptor (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

mtaPath

Defines the path to *.mtar for deployment with the mtaDeployPlugin

back to overview

Scope	Details
Aliases	-
Type	string
Mandatory	no
Default	$PIPER_mtaPath (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	commonPipelineEnvironment:   reference to: mtarFilePath

org

Cloud Foundry target organization.

back to overview

Scope	Details
Aliases	- cfOrg - cloudFoundry/org (deprecated)
Type	string
Mandatory	yes
Default	$PIPER_org (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

password

Password

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: cfCredentialsId   reference to: password Vault paths: $(vaultPath)/cloudfoundry-$(org)-$(space) $(vaultBasePath)/$(vaultPipelineName)/cloudfoundry-$(org)-$(space) $(vaultBasePath)/GROUP-SECRETS/cloudfoundry-$(org)-$(space)

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

smokeTestScript

Allows to specify a script which performs a check during blue-green deployment. The script gets the FQDN as parameter and returns exit code 0 in case check returned smokeTestStatusCode. More details can be found here. Currently this option is only considered for deployTool cf_native.

back to overview

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

smokeTestStatusCode

Expected status code returned by the check.

back to overview

Scope	Details
Aliases	-
Type	int
Mandatory	no
Default	200
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

space

Cloud Foundry target space

back to overview

Scope	Details
Aliases	- cfSpace - cloudFoundry/space (deprecated)
Type	string
Mandatory	yes
Default	$PIPER_space (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

username

User name used for deployment

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: cfCredentialsId   reference to: username Vault paths: $(vaultPath)/cloudfoundry-$(org)-$(space) $(vaultBasePath)/$(vaultPipelineName)/cloudfoundry-$(org)-$(space) $(vaultBasePath)/GROUP-SECRETS/cloudfoundry-$(org)-$(space)

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

cfCredentialsId

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

Jenkins 'Username with password' credentials ID containing user and password to authenticate to the Cloud Foundry API.

back to overview

Scope	Details
Aliases	cloudFoundry/credentialsId (deprecated)
Type	string
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages

dockerCredentialsId

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

Jenkins 'Username with password' credentials ID containing user and password to authenticate to the Docker registry.

back to overview

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