Getting started with the PKS API

As of PKS 1.3.5, I’m not sure if the PKS API is documented anywhere so I thought I’d share what I’ve found so far. I’ll walk through how to access the API and list/create objects such as PKS clusters.

You can access the PKS Swagger definition at https://PKS_API_HOSTNAME:9021/v2/api-docs. You can find the PKS API hostname in Ops Manager > PKS Tile > PKS API > API Hostname. In my environment, this address is https://uaa.pks.vmware.local:9021/v2/api-docs. Unfortunately when you access this page you won’t see a nicely formatted page and will just see a bunch of JSON. I’m not sure if there is another path that will display the data nicely but for now you can copy the JSON and paste it into something like https://editor.swagger.io/. You will probably see a bunch of errors at the top but you can ignore them and scroll down to cluster where you’ll see the following:

Accessing the Swagger API Docs

You’ll also see entries for users, plans, etc. Towards the bottom you’ll see the Models section. This will show us the object definitions, which is important to know so that we will send the correct data in our requests to the API:

Creating a client to talk to the API

I didn’t have much luck being able to login with my normal UAA account that I use to create PKS clusters using the pks command so I had to create a client. You can read more about this here.

Configure uaac to talk to my PKS VM

uaac target https://uaa.vmware.local:8443 –skip-ssl-validation

Get an admin token

You can find admin client secret in Ops Manager > PKS Tile > Credentials tab > Pks Uaa Management Admin Client > Value for secret

uaac token client get admin -s FI-xHjVkPCQEcn_w7q2L0S2jAcWGoUWK

Create the client

uaac client add api-client -s VMware1! –authorized_grant_types client_credentials –authorities pks.clusters.admin,pks.clusters.manage

Interacting with the API

First we need to obtain an access token from the API server. This will be in the form of a Bearer token. We can do this with curl:

curl -s https://uaa.pks.vmware.local:8443/oauth/token -k -XPOST -H ‘Accept: application/json;charset=utf-8’ -u “api-client:VMware1!” -H ‘Content-Type: application/x-www-form-urlencoded;charset=utf-8’ -d ‘grant_type=client_credentials’

In the returned JSON you’ll see the access_token as well as other information such as the type, when it expires, etc. You can also copy the access_token and paste it into https://jwt.io/ to see the data formatted nicely.

If you have jq installed, you can just retrieve the access token like so:

curl -s https://uaa.pks.vmware.local:8443/oauth/token -k -XPOST -H ‘Accept: application/json;charset=utf-8’ -u “api-client:VMware1!” -H ‘Content-Type: application/x-www-form-urlencoded;charset=utf-8’ -d ‘grant_type=client_credentials’ | jq -r .access_token

Let’s go ahead an store the access token in an environment variable named BEARER_TOKEN:

BEARER_TOKEN=$(curl -s https://uaa.pks.vmware.local:8443/oauth/token -k -XPOST -H ‘Accept: application/json;charset=utf-8’ -u “api-client:VMware1!” -H ‘Content-Type: application/x-www-form-urlencoded;charset=utf-8’ -d ‘grant_type=client_credentials’ | jq -r .access_token)

Listing clusters

Now that we have our bearer token we can start doing things like listing clusters:

curl -s -k -H “Authorization: Bearer ${BEARER_TOKEN}” -H “accept: application/json” -X GET https://uaa.pks.vmware.local:9021/v1/clusters | jq

Postman

Performing the above tasks can be tedious using curl so I’ve created a Postman collection to make things easier. You can find the file at Github. Let’s see how to use it.

Import the collection

From Postman’s menu select File > Import > Import from Link > paste in the link above and press Import.

Create a PKS environment

Let’s create an environment where we can define variables such as the PKS API hostname, credentials, etc. In the upper-right corner select the gear:

Select Add and make it look like this:

You don’t have to worry about filling in the Bearer token value as it will be filled in automatically for you.

Now you should have the following requests. It’s not fully fleshed out but should be enough to get you started:

Let’s start by getting logging into the API. We can do this by selecting Get auth token and press Send. If successful, you’ll see the following:

Feel free to check out the cookies and headers tabs, and make sure the Status is 200 OK. Test Results should be (1/1). If you select the Tests tab above, you’ll see how the tests work:

Here we can see that we are parsing the our request’s response and setting the access_token environment variable to the access_token value from the JSON.

Now that we have our token set we can make other request. To list all clusters select GET Clusters and press Send where you’ll see something similiar to: