## UpdateWarmPool

**post** `/gitpod.v1.PrebuildService/UpdateWarmPool`

Updates a warm pool's configuration.

Use this method to change the desired pool size.

### Examples

- Update pool size:

  ```yaml
  warmPoolId: "a1b2c3d4-5678-9abc-def0-1234567890ab"
  desiredSize: 5
  ```

### Body Parameters

- `warmPoolId: string`

  warm_pool_id specifies the warm pool to update

- `desiredSize: optional number`

  desired_size updates the number of warm instances to maintain.
  Deprecated: Use min_size and max_size instead for dynamic scaling.

- `maxSize: optional number`

  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.

- `minSize: optional number`

  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.

### Returns

- `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: 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/UpdateWarmPool \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "warmPoolId": "a1b2c3d4-5678-9abc-def0-1234567890ab"
        }'
```

#### 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"
  }
}
```