Skip to content

API for Managing Private Pools

Private Pools provide additional deployment types and versions than are offered in the Shared Pools. For example, Shared Pools for TAS only provide the small footprint type, with versions n-2 and newer.

General Shape

/v1/ - Version 1 of the API

/v1/private_pools/ - interact with Private Pools

List / Create / Delete operations

GET /v1/private_pools
POST /v1/private_pools
DELETE /v1/private_pools

Configure the pool

PATCH /v1/private_pools

List the supported deployment types:

GET  /v1/private_pools/deployment_types

Renew Pools which have not been used in a write operation for 1 month

POST  /v1/private_pools/renew

Create a Pool

This endpoint is used to create environments. All pools are created with a default size of 0.

HTTP Request

POST /v1/private_pools

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 The name of the pool that you will eventually claim environments from.
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 .)
region Yes The region the pool deploys environments into. See the deployment_types endpoint to find the available parameters.
deployment_type Yes The deployment_type that is created. See the deployment_types endpoint to find the available parameters.
deployment_subtype No The deployment_subtype of the deployment_type that is created. See the deployment_types endpoint to find the available parameters. Not all deployment_types have deployment_subtypes
version Yes The version that is deployed. See the deployment_types endpoint to find the available parameters.

Example Request

  export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
  curl -X POST "https://environments.toolsmiths.cf-app.com/v1/private_pools" \
  -H "Content-Type: application/json" \
  -d "{\"api_token\": \"$TOOLSMITHS_API_TOKEN\", \
  \"name\": \"mikes_pool\", \
  \"sa_gcp_key\": $sa_gcp_key_var, \
  \"region\": \"us\",
  \"deployment_type\": \"pas\",
  \"deployment_subtype\": \"srt\",
  \"version\": \"2_7\"}" | jq .

Example Response

  {
    "name": "mikes_pool",
    "deployment_type": "pas",
    "deployment_subtype": "srt",
    "region": "us",
    "version_string": "2_7",
    "pool_size": {
      "maximum_total_environments": 0,
      "minimum_unclaimed": 0,
      "minimum_unclaimed_weekend": 0,
    },
    "self_destruct_timestamp": "2019-11-01T13:01:02Z"
  }

Destroy a Pool

This endpoint is used to destroy an environment.

HTTP Request

DELETE /v1/private_pools

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 The name of the pool you want to delete

Example Request

    export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
    curl -X "DELETE" "https://environments.toolsmiths.cf-app.com/v1/private_pools?name=mikes_pool&api_token=$TOOLSMITHS_API_TOKEN"

Example Response

{
  "name": "mikes_pool",
  "deployment_type": "pas",
  "deployment_subtype": "srt",
  "region": "us",
  "version_string": "2_3"
}

Configure the pool

This endpoint is used to configure the pool size. The pool is renewed for 1 month each time the endpoint returns a 2xx. See instructions for rotating the sa_gcp_key.

HTTP Request

PATCH /v1/private_pools

Query Parameters

Parameter Required Description
api_token Yes Your team's API token
name Yes The name of the pool you want to update
minimum_unclaimed No The number of environments you want to have "unclaimed" at any time. Unclaimed environments are those which you can claim
minimum_unclaimed_weekend No The number of environments you want to have "unclaimed" during the weekend. A weekend begins at 6pm PT on Fridays, and ends at 12am PT on Mondays. This enables the same weekend to be used in the US and Europe.
maximum_total_environments No The maximum total environments you would like to have running in your pool at any given time. Prevents run-away environment provisioning
sa_gcp_key No The GCP Service account key in .json format should be from the same GCP Project. Recommended to be passed as an environment variable. export sa_gcp_key_var=$(cat ~/Desktop/mikes-owner-28a1873a42c8.json | jq -c .)

Example Request

