CreateWarmPool

client.Prebuilds.NewWarmPool(ctx, body) (*PrebuildNewWarmPoolResponse, error)

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 PrebuildNewWarmPoolParams

EnvironmentClassID param.Field[string]

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

formatuuid

ProjectID param.Field[string]

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

formatuuid

DeprecatedDesiredSize param.Field[int64]Optional

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 param.Field[int64]Optional

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 param.Field[int64]Optional

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

type PrebuildNewWarmPoolResponse struct{…}

WarmPool WarmPool

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

metadata contains organizational and ownership information

CreatedAt Time

created_at is when the warm pool was created

formatdate-time

UpdatedAt Time

updated_at is when the warm pool was last updated

formatdate-time

EnvironmentClassID stringOptional

environment_class_id is the environment class whose instances are warmed

formatuuid

OrganizationID stringOptional

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

formatuuid

ProjectID stringOptional

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

formatuuid

RunnerID stringOptional

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

formatuuid

Spec WarmPoolSpec

spec contains the desired configuration for this warm pool

DesiredPhase WarmPoolPhaseOptional

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

One of the following:

const WarmPoolPhaseUnspecified WarmPoolPhase = "WARM_POOL_PHASE_UNSPECIFIED"

const WarmPoolPhasePending WarmPoolPhase = "WARM_POOL_PHASE_PENDING"

const WarmPoolPhaseReady WarmPoolPhase = "WARM_POOL_PHASE_READY"

const WarmPoolPhaseDegraded WarmPoolPhase = "WARM_POOL_PHASE_DEGRADED"

const WarmPoolPhaseDeleting WarmPoolPhase = "WARM_POOL_PHASE_DELETING"

const WarmPoolPhaseDeleted WarmPoolPhase = "WARM_POOL_PHASE_DELETED"

DeprecatedDesiredSize int64Optional

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 int64Optional

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 int64Optional

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 stringOptional

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 stringOptional

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

Status WarmPoolStatus

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:

const WarmPoolPhaseUnspecified WarmPoolPhase = "WARM_POOL_PHASE_UNSPECIFIED"

const WarmPoolPhasePending WarmPoolPhase = "WARM_POOL_PHASE_PENDING"

const WarmPoolPhaseReady WarmPoolPhase = "WARM_POOL_PHASE_READY"

const WarmPoolPhaseDegraded WarmPoolPhase = "WARM_POOL_PHASE_DEGRADED"

const WarmPoolPhaseDeleting WarmPoolPhase = "WARM_POOL_PHASE_DELETING"

const WarmPoolPhaseDeleted WarmPoolPhase = "WARM_POOL_PHASE_DELETED"

DesiredSize int64Optional

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 stringOptional

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

RunningInstances int64Optional

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

formatint32

StatusVersion stringOptional

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

StoppedInstances int64Optional

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 stringOptional

id is the unique identifier for the warm pool

formatuuid

CreateWarmPool

package main

import (
  "context"
  "fmt"

  "github.com/gitpod-io/gitpod-sdk-go"
  "github.com/gitpod-io/gitpod-sdk-go/option"
)

func main() {
  client := gitpod.NewClient(
    option.WithBearerToken("My Bearer Token"),
  )
  response, err := client.Prebuilds.NewWarmPool(context.TODO(), gitpod.PrebuildNewWarmPoolParams{
    EnvironmentClassID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"),
    ProjectID: gitpod.F("b0e12f6c-4c67-429d-a4a6-d9838b5da047"),
    DesiredSize: gitpod.F(int64(2)),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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"
  }
}