Skip to content

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.

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) Vault Secret pass via ENV, Vault or Jenkins credentials (cfCredentialsId)
script (yes) Jenkins only reference to Jenkins main pipeline script
username (yes) Vault Secret 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 Jenkins only
containerShell no Jenkins only
dockerEnvVars no
dockerImage no
dockerName no
dockerOptions no
dockerPullImage no
dockerVolumeBind no Jenkins only
dockerWorkspace no Jenkins only
stashContent no Jenkins only

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

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 ppiper/cf-cli:latest
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 cf
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

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 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 paths:
  • $(vaultPath)/cloudfoundry-$(org)-$(space)
  • $(vaultBasePath)/$(vaultPipelineName)/cloudfoundry-$(org)-$(space)
  • $(vaultBasePath)/GROUP-SECRETS/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

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

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