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.
From a command line, run
ssh ubuntu@OPS-MANAGER-FQDN
to SSH into the Ops Manager VM. ReplaceOPS-MANAGER-FQDN
with the fully qualified domain name of Ops Manager.When prompted, enter the password that you set during the .ova deployment into vCenter. For example:
$ ssh ubuntu@my-opsmanager-fqdn.example.com Password: ***********
Proceed to Authenticate into Ops Manager.
AWS, Azure, and OpenStack
Locate the Ops Manager FQDN on the AWS EC2 instances page, Azure Virtual machines page, or the OpenStack Access & Security page.
Run
chmod 600 ops_mgr.pem
to change the permissions on the.pem
file to be more restrictive:$ chmod 600 ops_mgr.pem
Run
ssh -i ops_mgr.pem ubuntu@OPS-MANAGER-FQDN
to SSH into the Ops Manager VM. ReplaceOPS-MANAGER-FQDN
with the fully qualified domain name of Ops Manager. For example:$ ssh -i ops_mgr.pem ubuntu@my-opsmanager-fqdn.example.com
Proceed to Authenticate into Ops Manager.
GCP
Confirm that you have installed the gcloud CLI. If you do not have the gcloud CLI, see the Google Cloud Platform documentation.
Run
gcloud config set project MY-PROJECT
to configure your Google Cloud Platform project. For example:$ gcloud config set project gcp
Run
gcloud auth login MY-GCP-ACCOUNT
. For example:$ gcloud auth login user@example.com
Run
gcloud compute ssh MY-INSTANCE --zone MY-ZONE
. For example:$ gcloud compute ssh om-pcf-1a --zone us-central1-b
Run
sudo su - ubuntu
to switch to theubuntu
user.Proceed to Authenticate into Ops Manager.
Authenticate Into Ops Manager
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
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
ReplaceOPS-MAN-USERNAME
andOPS-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:
From your local machine, target your Ops Manager UAA server:
$ uaac target https://OPS-MAN-FQDN/uaa
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.
List your tokens:
$ uaac contexts
Locate the entry for your Ops Manager FQDN. Underclient_id: opsman
, record the value foraccess_token
.Use the
GET /api/v0/deployed/products
endpoint to retrieve a list of deployed products, replacingUAA-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"}]