Cloud Foundry CLI Plugin

The Cloud Foundry command line interface (CLI) 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

Jenkins System 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 click on Manage Jenkins, then click on Configure System to goto the Jenkins configuration page.

In the Cloud Foundry CLI section of the screen, click 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, goto the Configuration page of the job and, in the Build Environment section, check 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 (e.g. 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. See JENKINS-33000 for the latest information.

Copyright © 2010-2020 CloudBees, Inc.Online version published by CloudBees, Inc. under the Creative Commons Attribution-ShareAlike 4.0 license.CloudBees and CloudBees DevOptics are registered trademarks and CloudBees Core, CloudBees Flow, CloudBees Flow Deploy, CloudBees Flow DevOps Insight, CloudBees Flow DevOps Foresight, CloudBees Flow Release, CloudBees Accelerator, CloudBees Accelerator ElectricInsight, CloudBees Accelerator Electric Make, CloudBees CodeShip, CloudBees Jenkins Enterprise, CloudBees Jenkins Platform, CloudBees Jenkins Operations Center, and DEV@cloud are trademarks of CloudBees, Inc. Most CloudBees products are commonly referred to by their short names — Accelerator, Automation Platform, Flow, Deploy, Foresight, Release, Insight, and eMake — throughout various types of CloudBees product-specific documentation. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Jenkins is a registered trademark of the non-profit Software in the Public Interest organization. Used with permission. See here for more info about the Jenkins project. The registered trademark Jenkins® is used pursuant to a sublicense from the Jenkins project and Software in the Public Interest, Inc. Read more at www.cloudbees.com/jenkins/about. Apache, Apache Ant, Apache Maven, Ant and Maven are trademarks of The Apache Software Foundation. Used with permission. No endorsement by The Apache Software Foundation is implied by the use of these marks.Other names may be trademarks of their respective owners. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this content, and CloudBees was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this content, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.