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 config.yml file. In this case, calling the step is reduced to one simple line.
Calling the step can be done either via the Jenkins library step or on the command line.

Jenkins Pipeline

library('piper-lib-os')

cloudFoundryDeploy script: this

Command Line

piper cloudFoundryDeploy

Outputs

Output type Details
influx measurement deployment_data
  • artifactUrl
  • deployTime
  • jobTrigger

Additional Hints

Deployment can be done

Deployment supports multiple deployment tools

Currently the following are supported:

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 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 have to be defined via the manifest. You can find details in the Cloud Foundry Documentation

Prerequisites

  • Cloud Foundry organization, space and deployment user are available
  • Credentials for deployment have been configured in Jenkins with a dedicated Id

    Jenkins credentials configuration

Parameters

Overview

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
containerCommand no Jenkins only
containerShell no Jenkins only
deployDockerImage no
deployTool no
deployType no
dockerEnvVars no Jenkins only
dockerImage no Jenkins only
dockerName no Jenkins only
dockerOptions no Jenkins only
dockerPassword no Secret pass via ENV or Jenkins credentials (dockerCredentialsId)
dockerPullImage no Jenkins only
dockerUsername no Secret pass via ENV or Jenkins credentials (dockerCredentialsId)
dockerVolumeBind no Jenkins only
dockerWorkspace no Jenkins only
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

Details

apiEndpoint

Cloud Foundry API endpoint

back to overview

Scope Details
Aliases - cfApiEndpoint
- cloudFoundry/apiEndpoint
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
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

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 deployType and 'blue-green' as deployTool 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
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
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 false
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
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 as key-value Map objects used for variable substitution within the file given by manifest. Defaults to an empty list, if not specified otherwise. This can be used to set variables like it is provided by 'cf push --var key=value'. The order of the maps of variables given in the list is relevant in case there are conflicting variable names and value between maps contained within the list. In case of conflicts, the last specified map in the list will win. Though each map entry in the list can contain more than one key-value pair for variable substitution, it is recommended to stick to one entry per map, and rather declare more maps within the list. The reason is that if a map in the list contains more than one key-value entry, and the entries are conflicting, the conflict resolution behavior is undefined (since map entries have no sequence). 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'.

back to overview

Scope Details
Aliases - cfManifestVariables
- cloudFoundry/manifestVariables
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
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

back to overview

Scope Details
Aliases cloudFoundry/mtaExtensionCredentials
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
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
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)

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
Type string
Mandatory yes
Default $PIPER_space (if set)
Secret no
Configuration scope
  • ☒ parameter
  • ☒ general
  • ☒ steps
  • ☒ stages
Resource references none

username

User

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)

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

Example

cloudFoundryDeploy(
    script: script,
    deployType: 'blue-green',
    cloudFoundry: [apiEndpoint: 'https://test.server.com', appName:'cfAppName', credentialsId: 'cfCredentialsId', manifest: 'cfManifest', org: 'cfOrg', space: 'cfSpace'],
    deployTool: 'cf_native'
)