Skip to content

cloudFoundryDeploy

Deploys an application to Cloud Foundry

Description

Deploys an application to a test or production space within Cloud Foundry. This step supports two deployment types:

The step achieves this via following deploy tools * cf CLI - used as default for Non MTA apps * MTA CF CLI Plugin - used as default for MTA apps

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

Standard CF deployments

deployType parameter defaults to value standard.
This means that CF CLI is called by piper and command cf push is run by piper

Blue green deployments

With CF CLI

  • Blue green deployments are deprecated, but rolling deployment strategy is supported.
  • For rolling deployment strategy , set parameter cfNativeDeployParameters:'--strategy rolling'

With MTA CF CLI Plugin for MTA applications

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

Following table summarizes the different combinations of the step parameters deployType and deployTool and their impact. Parameter buildTool is used to differentiate between MTA and Non MTA applications. If buildTool is not available in the environment, user will have to provide deployTool explicitly.

Deployment Strategy Comparison

This table compares deployment strategies for MTA and Non-MTA applications.

deployType MTA Applications Non MTA Applications
standard deployTool = mtaDeployPlugin
Uses MTA plugin,
Command run cf deploy		 deployTool = cf_native
cf CLI used
Command cf push
Requires Manifest file and app name
appname can be provided via config or manifest file.
blue-green deployTool = mtaDeployPlugin,
Uses MTA plugin
Command run cf deploy bgdeploy		 Deprecated.
Alternative: Rolling deployment strategy by setting
cfNativeDeployParameters = '--strategy rolling'
deployDockerImage not supported deployDockerImage supported
Docker credentials can only be provided as Jenkins environment variable.

!!! 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.
  • 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
  • Recommended way to do docker image deployments is via kubernetesDeploy Piper step.This step is not capable of deploying docker images built in the same pipeline using other piper steps[i.e., kanikoExecute].

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
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. 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 documentationxx 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. Mandatory if buildTool is not found in pipeline environment

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 -standard or blue-green deployment. For mta build tool, possible values are standard, blue-green or bg-deploy. For cf native build tools, possible value is standard. To eliminate system downtime, an alternative is to pass '--strategy rolling' to the parameter cfNativeDeployParameters.

back to overview

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

dockerEnvVars

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

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

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

Docker options to be set when starting the container.

back to overview

Scope Details
Aliases -
Type []string
Mandatory no
Default [{--ulimit stack=67108864:67108864} {--ulimit nofile=65536:65536}]
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

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

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 file name to be used for deployment to Cloud Foundry. Defaults to manifest.yml

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 resource:
  name: cloudfoundryVaultSecretName
  default value: cloudfoundry-$(org)-$(space)

Vault paths:
  • $(vaultPath)/cloudfoundry-$(org)-$(space)
  • $(vaultBasePath)/$(vaultPipelineName)/cloudfoundry-$(org)-$(space)
  • $(vaultBasePath)/GROUP-SECRETS/cloudfoundry-$(org)-$(space)

script

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

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 resource:
  name: cloudfoundryVaultSecretName
  default value: cloudfoundry-$(org)-$(space)

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