Unary · Prebuilds
Updates a warm pool’s configuration.
Use this method to change the desired pool size.
Examples
-
Update pool size:
warmPoolId: "a1b2c3d4-5678-9abc-def0-1234567890ab" desiredSize: 5
Endpoint
POST /api/gitpod.v1.PrebuildService/UpdateWarmPool
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/UpdateWarmPool" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"warmPoolId": "<warm-pool-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.UpdateWarmPoolRequest(
warm_pool_id="<warm-pool-id>",
)
response = ona.services.prebuild.update_warm_pool(request)
print(response)
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { UpdateWarmPoolRequestSchema } from "@gitpod/sdk/gitpod/v1/prebuild_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(UpdateWarmPoolRequestSchema, {
warmPoolId: "<warm-pool-id>",
});
const response = await ona.services.prebuild.updateWarmPool(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.UpdateWarmPoolRequest{
WarmPoolId: "<warm-pool-id>",
})
response, err := ona.Services.Prebuild.UpdateWarmPool(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
{
"warmPoolId": "<warm-pool-id>"
}
Request
gitpod.v1.UpdateWarmPoolRequest
| Field | Type | Required | Description |
|---|---|---|---|
warmPoolId | string | Yes | warm_pool_id specifies the warm pool to update Constraints: required=true, string.uuid=true. |
desiredSize | integer | No | Deprecated. desired_size updates the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Constraints: int32.gte=1, int32.lte=20. |
minSize | integer | No | min_size updates 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 updates 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.UpdateWarmPoolResponse
| Field | Type | Required | Description |
|---|---|---|---|
warmPool | WarmPool | Yes | Constraints: required=true. |
Related types
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.
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
WarmPoolMetadata contains metadata about the warm pool
gitpod.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
WarmPoolSpec contains the desired configuration for a warm pool
gitpod.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
WarmPoolStatus contains the current status of a warm pool as reported by the runner
gitpod.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
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 |