Cloud Foundry CLI Plugin

3 minute read

The Cloud Foundry plugin provisions the Cloud Foundry CLI in your Jenkins jobs so that you can deploy applications or interact with a Cloud Foundry platform.

You can install the version of the Cloud Foundry CLI of your choice.

This plugin is tested with the following Cloud Foundry platforms:

  • Pivotal Web Services (aka PWS)

  • Pivotal CF (aka PCF)

Plugin Installation

To install Cloud Foundry CLI plugin, from the main page, click on Manage Jenkins, then Manage Plugins and on the Available tab, check Cloud Foundry CLI and then click on Download Now and Install After Restart.

cloudfoundry plugin install
Figure 1. Cloud Foundry CLI plugin installation

Configuration

Before jobs can utilize the Cloud Foundry CLI it is necessary to define the CLI version(s) to make available on Jenkins.

From the main page select on Manage Jenkins, then select on Configure System.

In the Cloud Foundry CLI section of the screen, select on the button Cloud Foundry Installations …​ and then on the button Add Cloud Foundry CLI.

Choose a name for the CLI installation (e.g. Cloud Foundry 6.9.0) and select the installation method. By default, the installer Installer from cloudfoundry.org is select and a drop-down list let you select the version.

cloudfoundry global config
Figure 2. Cloud Foundry CLI installer configuration

Note: if the dropdown list of available versions is not visible and replaced by an input box, you have to trigger the reloading of the update center: Click on Manage Jenkins then Manage Plugins then go on the Advanced tab and click on Check Now.

cloudfoundry reload update center
Figure 3. Reloading Jenkins Update Center

Using the Cloud Foundry CLI in a Pipeline Job

Once the Cloud Foundry CLI is setup in the System Configuration, you can use it in any Pipeline job as a build wrapper.

Cloud Foundry CLI Pipeline syntax

The Groovy syntax looks like:

node { // ... withCfCli( (1) apiEndpoint: 'https://api.cf-domain.example.com', (2) skipSslValidation: false, (3) cloudFoundryCliVersion: 'Cloud Foundry CLI (built-in)', (4) credentialsId: 'cf-user-cleclerc-credentials', (5) organization: 'my-org', (6) space: 'development') { (7) sh 'cf push my-app-name -p target/my-app*.war' (8) } }
1 withCfCli step
2 URL of the Cloud Foundry API endpoint (e.g. "http://api.cf-domain.example.com")
3 Skip SSL validation when using a self signed certificate for the API endpoint (please don’t)
4 Name of the Cloud Foundry CLI version defined in the Jenkins System Configuration screen
5 ID of the credentials to configure the Cloud Foundry CLI
6 Default Cloud Foundry Elastic Runtime organization
7 Default Cloud Foundry Elastic Runtime space
8 cf commands used in sh steps, the Cloud Foundry CLI is configured with the desired API endpoint, credentials and default organization and space.

Evaluating cf commands result

Evaluating the result of the cf command is key to the logic of your Pipeline.

  • cf commands return non-zero exit code in case of error and thus, shell steps will by default fail if a cf command fails

  • To capture the output of a cf command in a Pipeline, use returnStdout: true as described in the Pipeline steps reference

Pipeline snippet generator

You can generate the Pipeline statement to setup the Cloud Foundry CLI using the Jenkins Pipeline Snippet Generator.

cloudfoundry cli workflow snippet
Figure 4. Cloud Foundry CLI Pipeline snippet

Job configuration

To enable the Cloud Foundry CLI in a job, go to the Configuration page of the job, and in the Build Environment section, select Set up Cloud foundry CLI.

You can then select Cloud Foundry CLI version:: The version of the CLI to use in this job. This CLI installation has been configuration in Jenkins System Configuration. API EndPoint:: URL of the Cloud Foundry API (for example https://api.run.pivotal.io). Skip ssl validation:: Disable SSL certificate validation when invoking the Cloud Foundry API, please don’t disable SSL validation. API Credentials:: Login/password to use when invoking the Cloud Foundry API (see cf auth). Organization:: The Cloud Foundry Organization (see cf target). Space:: The Cloud Foundry Space (see cf target).

cloudfoundry job config
Figure 5. Cloud Foundry CLI job configuration

Using the Cloud Foundry CLI in a job

Once the Cloud Foundry CLI is setup in a job, you can use it in any Execute Shell or Execute Windows Batch Command step.

cloudfoundry sample shell step
Figure 6. Cloud Foundry CLI sample shell step

Security notes

The Cloud Foundry CLI is configured per job so that 2 jobs running on the same agent will not see the settings of each other (different CF_HOME for each job). Moreover, the Cloud Foundry CLI settings are deleted from the agent after the job execution (CF_HOME is deleted).

Known issue

This plugin is not compatible with CloudBees Docker Custom Build Environment. If the latter is used to run a Docker container to host the build, the CloudFoundry CLI plugin won’t configure credentials. The CLI won’t be able to interact with CloudFoundry. Refer to JENKINS-33000 for the latest information.