Zededa ZKSClusterInstances API
APIs for managing ZKS (ZEDEDA Kubernetes Service) cluster instances including creation, management, node operations, and status monitoring
OpenAPI Specification
swagger: '2.0'
info:
title: ZEDEDA App Profiles Service AppProfileService ZKSClusterInstances API
description: The ZEDEDA App Profiles Service is part of ZEDEDA Edge Orchestration Platform. This service enables customers to define their app profiles on ZEDEDA platform and to manage them remotely.
termsOfService: https://www.zededa.com/terms
version: '1.0'
contact:
name: ZEDEDA API Support
url: https://www.zededa.com/support
email: support@zededa.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
basePath: /api
schemes:
- https
consumes:
- application/json
produces:
- application/json
security:
- BearerToken: []
tags:
- name: ZKSClusterInstances
description: APIs for managing ZKS (ZEDEDA Kubernetes Service) cluster instances including creation, management, node operations, and status monitoring
paths:
/v1/zks/instances:
get:
summary: List all ZKS instances
description: "Retrieve a list of all ZKS instances with their basic information and metadata.\n\n**Query Parameters:**\n- Pagination parameters supported via cursor\n\n**Example Request:**\n```\nGET /v1/zks/instances\n```\n\n**Example Response:**\n```json\n{\n \"list\": [\n {\n \"id\": \"zks-instance-abc123\",\n \"projectId\": \"project-123\",\n \"name\": \"production-cluster\",\n \"title\": \"Production Kubernetes Cluster\",\n \"description\": \"Main production cluster for edge applications\",\n \"tags\": {\n \"environment\": \"production\",\n \"region\": \"us-west\"\n },\n \"nOfNodes\": 3\n },\n {\n \"id\": \"zks-instance-def456\",\n \"projectId\": \"project-456\",\n \"name\": \"development-cluster\",\n \"title\": \"Development Kubernetes Cluster\",\n \"description\": \"Development cluster for testing\",\n \"tags\": {\n \"environment\": \"development\",\n \"region\": \"us-east\"\n },\n \"nOfNodes\": 1\n }\n ],\n \"next\": {\n \"pageToken\": \"next-page-token\"\n }\n}\n```"
operationId: ZKSClusterInstances_ListZKSInstances
responses:
'200':
description: Successfully retrieved ZKS instances list
schema:
$ref: '#/definitions/ZksInstancesList'
'400':
description: Bad Request. The API gateway did not process the request because of invalid value of filter parameters.
schema:
$ref: '#/definitions/ZsrvResponse'
'401':
description: Unauthorized. Authentication credentials are missing or invalid.
schema:
$ref: '#/definitions/ZsrvResponse'
'403':
description: Forbidden. User does not have permission to list ZKS instances.
schema:
$ref: '#/definitions/ZsrvResponse'
'500':
description: Internal Server Error. Failed to retrieve ZKS instances list due to server error.
schema:
$ref: '#/definitions/ZsrvResponse'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
tags:
- ZKSClusterInstances
parameters:
- name: X-Request-Id
in: header
required: false
description: User-Agent specified id to track a request
type: string
post:
summary: Create a new ZKS instance
description: "Create a new ZKS (ZEDEDA Kubernetes Service) cluster instance with specified nodes and configuration.\n\n**Example Request:**\n```json\n{\n \"projectId\": \"project-123\",\n \"name\": \"production-cluster\",\n \"title\": \"Production Kubernetes Cluster\",\n \"description\": \"Main production cluster for edge applications\",\n \"tags\": {\n \"environment\": \"production\",\n \"region\": \"us-west\",\n \"purpose\": \"edge-computing\"\n },\n \"nodes\": [\n {\n \"id\": \"node-001\",\n \"clusterInterface\": \"eth0\"\n },\n {\n \"id\": \"node-002\",\n \"clusterInterface\": \"eth0\"\n }\n ],\n \"isImported\": false\n}\n```\n\n**Example Response:**\n```json\n{\n \"operationType\": \"OPS_TYPE_UNSPECIFIED\",\n \"operationStatus\": \"OPS_STATUS_UNSPECIFIED\",\n \"objectKind\": \"\",\n \"objectId\": \"zks-instance-abc123\",\n \"objectName\": \"production-cluster\",\n \"objectRevision\": \"\",\n \"objectType\": \"OBJECT_TYPE_UNSPECIFIED\",\n \"operationTime\": \"\",\n \"startTime\": \"\",\n \"endTime\": \"\",\n \"user\": \"\",\n \"httpStatusCode\": 201,\n \"httpStatusMsg\": \"\",\n \"jobId\": \"\",\n \"error\": [\n {\n \"ec\": \"zMsgSucess\",\n \"location\": \"\",\n \"details\": \"\"\n }\n ]\n}\n```"
operationId: ZKSClusterInstances_CreateZKSInstance
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/ZsrvResponse'
'201':
description: Successfully created ZKS instance
schema:
$ref: '#/definitions/ZsrvResponse'
'400':
description: Bad Request. Invalid ZKS instance configuration or missing required fields.
schema:
$ref: '#/definitions/ZsrvResponse'
'401':
description: Unauthorized. Authentication credentials are missing or invalid.
schema:
$ref: '#/definitions/ZsrvResponse'
'403':
description: Forbidden. User does not have permission to create ZKS instances.
schema:
$ref: '#/definitions/ZsrvResponse'
'409':
description: Conflict. ZKS instance with the same name already exists.
schema:
$ref: '#/definitions/ZsrvResponse'
'500':
description: Internal Server Error. Failed to create ZKS instance due to server error.
schema:
$ref: '#/definitions/ZsrvResponse'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: body
in: body
required: true
schema:
$ref: '#/definitions/ZksInstance'
- name: X-Request-Id
in: header
required: false
description: User-Agent specified id to track a request
type: string
tags:
- ZKSClusterInstances
put:
summary: Bulk update ZKS instances
description: "Update multiple ZKS instances at once with new tags or other common properties. This operation is useful for applying changes to multiple clusters simultaneously.\n\n**Example Request:**\n```json\n{\n \"ids\": [\n \"zks-instance-abc123\",\n \"zks-instance-def456\",\n \"zks-instance-ghi789\"\n ],\n \"data\": {\n \"tags\": {\n \"environment\": \"production\",\n \"version\": \"v2\",\n \"managed-by\": \"platform-team\"\n }\n }\n}\n```\n\n**Example Response:**\n```json\n{\n \"operationType\": \"OPS_TYPE_UNSPECIFIED\",\n \"operationStatus\": \"OPS_STATUS_UNSPECIFIED\",\n \"objectKind\": \"\",\n \"objectId\": \"\",\n \"objectName\": \"\",\n \"objectRevision\": \"\",\n \"objectType\": \"OBJECT_TYPE_UNSPECIFIED\",\n \"operationTime\": \"\",\n \"startTime\": \"\",\n \"endTime\": \"\",\n \"user\": \"\",\n \"httpStatusCode\": 200,\n \"httpStatusMsg\": \"\",\n \"jobId\": \"\",\n \"error\": [\n {\n \"ec\": \"zMsgSucess\",\n \"location\": \"\",\n \"details\": \"Successfully updated 3 ZKS instances\"\n }\n ]\n}\n```"
operationId: ZKSClusterInstances_BulkUpdateZKSInstances
responses:
'200':
description: Successfully updated ZKS instances
schema:
$ref: '#/definitions/ZsrvResponse'
'400':
description: Bad Request. Invalid bulk update configuration or empty instance IDs list.
schema:
$ref: '#/definitions/ZsrvResponse'
'401':
description: Unauthorized. Authentication credentials are missing or invalid.
schema:
$ref: '#/definitions/ZsrvResponse'
'403':
description: Forbidden. User does not have permission to update ZKS instances.
schema:
$ref: '#/definitions/ZsrvResponse'
'404':
description: Not Found. One or more ZKS instances with the specified IDs do not exist.
schema:
$ref: '#/definitions/ZsrvResponse'
'500':
description: Internal Server Error. Failed to update ZKS instances due to server error.
schema:
$ref: '#/definitions/ZsrvResponse'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: body
in: body
required: true
schema:
$ref: '#/definitions/ZksInstanceBulkUpdate'
- name: X-Request-Id
in: header
required: false
description: User-Agent specified id to track a request
type: string
tags:
- ZKSClusterInstances
/v1/zks/instances/id/{id}:
put:
summary: Update ZKS instance
description: "Update an existing ZKS instance configuration including name, title, description, and tags.\n\n**Example Request:**\n```json\n{\n \"id\": \"zks-instance-abc123\",\n \"projectId\": \"project-123\",\n \"name\": \"production-cluster\",\n \"title\": \"Updated Production Kubernetes Cluster\",\n \"description\": \"Updated main production cluster for edge applications\",\n \"tags\": {\n \"environment\": \"production\",\n \"region\": \"us-west\",\n \"version\": \"v2\"\n },\n \"nodes\": [\n {\n \"id\": \"node-001\",\n \"clusterInterface\": \"eth0\"\n },\n {\n \"id\": \"node-002\",\n \"clusterInterface\": \"eth0\"\n }\n ],\n \"isImported\": false\n}\n```\n\n**Example Response:**\n```json\n{\n \"operationType\": \"OPS_TYPE_UNSPECIFIED\",\n \"operationStatus\": \"OPS_STATUS_UNSPECIFIED\",\n \"objectKind\": \"\",\n \"objectId\": \"zks-instance-abc123\",\n \"objectName\": \"production-cluster\",\n \"objectRevision\": \"\",\n \"objectType\": \"OBJECT_TYPE_UNSPECIFIED\",\n \"operationTime\": \"\",\n \"startTime\": \"\",\n \"endTime\": \"\",\n \"user\": \"\",\n \"httpStatusCode\": 200,\n \"httpStatusMsg\": \"\",\n \"jobId\": \"\",\n \"error\": [\n {\n \"ec\": \"zMsgSucess\",\n \"location\": \"\",\n \"details\": \"\"\n }\n ]\n}\n```"
operationId: ZKSClusterInstances_UpdateZKSInstance
responses:
'200':
description: Successfully updated ZKS instance
schema:
$ref: '#/definitions/ZsrvResponse'
'400':
description: Bad Request. Invalid ZKS instance configuration or missing required fields.
schema:
$ref: '#/definitions/ZsrvResponse'
'401':
description: Unauthorized. Authentication credentials are missing or invalid.
schema:
$ref: '#/definitions/ZsrvResponse'
'403':
description: Forbidden. User does not have permission to update this ZKS instance.
schema:
$ref: '#/definitions/ZsrvResponse'
'404':
description: Not Found. ZKS instance with the specified ID does not exist.
schema:
$ref: '#/definitions/ZsrvResponse'
'409':
description: Conflict. Update conflicts with current instance state.
schema:
$ref: '#/definitions/ZsrvResponse'
'500':
description: Internal Server Error. Failed to update ZKS instance due to server error.
schema:
$ref: '#/definitions/ZsrvResponse'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: id
description: System defined universally unique Id of the zks instance
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
type: object
properties:
projectId:
type: string
description: Foreign key to the project
pattern: '[0-9A-Za-z-]+'
name:
type: string
description: User defined name of the zks instance, unique across the enterprise. Once zks instance is created, name can’t be changed
title:
type: string
description: User defined title of the zks instance. Title can be changed at any time
description:
type: string
description: Detailed description of the zks instance
tags:
type: object
additionalProperties:
type: string
description: Tags are name/value pairs that enable you to categorize resources. Tag names are case insensitive with max_length 512 and min_length 3. Tag values are case sensitive with max_length 256 and min_length 3.
maxLength: 32
pattern: ^[^<%&?/\>]+$
nodes:
type: array
items:
$ref: '#/definitions/ZksInstanceNode'
description: A list of nodes in the zks instance
isImported:
type: boolean
description: Indicates if the ZKS instance is imported from an external source
clusterPrefix:
type: string
description: Cluster prefix for the ZKS instance
description: ZKS Instance details
title: ZKS Instance details
required:
- projectId
- name
- nodes
- name: X-Request-Id
in: header
required: false
description: User-Agent specified id to track a request
type: string
tags:
- ZKSClusterInstances
/v1/zks/instances/id/{zksId}:
get:
summary: Get ZKS instance by ID
description: "Retrieve detailed information about a specific ZKS instance including its configuration, nodes, and metadata.\n\n**Example Request:**\n```\nGET /v1/zks/instances/id/zks-instance-abc123\n```\n\n**Example Response:**\n```json\n{\n \"id\": \"zks-instance-abc123\",\n \"projectId\": \"project-123\",\n \"name\": \"production-cluster\",\n \"title\": \"Production Kubernetes Cluster\",\n \"description\": \"Main production cluster for edge applications\",\n \"tags\": {\n \"environment\": \"production\",\n \"region\": \"us-west\",\n \"purpose\": \"edge-computing\"\n },\n \"nodes\": [\n {\n \"id\": \"node-001\",\n \"clusterInterface\": \"eth0\"\n },\n {\n \"id\": \"node-002\",\n \"clusterInterface\": \"eth0\"\n }\n ],\n \"isImported\": false\n}\n```"
operationId: ZKSClusterInstances_GetZKSInstance
responses:
'200':
description: Successfully retrieved ZKS instance information
schema:
$ref: '#/definitions/ZksInstance'
'400':
description: Bad Request. Invalid ZKS instance ID format.
schema:
$ref: '#/definitions/ZsrvResponse'
'401':
description: Unauthorized. Authentication credentials are missing or invalid.
schema:
$ref: '#/definitions/ZsrvResponse'
'403':
description: Forbidden. User does not have permission to view this ZKS instance.
schema:
$ref: '#/definitions/ZsrvResponse'
'404':
description: Not Found. ZKS instance with the specified ID does not exist.
schema:
$ref: '#/definitions/ZsrvResponse'
'500':
description: Internal Server Error. Failed to retrieve ZKS instance due to server error.
schema:
$ref: '#/definitions/ZsrvResponse'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: zksId
description: Unique identifier of the ZKS instance. This field is required and must be a valid ZKS instance ID.
in: path
required: true
type: string
- name: X-Request-Id
in: header
required: false
description: User-Agent specified id to track a request
type: string
tags:
- ZKSClusterInstances
delete:
summary: Delete ZKS instance
description: "Delete a ZKS instance and all its associated resources. This operation is irreversible and will terminate all running workloads.\n\n**Example Request:**\n```\nDELETE /v1/zks/instances/id/zks-instance-abc123\n```\n\n**Example Response:**\n```json\n{\n \"operationType\": \"OPS_TYPE_UNSPECIFIED\",\n \"operationStatus\": \"OPS_STATUS_UNSPECIFIED\",\n \"objectKind\": \"\",\n \"objectId\": \"zks-instance-abc123\",\n \"objectName\": \"production-cluster\",\n \"objectRevision\": \"\",\n \"objectType\": \"OBJECT_TYPE_UNSPECIFIED\",\n \"operationTime\": \"\",\n \"startTime\": \"\",\n \"endTime\": \"\",\n \"user\": \"\",\n \"httpStatusCode\": 200,\n \"httpStatusMsg\": \"\",\n \"jobId\": \"\",\n \"error\": [\n {\n \"ec\": \"zMsgSucess\",\n \"location\": \"\",\n \"details\": \"\"\n }\n ]\n}\n```\n\n**Warning:** This operation will permanently delete the ZKS instance and all its data. Ensure all important data is backed up before deletion."
operationId: ZKSClusterInstances_DeleteZKSInstance
responses:
'200':
description: Successfully deleted ZKS instance
schema:
$ref: '#/definitions/ZsrvResponse'
'400':
description: Bad Request. Invalid ZKS instance ID format.
schema:
$ref: '#/definitions/ZsrvResponse'
'401':
description: Unauthorized. Authentication credentials are missing or invalid.
schema:
$ref: '#/definitions/ZsrvResponse'
'403':
description: Forbidden. User does not have permission to delete this ZKS instance.
schema:
$ref: '#/definitions/ZsrvResponse'
'404':
description: Not Found. ZKS instance with the specified ID does not exist.
schema:
$ref: '#/definitions/ZsrvResponse'
'409':
description: Conflict. Cannot delete ZKS instance due to active workloads or dependencies.
schema:
$ref: '#/definitions/ZsrvResponse'
'500':
description: Internal Server Error. Failed to delete ZKS instance due to server error.
schema:
$ref: '#/definitions/ZsrvResponse'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: zksId
description: Unique identifier of the ZKS instance. This field is required and must be a valid ZKS instance ID.
in: path
required: true
type: string
- name: X-Request-Id
in: header
required: false
description: User-Agent specified id to track a request
type: string
tags:
- ZKSClusterInstances
/v1/zks/instances/id/{zksId}/metrics:
get:
summary: Get ZKS instance metrics by ID
description: "Retrieve detailed metrics for a specific ZKS instance including resource utilization and capacity information.\n\n**Example Request:**\n```\nGET /v1/zks/instances/id/zks-instance-abc123/metrics\n```\n\n**Example Response:**\n```json\n{\n \"id\": \"zks-instance-abc123\",\n \"name\": \"production-cluster\",\n \"provider\": \"k3s\",\n \"kubeVersion\": \"v1.28.2+k3s1\",\n \"architecture\": \"amd64\",\n \"created\": \"2024-01-15T10:00:00Z\",\n \"totalResources\": 100,\n \"nOfNodes\": 3,\n \"deployments\": 15,\n \"capacity\": {\n \"pods\": {\n \"used\": 25,\n \"total\": 110\n },\n \"cpus\": {\n \"reserved\": {\n \"current\": 2.5,\n \"total\": 8.0\n },\n \"used\": {\n \"current\": 1.8,\n \"total\": 8.0\n }\n },\n \"memory\": {\n \"reserved\": {\n \"current\": 4.0,\n \"total\": 16.0\n },\n \"used\": {\n \"current\": 3.2,\n \"total\": 16.0\n }\n }\n }\n}\n```"
operationId: ZKSClusterInstances_GetZKSInstanceMetrics
responses:
'200':
description: Successfully retrieved ZKS instance metrics
schema:
$ref: '#/definitions/ZksInstanceMetrics'
'400':
description: Bad Request. Invalid ZKS instance ID format.
schema:
$ref: '#/definitions/ZsrvResponse'
'401':
description: Unauthorized. Authentication credentials are missing or invalid.
schema:
$ref: '#/definitions/ZsrvResponse'
'403':
description: Forbidden. User does not have permission to view metrics for this ZKS instance.
schema:
$ref: '#/definitions/ZsrvResponse'
'404':
description: Not Found. ZKS instance with the specified ID does not exist.
schema:
$ref: '#/definitions/ZsrvResponse'
'500':
description: Internal Server Error. Failed to retrieve metrics due to server error.
schema:
$ref: '#/definitions/ZsrvResponse'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: zksId
description: Unique identifier of the ZKS instance. This field is required and must be a valid ZKS instance ID.
in: path
required: true
type: string
- name: X-Request-Id
in: header
required: false
description: User-Agent specified id to track a request
type: string
tags:
- ZKSClusterInstances
/v1/zks/instances/id/{zksId}/nodes:
put:
summary: Update ZKS instance nodes
description: "Add or remove nodes from a ZKS instance. This operation allows scaling the cluster up or down by managing individual nodes.\n\n**Example Request (Add Nodes):**\n```json\n{\n \"action\": \"NODE_ACTION_ADD_NODES\",\n \"nodes\": [\n {\n \"id\": \"node-003\",\n \"clusterInterface\": \"eth0\"\n },\n {\n \"id\": \"node-004\",\n \"clusterInterface\": \"eth0\"\n }\n ]\n}\n```\n\n**Example Request (Remove Nodes):**\n```json\n{\n \"action\": \"NODE_ACTION_REMOVE_NODES\",\n \"nodes\": [\n {\n \"id\": \"node-002\",\n \"clusterInterface\": \"eth0\"\n }\n ]\n}\n```\n\n**Example Response:**\n```json\n{\n \"operationType\": \"OPS_TYPE_UNSPECIFIED\",\n \"operationStatus\": \"OPS_STATUS_UNSPECIFIED\",\n \"objectKind\": \"\",\n \"objectId\": \"zks-instance-abc123\",\n \"objectName\": \"production-cluster\",\n \"objectRevision\": \"\",\n \"objectType\": \"OBJECT_TYPE_UNSPECIFIED\",\n \"operationTime\": \"\",\n \"startTime\": \"\",\n \"endTime\": \"\",\n \"user\": \"\",\n \"httpStatusCode\": 200,\n \"httpStatusMsg\": \"\",\n \"jobId\": \"\",\n \"error\": [\n {\n \"ec\": \"zMsgSucess\",\n \"location\": \"\",\n \"details\": \"\"\n }\n ]\n}\n```"
operationId: ZKSClusterInstances_UpdateZKSInstanceNodes
responses:
'200':
description: Successfully updated ZKS instance nodes
schema:
$ref: '#/definitions/ZsrvResponse'
'400':
description: Bad Request. Invalid node update configuration or missing required fields.
schema:
$ref: '#/definitions/ZsrvResponse'
'401':
description: Unauthorized. Authentication credentials are missing or invalid.
schema:
$ref: '#/definitions/ZsrvResponse'
'403':
description: Forbidden. User does not have permission to update this ZKS instance.
schema:
$ref: '#/definitions/ZsrvResponse'
'404':
description: Not Found. ZKS instance with the specified ID does not exist.
schema:
$ref: '#/definitions/ZsrvResponse'
'409':
description: Conflict. Cannot update nodes due to cluster state or resource constraints.
schema:
$ref: '#/definitions/ZsrvResponse'
'500':
description: Internal Server Error. Failed to update nodes due to server error.
schema:
$ref: '#/definitions/ZsrvResponse'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: zksId
description: ZKS instance ID for the node update operation
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
type: object
properties:
action:
$ref: '#/definitions/NodeAction'
description: Action to be performed on the nodes
nodes:
type: array
items:
$ref: '#/definitions/ZksInstanceNode'
description: List of nodes to be added or removed
title: ZksNodeUpdate for node update operations
- name: X-Request-Id
in: header
required: false
description: User-Agent specified id to track a request
type: string
tags:
- ZKSClusterInstances
/v1/zks/instances/id/{zksId}/registration-commands:
get:
summary: Get registration commands by ID
description: "Retrieve registration commands for adding nodes to a ZKS instance. These commands can be executed on edge devices to join them to the cluster.\n\n**Example Request:**\n```\nGET /v1/zks/instances/id/zks-instance-abc123/registration-commands\n```\n\n**Example Response:**\n```json\n{\n \"created\": \"2024-01-15T10:30:00Z\",\n \"manifestUrl\": \"https://api.zededa.com/manifests/zks-instance-abc123\",\n \"commands\": {\n \"command\": \"curl -sfL https://get.k3s.io | K3S_URL=https://cluster.example.com:6443 K3S_TOKEN=K1234567890abcdef::server:1234567890abcdef sh -\",\n \"insecureCommand\": \"curl -sfL https://get.k3s.io | K3S_URL=https://cluster.example.com:6443 K3S_TOKEN=K1234567890abcdef::server:1234567890abcdef INSTALL_K3S_SKIP_VERIFY=true sh -\",\n \"nodeCommand\": \"curl -sfL https://get.k3s.io | K3S_URL=https://cluster.example.com:6443 K3S_TOKEN=K1234567890abcdef::server:1234567890abcdef sh -s - agent\",\n \"windowsNodeCommand\": \"Invoke-WebRequest -Uri https://github.com/k3s-io/k3s/releases/download/v1.28.2%2Bk3s1/k3s-windows-amd64.exe -OutFile k3s.exe\"\n }\n}\n```"
operationId: ZKSClusterInstances_GetZKSInstanceRegistrationCommands
responses:
'200':
description: Successfully retrieved registration commands
schema:
$ref: '#/definitions/ZksInstanceRegistrationInfo'
'400':
description: Bad Request. Invalid ZKS instance ID format.
schema:
$ref: '#/definitions/ZsrvResponse'
'401':
description: Unauthorized. Authentication credentials are missing or invalid.
schema:
$ref: '#/definitions/ZsrvResponse'
'403':
description: Forbidden. User does not have permission to view registration commands.
schema:
$ref: '#/definitions/ZsrvResponse'
'404':
description: Not Found. ZKS instance with the specified ID does not exist.
schema:
$ref: '#/definitions/ZsrvResponse'
'500':
description: Internal Server Error. Failed to retrieve registration commands due to server error.
schema:
$ref: '#/definitions/ZsrvResponse'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: zksId
description: Unique identifier of the ZKS instance. This field is required and must be a valid ZKS instance ID.
in: path
required: true
type: string
- name: X-Request-Id
in: header
required: false
description: User-Agent specified id to track a request
type: string
tags:
- ZKSClusterInstances
/v1/zks/instances/id/{zksId}/upgrade:
put:
summary: Upgrade ZKS instance
description: "Upgrade a ZKS instance to a new base OS image or Kubernetes version. This operation will update the underlying infrastructure.\n\n**Example Request:**\n```json\n{\n \"baseOSImage\": {\n \"name\": \"ubuntu-22.04-lts\",\n \"version\": \"22.04.3\",\n \"digest\": \"sha256:abcd1234...\"\n }\n}\n```\n\n**Example Response:**\n```json\n{\n \"operationType\": \"OPS_TYPE_UNSPECIFIED\",\n \"operationStatus\": \"OPS_STATUS_UNSPECIFIED\",\n \"objectKind\": \"\",\n \"objectId\": \"zks-instance-abc123\",\n \"objectName\": \"production-cluster\",\n \"objectRevision\": \"\",\n \"objectType\": \"OBJECT_TYPE_UNSPECIFIED\",\n \"operationTime\": \"\",\n \"startTime\": \"\",\n \"endTime\": \"\",\n \"user\": \"\",\n \"httpStatusCode\": 200,\n \"httpStatusMsg\": \"\",\n \"jobId\": \"upgrade-job-123\",\n \"error\": [\n {\n \"ec\": \"zMsgSucess\",\n \"location\": \"\",\n \"details\": \"\"\n }\n ]\n}\n```\n\n**Note:** Upgrade operations may take significant time to complete and will be processed asynchronously."
operationId: ZKSClusterInstances_UpgradeZKSInstance
responses:
'200':
description: Successfully initiated ZKS instance upgrade
schema:
$ref: '#/definitions/ZsrvResponse'
'400':
description: Bad Request. Invalid upgrade configuration or missing required fields.
schema:
$ref: '#/definitions/ZsrvResponse'
'401':
description: Unauthorized. Authentication credentials are missing or invalid.
schema:
$ref: '#/definitions/ZsrvResponse'
'403':
description: Forbidden. User does not have permission to upgrade this ZKS instance.
schema:
$ref: '#/definitions/ZsrvResponse'
'404':
description: Not Found. ZKS instance with the specified ID does not exist.
schema:
$ref: '#/definitions/ZsrvResponse'
'409':
description: Conflict. Cannot upgrade due to cluster state or ongoing operations.
schema:
$ref: '#/definitions/ZsrvResponse'
'500':
description: Internal Server Error. Failed to initiate upgrade due to server error.
schema:
$ref: '#/definitions/ZsrvResponse'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: zksId
description: ZKS instance ID for the upgrade operation
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
type: object
properties:
baseOSImage:
$ref: '#/definitions/BaseOSImage'
- name: X-Request-Id
in: header
required: false
description: User-Agent specified id to track a request
type: string
tags:
- ZKSClusterInstances
/v1/zks/instances/import:
post:
summary: Import an existing ZKS instance
description: "Import an existing Kubernetes cluster as a ZKS instance into the ZEDEDA platform. This allows managing externally created clusters through ZEDEDA.\n\n**Example Request:**\n```json\n{\n \"projectId\": \"project-123\",\n \"name\": \"imported-cluster\",\n \"title\": \"Imported Production Cluster\",\n \"description\": \"Externally created cluster imported into ZEDEDA\",\n \"tags\": {\n \"environment\": \"production\",\n \"source\": \"external\"\n },\n \"nodes\": [\n {\n \"id\": \"node-001\",\n \"clusterInterface\": \"eth0\"\n }\n ],\n \"isImported\": true\n}\n```\n\n**Example Response:**\n```json\n{\n \"operationType\": \"OPS_TYPE_UNSPECIFIED\",\n \"operationStatus\": \"OPS_STATUS_UNSPECIFIED\",\n \"objectKind\": \"\",\n \"objectId\": \"zks-instance-def456\",\n \"objectName\": \"imported-cluster\",\n \"objectRevision\": \"\",\n \"objectType\": \"OBJECT_TYPE_UNSPECIFIED\",\n \"operationTime\": \"\",\n \"startTime\": \"\",\n \"endTime\": \"\",\n \"user\": \"\",\n \"httpStatusCode\": 2
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zededa/refs/heads/main/openapi/zededa-zksclusterinstances-api-openapi.yml