ListWarmPools

POST/gitpod.v1.PrebuildService/ListWarmPools

Lists warm pools with optional filtering.

Use this method to:

View all warm pools for a project
Monitor warm pool status across environment classes

Examples

List warm pools for a project:

filter:
  projectIds: ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"]

Query ParametersExpand Collapse

token: optional string

pageSize: optional number

maximum100

minimum0

Body ParametersJSONExpand Collapse

filter: optional object { environmentClassIds, projectIds }

filter contains the filter options for listing warm pools

environmentClassIds: optional array of string

environment_class_ids filters warm pools to specific environment classes

projectIds: optional array of string

project_ids filters warm pools to specific projects

pagination: optional object { token, pageSize }

pagination contains the pagination options for listing warm pools

token: optional string

Token for the next set of results that was returned as next_token of a PaginationResponse

pageSize: optional number

Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100.

formatint32

maximum100

ReturnsExpand Collapse

pagination: optional object { nextToken }

pagination contains the pagination response

nextToken: optional string

Token passed for retrieving the next set of results. Empty if there are no more results

warmPools: optional array of WarmPool { metadata, spec, status, id }

warm_pools are the warm pools that matched the query

metadata: WarmPoolMetadata { createdAt, updatedAt, environmentClassId, 3 more }

metadata contains organizational and ownership information

createdAt: string

created_at is when the warm pool was created

formatdate-time

updatedAt: string

updated_at is when the warm pool was last updated

formatdate-time

environmentClassId: optional string

environment_class_id is the environment class whose instances are warmed

formatuuid

organizationId: optional string

organization_id is the ID of the organization that owns the warm pool

formatuuid

projectId: optional string

project_id is the ID of the project this warm pool belongs to

formatuuid

runnerId: optional string

runner_id is the runner that manages this warm pool. Derived from the environment class.

formatuuid

spec: WarmPoolSpec { desiredPhase, desiredSize, maxSize, 3 more }

spec contains the desired configuration for this warm pool

desiredPhase: optional WarmPoolPhase

desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler.

One of the following:

"WARM_POOL_PHASE_UNSPECIFIED"

"WARM_POOL_PHASE_PENDING"

"WARM_POOL_PHASE_READY"

"WARM_POOL_PHASE_DEGRADED"

"WARM_POOL_PHASE_DELETING"

"WARM_POOL_PHASE_DELETED"

DeprecateddesiredSize: optional number

desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size.

formatint32

maximum20

minimum1

maxSize: optional number

max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20.

formatint32

maximum20

minimum1

minSize: optional number

min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down.

formatint32

maximum20

snapshotId: optional string

snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet.

formatuuid

specVersion: optional string

spec_version is incremented each time the spec is updated. Used for optimistic concurrency control.

status: WarmPoolStatus { phase, desiredSize, failureMessage, 3 more }

status contains the current status reported by the runner

phase: WarmPoolPhase

phase is the current phase of the warm pool lifecycle

One of the following:

"WARM_POOL_PHASE_UNSPECIFIED"

"WARM_POOL_PHASE_PENDING"

"WARM_POOL_PHASE_READY"

"WARM_POOL_PHASE_DEGRADED"

"WARM_POOL_PHASE_DELETING"

"WARM_POOL_PHASE_DELETED"

desiredSize: optional number

desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled.

formatint32

failureMessage: optional string

failure_message contains details about why the warm pool is degraded or failed

runningInstances: optional number

running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup.

formatint32

statusVersion: optional string

status_version is incremented each time the status is updated. Used for optimistic concurrency control.

stoppedInstances: optional number

stopped_instances is the number of pre-provisioned but stopped instances in the pool. When a running instance is claimed, stopped instances are used to backfill the running pool faster than provisioning from scratch. Stopped instances only incur storage costs, allowing a larger total pool at lower cost than keeping all instances running.

formatint32

id: optional string

id is the unique identifier for the warm pool

formatuuid

ListWarmPools

curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/ListWarmPools \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'

{
  "pagination": {
    "nextToken": "nextToken"
  },
  "warmPools": [
    {
      "metadata": {
        "createdAt": "2019-12-27T18:11:19.117Z",
        "updatedAt": "2019-12-27T18:11:19.117Z",
        "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "runnerId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      },
      "spec": {
        "desiredPhase": "WARM_POOL_PHASE_UNSPECIFIED",
        "desiredSize": 1,
        "maxSize": 1,
        "minSize": 20,
        "snapshotId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "specVersion": "specVersion"
      },
      "status": {
        "phase": "WARM_POOL_PHASE_UNSPECIFIED",
        "desiredSize": 0,
        "failureMessage": "failureMessage",
        "runningInstances": 0,
        "statusVersion": "statusVersion",
        "stoppedInstances": 0
      },
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
    }
  ]
}

Returns Examples

{
  "pagination": {
    "nextToken": "nextToken"
  },
  "warmPools": [
    {
      "metadata": {
        "createdAt": "2019-12-27T18:11:19.117Z",
        "updatedAt": "2019-12-27T18:11:19.117Z",
        "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "runnerId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      },
      "spec": {
        "desiredPhase": "WARM_POOL_PHASE_UNSPECIFIED",
        "desiredSize": 1,
        "maxSize": 1,
        "minSize": 20,
        "snapshotId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "specVersion": "specVersion"
      },
      "status": {
        "phase": "WARM_POOL_PHASE_UNSPECIFIED",
        "desiredSize": 0,
        "failureMessage": "failureMessage",
        "runningInstances": 0,
        "statusVersion": "statusVersion",
        "stoppedInstances": 0
      },
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
    }
  ]
}