Using the Ops Manager API

Overview
- Related Tools
Access the Ops Manager API
Example Ops Manager API Procedures

Page last updated:

This topic explains how to access the Ops Manager API, and gives examples of how to use the API to perform some common VMware Tanzu Operations Manager (Ops Manager) operations.

Overview

The Ops Manager API controls the Ops Manager VM directly, bypassing the Ops Manager UI.

Platform operators use the Ops Manager API to automate deployments, retrieve and manage credentials, and otherwise work with Ops Manager. Tile Developers use the Ops Manager API to test and debug Ops Manager product tiles.

For more information about the Ops Manager API, see the Ops Manager API documentation. Your Ops Manager serves a local copy of this documentation at https://YOUR-OPS-MANAGER-FQDN/docs.

For running Ops Manager operations from the command line or within shell scripts, the Ops Manager command-line interface (CLI) om is usually a better tool than the Ops Manager API.

For more information about om, see the om repository.

For an overview of the Ops Manager API and the tools based on it, see Using Ops Manager Programmatically and from the Command Line.

Access the Ops Manager API

To access the Ops Manager API, you must authenticate to the Ops Manager User Account and Authentication (UAA) server and log in as described below.

For more information about UAA, see UAA Overview.

Install the UAAC

If you haven’t already, install the UAA Command Line Interface (UAAC) by running the following command from a terminal window:

gem install cf-uaac

Retrieve an Authorization Token

Every call to the Ops Manager API must include an authorization token that is acceptable to the Ops Manager UAA.

How you retrieve this token depends on whether your Ops Manager user store is an internal IaaS component or an external server. With an internal UAA, the procedure depends on which IaaS you are on.

To retrieve your authorization token, perform the procedure below that corresponds to your Ops Man UAA location and IaaS.

Internal UAA on vSphere

To log in to the Ops Manager VM with SSH in vSphere, you need the public SSH key that imports the Ops Manager .ova or .ovf file into your virtualization system.

You set the public SSH key in the Public SSH Key field of the Customize template screen when you deployed Ops Manager. For more information, see Deploy Ops Manager.

To retrieve the authorization token from internal UAA on vSphere:

SSH onto the Ops Manager VM:
```
ssh ubuntu@OPS-MANAGER-FQDN
```
Where OPS-MANAGER-FQDN is the fully qualified domain name of Ops Manager.

For example:
```
$ ssh ubuntu@my-opsmanager.example.com
```
When prompted, enter the public SSH key.
Proceed to Log in to Ops Manager.

Internal UAA on AWS, Azure, or 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 to change the permissions on the .pem file to be more restrictive:
```
chmod 600 OPS-MGR-PEM
```
Where OPS-MGR-PEM is the public key from the keypair used when creating the Ops Manager VM.

For example:
```
$ chmod 600 ops_mgr.pem
```
Run ssh -i OPS-MGR-PEM ubuntu@OPS-MANAGER-FQDN to SSH into the Ops Manager VM:
```
ssh -i ops_mgr.pem ubuntu@OPS-MANAGER-FQDN
```
Where:
- OPS-MGR-PEM is the public key from the keypair used when creating the Ops Manager VM.
- OPS-MANAGER-FQDN is the fully qualified domain name of your Ops Manager.
For example:
```
$ ssh -i ops_mgr.pem ubuntu@my-opsmanager.example.com
```
Proceed to Log in to Ops Manager.

Internal UAA on GCP

Confirm that you have installed the gcloud CLI. If you do not have the gcloud CLI, see the Google Cloud Platform documentation:
To configure your Google Cloud Platform project, run the following command:
```
$ gcloud config set project MY-PROJECT
```
Where PROJECT is the name of your GCP project.

For example:
```
$ gcloud config set project gcp
```
Run the following command:
```
gcloud auth login MY-GCP-ACCOUNT
```
Where MY-GCP-ACCOUNT is your GCP account ID.

For example:
```
$ gcloud auth login user@example.com
```
Run the following command:
```
gcloud compute ssh MY-INSTANCE --zone MY-ZONE
```
Where:
- MY-INSTANCE is your Ops Manager VM instance.
- MY-ZONE is the zone where your Ops Manager VM is running.
For example:
```
$ gcloud compute ssh om-pcf-1a --zone us-central1-b
```
Switch to the ubuntu user by running the following command:
```
sudo su - ubuntu
```
Proceed to Log in to Ops Manager.

External UAA

If you configured your Ops Manager for an external Identity Provider with SAML or LDAP, you do not need any IaaS-specific setup. You can proceed to Log in to Ops Manager.

