github.com/jaylevin/jenkins-library@v1.230.4/documentation/docs/steps/cloudFoundryCreateService.md (about)

     1  # ${docGenStepName}
     2  
     3  ## ${docGenDescription}
     4  
     5  ## Prerequisites
     6  
     7  * You have a user for the SAP BTP Cloud Foundry environment
     8  * Credentials have been configured in Jenkins with a dedicated Id
     9  
    10  ## ${docGenParameters}
    11  
    12  ## ${docGenConfiguration}
    13  
    14  ## ${docJenkinsPluginDependencies}
    15  
    16  ## Example
    17  
    18  * ### Single Service Creation in Cloud Foundry example with JSON-configuration in Jenkinsfile
    19  
    20  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.
    21  
    22  You can store the credentials in Jenkins and use the `cfCredentialsId` parameter to authenticate to Cloud Foundry.
    23  
    24  This can be done accordingly:
    25  
    26  ```groovy
    27  cloudFoundryCreateService(
    28      cfApiEndpoint : 'https://test.server.com',
    29      cfOrg : 'cfOrg',
    30      cfSpace: 'cfSpace',
    31      cfCredentialsId: 'cfCredentialsId',
    32      cfService:  'myService',
    33      cfServiceInstanceName: 'myServiceInstanceName',
    34      cfServicePlan: 'myPlan',
    35      cfCreateServiceConfig: '{\"example\":\"value\",\"example\":\"value\"}',
    36      cfServiceTags: 'list, of, tags',
    37      script: this,
    38  )
    39  ```
    40  
    41  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.
    42  Such a JSON file with the appropriate step configuration could look as follows:
    43  
    44  The JSON config file, e.g. `createServiceConfig.json` can look like this:
    45  
    46  ```json
    47  {
    48    "example":"value",
    49    "example":"value"
    50  }
    51  ```
    52  
    53  The step configuration needs to contain the path to the JSON file:
    54  
    55  ```groovy
    56  cloudFoundryCreateService(
    57      cfApiEndpoint : 'https://test.server.com',
    58      cfOrg : 'cfOrg',
    59      cfSpace: 'cfSpace',
    60      cfCredentialsId: 'cfCredentialsId',
    61      cfService:  'myService',
    62      cfServiceInstanceName: 'myServiceInstanceName',
    63      cfServicePlan: 'myPlan',
    64      cfCreateServiceConfig: 'createServiceConfig.json',
    65      cfServiceTags: 'list, of, tags',
    66      script: this,
    67  )
    68  ```
    69  
    70  * ### Multiple Service Creation in Cloud Foundry example with manifest file in Jenkinsfile
    71  
    72  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.
    73  
    74  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.
    75  
    76  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:
    77  
    78  ```yaml
    79  
    80  ---
    81  create-services:
    82  - name:   "testDatabase1"
    83    broker: "mongodb"
    84    plan:   "v4.0-dev"
    85  
    86  - name:   "testDatabase2"
    87    broker: "mongodb"
    88    plan:   "v4.0-dev"
    89  
    90  - name:   "testDatabase3"
    91    broker: "mongodb"
    92    plan:   "v4.0-dev"
    93  ```
    94  
    95  The path of the `manifest.yml` config file needs to be passed as a parameter in the `serviceManifest` flag.
    96  You can store the credentials in Jenkins and use the `cfCredentialsId` parameter to authenticate to Cloud Foundry.
    97  
    98  This can be done accordingly:
    99  
   100  ```groovy
   101  cloudFoundryCreateService(
   102      cfApiEndpoint : 'https://test.server.com',
   103      cfOrg : 'cfOrg',
   104      cfSpace: 'cfSpace',
   105      cfCredentialsId: 'cfCredentialsId',
   106      serviceManifest: 'manifest.yml',
   107      script: this,
   108  )
   109  ```
   110  
   111  * ### Multiple Service Creation in Cloud Foundry example with manifest file and variable substitution in Jenkinsfile
   112  
   113  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.
   114  
   115  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:
   116  
   117  ```yaml
   118  
   119  ---
   120  create-services:
   121  - name:   ((name1))
   122    broker: "mongodb"
   123    plan:   "v4.0-dev"
   124  
   125  - name:   ((name2))
   126    broker: "mongodb"
   127    plan:   "v4.0-dev"
   128  
   129  - name:   ((name3))
   130    broker: "mongodb"
   131    plan:   "v4.0-dev"
   132  ```
   133  
   134  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:
   135  
   136  ```yaml
   137  name1: test1
   138  name2: test2
   139  name3: test3
   140  ```
   141  
   142  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.
   143  You can store the credentials in Jenkins and use the `cfCredentialsId` parameter to authenticate to Cloud Foundry.
   144  
   145  This can be done accordingly:
   146  
   147  ```groovy
   148  cloudFoundryCreateService(
   149      cfApiEndpoint : 'https://test.server.com',
   150      cfOrg : 'cfOrg',
   151      cfSpace: 'cfSpace',
   152      cfCredentialsId: 'cfCredentialsId',
   153      serviceManifest: 'manifest.yml',
   154      manifestVariablesFiles: 'vars.yml',
   155      script: this,
   156  )
   157  ```
   158  
   159  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.
   160  This can be done accordingly:
   161  
   162  ```groovy
   163  cloudFoundryCreateService(
   164      cfApiEndpoint : 'https://test.server.com',
   165      cfOrg : 'cfOrg',
   166      cfSpace: 'cfSpace',
   167      cfCredentialsId: 'cfCredentialsId',
   168      serviceManifest: 'manifest.yml',
   169      manifestVariables: ["name1=test1","name2=test2", "name3=test3"],
   170      script: this,
   171  )
   172  ```