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.
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.
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.
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
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.
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.
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
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.
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.
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.
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.
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:
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"}]
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.
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 passphraseEULA-STATUS is your EULA statusIDP-LOCATION is your identity provider location, internal or externalADMIN-USERNAME is your Ops Manager admin usernameADMIN-PASSWORD is your Ops Manager admin passwordHTTP-PROXY is your HTTP proxy, if applicableHTTPS-PROXY is your HTTPS proxy, if applicableFor 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 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. 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:
GET request to api/v0/staged/products to find your Director’s GUID.GET api/v0/staged/products/:BOSH-DIRECTOR-GUID/jobs.PUT api/v0/staged/products/:BOSH-DIRECTOR-GUID/jobs/:JOB-GUID/resource_config.The following procedure uploads, stages, and configures a product tile using the Ops Manager API:
POST request to the api/v0/available_products endpoint to upload the product.GET request to the api/v0/available_products endpoint to list the names of available products.available_products, find the product you uploaded by referencing its name and version.POST request to the /api/v0/staged/products endpoint to add the uploaded product to Ops Manager.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.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.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.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.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.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.The following procedure upgrades Ops Manager using the Ops Manager API:
Before you upgrade Ops Manager with the Ops Manager API, you must have the following:
Follow this procedure to upgrade your Ops Manager:
GET request to the /api/v0/installation_asset_collection endpoint of your old Ops Manager to export your existing installation data.POST request to the /api/v0/installation_asset_collection endpoint of your new Ops Manager to import your installation data to the new deployment.POST request to the /api/v0/installations endpoint of your new Ops Manager to trigger a new installation process.