Create Warm Pool

Unary · Prebuilds 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

Endpoint

POST /api/gitpod.v1.PrebuildService/CreateWarmPool

Send a Bearer token as described in Authentication. If your organization uses a custom management-plane domain, replace https://app.ona.com with that domain.

Request example

export ONA_HOST=https://app.ona.com
export ONA_API_KEY=<your-token>

curl --request POST \
  --url "$ONA_HOST/api/gitpod.v1.PrebuildService/CreateWarmPool" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "environmentClassId": "<environment-class-id>",
  "projectId": "<project-id>"
}'

import gitpod.v1.prebuild_pb2 as prebuild_pb2
from ona_sdk import create_client_from_env

ona = create_client_from_env()
request = prebuild_pb2.CreateWarmPoolRequest(
    project_id="<project-id>",
    environment_class_id="<environment-class-id>",
)
response = ona.services.prebuild.create_warm_pool(request)
print(response)

import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { CreateWarmPoolRequestSchema } from "@gitpod/sdk/gitpod/v1/prebuild_pb";

async function main() {
  const ona = createClientFromEnv();
  const request = create(CreateWarmPoolRequestSchema, {
    projectId: "<project-id>",
    environmentClassId: "<environment-class-id>",
  });
  const response = await ona.services.prebuild.createWarmPool(request);
  console.log(response);
}

main().catch(console.error);

package main

import (
	"context"
	"fmt"
	"log"

	"connectrpc.com/connect"
	"github.com/gitpod-io/gitpod-sdk-go/sdk"
	gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
)

func main() {
	ona, err := sdk.NewFromEnv()
	if err != nil {
		log.Fatal(err)
	}

	request := connect.NewRequest(&gitpodpb.CreateWarmPoolRequest{
		ProjectId: "<project-id>",
		EnvironmentClassId: "<environment-class-id>",
	})
	response, err := ona.Services.Prebuild.CreateWarmPool(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}

{
  "environmentClassId": "<environment-class-id>",
  "projectId": "<project-id>"
}

Request

gitpod.v1.CreateWarmPoolRequest

Field	Type	Required	Description
`projectId`	string	Yes	project_id specifies the project this warm pool belongs to. The project must have prebuilds enabled. Constraints: `required=true, string.uuid=true`.
`environmentClassId`	string	Yes	environment_class_id specifies which environment class to warm. Must be listed in the project’s prebuild configuration environment_class_ids. Constraints: `required=true, string.uuid=true`.
`desiredSize`	integer	No	Deprecated. desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Constraints: `ignore=1, int32.gte=1, int32.lte=20`.
`minSize`	integer	No	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. Constraints: `int32.gte=0, int32.lte=20`.
`maxSize`	integer	No	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. Constraints: `int32.gte=1, int32.lte=20`.

Response

gitpod.v1.CreateWarmPoolResponse

Field	Type	Required	Description
`warmPool`	WarmPool	Yes	Constraints: `required=true`.

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.gitpod.v1.WarmPool

Field	Type	Required	Description
`id`	string	No	id is the unique identifier for the warm pool Constraints: `string.uuid=true`.
`metadata`	WarmPoolMetadata	Yes	metadata contains organizational and ownership information Constraints: `required=true`.
`spec`	WarmPoolSpec	Yes	spec contains the desired configuration for this warm pool Constraints: `required=true`.
`status`	WarmPoolStatus	Yes	status contains the current status reported by the runner Constraints: `required=true`.

WarmPoolMetadata

WarmPoolMetadata contains metadata about the warm poolgitpod.v1.WarmPoolMetadata

Field	Type	Required	Description
`organizationId`	string	No	organization_id is the ID of the organization that owns the warm pool Constraints: `string.uuid=true`.
`projectId`	string	No	project_id is the ID of the project this warm pool belongs to Constraints: `string.uuid=true`.
`environmentClassId`	string	No	environment_class_id is the environment class whose instances are warmed Constraints: `string.uuid=true`.
`runnerId`	string	No	runner_id is the runner that manages this warm pool. Derived from the environment class. Constraints: `string.uuid=true`.
`createdAt`	RFC 3339 timestamp	Yes	created_at is when the warm pool was created Constraints: `required=true`.
`updatedAt`	RFC 3339 timestamp	Yes	updated_at is when the warm pool was last updated Constraints: `required=true`.

WarmPoolSpec

WarmPoolSpec contains the desired configuration for a warm poolgitpod.v1.WarmPoolSpec

Field	Type	Required	Description
`specVersion`	64-bit integer string	No	spec_version is incremented each time the spec is updated. Used for optimistic concurrency control.
`desiredSize`	integer	No	Deprecated. 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. Constraints: `ignore=1, int32.gte=1, int32.lte=20`.
`snapshotId`	string	No	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. Constraints: `ignore=1, string.uuid=true`.
`desiredPhase`	WarmPoolPhase	No	desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. Constraints: `enum.defined_only=true`.
`minSize`	integer	No	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. Constraints: `int32.gte=0, int32.lte=20`.
`maxSize`	integer	No	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. Constraints: `int32.gte=1, int32.lte=20`.

WarmPoolStatus

WarmPoolStatus contains the current status of a warm pool as reported by the runnergitpod.v1.WarmPoolStatus

Field	Type	Required	Description
`phase`	WarmPoolPhase	Yes	phase is the current phase of the warm pool lifecycle Constraints: `enum.defined_only=true, required=true`.
`failureMessage`	string	No	failure_message contains details about why the warm pool is degraded or failed
`statusVersion`	64-bit integer string	No	status_version is incremented each time the status is updated. Used for optimistic concurrency control.
`runningInstances`	integer	No	running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup.
`stoppedInstances`	integer	No	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.
`desiredSize`	integer	No	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.

WarmPoolPhase

WarmPoolPhase represents the lifecycle phase of a warm pool

Value	Number	Description
`WARM_POOL_PHASE_UNSPECIFIED`	0	WARM_POOL_PHASE_UNSPECIFIED is the default value and should not be used
`WARM_POOL_PHASE_PENDING`	10	WARM_POOL_PHASE_PENDING indicates the warm pool has been created but no snapshot is assigned yet
`WARM_POOL_PHASE_READY`	20	WARM_POOL_PHASE_READY indicates the runner has acknowledged the pool and instances are available
`WARM_POOL_PHASE_DEGRADED`	30	WARM_POOL_PHASE_DEGRADED indicates the runner reported a problem with the pool
`WARM_POOL_PHASE_DELETING`	40	WARM_POOL_PHASE_DELETING indicates the warm pool is being deleted and instances are draining
`WARM_POOL_PHASE_DELETED`	50	WARM_POOL_PHASE_DELETED indicates the warm pool has been fully cleaned up

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Examples

Endpoint

Request example

Request

Response

​Examples

​Endpoint

​Request example

​Request

​Response

​Related types

Examples

Endpoint

Request example

Request

Response

Related types