Log in to Ops Manager

To log in to the Ops Manager VM and retrieve your token:

Use the UAAC to target your Ops Manager UAA server:
```
uaac target https://OPS-MAN-FQDN/uaa
```
Where OPS-MANAGER-FQDN is the fully qualified domain name of Ops Manager.

For example:
```
$ uaac target https://my-opsmanager.example.com/uaa
```

Depending on whether your Ops Manager UAA is internal or external, run a command to retrieve your UAA token and respond to the authentication prompts as follows:

Internal

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

Where OPS-MAN-USERNAME and OPS-MAN-PASSWORD are the credentials that you use to log in to the Ops Manager web interface. For example:

$ uaac token owner get
Client ID: opsman
Client secret:
User name: my-opsman-username
Password: my-opsman-password

External

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

Where OPS-MAN-PASSCODE is the value you retrieve from https://OPS-MAN-FQDN/uaa/passcode. For example:

$ uaac token sso get
Client ID: opsman
Client secret:
Password: my-opsman-passcode

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

Run API Commands

To run any Ops Manager API command, you pass your authorization token to the API command endpoint in a header that follows the format Authorization: Bearer YOUR-ACCESS-TOKEN.

If you are calling Ops Manager API commands from the command line, the machine that you can be logged into depends on the location of your Ops Manager UAA, as follows:

Internal: You must run Ops Manager API commands from the Ops Manager VM.
External: You may run commands from your local machine.

API Access Test

The following procedure tests whether you can access the Ops Manager API from the command line by retrieving a list of deployed products:

List your tokens by running the following command:
```
uaac contexts
```
In the command output, locate the entry for your Ops Manager FQDN. Under client_id: opsman, record the value for access_token.

Use the GET /api/v0/deployed/products endpoint to retrieve a list of deployed products:

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

Where UAA-ACCESS-TOKEN is the access token recorded in the previous step.

The command output should look like the following:

$ curl "https:my-opsmanager.example.com/api/v0/deployed/products" \
    -X GET \
    -H "Authorization: Bearer my-access-token"
[{"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"}]

Example Ops Manager API Procedures

The following procedures illustrate how to test API calls from the command line. If you are a developer writing deployment or test routines in programming languages, these procedures show how you might test the routines line-by-line while building them.

The Ops Manager command-line interface (CLI) om is usually a better tool than the Ops Manager API for running Ops Manager operations directly from the command-line or within shell scripts.

These methods are intended for advanced Ops Manager operators and administrators.

Configure the BOSH Director

The following procedure configures the BOSH Director for your IaaS using the Ops Manager API.

VMware recommends that beginning users configure the BOSH Director through the Ops Manager UI, which provides context and explanations for each option. For information about configuring the BOSH Director tile in the Ops Manager UI, see one of the following:

To configure the BOSH Director with the Ops Manager API:

Access the Ops Manager API by following the procedure in Access the Ops Manager API procedure above.

To perform initial setup, enter a POST request to the Ops Man API setup endpoint, passing metadata to the -d flag:

curl "https://YOUR-OPS-MANAGER-URL.com/api/v0/setup" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "setup": {
  "decryption_passphrase": "PASSPHRASE",
  "decryption_passphrase_confirmation":"PASSPHRASE",
  "eula_accepted": "EULA-STATUS",
  "identity_provider": "IDP-LOCATION",
  "admin_user_name": "ADMIN-USERNAME",
  "admin_password": "ADMIN-PASSWORD",
  "admin_password_confirmation": "ADMIN-PASSWORD",
  "http_proxy": HTTP-PROXY,
  "https_proxy": HTTPS-PROXY,
  "no_proxy": "127.0.0.1"

Where:

PASSPHRASE is your deployment’s decryption passphrase
EULA-STATUS is your EULA status
IDP-LOCATION is your identity provider location, internal or external
ADMIN-USERNAMEis your Ops Manager admin username
ADMIN-PASSWORDis your Ops Manager admin password
HTTP-PROXY is your HTTP proxy, if applicable
HTTPS-PROXY is your HTTPS proxy, if applicable

For example:

$ curl "https://my-opsman.example.com/api/v0/setup" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "setup": {
  "decryption_passphrase": "my-passphrase",
  "decryption_passphrase_confirmation":"my-passphrase",
  "eula_accepted": "true",
  "identity_provider": "internal",
  "admin_user_name": "my-username",
  "admin_password": "my-password",
  "admin_password_confirmation": "my-password",
  "http_proxy": "http://myproxy.example.com",
  "https_proxy": "https://myproxy.example.com",
  "no_proxy": "127.0.0.1"
} }'

