## CreateWarmPool **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 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. ```yaml projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" desiredSize: 2 ``` ### Body Parameters - `environmentClassId: string` environment_class_id specifies which environment class to warm. Must be listed in the project's prebuild configuration environment_class_ids. - `projectId: string` project_id specifies the project this warm pool belongs to. The project must have prebuilds enabled. - `desiredSize: optional number` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. - `maxSize: optional number` 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. - `minSize: optional number` 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. ### Returns - `warmPool: WarmPool` WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per pair. - `metadata: WarmPoolMetadata` metadata contains organizational and ownership information - `createdAt: string` created_at is when the warm pool was created - `updatedAt: string` updated_at is when the warm pool was last updated - `environmentClassId: optional string` environment_class_id is the environment class whose instances are warmed - `organizationId: optional string` organization_id is the ID of the organization that owns the warm pool - `projectId: optional string` project_id is the ID of the project this warm pool belongs to - `runnerId: optional string` runner_id is the runner that manages this warm pool. Derived from the environment class. - `spec: WarmPoolSpec` spec contains the desired configuration for this warm pool - `desiredPhase: optional WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `"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: optional 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. - `maxSize: optional number` 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. - `minSize: optional number` 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. - `snapshotId: optional string` 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. - `specVersion: optional string` 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 - `desiredSize: optional 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. - `failureMessage: optional string` failure_message contains details about why the warm pool is degraded or failed - `runningInstances: optional number` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `statusVersion: optional string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stoppedInstances: optional 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. - `id: optional string` id is the unique identifier for the warm pool ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/CreateWarmPool \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "environmentClassId": "d2c94c27-3b76-4a42-b88c-95a85e392c68", "projectId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047" }' ``` #### Response ```json { "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" } } ```