Skip to content

[Future] API for Custom GCP Environments

Custom environments provide more flexibility than pooled environments. For example, custom environments can be deployed with either small footprint PAS or normal PAS. 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's are supported:

  • pas
  • pks
  • cf-deployment
  • cf-for-k8s

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 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. 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 PAS Request

--This example shows how to deploy the Full PAS version 2.3 to the US Data Center
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_3\", \"notes\": \"this is for testing the memory leak\"}"

Example Response

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

Example PKS Request

--This example shows how to deploy the PKS version 1.5 to the US Data Center
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_5\", \"notes\": \"this is for testing new features\"}"

Example PKS Response

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

Example cf-deployment Request

--This example shows how to deploy cf-deployment to the US Data Center
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"}

Example cf-for-k8s Request

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

Example cf-for-k8s 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 PAS 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 PAS Response

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

Example PKS 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 PKS 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.

Example cf-for-k8s Request

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

Example cf-for-k8s 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 PAS 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 PAS 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 PKS 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 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"
  }
]

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

Example cf-for-k8s Request

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

Example cf-for-k8s Response

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

List versions

This endpoint is used to list versions that can be used

HTTP Request

GET /v1/custom_gcp/{deployment_type}/versions

Example PAS Request

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

Example PAS 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 PKS Request

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

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

Example cf-for-k8s Request

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

Example cf-for-k8s Response

[
  {
    "version": "us_toolsmiths_default",
    "kubernetes_version": "1.14.0",
    "cf-for-k8s_branch": "master",
    "cf-for-k8s_version": "fbb64528cb5db61c25aa3f33ee3c0a2c3e74bd4b"
  },
  {
    "version": "eu_toolsmiths_default",
    "kubernetes_version": "1.14.0",
    "cf-for-k8s_branch": "master",
    "cf-for-k8s_version": "fbb64528cb5db61c25aa3f33ee3c0a2c3e74bd4b"
  }
]