pcf Command Line Utility

The pcf utility provides a command line interface to Pivotal Cloud Foundry for the purpose of deploying and testing tiles. Its primary reason for existence is to enable Ops Manager access from CI pipelines, but developers also find it convenient to use this CLI rather than the Ops manager GUI.

The pcf utility also allows you to test your tile’s BOSH errands directly from your CLI, without going through Ops Manager and BOSH. This greatly reduces the time it takes to deploy/test each iteration of your software components.

Installation

The pcf utility comes bundled with the Tile Generator tool. To install the pcf utility, follow the Tile Generator installation instructions.

Authentication

The pcf utility looks for a file called metadata in the current directory. This file is expected to provide the URL and credentials to connect to Ops Manager, in the following format:

---
opsmgr:
    url: https://opsmgr.example.com
    username: admin
    password: <redacted>

The reason for this file naming is because this is how Concourse passes credentials of a “claimed” PCF pool resource to the CI pipeline scripts. For interactive use, this means that you will have to create a metadata file in the directory where you run the pcf command.

We recommend that you do not create this file inside your git (or other version control system) repository, as you do not want to accidentally commit these credentials to version control.

Commands

The pcf utility implements many different commands. To see available commands:

$ pcf --help
Usage: pcf [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  apply-changes
  cf-info
  changes
  configure
  delete-unused-products
  import
  install
  is-available
  is-installed
  logs
  products
  settings
  target
  test-errand
  uninstall

Checking Ops Manager Settings

To see which products are currently available and installed in Ops Manager:

$ pcf products
- p-bosh 1.7.0.0 (installed)
- cf 1.7.0-build.258 (installed)
- test-tile 0.3.95

To test if a specific product is available or installed from within a script:

$ pcf is-available test-tile && echo "Product test-tile is available"
$ pcf is-installed test-tile && echo "Product test-tile is installed"

You can retrieve the settings for a specific product (this will give you a lot of json):

$ pcf settings test-tile
{
    "network_reference": "669e213111ab5aa1008a",
    "guid": "test-tile-be3e50cf26c530acca6e",
    "jobs": [
        {
            "instance": {
                "identifier": "instances"
            },
            "identifier": "compilation",
            "guid": "compilation-066a85d82fbcd936f9d7",
            "installation_name": "compilation",
            "vm_credentials": {
                "password": <redacted>,
                "salt": <redacted>,
                "identity": "vcap"
            }
        },
        {
            "guid": "deploy-all-b83a7cb7be00ebfd26d6",
            "vm_credentials": {
    ...

Testing Errands

You can test your tile’s BOSH errands directly from your current shell. Deploy your tile’s packages using:

$ pcf test-errand test-tile-repo deploy-all
/usr/local/bin/cf version 6.15.0+fa1bfe2-2016-01-13
cf api https://api.run-04.example.com --skip-ssl-validation
cf auth system_services <redacted>
cf target -o test-tile-org
cf update-quota test-tile-org-quota -m 4096m -r 1000 -s 100
cf update-quota test-tile-org-quota --allow-paid-service-plans
cf set-quota test-tile-org test-tile-org-quota
cf target -s test-tile-space
cf bind-running-security-group all_open
cf push app1-0.0.2 -n app1 -d cfapps-04.example.com -f sample/release/blobs/app1/manifest.yml --no-start
cf set-env app1-0.0.2 UAA_HOST https://uaa.run-04.example.com
cf set-env app1-0.0.2 CC_HOST https://api.run-04.example.com
cf set-env app1-0.0.2 LOGIN_HOST https://login.run-04.example.com
cf set-env app1-0.0.2 ROOT $HOME
cf set-env app1-0.0.2 SCHEME https
cf set-env app1-0.0.2 VERIFY_SSL True
cf set-env app1-0.0.2 CF_ORG test-tile-org
cf set-env app1-0.0.2 CF_SPACE test-tile-space
cf set-env app1-0.0.2 CF_TARGET https://api.run-04.example.com
cf set-env app1-0.0.2 SECURITY_USER_NAME admin
...

Delete them using:

$ pcf test-errand test-tile-repo delete-all
/usr/local/bin/cf version 6.15.0+fa1bfe2-2016-01-13
cf api https://api.run-04.example.com --skip-ssl-validation
cf auth system_services <redacted>
cf delete -f app3-0.0.2
cf delete-buildpack -f noop_buildpack
cf purge-service-offering -f service-broker2-service
cf delete-service-broker -f service-broker2
cf delete -f service-broker2-0.0.2
cf delete -f app2-0.0.2
cf purge-service-offering -f service-broker1-service
cf delete-service-broker -f service-broker1
cf delete -f service-broker1-0.0.2
cf delete -f app1-0.0.2
cf delete-space -f test-tile-space
cf delete-org -f test-tile-org
cf delete-quota -f test-tile-org-quota

This only reliably works for the above two errands generated by the tile generator. If your tile includes any packages that are not deployed into them Elastic Runtime, such as docker-bosh packages, those will not be deployed when using this method.

Deploying Tiles

Once your software works and correctly deploys using test-errand, you can go through the real Ops Manager deployment process from the CLI, as you would normally do through the Ops Manager GUI.

Import your .pivotal file into Ops Manager:

$ pcf import sample/product/test-tile-0.0.2.pivotal

Install the uploaded version of your product:

$ pcf install test-tile 0.0.2

Where you would normally configure the tile settings in the GUI, the configure command lets you pass in any user-specified properties as a .yml file. This command also sets the stemcell for the tile to the same one used by your Elastic Runtime, to avoid the need to upload a tile-specific stemcell.

$ pcf configure test-tile sample/missing-properties.yml
- Using stemcell bosh-vsphere-esxi-ubuntu-trusty-go_agent version 3215

The property file looks like this:

---
customer_name: Jimmy's Johnnys
street_address: Cartaway Alley
city: New Jersey
country: US
username: SpongeBob
password: { 'secret': SquarePants }
app2:
  persistence_store_type: none
# In PCF 1.8+, BOSH-job-specific configuration is supported:
jobs:
  a_job:
    # Job resource configuration:
    resource_config:
      persistent_disk:
        size_mb: "10240"
    # Job-specific property configuration:
    job_property: property_value

Note the special handling of the secret type property. Specifying a simple string value for a field of this type will result in a 500 System Error being returned from pcf configure.

To see what changes are ready to be applied:

$ pcf changes
install: test-tile-207b165fcb7dc8b2597b
delete:  

To apply these changes:

$ pcf apply-changes
  ===== 2016-04-21 18:45:05 UTC Running "bosh-init deploy /var/tempest/workspaces/default/deployments/bosh.yml"
  Deployment manifest: '/var/tempest/workspaces/default/deployments/bosh.yml'
  Deployment state: '/var/tempest/workspaces/default/deployments/bosh-state.json'

  Started validating
    Validating release 'bosh'... Finished (00:00:08)
    Validating release 'bosh-vsphere-cpi'... Finished (00:00:00)
    Validating release 'uaa'... Finished (00:00:06)
    Validating cpi release... Finished (00:00:00)
    Validating deployment manifest... Finished (00:00:00)

pcf apply-changes automatically tails the logs for the installation process it started. If this gets aborted for any reason, you can always tail the logs of the most recent installation:

$ pcf logs

Removing Tiles

To uninstall a tile:

$ pcf uninstall test-tile

If you accumulate a lot of uninstalled tiles or old versions, you can clean up Ops Manager’s available products (and disk space):

$ pcf delete-unused-products

Accessing Elastic Runtime

To see details about the Elastic Runtime of your PCF environment:

$ pcf cf-info
- admin_password: <redacted>
- admin_username: admin
- apps_domain: cfapps-04.example.com
- system_domain: run-04.example.com
- system_services_password: <redacted>
- system_services_username: system_services

To target your cf command line at this PCF environment:

$ pcf target
Setting api endpoint to api.example.com...
OK

API endpoint:   https://api.example.com (API version: 2.52.0)   
User:           admin   
Org:            my-org
Space:          my-space
API endpoint: https://api.example.com
Authenticating...
OK

...
Create a pull request or raise an issue on the source for this page in GitHub