export TOOLSMITHS_API_TOKEN=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
curl -X PATCH "https://environments.toolsmiths.cf-app.com/v1/private_pools" \
  -H "Content-Type: application/json" \
  -d "{\"api_token\": \"$TOOLSMITHS_API_TOKEN\", \
  \"name\": \"mikes_pool\", \
  \"sa_gcp_key\": $sa_gcp_key_var, \
  \"maximum_total_environments\": \"20\",
  \"minimum_unclaimed\": \"10\",
  \"minimum_unclaimed_weekend\": \"0\"}" | jq .

Example Response

{
  "name": "mikes_pool",
  "deployment_type": "pas",
  "deployment_subtype": "ert",
  "region": "us",
  "version": "2_6",
  "pool_size": {
    "maximum_total_environments": 20,
    "minimum_unclaimed": 10,
    "minimum_unclaimed_weekend": 0
  },
  "self_destruct_timestamp": "2019-11-29T14:33:44.000Z"
}

Renew the pool

This endpoint enables you to renew your pool.

HTTP Request

POST /v1/private_pools/renew

Query Parameters

Parameter Required Description
api_token Yes Your team's API token
name Yes The name of the pool you wish to renew

Example Request

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

Example Response

{
  "message": "Thank you! mikes_pool has been renewed for 1 month",
  "self_destruct_timestamp": "2019-11-01T13:01:02Z"
}

List Pools

This endpoint is used to list Private Pools owned by your team.

HTTP Request

GET /v1/private_pools

Query Parameters

Parameter Required Description
api_token Yes Your team's API token

Example Request

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

Example Response

[
  {
    "name": "mikes_pool",
    "deployment_type": "pas",
    "deployment_subtype": "ert",
    "region": "us",
    "version": "2_7",
    "self_destruct_timestamp": "2019-07-07T16:00:00Z"
  },
  {
    "name": "todds_pool",
    "deployment_type": "pks",
    "deployment_subtype": "",
    "region": "us",
    "version": "1_5",
    "self_destruct_timestamp": "2019-07-06T16:00:00Z"
  }
]

Get Pool Info

This endpoint is used to get information about your pool, such as current environments and utilization.

HTTP Request

GET /v1/private_pools

Query Parameters

Parameter Required Description
api_token Yes Your team's API token
name Yes The name of the pool which you would like to get information about

Example Request

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

Example Response

{
  "metadata": {
    "name": "mikes_pool",
    "deployment_type": "pas",
    "deployment_subtype": "ert",
    "region": "us",
    "version": "2_7",
    "pool_size": {
      "maximum_total_environments": 2,
      "minimum_unclaimed": 1,
      "minimum_unclaimed_weekend": 1
    },
   "current_environment_counts": {
      "initializing": 0,
      "unclaimed": 0,
      "claimed": 2,
      "deleting": 0,
      "error": 0
    },
  "self_destruct_timestamp": "2019-11-01T13:01:02Z"
  },
  "environments": [
    {
      "name": "tulip",
      "state": "CLAIMED",
      "notes": "testing networking release"
    },
    {
      "name": "sunflower",
      "state": "CLAIMED",
      "notes": "testing capi release"
    }
  ]
}

List deployment types

This endpoint is used to list the available deployment_types for use with the create endpoint.

HTTP Request

GET /v1/private_pools/deployment_types

Example Request

curl "https://environments.toolsmiths.cf-app.com/v1/private_pools/deployment_types" | jq .

Example Response

[
  {
    "deployment_type": "pas",
    "regions": [
      "us",
      "eu"
    ],
    "deployment_subtypes": [
      "srt",
      "full_pas"
    ],
    "versions": [
      "1_12",
      "2_0",
      "2_1",
      "2_2",
      "2_3",
      "2_4",
      "2_5",
      "2_6",
      "2_7",
      "2_8"
    ]
  },
  {
    "deployment_type": "pks",
    "regions": [
      "us",
      "eu"
    ],
    "deployment_subtypes": [],
    "versions": [
      "1_4",
      "1_5"
    ]
  },
  {
    "deployment_type": "cf-deployment",
    "regions": [
      "us",
      "eu"
    ],
    "deployment_subtypes": [],
    "versions": [
      "latest_stable_release"
    ]
  }
]