---
updatedAt: 2026-05-27T20:00:17.000Z
agentTools:
  projectIndex: https://replicated-vendor-api.readme.io/llms.txt
---

# Upgrade a test cluster.

Required RBAC Policy: kots/cluster/[:clusterid]/upgrade

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "description": "List, create, update, archive customers and fetch customer licenses",
    "title": "Vendor API V3",
    "contact": {
      "name": "Replicated, Inc.",
      "url": "http://www.replicated.com/",
      "email": "info@replicated.com"
    },
    "version": "3.0.0"
  },
  "paths": {
    "/cluster/{cluster_id}/upgrade": {
      "post": {
        "security": [
          {
            "api_key": []
          }
        ],
        "description": "Required RBAC Policy: kots/cluster/[:clusterid]/upgrade",
        "tags": [
          "clusters"
        ],
        "summary": "Upgrade a test cluster.",
        "operationId": "upgradeCluster",
        "parameters": [
          {
            "x-go-name": "ClusterID",
            "description": "Cluster identifier",
            "name": "cluster_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "x-go-name": "DryRun",
            "name": "dry-run",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "kubernetes_version": {
                    "type": "string",
                    "x-go-name": "KubernetesVersion"
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/upgradeClusterResponse"
          },
          "400": {
            "$ref": "#/components/responses/upgradeClusterValidationErrorResponse"
          },
          "401": {
            "$ref": "#/components/responses/responseErrUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/responseErrForbidden"
          },
          "404": {
            "$ref": "#/components/responses/responseErrNotFound"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.replicated.com/vendor/v3"
    }
  ],
  "components": {
    "responses": {
      "responseErrForbidden": {
        "description": "Returned if the caller does not have the needed permission",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "x-go-name": "Message"
                    },
                    "messageCode": {
                      "type": "string",
                      "x-go-name": "MessageCode"
                    }
                  },
                  "x-go-name": "Error"
                }
              }
            }
          }
        }
      },
      "responseErrNotFound": {
        "description": "Returned on resource not found",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "x-go-name": "Message"
                }
              }
            }
          }
        }
      },
      "responseErrUnauthorized": {
        "description": "Return if the caller is not authorized",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "x-go-name": "Message"
                }
              }
            }
          }
        }
      },
      "upgradeClusterResponse": {
        "description": "UpgradeClusterResponse contains the response to upgrade a cluster",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "cluster": {
                  "$ref": "#/components/schemas/Cluster"
                }
              }
            }
          }
        }
      },
      "upgradeClusterValidationErrorResponse": {
        "description": "UpgradeClusterValidationErrorResponse contains a bad request response when upgrading a cluster",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ValidationError"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header"
      }
    },
    "schemas": {
      "Actor": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "x-go-name": "Description"
          },
          "id": {
            "type": "string",
            "x-go-name": "ID"
          },
          "link": {
            "type": "string",
            "x-go-name": "Link"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "x-go-name": "Timestamp"
          },
          "type": {
            "type": "string",
            "x-go-name": "Type"
          }
        },
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/models/types"
      },
      "Cluster": {
        "type": "object",
        "properties": {
          "actor": {
            "$ref": "#/components/schemas/Actor"
          },
          "addons": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ClusterAddon"
            },
            "x-go-name": "Addons"
          },
          "assigned_at": {
            "type": "string",
            "format": "date-time",
            "x-go-name": "AssignedAt"
          },
          "cluster_node": {
            "$ref": "#/components/schemas/ClusterNode"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "x-go-name": "CreatedAt"
          },
          "credits_per_hour_per_cluster": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "CreditsPerHourPerCluster"
          },
          "distribution": {
            "type": "string",
            "x-go-name": "Distribution"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "x-go-name": "ExpiresAt"
          },
          "flat_fee": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "FlatFee"
          },
          "guid": {
            "type": "string",
            "x-go-name": "GUID"
          },
          "id": {
            "type": "string",
            "x-go-name": "ShortID"
          },
          "installer_url": {
            "type": "string",
            "x-go-name": "InstallerURL"
          },
          "ip_family": {
            "type": "string",
            "x-go-name": "IPFamily"
          },
          "kubernetes_distribution": {
            "type": "string",
            "x-go-name": "KubernetesDistribution"
          },
          "kubernetes_version": {
            "type": "string",
            "x-go-name": "KubernetesVersion"
          },
          "last_scheduling_status": {
            "type": "string",
            "x-go-name": "LastSchedulingStatus"
          },
          "license_id": {
            "type": "string",
            "x-go-name": "LicenseID"
          },
          "name": {
            "type": "string",
            "x-go-name": "Name"
          },
          "network_id": {
            "type": "string",
            "x-go-name": "NetworkID"
          },
          "node_groups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NodeGroup"
            },
            "x-go-name": "NodeGroups"
          },
          "running_at": {
            "type": "string",
            "format": "date-time",
            "x-go-name": "RunningAt"
          },
          "status": {
            "$ref": "#/components/schemas/ClusterStatus"
          },
          "tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tag"
            },
            "x-go-name": "Tags"
          },
          "team_id": {
            "type": "string",
            "x-go-name": "TeamID"
          },
          "total_credits": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "TotalCredits"
          },
          "ttl": {
            "type": "string",
            "x-go-name": "TTL"
          },
          "version": {
            "type": "string",
            "x-go-name": "Version"
          }
        },
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/vendor-api/cluster/types"
      },
      "ClusterAddon": {
        "type": "object",
        "properties": {
          "cluster_guid": {
            "type": "string",
            "x-go-name": "ClusterGUID"
          },
          "cluster_id": {
            "type": "string",
            "x-go-name": "ClusterShortID"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "x-go-name": "CreatedAt"
          },
          "guid": {
            "type": "string",
            "x-go-name": "GUID"
          },
          "id": {
            "type": "string",
            "x-go-name": "ShortID"
          },
          "object_store": {
            "$ref": "#/components/schemas/ClusterAddonObjectStore"
          },
          "port": {
            "$ref": "#/components/schemas/ClusterAddonPort"
          },
          "ready_at": {
            "type": "string",
            "format": "date-time",
            "x-go-name": "ReadyAt"
          },
          "status": {
            "$ref": "#/components/schemas/ClusterAddonStatus"
          },
          "terminated_at": {
            "type": "string",
            "format": "date-time",
            "x-go-name": "TerminatedAt"
          },
          "total_credits": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "TotalCredits"
          }
        },
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/vendor-api/cluster/types"
      },
      "ClusterAddonObjectStore": {
        "type": "object",
        "properties": {
          "bucket_name": {
            "type": "string",
            "x-go-name": "BucketName"
          },
          "bucket_prefix": {
            "type": "string",
            "x-go-name": "BucketPrefix"
          },
          "service_account_name": {
            "type": "string",
            "x-go-name": "ServiceAccountName"
          },
          "service_account_name_read_only": {
            "type": "string",
            "x-go-name": "ServiceAccountNameReadOnly"
          },
          "service_account_namespace": {
            "type": "string",
            "x-go-name": "ServiceAccountNamespace"
          }
        },
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/vendor-api/cluster/types"
      },
      "ClusterAddonPort": {
        "type": "object",
        "properties": {
          "is_wildcard": {
            "type": "boolean",
            "x-go-name": "IsWildcard"
          },
          "name": {
            "type": "string",
            "x-go-name": "Name"
          },
          "protocol_http": {
            "type": "boolean",
            "x-go-name": "ProtocolHTTP"
          },
          "protocol_https": {
            "type": "boolean",
            "x-go-name": "ProtocolHTTPS"
          },
          "protocol_ws": {
            "type": "boolean",
            "x-go-name": "ProtocolWS"
          },
          "protocol_wss": {
            "type": "boolean",
            "x-go-name": "ProtocolWSS"
          },
          "upstream_port": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "UpstreamPort"
          }
        },
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/vendor-api/cluster/types"
      },
      "ClusterAddonStatus": {
        "type": "string",
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/vendor-api/cluster/types"
      },
      "ClusterDistributionStatus": {
        "type": "object",
        "properties": {
          "enabled": {
            "type": "boolean",
            "x-go-name": "Enabled"
          },
          "status": {
            "type": "string",
            "x-go-name": "Status"
          },
          "status_message": {
            "type": "string",
            "x-go-name": "StatusMessage"
          },
          "versions": {
            "type": "string",
            "x-go-name": "Versions"
          }
        },
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/vendor-api/cluster/types"
      },
      "ClusterNode": {
        "type": "object",
        "properties": {
          "join_command": {
            "type": "string",
            "x-go-name": "JoinCommand"
          },
          "network_id": {
            "description": "Used by vxlan nodes",
            "type": "string",
            "x-go-name": "NetworkID"
          },
          "network_public_ips": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "x-go-name": "NetworkPublicIPs"
          },
          "node_group_id": {
            "type": "string",
            "x-go-name": "NodeGroupID"
          },
          "node_index": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "Index"
          },
          "node_type": {
            "$ref": "#/components/schemas/NodeType"
          },
          "ssh_endpoint": {
            "type": "string",
            "x-go-name": "SSHEndpoint"
          },
          "ssh_key": {
            "type": "string",
            "x-go-name": "SSHKey"
          },
          "ssh_port": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "SSHPort"
          }
        },
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/vendor-api/cluster/types"
      },
      "ClusterStatus": {
        "type": "string",
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/vendor-api/cluster/types"
      },
      "NodeGroup": {
        "type": "object",
        "properties": {
          "cluster_guid": {
            "type": "string",
            "x-go-name": "ClusterGUID"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "x-go-name": "CreatedAt"
          },
          "credits_per_hour": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "CreditsPerHour"
          },
          "disk_gib": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "DiskGiB"
          },
          "id": {
            "type": "string",
            "x-go-name": "ID"
          },
          "instance_type": {
            "type": "string",
            "x-go-name": "InstanceType"
          },
          "is_default": {
            "type": "boolean",
            "x-go-name": "IsDefault"
          },
          "max_node_count": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "MaxNodeCount"
          },
          "min_node_count": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "MinNodeCount"
          },
          "minutes_billed": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "MinutesBilled"
          },
          "name": {
            "type": "string",
            "x-go-name": "Name"
          },
          "node_count": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "NodeCount"
          },
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ClusterNode"
            },
            "x-go-name": "ClusterNodes"
          },
          "running_at": {
            "type": "string",
            "format": "date-time",
            "x-go-name": "RunningAt"
          },
          "total_credits": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "TotalCredits"
          }
        },
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/vendor-api/cluster/types"
      },
      "NodeType": {
        "type": "string",
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/vendor-api/cluster/types"
      },
      "SupportedDistributionAndVersions": {
        "type": "object",
        "properties": {
          "instance_types": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "x-go-name": "InstanceTypes"
          },
          "nodes_max": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "NodesMax"
          },
          "short_name": {
            "type": "string",
            "x-go-name": "ShortName"
          },
          "status": {
            "$ref": "#/components/schemas/ClusterDistributionStatus"
          },
          "version_details": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SupportedVersion"
            },
            "x-go-name": "VersionDetails"
          },
          "versions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "x-go-name": "Versions"
          }
        },
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/vendor-api/cluster/types"
      },
      "SupportedVersion": {
        "type": "object",
        "properties": {
          "nodes_max": {
            "type": "integer",
            "format": "int64",
            "x-go-name": "NodesMax"
          },
          "version": {
            "type": "string",
            "x-go-name": "Version"
          }
        },
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/vendor-api/cluster/types"
      },
      "Tag": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "x-go-name": "Key"
          },
          "value": {
            "type": "string",
            "x-go-name": "Value"
          }
        },
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/vendor-api/cmx/types"
      },
      "ValidationError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "x-go-name": "Errors"
          },
          "supported_distributions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SupportedDistributionAndVersions"
            },
            "x-go-name": "SupportedDistributions"
          }
        },
        "x-go-package": "github.com/replicatedhq/vandoor/pkg/vendor-api/cluster/types"
      }
    }
  }
}
```