> ## Documentation Index > Fetch the complete documentation index at: https://www.latitude.sh/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update Kubernetes Cluster > Updates a Kubernetes cluster by scaling nodes or upgrading the Kubernetes version. The cluster must be in `Provisioned` phase to accept updates. ## Scaling Operations Exactly one of `worker_count` or `control_plane_count` must be provided per request. You cannot scale workers and control plane nodes in the same request. When scaling up, the API validates that sufficient server stock is available for the requested delta (e.g., scaling from 2 to 5 workers checks for 3 available servers). When scaling from 0 workers, you must provide a `worker_plan` since there is no existing configuration to inherit the plan from. Control plane scaling has a minimum of 1 node. You cannot scale control plane nodes to zero. ## Version Upgrades Provide a `kubernetes_version` parameter to upgrade the cluster to a new Kubernetes version. Version upgrades follow these rules: - **No downgrades**: You cannot downgrade to a lower version than currently installed - **One minor version at a time**: You can only upgrade one minor version at a time (e.g., from 1.34 to 1.35, not from 1.34 to 1.36) - **Mutually exclusive**: Version upgrades cannot be combined with scaling operations in the same request - **Available versions only**: The target version must be in the list returned by `GET /kubernetes_clusters/available_versions` Returns 202 Accepted when an update operation is triggered. Poll the GET endpoint to monitor progress. Returns 200 OK if no change is needed (no-op). ## OpenAPI ````yaml https://spec.speakeasy.com/latitude/latitude/latitude-sh-api-with-code-samples patch /kubernetes_clusters/{kubernetes_cluster_id} openapi: 3.0.1 info: title: Latitude.sh API version: '2023-06-01' description: >- The Latitude.sh API is a RESTful API to manage your Latitude.sh account. It allows you to perform the same actions as the Latitude.sh dashboard. servers: - url: https://api.latitude.sh variables: latitude_api_key: default: - url: http://api.latitude.sh variables: latitude_api_key: default: security: [] tags: - name: API keys - name: Billing - name: Elastic Ips - name: Events - name: Firewalls - name: IP Addresses - name: Kubernetes Clusters - name: Operating Systems - name: Plans - name: Private Networks - name: Projects - name: Regions - name: Roles - name: SSH Keys - name: Servers - name: Storage - name: Tags - name: Teams - name: Team members - name: Traffic - name: User data - name: User profile - name: VPN Sessions - name: Virtual machines paths: /kubernetes_clusters/{kubernetes_cluster_id}: patch: tags: - Kubernetes Clusters summary: Update Kubernetes Cluster description: > Updates a Kubernetes cluster by scaling nodes or upgrading the Kubernetes version. The cluster must be in `Provisioned` phase to accept updates. ## Scaling Operations Exactly one of `worker_count` or `control_plane_count` must be provided per request. You cannot scale workers and control plane nodes in the same request. When scaling up, the API validates that sufficient server stock is available for the requested delta (e.g., scaling from 2 to 5 workers checks for 3 available servers). When scaling from 0 workers, you must provide a `worker_plan` since there is no existing configuration to inherit the plan from. Control plane scaling has a minimum of 1 node. You cannot scale control plane nodes to zero. ## Version Upgrades Provide a `kubernetes_version` parameter to upgrade the cluster to a new Kubernetes version. Version upgrades follow these rules: - **No downgrades**: You cannot downgrade to a lower version than currently installed - **One minor version at a time**: You can only upgrade one minor version at a time (e.g., from 1.34 to 1.35, not from 1.34 to 1.36) - **Mutually exclusive**: Version upgrades cannot be combined with scaling operations in the same request - **Available versions only**: The target version must be in the list returned by `GET /kubernetes_clusters/available_versions` Returns 202 Accepted when an update operation is triggered. Poll the GET endpoint to monitor progress. Returns 200 OK if no change is needed (no-op). operationId: update-kubernetes-cluster parameters: - name: kubernetes_cluster_id in: path required: true description: >- The cluster ID (format: kc_) or cluster name. Both formats are accepted for backward compatibility. schema: type: string requestBody: content: application/vnd.api+json: schema: $ref: '#/components/schemas/update_kubernetes_cluster' examples: ScaleWorkersUp: summary: Scale workers from 2 to 5 value: data: type: kubernetes_clusters attributes: worker_count: 5 ScaleWorkersDown: summary: Scale workers from 5 to 2 value: data: type: kubernetes_clusters attributes: worker_count: 2 ScaleWorkersFromZero: summary: Scale from 0 workers (requires worker_plan) value: data: type: kubernetes_clusters attributes: worker_count: 3 worker_plan: c3-small-x86 ScaleWorkersToZero: summary: Scale down to 0 workers value: data: type: kubernetes_clusters attributes: worker_count: 0 ScaleControlPlaneUp: summary: Scale control plane from 1 to 3 nodes value: data: type: kubernetes_clusters attributes: control_plane_count: 3 ScaleControlPlaneDown: summary: Scale control plane from 3 to 1 node value: data: type: kubernetes_clusters attributes: control_plane_count: 1 UpgradeVersion: summary: Upgrade Kubernetes version value: data: type: kubernetes_clusters attributes: kubernetes_version: v1.35.0+rke2r1 required: true responses: '200': description: OK - No change needed content: application/vnd.api+json: examples: WorkersUnchanged: summary: Worker count unchanged value: data: type: kubernetes_clusters id: kc_pRMLydp0dQKr1 attributes: name: my-cluster status: unchanged worker_count: 3 ControlPlaneUnchanged: summary: Control plane count unchanged value: data: type: kubernetes_clusters id: kc_pRMLydp0dQKr1 attributes: name: my-cluster status: unchanged control_plane_count: 3 schema: $ref: '#/components/schemas/kubernetes_cluster_update_response' '202': description: Accepted - Update operation started content: application/vnd.api+json: examples: ScalingWorkers: summary: Worker scaling in progress value: data: type: kubernetes_clusters id: kc_pRMLydp0dQKr1 attributes: name: my-cluster status: scaling worker_count: 5 ScalingControlPlane: summary: Control plane scaling in progress value: data: type: kubernetes_clusters id: kc_pRMLydp0dQKr1 attributes: name: my-cluster status: scaling control_plane_count: 3 UpgradingVersion: summary: Version upgrade in progress value: data: type: kubernetes_clusters id: kc_pRMLydp0dQKr1 attributes: name: my-cluster status: upgrading kubernetes_version: v1.35.0+rke2r1 schema: $ref: '#/components/schemas/kubernetes_cluster_update_response' '400': description: Bad Request content: application/vnd.api+json: examples: MissingParameter: summary: No update parameter provided value: errors: - code: VALIDATION_ERROR message: >- worker_count, control_plane_count, or kubernetes_version is required ScalingMutualExclusion: summary: Both worker_count and control_plane_count provided value: errors: - code: VALIDATION_ERROR message: >- cannot update control_plane_count and worker_count in the same request VersionWithScaling: summary: Version upgrade combined with scaling value: errors: - code: VALIDATION_ERROR message: >- cannot combine kubernetes_version with scaling operations InvalidWorkerCountType: value: errors: - code: VALIDATION_ERROR message: worker_count must be an integer InvalidControlPlaneCountType: summary: Control plane count is not an integer value: errors: - code: VALIDATION_ERROR message: control_plane_count must be an integer schema: $ref: '#/components/schemas/error_object' '403': description: Forbidden content: application/vnd.api+json: examples: InsufficientPermissions: value: errors: - code: FORBIDDEN message: You don't have permission to perform this action schema: $ref: '#/components/schemas/error_object' '404': description: Not Found content: application/vnd.api+json: examples: ClusterNotFound: value: errors: - code: NOT_FOUND message: Cluster my-cluster not found schema: $ref: '#/components/schemas/error_object' '422': description: Unprocessable Entity content: application/vnd.api+json: examples: ClusterNotReady: value: errors: - code: VALIDATION_ERROR message: >- Cluster must be in Provisioned phase to accept updates (current phase: Provisioning) InvalidWorkerCount: value: errors: - code: INVALID_WORKER_COUNT message: worker_count must be between 0 and 10 WorkerPlanRequired: value: errors: - code: WORKER_PLAN_REQUIRED message: worker_plan is required when scaling from 0 workers InvalidControlPlaneCount: summary: Control plane count below minimum value: errors: - code: VALIDATION_ERROR message: control_plane_count must be at least 1 InsufficientStock: value: errors: - code: INSUFFICIENT_STOCK message: >- No stock available of plan suitable for Kubernetes cluster VersionDowngrade: summary: Attempted to downgrade Kubernetes version value: errors: - code: VERSION_DOWNGRADE message: Cannot downgrade from v1.35.0+rke2r1 to v1.34.0+rke2r1 MinorVersionSkip: summary: Attempted to skip a minor version value: errors: - code: MINOR_VERSION_SKIP message: >- Cannot skip minor versions. Current: 1.34, target: 1.36. Upgrade to 1.35 first. VersionNotAvailable: summary: Target version not in available versions list value: errors: - code: VERSION_NOT_AVAILABLE message: Version v1.30.0+rke2r1 is not available for upgrade schema: $ref: '#/components/schemas/error_object' '503': description: Service Unavailable content: application/vnd.api+json: examples: ManagementClusterError: value: errors: - code: MANAGEMENT_CLUSTER_ERROR message: Failed to communicate with the management cluster schema: $ref: '#/components/schemas/error_object' security: - Bearer: [] x-codeSamples: - lang: python label: Python (SDK) source: |- import latitudesh_python_sdk from latitudesh_python_sdk import Latitudesh import os with Latitudesh( bearer=os.getenv("LATITUDESH_BEARER", ""), ) as latitudesh: res = latitudesh.kubernetes_clusters.update_kubernetes_cluster(kubernetes_cluster_id="", data={ "type": latitudesh_python_sdk.UpdateKubernetesClusterType.KUBERNETES_CLUSTERS, "attributes": { "worker_count": 5, }, }) # Handle response print(res) - lang: go label: Go (SDK) source: "package main\n\nimport(\n\t\"context\"\n\t\"os\"\n\tlatitudeshgosdk \"github.com/latitudesh/latitudesh-go-sdk\"\n\t\"github.com/latitudesh/latitudesh-go-sdk/models/components\"\n\t\"log\"\n)\n\nfunc main() {\n ctx := context.Background()\n\n s := latitudeshgosdk.New(\n latitudeshgosdk.WithSecurity(os.Getenv(\"LATITUDESH_BEARER\")),\n )\n\n res, err := s.KubernetesClusters.UpdateKubernetesCluster(ctx, \"\", components.UpdateKubernetesCluster{\n Data: components.UpdateKubernetesClusterData{\n Type: components.UpdateKubernetesClusterTypeKubernetesClusters,\n Attributes: components.UpdateKubernetesClusterAttributes{\n WorkerCount: latitudeshgosdk.Pointer[int64](5),\n },\n },\n })\n if err != nil {\n log.Fatal(err)\n }\n if res.KubernetesClusterUpdateResponse != nil {\n // handle response\n }\n}" - lang: typescript label: Typescript (SDK) source: |- import { Latitudesh } from "latitudesh-typescript-sdk"; const latitudesh = new Latitudesh({ bearer: process.env["LATITUDESH_BEARER"] ?? "", }); async function run() { const result = await latitudesh.kubernetesClusters.updateKubernetesCluster({ kubernetesClusterId: "", updateKubernetesCluster: { data: { type: "kubernetes_clusters", attributes: { workerCount: 5, }, }, }, }); console.log(result); } run(); components: schemas: update_kubernetes_cluster: type: object required: - data properties: data: type: object required: - type - attributes properties: type: type: string enum: - kubernetes_clusters attributes: type: object description: >- Provide one of: worker_count, control_plane_count (for scaling), or kubernetes_version (for upgrades). These are mutually exclusive operations. properties: worker_count: type: integer description: >- Desired number of worker nodes. Must be between 0 and 10. Mutually exclusive with control_plane_count and kubernetes_version. minimum: 0 maximum: 10 control_plane_count: type: integer description: >- Desired number of control plane nodes. Minimum 1. Mutually exclusive with worker_count and kubernetes_version. minimum: 1 worker_plan: type: string nullable: true description: >- Plan slug for worker nodes. Required when scaling from 0 workers. Ignored when scaling an existing deployment. kubernetes_version: type: string description: >- Target Kubernetes version for upgrade (e.g., v1.35.0+rke2r1). Mutually exclusive with scaling operations. Must be one minor version higher than current. kubernetes_cluster_update_response: type: object properties: data: type: object properties: type: type: string enum: - kubernetes_clusters id: type: string description: 'The cluster ID (format: kc_)' attributes: type: object properties: name: type: string description: The cluster name status: type: string enum: - scaling - upgrading - unchanged description: >- The update status. 'scaling' indicates nodes are being added or removed. 'upgrading' indicates a version upgrade is in progress. 'unchanged' indicates no change was needed. worker_count: type: integer nullable: true description: >- The requested number of worker nodes. Present when scaling workers. control_plane_count: type: integer nullable: true description: >- The requested number of control plane nodes. Present when scaling control plane. kubernetes_version: type: string nullable: true description: >- The target Kubernetes version. Present when upgrading version. error_object: type: object properties: errors: type: array items: type: object properties: code: type: string nullable: true status: type: string title: type: string detail: type: string source: type: object properties: pointer: type: string parameter: type: string meta: type: object securitySchemes: Bearer: type: apiKey name: Authorization in: header ````