cloudFoundryCreateService¶

Creates one or multiple Services in Cloud Foundry

Description¶

Creates one or multiple Cloud Foundry Services in Cloud Foundry Mandatory: * Cloud Foundry API endpoint, Organization, Space and user are available

Please provide either of the following options: * If you chose to create a single Service the Service Instance Name, Service Plan and Service Broker of the Service to be created have to be available. You can set the optional cfCreateServiceConfig flag to configure the Service creation with your respective JSON configuration. The JSON configuration can either be an in-line JSON string or the path a dedicated JSON configuration file containing the JSON configuration. If you chose a dedicated config file, you must store the file in the same folder as your Jenkinsfile that starts the Pipeline in order for the Pipeline to be able to find the file. Most favourable SCM is Git. If you want the service to be created from a particular broker you can set the optional cfServiceBrokerflag. You can set user provided tags for the Service creation using a flat list as the value for the optional cfServiceTags flag. The optional cfServiceBroker flag can be used when the service name is ambiguous. * For creating one or multiple Cloud Foundry Services at once with the Cloud Foundry Create-Service-Push Plugin using the optional serviceManifest flag. If you chose to set this flag, the Create-Service-Push Plugin will be used for all Service creations in this step and you will need to provide a serviceManifest.yml file. In that case, above described flags and options will not be used for the Service creations, since you chose to use the Create-Service-Push Plugin. Please see below examples for more information on how to make use of the plugin with the appropriate step configuation. Additionally the Plugin provides the option to make use of variable substitution for the Service creations. You can find further information regarding the functionality of the Cloud Foundry Create-Service-Push Plugin in the respective documentation: Cloud Foundry Create-Service-Push Plugin

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.

JenkinsCommand Line

library('piper-lib-os')

cloudFoundryCreateService script: this

piper cloudFoundryCreateService

Prerequisites¶

You have a user for the SAP BTP Cloud Foundry environment
Credentials have been configured in Jenkins with a dedicated Id

Parameters¶

Overview - Step¶

Name	Mandatory	Additional information
cfOrg	yes
cfSpace	yes
password	(yes)	pass via ENV, Vault or Jenkins credentials (`cfCredentialsId`)
script	(yes)	reference to Jenkins main pipeline script
username	(yes)	pass via ENV, Vault or Jenkins credentials (`cfCredentialsId`)
cfApiEndpoint	no
cfAsync	no
cfCreateServiceConfig	no
cfService	no
cfServiceBroker	no
cfServiceInstanceName	no
cfServicePlan	no
cfServiceTags	no
manifestVariables	no
manifestVariablesFiles	no
serviceManifest	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
stashContent	no

Details¶

cfApiEndpoint¶

Cloud Foundry API endpoint

back to overview

