Using the Tanzu Operations Manager API

This topic explains how you can access the VMware Tanzu Operations Manager API, and gives examples on using the API to perform common operations.

The Tanzu Operations Manager API controls the Tanzu Operations Manager VM directly, bypassing the Tanzu Operations Manager UI. Platform operators use the Tanzu Operations Manager API to automate deployments, retrieve and manage credentials, and otherwise work with Tanzu Operations Manager. Tile Developers use the Tanzu Operations Manager API to test and debug Tanzu Operations Manager product tiles.

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

Related tools

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

For more information about om, see the om repository.

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

Access the Tanzu Operations Manager API

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

For more information about UAA, see User Accounts and Authentication overview.

Install the UAAC

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

gem install cf-uaac

Log in to Tanzu Operations Manager

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

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

For example:
```
$ uaac target https://my-opsmanager.example.com/uaa
```
Run a command to retrieve your UAA token. See below for the appropriate command to run and responses to provide for the authentication prompts.
- If Tanzu Operations Manager UAA uses an internal or LDAP identity provider, run:
```
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 Tanzu Operations Manager web interface.
  
  For example:
```
$ uaac token owner get
Client ID: opsman
Client secret:
User name: my-opsman-username
Password: my-opsman-password
```
- If Tanzu Operations Manager UAA uses a SAML or OIDC identity provider, run
```
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 Tanzu Operations 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 Tanzu Operations Manager API commands from the command line, the machine that you can be logged into depends on the location of your Tanzu Operations Manager UAA, as follows:

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

API access test

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

List your tokens. Run:
```
uaac contexts
```
In the command output, locate the entry for your Tanzu Operations 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 looks 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 Tanzu Operations 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 Tanzu Operations Manager command-line interface (CLI) om is usually a better tool than the Tanzu Operations Manager API for running Tanzu Operations Manager operations directly from the command-line or within shell scripts.

These methods are intended for advanced Tanzu Operations Manager operators and administrators.

Configure the BOSH Director

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

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

To configure the BOSH Director with the Tanzu Operations Manager API:

Access the Tanzu Operations Manager API by following the procedure in Access the Tanzu Operations Manager API procedure.

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-USERNAME is your Tanzu Operations Manager admin username
ADMIN-PASSWORD is your Tanzu Operations 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"
} }'

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 is complete. 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. Tanzu Operations 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 Tanzu Operations 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 can 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.

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 Tanzu Operations Manager API:

Upload or import the product into Tanzu Operations 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 Tanzu Operations Manager.
Send an HTTP GET request to the api/v0/staged_products endpoint to confirm that the product is staged for deployment in Tanzu Operations 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 Tanzu Operations Manager

The following procedure upgrades Tanzu Operations Manager using the Tanzu Operations Manager API:

Prerequisites

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

Two versions of Tanzu Operations 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 Tanzu Operations Manager

Procedure

Follow this procedure to upgrade your Tanzu Operations Manager:

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