

cloudFoundryDeploy

Description

Deploys an application to a test or production space within Cloud Foundry. 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

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

  

Parameters

name	mandatory	default	possible values
apiParameters	no	``
buildTool	no
cfNativeDeployParameters	no	``
cloudFoundry/apiEndpoint	no	https://api.cf.eu10.hana.ondemand.com
cloudFoundry/appName	no
cloudFoundry/credentialsId	yes
cloudFoundry/manifest	no
cloudFoundry/manifestVariablesFiles	no
cloudFoundry/org	yes
cloudFoundry/space	yes
deployDockerImage	no
deployTool	no		'cf_native', 'mtaDeployPlugin'
deployType	no	standard	'standard', 'blue-green'
dockerCredentialsId	no
dockerImage	no	deployTool=cf_native:ppiper/cf-cli deployTool=mtaDeployPlugin:ppiper/cf-cli
dockerWorkspace	no	deployTool=cf_native:/home/piper deployTool=mtaDeployPlugin:/home/piper
keepOldInstance	no	false	true, false
loginParameters	no	``
manifestVariables	no
mtaDeployParameters	no	-f
mtaExtensionCredentials	no
mtaExtensionDescriptor	no	``
mtaPath	no	``
script	yes
smokeTestScript	no	blueGreenCheckScript.sh
smokeTestStatusCode	no	200
stashContent	no	[deployDescriptor, pipelineConfigAndTests]
verbose	no		true, false

• apiParameters - Addition command line options for cf api command. No escaping/quoting is performed. Not recommanded for productive environments.
• buildTool -
• cfNativeDeployParameters - Additional parameters passed to cf native deployment command.
• cloudFoundry/apiEndpoint - Cloud Foundry API endpoint.
• cloudFoundry/appName - Defines the name of the application to be deployed to the Cloud Foundry space.
• cloudFoundry/credentialsId - Credentials to be used for deployment.
• cloudFoundry/manifest - Defines the manifest to be used for deployment to Cloud Foundry.
• cloudFoundry/manifestVariablesFiles - Defines the manifest variables Yaml files to be used to replace variable references in manifest. This parameter is optional and will default to ["manifest-variables.yml"]. This can be used to set variable files like it is provided by cf push --vars-file <file>. If the manifest is present and so are all variable files, a variable substitution will be triggered that uses the cfManifestSubstituteVariables step before deployment. The format of variable references follows the Cloud Foundry standard.
• cloudFoundry/org - Cloud Foundry target organization.
• cloudFoundry/space - Cloud Foundry target space.
• 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.
• deployTool - Defines the tool which should be used for deployment. If it is not set it will be inferred automatically based on the buildTool, i.e., for MTA projects mtaDeployPlugin will be used and cf_native for other types of projects.
• 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'.
• dockerCredentialsId - If the specified image in deployDockerImage is contained in a Docker registry, which requires authorization this defines the credentials to be used.
• dockerImage - Name of the docker image that should be used. Configure with empty value to execute the command directly on the Jenkins system (not using a container). Omit to use the default image (cf. default_pipeline_environment.yml) Overwrite to use custom Docker image.
• dockerWorkspace - Kubernetes only: Specifies a dedicated user home directory for the container which will be passed as value for environment variable HOME.
• 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.
• loginParameters - Addition command line options for cf login command. No escaping/quoting is performed. Not recommanded for productive environments.
• 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 values 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.
• mtaDeployParameters - Additional parameters passed to mta deployment command.
• 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
• mtaExtensionDescriptor - Defines additional extension descriptor file for deployment with the mtaDeployPlugin.
• mtaPath - Defines the path to *.mtar for deployment with the mtaDeployPlugin. If not specified, it will use the mta file created in mtaBuild or search for an mtar file in the workspace.
• 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.
• 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.
• smokeTestStatusCode - Expected status code returned by the check.
• stashContent - Specific stashes that should be considered for the step execution.
• verbose - Provides more output. May reveal sensitive information.

Step configuration

We recommend to define values of step parameters via config.yml file.

In following sections of the config.yml the configuration is possible:

parameter	general	step/stage
apiParameters	X	X
buildTool	X	X
cfNativeDeployParameters	X	X
cloudFoundry/apiEndpoint	X	X
cloudFoundry/appName	X	X
cloudFoundry/credentialsId	X	X
cloudFoundry/manifest	X	X
cloudFoundry/manifestVariablesFiles	X	X
cloudFoundry/org	X	X
cloudFoundry/space	X	X
deployDockerImage	X	X
deployTool	X	X
deployType	X	X
dockerCredentialsId	X	X
dockerImage	X	X
dockerWorkspace	X	X
keepOldInstance	X	X
loginParameters	X	X
manifestVariables	X	X
mtaDeployParameters	X	X
mtaExtensionCredentials	X	X
mtaExtensionDescriptor	X	X
mtaPath	X	X
script
smokeTestScript	X	X
smokeTestStatusCode	X	X
stashContent	X	X
verbose	X	X

Dependencies

The step depends on the following Jenkins plugins

• credentials-binding
• docker
• kubernetes
• pipeline-utility-steps
• workflow-basic-steps
• workflow-cps-global-lib
• workflow-durable-task-step

The kubernetes plugin is only used if running in a kubernetes environment. Transitive dependencies are omitted.

The list might be incomplete.

Consider using the ppiper/jenkins-master docker image. This images comes with preinstalled plugins.

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