Using the Ops Manager API

Page last updated:

Warning: Pivotal Cloud Foundry (PCF) v2.3 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.

This topic explains how to start using the Ops Manager API.

Platform operators use the Ops Manager API to automate deployments, retrieve and manage credentials, and otherwise work under the hood of the Ops Manager interface.

Tile developers use the Ops Manager API to test and debug Pivotal Cloud Foundry (PCF) product tiles.

For the complete Ops Manager API documentation, see either of the following:

• https://docs.pivotal.io/pivotalcf/2-3/opsman-api
• https://YOUR-OPS-MANAGER-FQDN/docs, adding /docs to the URL of your Ops Manager

Requirements

You must install the User Account and Authentication Command Line Interface (UAAC) to perform the procedures in this topic. To install the UAAC, run the following command from a terminal window:

$ gem install cf-uaac

Step 1: Authenticate

To use the Ops Manager API, you must authenticate and retrieve a token from the Ops Manager User Account and Authentication (UAA) server. For more information about UAA, see the User Account and Authentication (UAA) Server topic.

Perform the procedures in the Internal Authentication or External Identity Provider section below depending on which authentication system you configured for Ops Manager.

Internal Authentication

If you configured your Ops Manager for Internal Authentication, perform the following procedures specific to your IaaS:

vSphere

You need the credentials used to import the PCF .ova or .ovf file into your virtualization system.

1. From a command line, run ssh ubuntu@OPS-MANAGER-FQDN to SSH into the Ops Manager VM. Replace OPS-MANAGER-FQDN with the fully qualified domain name of Ops Manager.

2. When prompted, enter the password that you set during the .ova deployment into vCenter. For example:

   $ ssh ubuntu@my-opsmanager-fqdn.example.com
   Password: ***********
   

3. Proceed to Authenticate into Ops Manager.

AWS, Azure, and OpenStack

1. Locate the Ops Manager FQDN on the AWS EC2 instances page, Azure Virtual machines page, or the OpenStack Access & Security page.

2. Run chmod 600 ops_mgr.pem to change the permissions on the .pem file to be more restrictive:

   $ chmod 600 ops_mgr.pem
   

3. Run ssh -i ops_mgr.pem ubuntu@OPS-MANAGER-FQDN to SSH into the Ops Manager VM. Replace OPS-MANAGER-FQDN with the fully qualified domain name of Ops Manager. For example:

   $ ssh -i ops_mgr.pem ubuntu@my-opsmanager-fqdn.example.com
   

4. Proceed to Authenticate into Ops Manager.

GCP

1. Confirm that you have installed the gcloud CLI. If you do not have the gcloud CLI, see the Google Cloud Platform documentation.

2. Run gcloud config set project MY-PROJECT to configure your Google Cloud Platform project. For example:

   $ gcloud config set project gcp
   

3. Run gcloud auth login MY-GCP-ACCOUNT. For example:

   $ gcloud auth login user@example.com
   

4. Run gcloud compute ssh MY-INSTANCE --zone MY-ZONE. For example:

   $ gcloud compute ssh om-pcf-1a --zone us-central1-b
   

5. Run sudo su - ubuntu to switch to the ubuntu user.

6. Proceed to Authenticate into Ops Manager.

Authenticate Into Ops Manager

1. After successfully SSHing into the Ops Manager VM, use the UAAC to target your Ops Manager UAA server:

   $ uaac target https://OPS-MAN-FQDN/uaa

2. Retrieve your token to authenticate:

   $ uaac token owner get
   Client ID: opsman
   Client secret: [Leave Blank]
   User name: OPS-MAN-USERNAME
   Password: OPS-MAN-PASSWORD
   

   Replace OPS-MAN-USERNAME and OPS-MAN-PASSWORD with the credentials that you use to log in to the Ops Manager web interface.

External Identity Provider

If you configured your Ops Manager for an external Identity Provider with SAML or LDAP, do the following:

1. From your local machine, target your Ops Manager UAA server:

   $ uaac target https://OPS-MAN-FQDN/uaa

2. Retrieve your token to authenticate. When prompted for a passcode, retrieve it from https://OPS-MAN-FQDN/uaa/passcode.

   $ uaac token sso get
   Client ID: opsman
   Client secret: [Leave Blank]
   Passcode: YOUR-PASSCODE
   

   If authentication is successful, the UAAC displays the following message: Successfully fetched token via owner password grant.

Step 2: Access the API

Ops Manager uses authorization tokens to allow access to the API. You must pass an access token to the API endpoint in a header that follows the format Authorization: Bearer YOUR-ACCESS-TOKEN.

The following example procedure retrieves a list of deployed products. See the Ops Manager API documentation for the full range of API endpoints.

If you use Internal Authentication, you must perform the following procedures from the Ops Manager VM. If you use an External Identity Provider, you may perform the procedures from your local machine.

1. List your tokens:

   $ uaac contexts
   

   Locate the entry for your Ops Manager FQDN. Under client_id: opsman, record the value for access_token.

2. Use the GET /api/v0/deployed/products endpoint to retrieve a list of deployed products, replacing UAA-ACCESS-TOKEN with the access token recorded in the previous step:

   $ curl "https://OPS-MAN-FQDN/api/v0/deployed/products" \
       -X GET \
       -H "Authorization: Bearer UAA-ACCESS-TOKEN"

   The request produces the following response:

   [{"installation_name":"p-bosh","guid":"p-bosh
   -00000000000000000000","type":"p-
   bosh","product_version":"1.10.0.
   0"},{"installation_name":"cf-
   00000000000000000000","guid":"cf-0000000000000
   0000000","type":"cf","product_version":"1.10.0"}]