Note: You do not need to specify UAA or other authentication details on a first-time deploy. Making the setup request automatically creates a UAA client when it completes successfully. If you specify a UAA client for a first-time deployment, the deployment will fail.

A 200 OK response appears.

After the successful response, a UAA client with the metadata you specified is created and launched. Ops Manager users can authenticate with UAAC, and if they have a pre-created client they can target UAAC with the client name and password. For more information on pre-created clients, see Creating and Managing Ops Manager User and Client Accounts.
Send an HTTP PUT request to the api/v0/staged/director/properties endpoint to configure your IaaS and BOSH Director. There are many configuration parameters available to customize your BOSH Director. All the commands are IaaS-agnostic except the IaaS configuration key. Missing required fields should cause an error. For more information about configuring the BOSH Director, see Fetching Director, IaaS, and Security Properties.
Send an HTTP POST request to the api/v0/staged/director/availability_zones endpoint to create Availability Zones (AZs) for your product.
Note: The create-azs endpoint is optional for Azure-based deployments, because you cannot manually configure Azure AZs.
Send an HTTP PUT request to the api/v0/staged/director/networks endpoint to create networking rules for the deployment. Specify whether or not to use ICMP checks by setting the icmp_checks_enabled parameter to true or false.
Send an HTTP PUT request to the api/v0/staged/director/network_and_az endpoint to assign a singleton AZ and a network where your BOSH Director will be located.
You must update the BOSH Director’s resource configuration settings before deploying BOSH. To update the resource config:
1. Send a GET request to api/v0/staged/products to find your Director’s GUID.
2. Use the following HTTP request to list all jobs on the Director: GET api/v0/staged/products/:BOSH-DIRECTOR-GUID/jobs.
3. Use the following HTTP request to update the resource config of each job on the BOSH Director: PUT api/v0/staged/products/:BOSH-DIRECTOR-GUID/jobs/:JOB-GUID/resource_config.

Configure a Product

The following procedure uploads, stages, and configures a product tile using the Ops Manager API:

Upload or import the product into Ops Manager.
1. Send an HTTP POST request to the api/v0/available_products endpoint to upload the product.
2. Send an HTTP GET request to the api/v0/available_products endpoint to list the names of available products.
3. In the output list from available_products, find the product you uploaded by referencing its name and version.
4. Send an HTTP POST request to the /api/v0/staged/products endpoint to add the uploaded product to Ops Manager.
Send an HTTP GET request to the api/v0/staged_products endpoint to confirm that the product is staged for deployment in Ops Manager and display the product GUID.
Send an HTTP PUT request to the PUT /api/v0/staged/products/:PRODUCT-GUID/networks_and_azs to assign availability zones (AZs) and networks to the product. Where PRODUCT-GUID is the product GUID.
Send an HTTP PUT request to the /api/v0/staged/products/:PRODUCT-GUID/properties endpoint to update the product’s properties. Where PRODUCT-GUID is the product GUID.
Send an HTTP PUT request to the /api/v0/staged/products/:PRODUCT-GUID/syslog_configuration endpoint to configure syslog for the product. Where PRODUCT-GUID is the product GUID.
Update the product’s resource configuration by doing the following:
1. Send an HTTP GET request to the api/v0/staged/products/:PRODUCT-GUID/jobs endpoint to list all jobs on a product and display the GUID for each job. Where PRODUCT-GUID is the product GUID.
2. Send an HTTP PUT request to the api/v0/staged/products/:PRODUCT-GUID/jobs/:JOB-GUID/resource_config endpoint to update the resource config for a particular job. Where:
  - PRODUCT-GUID is the product GUID.
  - JOB-GUID is the job GUID.

Upgrade Ops Manager

The following procedure upgrades Ops Manager using the Ops Manager API:

Prerequisites

Before you upgrade Ops Manager with the Ops Manager API, you must have the following:

Two versions of Ops Manager: an existing deployment and a new deployment of a later version. The new deployment cannot be configured in any way.
DNS information for the existing deployment of Ops Manager

Procedure

Follow this procedure to upgrade your Ops Manager:

Send an HTTP GET request to the /api/v0/installation_asset_collection endpoint of your old Ops Manager to export your existing installation data.
Send an HTTP POST request to the /api/v0/installation_asset_collection endpoint of your new Ops Manager to import your installation data to the new deployment.
Send an HTTP POST request to the /api/v0/installations endpoint of your new Ops Manager to trigger a new installation process.
Test the new deployment.
(Optional) Delete the old deployment.

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