CreateWarmPool

client.prebuilds.createWarmPool(, ?): PrebuildCreateWarmPoolResponse { warmPool }

POST/gitpod.v1.PrebuildService/CreateWarmPool

Creates a warm pool for a project and environment class.

A warm pool maintains pre-created environment instances from a prebuild snapshot so that new environments can start near-instantly.

Only one warm pool is allowed per <project, environment_class> pair. The environment class must have prebuilds enabled on the project.

The pool’s snapshot is managed automatically: when a new prebuild completes for the same project and environment class, the pool’s snapshot is updated and the runner rotates instances.

Examples

Create warm pool:

Creates a warm pool with 2 instances for a project and environment class.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
desiredSize: 2

ParametersExpand Collapse

body: PrebuildCreateWarmPoolParams { environmentClassId, projectId, desiredSize, 2 more }

environmentClassId: string

environment_class_id specifies which environment class to warm. Must be listed in the project’s prebuild configuration environment_class_ids.

formatuuid

projectId: string

project_id specifies the project this warm pool belongs to. The project must have prebuilds enabled.

formatuuid

DeprecateddesiredSize?: number

desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling.

formatint32

maximum20

minimum1

maxSize?: number | null

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?: number | null

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

ReturnsExpand Collapse

PrebuildCreateWarmPoolResponse { warmPool }

warmPool: WarmPool { metadata, spec, status, id }

WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per <project, environment_class> pair.

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?: string

environment_class_id is the environment class whose instances are warmed

formatuuid

organizationId?: string

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

formatuuid

projectId?: string

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

formatuuid

runnerId?: 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?: 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?: 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?: number | null

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?: number | null

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?: string | null

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?: 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?: 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?: string

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

runningInstances?: number

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

formatint32

statusVersion?: string

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

stoppedInstances?: 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?: string

id is the unique identifier for the warm pool

formatuuid

CreateWarmPool

import Gitpod from '@gitpod/sdk';

const client = new Gitpod({
  bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted
});

const response = await client.prebuilds.createWarmPool({
  environmentClassId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68',
  projectId: 'b0e12f6c-4c67-429d-a4a6-d9838b5da047',
  desiredSize: 2,
});

console.log(response.warmPool);

{
  "warmPool": {
    "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

{
  "warmPool": {
    "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"
  }
}