--- updatedAt: 2026-08-10T08:34:59.000Z agentTools: projectIndex: https://docs.cast.ai/llms.txt --- # Lists rebalancing plans for a cluster. Lists rebalancing plans for a cluster. # OpenAPI definition ```json { "openapi": "3.0.3", "servers": [ { "url": "https://api.cast.ai/", "description": "US endpoint" }, { "url": "https://api.eu.cast.ai/", "description": "EU endpoint" } ], "info": { "title": "Kent", "version": "0.0.1" }, "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "paths": { "/kent/v1alpha/organizations/{organizationId}/clusters/{clusterId}/rebalancing-plans": { "get": { "tags": [ "RebalancingAPI" ], "summary": "Lists rebalancing plans for a cluster.", "description": "Lists rebalancing plans for a cluster.", "operationId": "RebalancingAPI_ListRebalancingPlans", "parameters": [ { "name": "organizationId", "in": "path", "description": "The ID of the Organization.", "required": true, "schema": { "type": "string" } }, { "name": "clusterId", "in": "path", "description": "The ID of the cluster.", "required": true, "schema": { "type": "string" } }, { "name": "page.limit", "in": "query", "description": "Defines the number of items that should be returned", "schema": { "type": "string" } }, { "name": "page.cursor", "in": "query", "description": "Cursor that defines token indicating where to start the next page.\n Empty value indicates to start from beginning of the dataset.", "schema": { "type": "string" } }, { "name": "statusFilter", "in": "query", "description": "Filter plans by status (optional).\n If empty, all statuses are returned.", "schema": { "type": "array", "items": { "enum": [ "REBALANCING_PLAN_STATUS_UNSPECIFIED", "GENERATING", "READY", "EXECUTING", "COMPLETED", "FAILED", "CANCELED", "PARTIALLY_COMPLETED", "STALE", "SKIPPED", "EXPIRED" ], "type": "string", "format": "enum" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRebalancingPlansResponse" } } } }, "default": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "AggressiveModeConfig": { "type": "object", "properties": { "ignoreLocalPersistentVolumes": { "type": "boolean", "description": "Rebalance workloads that use local-path Persistent Volumes.\n WARNING: THIS WILL RESULT IN DATA LOSS." }, "ignoreProblemJobPods": { "type": "boolean", "description": "Pods spawned by Jobs or CronJobs will not prevent the Rebalancer from deleting a node on which they run.\n WARNING: When true, pods spawned by Jobs or CronJobs will be terminated if the Rebalancer picks a node that runs them.\n As such, they are likely to lose their progress." }, "ignoreProblemRemovalDisabledPods": { "type": "boolean", "description": "Pods that are marked with \"removal disabled\" will not prevent the Rebalancer from deleting a node on which they run.\n WARNING: When true, such pods will be evicted and disrupted." }, "ignoreProblemPodsWithoutController": { "type": "boolean", "description": "Pods that don't have a controller (bare pods) will not prevent the Rebalancer from deleting a node on which they run.\n WARNING: When true, such pods might not restart, since they have no controller to do it." }, "ignoreInstanceCriteria": { "type": "boolean", "description": "Ignore instance criteria constraints from node pools during rebalancing.\n When true, removes requirements that constrain instance types by name patterns\n (instance-category, instance-family, instance-generation, instance-size, instance-cpu, instance-memory).\n This allows the rebalancer to select from a broader range of instance types." }, "aggressiveEviction": { "type": "boolean", "description": "Use aggressive eviction of NodeClaims which could block rebalancing plan execution\n When true, NodeClaims and pods on them will be forcefully deleted after a default or specified\n time interval has passed" }, "drainTimeoutSeconds": { "type": "string", "description": "drain_timeout_seconds specifies the maximum time allowed for draining nodes during aggressive eviction.\n OPTIONAL: If not specified (0), nodes drain indefinitely (graceful drain).\n When specified, valid range: 60-3600 seconds (1 minute to 1 hour).\n (-- api-linter: core::0142::time-field-type=disabled\n aip.dev/not-precedent: Using plain int64 seconds for simpler REST API client usage. --)" }, "ignoreBlockingPdb": { "type": "boolean", "description": "Ignore pods blocked by PodDisruptionBudgets with 0 disruptions allowed.\n WARNING: May violate PDB guarantees during eviction." }, "ignoreZeroNodePoolDisruptionBudgets": { "type": "boolean", "description": "Ignore NodePool disruption budgets that allow 0 disruptions.\n When true, overrides zero-disruption NodePool budgets with the default 10% safety budget\n so rebalancing can proceed.\n WARNING: May violate NodePool disruption budget guarantees." }, "ignoreProblemRemovalDisabledNodes": { "type": "boolean", "description": "Nodes that are marked with \"removal disabled\" or \"do-not-disrupt\" annotations/labels\n will not prevent the Rebalancer from deleting them.\n WARNING: When true, such nodes will be disrupted despite their protection annotations." }, "ignoreConsolidatable": { "type": "boolean", "description": "When true, bypasses the Karpenter Consolidatable condition check during node\n candidate selection. Nodes that Karpenter has not yet marked as consolidatable\n (e.g. the ConsolidateAfter time window has not elapsed) will still be considered\n for rebalancing.\n WARNING: May disrupt nodes before Karpenter's own consolidation timing." }, "ignoreBlockingPdbTimeout": { "pattern": "^-?(?:0|[1-9][0-9]{0,11})(?:\\.[0-9]{1,9})?s$", "type": "string", "description": "ignore_blocking_pdb_timeout specifies how long to wait before force-deleting PDB-blocked pods.\n OPTIONAL: If not specified, defaults to 10m. When specified, must be a positive duration.\n (-- api-linter: core::0142::time-field-type=disabled\n aip.dev/not-precedent: Using google.protobuf.Duration for consistency with kentroller proto. --)" }, "ignoreProblemRemovalDisabledPodsTimeout": { "pattern": "^-?(?:0|[1-9][0-9]{0,11})(?:\\.[0-9]{1,9})?s$", "type": "string", "description": "ignore_problem_removal_disabled_pods_timeout specifies how long to wait before force-deleting\n pods marked karpenter.sh/do-not-disrupt=true on nodes being drained by a rebalancing plan.\n OPTIONAL: If not specified, defaults to 10m. When specified, must be a positive duration.\n (-- api-linter: core::0142::time-field-type=disabled\n aip.dev/not-precedent: Using google.protobuf.Duration for consistency with kentroller proto. --)" } }, "description": "Advanced configuration for aggressive rebalancing mode.\n Provides granular control over which types of problematic pods can be rebalanced." }, "Configuration_FailedNode": { "type": "object", "properties": { "name": { "readOnly": true, "type": "string", "description": "The name of the node (Kubernetes node name)." }, "attempts": { "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/FailedNode_FailedAttempt" }, "description": "Per-attempt failure records." } }, "description": "Describes a node that failed to provision, with per-attempt failure reasons." }, "Configuration_Node": { "type": "object", "properties": { "instanceType": { "readOnly": true, "type": "string", "description": "The instance type of this node." }, "milliCpu": { "readOnly": true, "type": "integer", "description": "Milli CPU capacity of this node.", "format": "int32" }, "memoryMib": { "readOnly": true, "type": "integer", "description": "Memory capacity of this node in MiBs.", "format": "int32" }, "isSpot": { "readOnly": true, "type": "boolean", "description": "Whether this node is a spot instance.\n (-- api-linter: core::0122::boolean-name-prefix=disabled\n aip.dev/not-precedent: Matches autoscaler proto naming. --)" }, "priceHourly": { "readOnly": true, "type": "string", "description": "The hourly price of this node in $ currency." }, "name": { "readOnly": true, "type": "string", "description": "The name of this node (Kubernetes node name), if known." } }, "description": "Defines a single node in the configuration." }, "Configurations": { "type": "object", "properties": { "blue": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Configurations_Configuration" } ], "description": "Blue configuration, i.e. legacy." }, "green": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Configurations_Configuration" } ], "description": "Green configuration, i.e. new rebalanced cluster." }, "diff": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Configurations_Diff" } ], "description": "Difference between the blue and green configurations." }, "achievedDiff": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Configurations_Diff" } ], "description": "The achieved difference between the blue configuration and the created configuration." }, "achieved": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Configurations_ConfigurationTotals" } ], "description": "Scoped and cluster level totals summary of created configuration." }, "recommendations": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Configurations_Recommendations" } ], "description": "Recommendations contains information about resource recommendations which impact rebalancing." } }, "description": "Defines the cluster rebalancing plan configurations." }, "Configurations_Configuration": { "type": "object", "properties": { "nodes": { "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/Configuration_Node" }, "description": "A list of node in this configuration." }, "totals": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Configurations_Totals" } ], "description": "Precalculated totals of the affected nodes of this configuration." }, "clusterTotals": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Configurations_Totals" } ], "description": "Precalculated totals of the whole cluster of this configuration." }, "failedNodes": { "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/Configuration_FailedNode" }, "description": "Nodes that failed to provision (e.g. due to InsufficientCapacityError), if any." } }, "description": "Defines a single rebalancing plan configuration." }, "Configurations_ConfigurationTotals": { "type": "object", "properties": { "affectedNodeTotals": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Configurations_Totals" } ], "description": "Precalculated totals of the affected nodes of this configuration." }, "clusterTotals": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Configurations_Totals" } ], "description": "Precalculated totals of the whole cluster of this configuration." } }, "description": "Contains affected and cluster node aggregated calculations." }, "Configurations_Diff": { "type": "object", "properties": { "priceHourly": { "readOnly": true, "type": "string", "description": "Hourly price difference between blue and green node configurations in $ currency." }, "priceMonthly": { "readOnly": true, "type": "string", "description": "Monthly price difference between blue and green node configurations in $ currency." }, "savingsPercentage": { "readOnly": true, "type": "string", "description": "Savings percentage achieved by rebalancing the selected nodes." }, "clusterSavingsPercentage": { "readOnly": true, "type": "string", "description": "Saving percentage achieved by rebalancing the selected nodes for the whole cluster." } }, "description": "Defines the difference between blue and green node configurations." }, "Configurations_Recommendations": { "type": "object", "properties": { "applied": { "readOnly": true, "type": "boolean", "description": "Applied indicates whether recommendations (e.g. WOOP) impacts rebalancing" } }, "description": "Recommendations contains information about resource recommendations which impact rebalancing." }, "Configurations_Totals": { "type": "object", "properties": { "nodes": { "readOnly": true, "type": "integer", "description": "Count of nodes in this configuration.", "format": "int32" }, "replaceableNodes": { "readOnly": true, "type": "integer", "description": "Count of nodes which can be replaced in this configuration.", "format": "int32" }, "migratablePods": { "readOnly": true, "type": "integer", "description": "Count of pods which can be migrated. They come from replaceable nodes.", "format": "int32" }, "milliCpu": { "readOnly": true, "type": "integer", "description": "Total milli CPU capacity of this configuration.", "format": "int32" }, "memoryMib": { "readOnly": true, "type": "integer", "description": "Total memory capacity of this configuration in MiBs.", "format": "int32" }, "priceHourly": { "readOnly": true, "type": "string", "description": "Total hourly price of this configuration in $ currency." }, "priceMonthly": { "readOnly": true, "type": "string", "description": "Total monthly price of this configuration in $ currency." }, "pods": { "readOnly": true, "type": "integer", "description": "Total number of pods in this configuration.", "format": "int32" }, "problematicPods": { "readOnly": true, "type": "integer", "description": "Total number of problematic pods in this configuration.", "format": "int32" } }, "description": "Defines the totals of a single configuration." }, "ExecutionProgress": { "type": "object", "properties": { "nodesCreated": { "readOnly": true, "type": "integer", "description": "nodes_created is the number of new nodes successfully provisioned.", "format": "int32" }, "nodesToCreate": { "readOnly": true, "type": "integer", "description": "nodes_to_create is the total number of nodes that need to be created.", "format": "int32" }, "nodesDeleted": { "readOnly": true, "type": "integer", "description": "nodes_deleted is the number of old nodes successfully deleted.", "format": "int32" }, "nodesToDelete": { "readOnly": true, "type": "integer", "description": "nodes_to_delete is the total number of nodes that need to be deleted.", "format": "int32" }, "nodesDrained": { "readOnly": true, "type": "integer", "description": "nodes_drained is the number of nodes that have been drained.", "format": "int32" }, "nodesToDrain": { "readOnly": true, "type": "integer", "description": "nodes_to_drain is the total number of nodes that need to be drained (same as nodes_to_delete).", "format": "int32" }, "nodePoolBudgets": { "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/NodePoolBudgetInfo" }, "description": "node_pool_budgets captures per-NodePool NPDB budget state for pools that\n have nodes in this plan's NodeClaimsToDelete. Display-only context." }, "budgetWaitState": { "readOnly": true, "enum": [ "BUDGET_WAIT_STATE_UNSPECIFIED", "BUDGET_WAIT_STATE_AVAILABLE", "BUDGET_WAIT_STATE_BLOCKED" ], "type": "string", "description": "budget_wait_state is the primary UI signal: whether execution is blocked\n by exhausted NPDB budgets. Derived from node_pool_budgets.", "format": "enum" } }, "description": "ExecutionProgress tracks per-node operation counts during plan execution." }, "FailedNode_FailedAttempt": { "type": "object", "properties": { "instanceType": { "readOnly": true, "type": "string", "description": "The instance type attempted." }, "description": { "readOnly": true, "type": "string", "description": "Human-readable failure description (e.g. \"InsufficientCapacityError\")." } }, "description": "A single provisioning attempt that failed." }, "GoogleProtobufAny": { "type": "object", "properties": { "@type": { "type": "string", "description": "The type of the serialized message." } }, "additionalProperties": true, "description": "Contains an arbitrary serialized message along with a @type that describes the type of the serialized message." }, "ListRebalancingPlansResponse": { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/RebalancingPlan" }, "description": "List of rebalancing plans." }, "nextPageCursor": { "type": "string", "description": "Cursor for retrieving the next page of results." } }, "description": "Response containing a list of rebalancing plans." }, "NodePoolBudgetInfo": { "type": "object", "properties": { "nodePoolName": { "readOnly": true, "type": "string", "description": "The metadata.name of the Karpenter NodePool." }, "totalNodes": { "readOnly": true, "type": "integer", "description": "Count of initialized, non-terminating nodes in the pool.", "format": "int32" }, "allowedDisruptions": { "readOnly": true, "type": "integer", "description": "NPDB budget limit for this pool.", "format": "int32" }, "disruptingCount": { "readOnly": true, "type": "integer", "description": "Number of nodes already being disrupted.", "format": "int32" }, "remainingDisruptions": { "readOnly": true, "type": "integer", "description": "AllowedDisruptions - DisruptingCount, clamped to >= 0. When 0, budget exhausted.", "format": "int32" } }, "description": "NodePoolBudgetInfo captures the NPDB budget state for a single NodePool\n during rebalancing plan deletion phase." }, "RebalancingError": { "type": "object", "properties": { "code": { "readOnly": true, "enum": [ "REBALANCING_ERROR_CODE_UNSPECIFIED", "GENERATION_FAILED", "UPSCALING_FAILED", "NODE_DRAIN_FAILED", "NODE_CREATE_FAILED", "NODE_PREPARE_FAILED", "NODE_DELETE_FAILED", "TIMEOUT", "INSUFFICIENT_SAVINGS", "UNKNOWN", "INSUFFICIENT_CAPACITY", "OPERATION_CANCELED", "QUOTA_EXCEEDED" ], "type": "string", "description": "The error code categorizing the error.", "format": "enum" }, "message": { "readOnly": true, "type": "string", "description": "Human-readable error message." }, "affectedResource": { "readOnly": true, "type": "string", "description": "Optional identifier of the affected resource (node ID, pod name, etc.)." } }, "description": "Represents an error that occurred during rebalancing." }, "RebalancingNode": { "type": "object", "properties": { "nodeName": { "type": "string", "description": "Node name to rebalance" } }, "description": "Represents a node to be rebalanced." }, "RebalancingPlan": { "type": "object", "properties": { "id": { "readOnly": true, "type": "string", "description": "The unique identifier of the rebalancing plan." }, "organizationId": { "readOnly": true, "type": "string", "description": "The ID of the organization." }, "clusterId": { "readOnly": true, "type": "string", "description": "The ID of the cluster being rebalanced." }, "status": { "readOnly": true, "enum": [ "REBALANCING_PLAN_STATUS_UNSPECIFIED", "GENERATING", "READY", "EXECUTING", "COMPLETED", "FAILED", "CANCELED", "PARTIALLY_COMPLETED", "STALE", "SKIPPED", "EXPIRED" ], "type": "string", "description": "The current status of the rebalancing plan.", "format": "enum" }, "createTime": { "readOnly": true, "type": "string", "description": "Timestamp when the plan was created.", "format": "date-time" }, "updateTime": { "readOnly": true, "type": "string", "description": "Timestamp when the plan was last updated.", "format": "date-time" }, "executeTime": { "readOnly": true, "type": "string", "description": "Timestamp when the plan execution started.", "format": "date-time" }, "completeTime": { "readOnly": true, "type": "string", "description": "Timestamp when the plan execution completed.", "format": "date-time" }, "errors": { "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/RebalancingError" }, "description": "List of errors encountered during plan generation or execution." }, "configurations": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Configurations" } ], "description": "Configurations is the heart of the rebalancing plan: it contains the blue and green configurations and their difference." }, "rebalancingNodes": { "type": "array", "items": { "$ref": "#/components/schemas/RebalancingNode" }, "description": "List of nodes to rebalance." }, "scheduleName": { "readOnly": true, "type": "string", "description": "schedule_name is the name of the RebalancePlanSchedule that triggered this plan, if any." }, "executionProgress": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/ExecutionProgress" } ], "description": "execution_progress tracks per-node operation progress during plan execution." }, "warnings": { "readOnly": true, "type": "array", "items": { "$ref": "#/components/schemas/RebalancingWarning" }, "description": "warnings contains warnings from pod placement events during plan generation.\n Each entry corresponds to a pod that could not be placed." }, "aggressiveModeConfig": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/AggressiveModeConfig" } ], "description": "aggressive_mode_config is the aggressive rebalancing configuration that was used\n when generating this plan. Output only; reflects the settings from plan creation." }, "skippedReason": { "readOnly": true, "type": "string", "description": "skipped_reason is a machine-readable reason code for why the plan was skipped." }, "skippedMessage": { "readOnly": true, "type": "string", "description": "skipped_message is a human-readable message describing why the plan was skipped." } }, "description": "Represents a cluster rebalancing plan." }, "RebalancingWarning": { "type": "object", "properties": { "description": { "readOnly": true, "type": "string", "description": "Human-readable warning description." } }, "description": "RebalancingWarning represents a warning encountered during plan generation." }, "Status": { "type": "object", "properties": { "code": { "type": "integer", "description": "The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].", "format": "int32" }, "message": { "type": "string", "description": "A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client." }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/GoogleProtobufAny" }, "description": "A list of messages that carry the error details. There is a common set of message types for APIs to use." } }, "description": "The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors)." } } }, "tags": [ { "name": "RebalancingAPI", "description": "Provides an API to manage cluster rebalancing operations in Karpenter-managed clusters.\n This API simplifies the creation and management of rebalancing plans that optimize\n node configurations for cost and resource efficiency." } ] } ```