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
|
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
anddeployType=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) | cfCredentialsId ) |
script | (yes) | |
space | yes | |
username | (yes) | 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 | dockerCredentialsId ) |
dockerUsername | no | 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
Scope | Details |
---|---|
Aliases | - cfApiEndpoint - cloudFoundry/apiEndpoint (deprecated) |
Type | string |
Mandatory | no |
Default | https://api.cf.eu10.hana.ondemand.com |
Secret | no |
Configuration scope |
|
Resource references | none |
appName¶
Defines the name of the application to be deployed to the Cloud Foundry space
Scope | Details |
---|---|
Aliases | - cfAppName - cloudFoundry/appName (deprecated) |
Type | string |
Mandatory | no |
Default | $PIPER_appName (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
artifactVersion¶
The artifact version, used for influx reporting
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_artifactVersion (if set) |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_buildTool (if set) |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_cfHome (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
cfNativeDeployParameters¶
Additional parameters passed to cf native deployment command
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_cfNativeDeployParameters (if set) |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_cfPluginHome (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
commitHash¶
The commit hash, used for influx reporting
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_commitHash (if set) |
Secret | no |
Configuration scope |
|
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).
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
Resource references | none |
containerShell¶
Jenkins-specific: Used for proper environment setup.
Allows to specify the shell to be executed for container with containerName.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_deployDockerImage (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
deployTool¶
Defines the tool which should be used for deployment.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_deployTool (if set) |
Secret | no |
Configuration scope |
|
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'.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | standard |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerEnvVars¶
Jenkins-specific: Used for proper environment setup.
Environment variables to set in the container, e.g. [http_proxy: "proxy:8080"].
Scope | Details |
---|---|
Aliases | - |
Type | map[string]string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | ppiper/cf-cli:latest |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | cfDeploy |
Secret | no |
Configuration scope |
|
Resource references | none |
dockerOptions¶
Jenkins-specific: Used for proper environment setup.
Docker options to be set when starting the container.
Scope | Details |
---|---|
Aliases | - |
Type | []string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_dockerPassword (if set) |
Secret | yes |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | true |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_dockerUsername (if set) |
Secret | yes |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | map[string]string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
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
.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
Resource references | none |
loginParameters¶
Addition command line options for cf login command. No escaping/quoting is performed. Not recommended for productive environments.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_loginParameters (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
manifest¶
Defines the manifest to be used for deployment to Cloud Foundry.
Scope | Details |
---|---|
Aliases | - cfManifest - cloudFoundry/manifest (deprecated) |
Type | string |
Mandatory | no |
Default | $PIPER_manifest (if set) |
Secret | no |
Configuration scope |
|
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'
...
Scope | Details |
---|---|
Aliases | - cfManifestVariables - cloudFoundry/manifestVariables (deprecated) |
Type | []string |
Mandatory | no |
Default | $PIPER_manifestVariables (if set) |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - cfManifestVariablesFiles - cloudFoundry/manifestVariablesFiles (deprecated) |
Type | []string |
Mandatory | no |
Default | - manifest-variables.yml |
Secret | no |
Configuration scope |
|
Resource references | none |
mtaDeployParameters¶
Additional parameters passed to mta deployment command
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | -f |
Secret | no |
Configuration scope |
|
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]+$
.
Scope | Details |
---|---|
Aliases | cloudFoundry/mtaExtensionCredentials (deprecated) |
Type | map[string]interface{} |
Mandatory | no |
Default | $PIPER_mtaExtensionCredentials (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
mtaExtensionDescriptor¶
Defines additional extension descriptor file for deployment with the mtaDeployPlugin
Scope | Details |
---|---|
Aliases | cloudFoundry/mtaExtensionDescriptor (deprecated) |
Type | string |
Mandatory | no |
Default | $PIPER_mtaExtensionDescriptor (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
mtaPath¶
Defines the path to *.mtar for deployment with the mtaDeployPlugin
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | $PIPER_mtaPath (if set) |
Secret | no |
Configuration scope |
|
Resource references | commonPipelineEnvironment: reference to: mtarFilePath |
org¶
Cloud Foundry target organization.
Scope | Details |
---|---|
Aliases | - cfOrg - cloudFoundry/org (deprecated) |
Type | string |
Mandatory | yes |
Default | $PIPER_org (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
password¶
Password
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | yes |
Default | $PIPER_password (if set) |
Secret | yes |
Configuration scope |
|
Resource references | Jenkins credential id: id: cfCredentialsId reference to: password Vault paths:
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | Jenkins Script |
Mandatory | yes |
Default | |
Secret | no |
Configuration scope |
|
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
.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | no |
Default | blueGreenCheckScript.sh |
Secret | no |
Configuration scope |
|
Resource references | none |
smokeTestStatusCode¶
Expected status code returned by the check.
Scope | Details |
---|---|
Aliases | - |
Type | int |
Mandatory | no |
Default | 200 |
Secret | no |
Configuration scope |
|
Resource references | none |
space¶
Cloud Foundry target space
Scope | Details |
---|---|
Aliases | - cfSpace - cloudFoundry/space (deprecated) |
Type | string |
Mandatory | yes |
Default | $PIPER_space (if set) |
Secret | no |
Configuration scope |
|
Resource references | none |
username¶
User name used for deployment
Scope | Details |
---|---|
Aliases | - |
Type | string |
Mandatory | yes |
Default | $PIPER_username (if set) |
Secret | yes |
Configuration scope |
|
Resource references | Jenkins credential id: id: cfCredentialsId reference to: username Vault paths:
|
verbose¶
verbose output
Scope | Details |
---|---|
Aliases | - |
Type | bool |
Mandatory | no |
Default | false |
Possible values | - true - false |
Secret | no |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | cloudFoundry/credentialsId (deprecated) |
Type | string |
Configuration scope |
|
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.
Scope | Details |
---|---|
Aliases | - |
Type | string |
Configuration scope |
|