API for Custom GCP Environments

Custom environments provide more flexibility than pooled environments. For example, custom environments can be deployed with either small footprint TAS or normal TAS. The environments are also created inside of your GCP Project, giving you full access to modify them. These are also renewable forever.

General Shape

/v1/ - Version 1 of the API

/v1/custom_gcp/ - interact with the GCP IaaS

Custom GCP Endpoints

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

Deployment Types

The following deployment_type are supported:

pas
pks
cf-deployment

Note: Use pas and pks when passing a deployment_type to the API. In the documentation, we refer to the products corresponding to those deployment types by their current names, TAS and TKi.

Create an environment

This endpoint is used to create environments.

HTTP Request

POST /v1/custom_gcp/{deployment_type}/create

Query Parameters

Parameter	Required	Description
api_token	Yes	Your team's API token. More info is available under Programmatic Access.
sa_gcp_key	Yes	The GCP Service account key in .json format. Recommended to be passed as an environment variable. `export sa_gcp_key_var=$(cat ~/Desktop/mikes-owner-28a1873a42c8.json \| jq -c .)`
version	Yes	Version that is deployed. See the `versions` endpoint to find the correct values based on your desired `deployment_type`
tile_type	No	Only relevant for the TAS `deployment_type`. It defaults to `srt`, but accepts either `srt` or `full_pas`. For TKGi deployments, it defaults to `full_pks`, and does not currently accept any other types. For cf-deployment deployments, it currently ignores this parameter.
notes	No	Notes you wish to leave on the environment. The notes are displayed when the /list endpoint is invoked

Example TAS Request

# This example shows how to deploy Full TAS version 2.11 to the US GCP region
export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
curl "https://environments.toolsmiths.cf-app.com/v1/custom_gcp/pas/create" \
-H "Content-Type: application/json" \
-d "{\"api_token\": \"$TOOLSMITHS_API_TOKEN\", \
\"sa_gcp_key\": $sa_gcp_key_var, \
\"tile_type\": \"full_pas\", \"version\": \"us_2_11\", \"notes\": \"this is for testing the memory leak\"}"

Example Response

{"name":"porthueneme","version":"us_2_11"}

Example TKGi Request

# This example shows how to deploy TKGi version 1.10 to the US GCP region
export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
curl "https://environments.toolsmiths.cf-app.com/v1/custom_gcp/pks/create" \
-H "Content-Type: application/json" \
-d "{\"api_token\": \"$TOOLSMITHS_API_TOKEN\", \
\"sa_gcp_key\": $sa_gcp_key_var, \
\"version\": \"us_1_10\", \"notes\": \"this is for testing new features\"}"

Example TKGi Response

{"name":"porthueneme","version":"us_1_5"}

Example cf-deployment Request

# This example shows how to deploy cf-deployment to the US GCP region
export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
curl "https://environments.toolsmiths.cf-app.com/v1/custom_gcp/cf-deployment/create" \
-H "Content-Type: application/json" \
-d "{\"api_token\": \"$TOOLSMITHS_API_TOKEN\", \
\"sa_gcp_key\": $sa_gcp_key_var, \
\"version\": \"us_latest_stable_release\", \"notes\": \"this is for testing new features\"}"

Example cf-deployment Response

{"name":"porthueneme","version":"us_latest_stable_release"}

Destroy an environment

This endpoint is used to destroy an environment.

HTTP Request

POST /v1/custom_gcp/{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 Request

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

Example Response

["Your environment aleppo 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_gcp/{deployment_type}/metadata

Query Parameters

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

Example TAS Request

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

Example TAS Response

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

Example TKGi Request

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

Example TKGi Response

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

Example cf-deployment Request

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

Example cf-deployment 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 GCP environments. The correct deployment_type must be specified.

HTTP Request

POST /v1/custom_gcp/{deployment_type}/renew

Query Parameters

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

Example Request

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

Example Response

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

List GCP Environments

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

HTTP Request

GET /v1/custom_gcp/{deployment_type}/list

Query Parameters

Parameter	Required	Description
api_token	Yes	Your team's API token

Example TAS Request

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

Example TAS Response

[
  {
    "name": "grape-staging",
    "state": "INITIALIZING",
    "deployment_type": "pas",
    "self_destruct_timestamp": "2019-07-07T16:00:00Z",
    "notes": "2019-06-27:mjarvis@pivotal.io has deployed pcf with opsmanager 2.3 and ert 2.3 for team mjarvis@pivotal.io\n\n ",
    "ert_version": null,
    "opsman_version": null
  },
  {
    "name": "banana-staging",
    "state": "IN USE",
    "deployment_type": "pas",
    "self_destruct_timestamp": "2019-07-06T16:00:00Z",
    "notes": "2019-06-26:mjarvis@pivotal.io has deployed pcf with opsmanager 2.3 and ert 2.3 for team mjarvis@pivotal.io\n\n ",
    "ert_version": "2.3.3",
    "opsman_version": "2.3-build.194"
  }
]

Example TKGi Request

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

Example TKGi 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"
  }
]

Example cf-deployment Request

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

Example cf-deployment Response

[
  {
    "name": "grape-staging",
    "state": "INITIALIZING",
    "deployment_type": "cf-deployment",
    "self_destruct_timestamp": "2019-07-07T16:00:00Z",
    "notes": "2019-06-27:mjarvis@pivotal.io has deployed cf-deployment with version 9.4.0 for team mjarvis@pivotal.io\n\n ",
    "version": "9.4.0"
  },
  {
    "name": "banana-staging",
    "state": "IN USE",
    "deployment_type": "cf-deployment",
    "self_destruct_timestamp": "2019-07-06T16:00:00Z",
    "notes": "2019-06-27:mjarvis@pivotal.io has deployed cf-deployment with version 9.3.0 for team mjarvis@pivotal.io\n\n ",
    "version": "9.3.0"
  }
]

List versions

This endpoint is used to list TAS or TKGi versions that can be used

HTTP Request

GET /v1/custom_gcp/{deployment_type}/versions

Example TAS Request

curl "https://environments.toolsmiths.cf-app.com/v1/custom_gcp/pas/versions" | jq .

Example TAS Response

[
  {
    "version": "us_2_7",
    "tile_type": "srt",
    "ert_version": "2.7.0-build.4",
    "opsman_version": "2.6"
  },
  {
    "version": "eu_2_7",
    "tile_type": "srt",
    "ert_version": "2.7.0-build.4",
    "opsman_version": "2.6"
  }
]

Example TKGi Request

curl "https://environments.toolsmiths.cf-app.com/v1/custom_gcp/pks/versions" | jq .

Example TKGi Response

[
  {
    "version": "us_1_4",
    "tile_type": "full_pks",
    "pks_version": "1.4",
    "opsman_version": "2.5"
  },
  {
    "version": "eu_1_4",
    "tile_type": "full_pks",
    "pks_version": "1.4",
    "opsman_version": "2.5"
  }
]

Example cf-deployment Request

curl "https://environments.toolsmiths.cf-app.com/v1/custom_gcp/cf-deployment/versions" | jq .

Example cf-deployment Response

[
  {
    "version": "us_latest_stable_release",
    "cf-deployment_version": "11.0.0",
  },
  {
    "version": "eu_latest_stable_release",
    "cf-deployment_version": "11.0.0",
  }
]