API for Custom vSphere Environments

You need to be assigned a vSphere environment before you can begin to use the API. Please review the general vSphere docs for more information.

General Shape

/v1/ - Version 1 of the API

/v1/custom_vsphere/ - interact with the vSphere IaaS

Custom vsphere Endpoints

/v1/custom_vsphere/{deployment_type}/create - create custom vsphere environments
/v1/custom_vsphere/{deployment_type}/destroy - destroy custom vsphere environment
/v1/custom_vsphere/{deployment_type}/metadata - get metadata for environments
/v1/custom_vsphere/{deployment_type}/renew - extend lease for vsphere environments
/v1/custom_vsphere/{deployment_type}/list - get list of vsphere environments
/v1/custom_vsphere/{deployment_type}/versions - get list of versions that can be used

Deployment Types

• deployment_type=PKS is fully support
• deployment_type=PAS supports only the create and metadata endpoints at this time [31-OCT-2019].

Create an environment

This endpoint is used to create environments. The create endpoint will remove all pre-existing VMs in the Resource Pool specified by name.

HTTP Request

POST /v1/custom_vsphere/{deployment_type}/create

Query Parameters

Parameter	Required	Description
api_token	Yes	Your team's API token. This can be obtained from CF Toolsmiths via slack/email
version	Yes	Version that is deployed. Options would be similar to: 1_4 or 1_3 for PKS environments.
name	Yes	The name of the vSphere environment which is owned by your team, and you want to either create, or delete and re-create the environment.
tile_type	No	Only relevant for the PAS deployment_type. It defaults to srt, but accepts either srt or full_pas. For PKS deployments, it defaults to full_pks, and does not currently accept any other types.
delete_vms_and_recreate	No	Indicates that if there are existing VMs in the resource pool, you would like to delete them before creating the new environment.
Notes	No	Notes you wish to leave on the environment. The notes are displayed when the /list endpoint is invoked

Example PKS Request

--This example shows how to deploy PKS version 1.7 to the `markham` environment.
export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
curl "https://environments.toolsmiths.cf-app.com/v1/custom_vsphere/pks/create" \
-H "Content-Type: application/json" \
-d "{\"api_token\": \"$TOOLSMITHS_API_TOKEN\", \
\"name\": \"markham\", \
\"version\": \"1_7\", \"notes\": \"this is for testing the memory leak bug\"}"

Example PKS Response

{"name":"markham","version":"1_4"}

Example PAS Request

--This example shows how to deploy PAS version 2.8 to the `markham` environment.
export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
curl "https://environments.toolsmiths.cf-app.com/v1/custom_vsphere/pas/create" \
-H "Content-Type: application/json" \
-d "{\"api_token\": \"$TOOLSMITHS_API_TOKEN\", \
\"name\": \"markham\", \
\"version\": \"2_8\", \"notes\": \"this is for testing the memory leak bug\"}"

Example PAS Response

{"name":"markham","version":"2_8"}

Destroy an environment

This endpoint is used to destroy an environment. The destroy endpoint will remove all existing VMs in the Resource Pool specified by name.

HTTP Request

POST /v1/custom_vsphere/{deployment_type}/destroy

Query Parameters

Parameter	Required	Description
api_token	Yes	Your team's API token. This can be obtained from CF Toolsmiths via slack/email
name	Yes	Name of the environment you would like to destroy

Example PKS Request

    export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
    curl "https://environments.toolsmiths.cf-app.com/v1/custom_vsphere/pks/destroy" \
    -H "Content-Type: application/json" \
    -d "{\"api_token\": \"$TOOLSMITHS_API_TOKEN\", \
    \"name\": \"markham\"}"

Example PKS Response

["Your environment markham has been queued to be destroyed."]

Fetching the metadata file for an environment

This endpoint is used to fetch the metadata file for an environment. The metadata file contains detailed information about an environment.

HTTP Request

GET /v1/custom_vsphere/{deployment_type}/metadata

Query Parameters

Parameter	Required	Description
api_token	Yes	Your team's API token
name	Yes	The environment name

Example PKS Request

export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
curl "https://environments.toolsmiths.cf-app.com/v1/custom_vsphere/pks/metadata?api_token=$TOOLSMITHS_API_TOKEN&name=markham" | jq .

Example PKS Response

The response is the metadata file for the deployment_type of your environment. The schema can be found here.

Renew custom environment

This endpoint is used to renew custom vsphere environments

HTTP Request

POST /v1/custom_vsphere/{deployment_type}/renew

Query Parameters

Parameter	Required	Description
api_token	Yes	Your team's API token
name	Yes	The environment name

Example PKS Request

export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
curl "https://environments.toolsmiths.cf-app.com/v1/custom_vsphere/pks/renew" \
-H "Content-Type: application/json" \
-d "{\"api_token\": \"$TOOLSMITHS_API_TOKEN\", \
\"name\": \"markham\"}"

Example PKS Response

{"message":"Thank you! Environment markham has been renewed for 1 month. We will check back in on 2019-07-26"}

List vsphere Environments

This endpoint is used to list custom vsphere environments owned by your team.

HTTP Request

GET /v1/custom_vsphere/{deployment_type}/list

Query Parameters

Parameter	Required	Description
api_token	Yes	Your team's API token

Example PKS Request

export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
curl "https://environments.toolsmiths.cf-app.com/v1/custom_vsphere/pks/list?api_token=$TOOLSMITHS_API_TOKEN" | jq .

Example PKS Response

[
  {
    "name": "suva-staging",
    "state": "INITIALIZING",
    "deployment_type": "pks",
    "tile_type": "full_pks",
    "self_destruct_timestamp": "2019-07-07T16:00:00Z",
    "notes": "2019-06-27:mjarvis@pivotal.io has deployed pcf with opsmanager 2.4 and pks 1.3 for team mjarvis@pivotal.io\n\n ",
    "pks_version": null,
    "opsman_version": null
  },
  {
    "name": "trip-staging",
    "state": "IN USE",
    "deployment_type": "pks",
    "tile_type": "full_pks",
    "self_destruct_timestamp": "2018-07-06T16:00:00Z",
    "notes": "2019-06-26:mjarvis@pivotal.io has deployed pcf with opsmanager 2.4 and pks 1.3 for team mjarvis@pivotal.io\n\n ",
    "pks_version": "1.3",
    "opsman_version": "2.4"
  }
]

List versions

This endpoint is used to list versions that can be used

HTTP Request

GET /v1/custom_vsphere/{deployment_type}/versions

Example PKS Request

curl "https://environments.toolsmiths.cf-app.com/v1/custom_vsphere/pks/versions"

Example PKS Response

[
  {
    "version": "1_4",
    "tile_type": "full_pks",
    "pks_version": "1.4",
    "opsman_version": "2.5"
  },
  {
    "version": "1_3",
    "tile_type": "full_pks",
    "pks_version": "1.3",
    "opsman_version": "2.4"
  }
]