Scope	Details
Aliases	`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

cfAsync¶

Decides if the service creation runs asynchronously

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

cfCreateServiceConfig¶

Path to JSON file or JSON in-line string for a Cloud Foundry Service creation

back to overview

Scope	Details
Aliases	`cloudFoundry/createServiceConfig`
Type	`string`
Mandatory	no
Default	`$PIPER_cfCreateServiceConfig` (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

cfOrg¶

Cloud Foundry org

back to overview

Scope	Details
Aliases	`cloudFoundry/org`
Type	`string`
Mandatory	yes
Default	`$PIPER_cfOrg` (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

cfService¶

Parameter for Cloud Foundry Service to be used for creating Cloud Foundry Service

back to overview

Scope	Details
Aliases	`cloudFoundry/service`
Type	`string`
Mandatory	no
Default	`$PIPER_cfService` (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

cfServiceBroker¶

Parameter for Service Broker to be used when creating a Cloud Foundry Service

back to overview

Scope	Details
Aliases	`cloudFoundry/serviceBroker`
Type	`string`
Mandatory	no
Default	`$PIPER_cfServiceBroker` (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

cfServiceInstanceName¶

Parameter for naming the Service Instance when creating a Cloud Foundry Service

back to overview

Scope	Details
Aliases	`cloudFoundry/serviceInstanceName`
Type	`string`
Mandatory	no
Default	`$PIPER_cfServiceInstanceName` (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

cfServicePlan¶

Parameter for Cloud Foundry Service Plan to be used when creating a Cloud Foundry Service

back to overview

Scope	Details
Aliases	`cloudFoundry/servicePlan`
Type	`string`
Mandatory	no
Default	`$PIPER_cfServicePlan` (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

cfServiceTags¶

Flat list of Tags to be used when creating a Cloud Foundry Service in a single string

back to overview

Scope	Details
Aliases	`cloudFoundry/serviceTags`
Type	`string`
Mandatory	no
Default	`$PIPER_cfServiceTags` (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

cfSpace¶

Cloud Foundry Space

back to overview

Scope	Details
Aliases	`cloudFoundry/space`
Type	`string`
Mandatory	yes
Default	`$PIPER_cfSpace` (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

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	`cf`
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
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

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

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

manifestVariables¶

Defines a List of variables as key-value Map objects used for variable substitution within the file given by the 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). 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	- `cloudFoundry/manifestVariables` - `cfManifestVariables`
Type	`[]string`
Mandatory	no
Default	`$PIPER_manifestVariables` (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

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 in https://docs.cloudfoundry.org/devguide/deploy-apps/manifest-attributes.html#variable-substitution

back to overview

Scope	Details
Aliases	- `cloudFoundry/manifestVariablesFiles` - `cfManifestVariablesFiles`
Type	`[]string`
Mandatory	no
Default	`$PIPER_manifestVariablesFiles` (if set)
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

password¶

Password for Cloud Foundry User

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

serviceManifest¶

Path to Cloud Foundry Service Manifest in YAML format for multiple service creations that are being passed to a Create-Service-Push Cloud Foundry cli plugin

back to overview

Scope	Details
Aliases	- `cloudFoundry/serviceManifest` - `cfServiceManifest`
Type	`string`
Mandatory	no
Default	`service-manifest.yml`
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

stashContent¶

Jenkins-specific: Used for proper environment setup.

Specific stashes that should be considered for the step execution.

back to overview

Scope	Details
Aliases	-
Type	`[]string`
Mandatory	no
Default	- `deployDescriptor`
Secret	no
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages
Resource references	none

username¶

User or E-Mail for CF

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`
Type	`string`
Configuration scope	☒ parameter ☒ general ☒ steps ☒ stages

Example¶

Single Service Creation in Cloud Foundry example with JSON-configuration in Jenkinsfile¶

The following example creates a single Service in Cloud Foundry. It makes use of the cfCreateServiceConfig flag for passing a JSON configuration as an in-line parameter string as well as the cfServiceTags for providing user tags.

You can store the credentials in Jenkins and use the cfCredentialsId parameter to authenticate to Cloud Foundry.

This can be done accordingly:

cloudFoundryCreateService(
    cfApiEndpoint : 'https://test.server.com',
    cfOrg : 'cfOrg',
    cfSpace: 'cfSpace',
    cfCredentialsId: 'cfCredentialsId',
    cfService:  'myService',
    cfServiceInstanceName: 'myServiceInstanceName',
    cfServicePlan: 'myPlan',
    cfCreateServiceConfig: '{\"example\":\"value\",\"example\":\"value\"}',
    cfServiceTags: 'list, of, tags',
    script: this,
)

If you chose to having a dedicated JSON file for the JSON configuration for the cfCreateServiceConfig flag you can do so by referencing the file path accordingly. This file should be stored in the same folder as your Jenkinsfile that starts the Pipeline in order for the Pipeline to be able to find the file. Most favourable SCM is Git. Such a JSON file with the appropriate step configuration could look as follows:

The JSON config file, e.g. createServiceConfig.json can look like this:

{
  "example":"value",
  "example":"value"
}

The step configuration needs to contain the path to the JSON file:

cloudFoundryCreateService(
    cfApiEndpoint : 'https://test.server.com',
    cfOrg : 'cfOrg',
    cfSpace: 'cfSpace',
    cfCredentialsId: 'cfCredentialsId',
    cfService:  'myService',
    cfServiceInstanceName: 'myServiceInstanceName',
    cfServicePlan: 'myPlan',
    cfCreateServiceConfig: 'createServiceConfig.json',
    cfServiceTags: 'list, of, tags',
    script: this,
)

Multiple Service Creation in Cloud Foundry example with manifest file in Jenkinsfile¶

The following example shows the option to create multiple Services in Cloud Foundry. It makes use of the Cloud Foundry Create-Service-Push Plugin. This is described in above Prerequisites, please check this section for further information regarding its usage. This plugin enables this step to create multiple Cloud Foundry Services in one step.

It requires a dedicated YAML file, e.g. manifest.yml, that contains all the information for creating the services, including their names, service plan and the service broker.

Such a manifest.yml file needs to have the following structure, e.g. for creating three mongoDB Services with the Service Plan v4.0-dev:

---
create-services:
- name:   "testDatabase1"
  broker: "mongodb"
  plan:   "v4.0-dev"

- name:   "testDatabase2"
  broker: "mongodb"
  plan:   "v4.0-dev"

- name:   "testDatabase3"
  broker: "mongodb"
  plan:   "v4.0-dev"

The path of the manifest.yml config file needs to be passed as a parameter in the serviceManifest flag. You can store the credentials in Jenkins and use the cfCredentialsId parameter to authenticate to Cloud Foundry.

This can be done accordingly:

cloudFoundryCreateService(
    cfApiEndpoint : 'https://test.server.com',
    cfOrg : 'cfOrg',
    cfSpace: 'cfSpace',
    cfCredentialsId: 'cfCredentialsId',
    serviceManifest: 'manifest.yml',
    script: this,
)

Multiple Service Creation in Cloud Foundry example with manifest file and variable substitution in Jenkinsfile¶

Additionally the Cloud Foundry Create-Service-Push Plugin offers the option to make use of variable substitution. This enables you to rename variables in the manifest.yml dynamically. It can be done either via providing the file path to a dedicated YAML file containing the information regarding the variable substitution values in the manifestVariablesFiles flag or via providing a String List in the manifestVariables flag. Either ways can be achieved as seen in below examples for creating MongoDB instances.

For both ways you need to adapt the manifest.yml file to be relevant for variable substitution. This can be done according to below example:

---
create-services:
- name:   ((name1))
  broker: "mongodb"
  plan:   "v4.0-dev"

- name:   ((name2))
  broker: "mongodb"
  plan:   "v4.0-dev"

- name:   ((name3))
  broker: "mongodb"
  plan:   "v4.0-dev"

If you chose to have a dedicated file for the variable substitution values, it needs to have the following structure of the vars.yml file:

name1: test1
name2: test2
name3: test3

The path of the manifest.yml config file needs to be passed as a parameter in the serviceManifest flag as well as the path to the vars.yml file in the manifestVariablesFiles flag. You can store the credentials in Jenkins and use the cfCredentialsId parameter to authenticate to Cloud Foundry.

This can be done accordingly:

cloudFoundryCreateService(
    cfApiEndpoint : 'https://test.server.com',
    cfOrg : 'cfOrg',
    cfSpace: 'cfSpace',
    cfCredentialsId: 'cfCredentialsId',
    serviceManifest: 'manifest.yml',
    manifestVariablesFiles: 'vars.yml',
    script: this,
)

You can also pass the values for the variable substition as a string list for the manifestVariables flag. This needs to follow the pattern key=value. This can be done accordingly:

cloudFoundryCreateService(
    cfApiEndpoint : 'https://test.server.com',
    cfOrg : 'cfOrg',
    cfSpace: 'cfSpace',
    cfCredentialsId: 'cfCredentialsId',
    serviceManifest: 'manifest.yml',
    manifestVariables: ["name1=test1","name2=test2", "name3=test3"],
    script: this,
)

cloudFoundryCreateService¶

Description¶

Usage¶

Prerequisites¶

Parameters¶

Overview - Step¶

Overview - Execution Environment¶

Details¶

cfApiEndpoint¶

cfAsync¶

cfCreateServiceConfig¶

cfOrg¶

cfService¶

cfServiceBroker¶

cfServiceInstanceName¶

cfServicePlan¶

cfServiceTags¶

cfSpace¶

containerCommand¶

containerShell¶

dockerEnvVars¶

dockerImage¶

dockerName¶

dockerOptions¶

dockerPullImage¶

dockerVolumeBind¶

dockerWorkspace¶

manifestVariables¶

manifestVariablesFiles¶

password¶

script¶

serviceManifest¶

stashContent¶

username¶

verbose¶

cfCredentialsId¶

Example¶

Single Service Creation in Cloud Foundry example with JSON-configuration in Jenkinsfile¶

Multiple Service Creation in Cloud Foundry example with manifest file in Jenkinsfile¶

Multiple Service Creation in Cloud Foundry example with manifest file and variable substitution in Jenkinsfile¶