Skip to content
Ona API Reference
Ona Docs
API Reference
Prebuilds

ListWarmPools

client.Prebuilds.ListWarmPools(ctx, params) (*WarmPoolsPage[WarmPool], error)
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"]
ParametersExpand Collapse
params PrebuildListWarmPoolsParams
Token param.Field[string]Optional

Query param

PageSize param.Field[int64]Optional

Query param

maximum100
minimum0
Filter param.Field[PrebuildListWarmPoolsParamsFilter]Optional

Body param: filter contains the filter options for listing warm pools

EnvironmentClassIDs []stringOptional

environment_class_ids filters warm pools to specific environment classes

ProjectIDs []stringOptional

project_ids filters warm pools to specific projects

ReturnsExpand Collapse
type WarmPool struct{…}

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

ListWarmPools

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"),
  )
  page, err := client.Prebuilds.ListWarmPools(context.TODO(), gitpod.PrebuildListWarmPoolsParams{
    Filter: gitpod.F(gitpod.PrebuildListWarmPoolsParamsFilter{
      ProjectIDs: gitpod.F([]string{"b0e12f6c-4c67-429d-a4a6-d9838b5da047"}),
    }),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}

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