Skip to content

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.

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

Deployment supports multiple deployment tools

Currently the following are supported:

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) Vault Secret pass via ENV, Vault or Jenkins credentials (cfCredentialsId)
script (yes) Jenkins only reference to Jenkins main pipeline script
space yes
username (yes) Vault Secret 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 Secret pass via ENV or Jenkins credentials (dockerCredentialsId)
dockerUsername no Secret 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 Jenkins only
containerShell no Jenkins only
dockerEnvVars no
dockerImage no
dockerName no
dockerOptions no
dockerPullImage no
dockerVolumeBind no Jenkins only
dockerWorkspace no Jenkins only

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