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

Retrieve an authorization token

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

How you retrieve this token depends on whether your Tanzu Operations 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 following procedure that corresponds to your Tanzu Operations Manager UAA location and IaaS.

Internal UAA on vSphere

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

You set the public SSH key in the Public SSH Key text box of the Customize template pane when you deployed Tanzu Operations Manager. For more information, see Deploy Tanzu Operations Manager.

To retrieve the authorization token from internal UAA on vSphere:

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

For example:
```
$ ssh [email protected]
```
When prompted, enter the public SSH key.
Proceed to Log in to Tanzu Operations Manager.

Internal UAA on AWS, Azure, or OpenStack

Locate the Tanzu Operations 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 Tanzu Operations Manager VM.

For example:
```
$ chmod 600 ops_mgr.pem
```
SSH into the Tanzu Operations 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 Tanzu Operations Manager VM.
- OPS-MANAGER-FQDN is the fully qualified domain name of your Tanzu Operations Manager.
For example:
```
$ ssh -i ops_mgr.pem [email protected]
```
Proceed to Log in to Tanzu Operations 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:
```
gcloud config set project MY-PROJECT
```
Where PROJECT is the name of your GCP project.

For example:
```
$ gcloud config set project gcp
```

Run:

gcloud auth login MY-GCP-ACCOUNT

Where MY-GCP-ACCOUNT is your GCP account ID.

For example:

$ gcloud auth login [email protected]

Run:
```
gcloud compute ssh MY-INSTANCE --zone MY-ZONE
```
Where:
- MY-INSTANCE is your Tanzu Operations Manager VM instance.
- MY-ZONE is the zone where your Tanzu Operations 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 Tanzu Operations Manager.

External UAA

If you configured your Tanzu Operations 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 Tanzu Operations Manager.

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
```
Depending on whether your Tanzu Operations 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 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
```
- 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 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.