From 83555d488d797968e77b2df1504eccf721a3e84e Mon Sep 17 00:00:00 2001 From: Victor Palma Date: Wed, 10 Jun 2026 11:29:01 +0200 Subject: [PATCH 1/3] F OpenNebula/one#7676: Update oneks docs with deployment options --- content/openapi/oneks_v1.json | 862 ++++++++++-------- .../oneks/getting_started/core_concepts.md | 3 +- .../oneks/management/configuration.md | 10 +- .../k8s_cluster_lifecycle_management.md | 47 +- .../monitoring_and_troubleshooting.md | 9 +- .../oneks/references/oneks_cli.md | 4 +- 6 files changed, 539 insertions(+), 396 deletions(-) diff --git a/content/openapi/oneks_v1.json b/content/openapi/oneks_v1.json index a98ebf13..d13498ab 100644 --- a/content/openapi/oneks_v1.json +++ b/content/openapi/oneks_v1.json @@ -219,8 +219,19 @@ "name": "production-cluster", "description": "General-purpose production cluster", "kubernetes_version": "v1.32.9", - "public_network": 105, - "private_network": 106, + "deployment": { + "cluster": { + "id": 0 + }, + "networks": { + "public": { + "id": 105 + }, + "private": { + "id": 106 + } + } + }, "spec": { "family": "general", "flavour": "ha", @@ -268,13 +279,13 @@ } } }, - "/clusters/check": { + "/clusters/deployment/check": { "get": { "tags": [ "clusters" ], - "summary": "Get readiness check service status", - "description": "Returns whether the OneKS readiness check service is enabled in the OneKS server configuration.", + "summary": "Get deployment readiness check service status", + "description": "Returns whether the OneKS deployment readiness check service is enabled in the OneKS server configuration.", "responses": { "200": { "description": "Readiness check service status", @@ -310,32 +321,27 @@ "tags": [ "clusters" ], - "summary": "Run a readiness check", - "description": "Runs the OneKS readiness check service against a public and private Virtual Network pair before provisioning a Kubernetes cluster. The response is a Server-Sent Events stream. Each progress event uses the `check_cluster` event name and sends a JSON object inline in the event `data` field with the following structure: `name` is the check step, `state` is one of `started`, `success`, or `failure`, and `context` is an optional error or detail message.", + "summary": "Run a deployment readiness check", + "description": "Runs the OneKS deployment readiness check service against a complete deployment placement before provisioning a Kubernetes cluster. The check validates the target OpenNebula cluster and networks, required OneKS appliance, and live bootstrap connectivity. The response is a Server-Sent Events stream. Each progress event uses the `check_cluster` event name and sends a JSON object inline in the event `data` field with the following structure: `name` is the check step, `state` is one of `started`, `success`, or `failure`, and `context` is an optional error or detail message.", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "type": "object", - "required": [ - "public_network", - "private_network" - ], - "properties": { - "public_network": { - "type": "integer", - "description": "Public Virtual Network ID used by the readiness probe VM." + "$ref": "#/components/schemas/ClusterDeployment" + }, + "example": { + "cluster": { + "id": 0 + }, + "networks": { + "public": { + "id": 105 }, - "private_network": { - "type": "integer", - "description": "Private Virtual Network ID validated by the readiness probe VM." + "private": { + "id": 106 } } - }, - "example": { - "public_network": 105, - "private_network": 106 } } } @@ -362,8 +368,73 @@ "403": { "$ref": "#/components/responses/403" }, - "405": { - "$ref": "#/components/responses/405" + "500": { + "$ref": "#/components/responses/500" + } + } + } + }, + "/clusters/deployment/validate": { + "post": { + "tags": [ + "clusters" + ], + "summary": "Validate cluster deployment placement", + "description": "Validates a OneKS deployment placement before creating a cluster. The operation checks that the target OpenNebula cluster exists, that the selected public and private networks belong to it, that the optional image datastore is available in it, and that the OneKS appliance required by the selected family is available. It does not create any OneKS resources.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterDeployment" + }, + "example": { + "cluster": { + "id": 0 + }, + "networks": { + "public": { + "id": 105 + }, + "private": { + "id": 106 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Deployment placement is valid", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "valid": { + "type": "boolean", + "description": "Whether the deployment placement can be used." + } + }, + "required": [ + "valid" + ] + }, + "example": { + "valid": true + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" @@ -1412,200 +1483,190 @@ "type": "object", "description": "OpenNebula JSON document representing a OneKS cluster", "properties": { - "DOCUMENT": { - "type": "object", - "properties": { - "ID": { - "type": "string", - "description": "ID of the resource in OpenNebula" - }, - "UID": { - "type": "string", - "description": "User ID" - }, - "GID": { - "type": "string", - "description": "Group ID" - }, - "UNAME": { - "type": "string", - "description": "Username" - }, - "GNAME": { - "type": "string", - "description": "Group name" - }, - "NAME": { - "type": "string", - "description": "Name of the object" - }, - "TYPE": { - "type": "string", - "description": "Type identifier of the object" - }, - "PERMISSIONS": { + "DOCUMENT": { "type": "object", - "description": "Permission bits for the object (U: Use, M: Manage, A: Admin)", "properties": { - "OWNER_U": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "OWNER_M": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "OWNER_A": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "GROUP_U": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "GROUP_M": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "GROUP_A": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "OTHER_U": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "OTHER_M": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "OTHER_A": { - "type": "string", - "enum": [ - "0", - "1" - ] - } - } - }, - "TEMPLATE": { - "type": "object", - "properties": { - "CLUSTER_BODY": { + "ID": { + "type": "string", + "description": "ID of the resource in OpenNebula" + }, + "UID": { + "type": "string", + "description": "User ID" + }, + "GID": { + "type": "string", + "description": "Group ID" + }, + "UNAME": { + "type": "string", + "description": "Username" + }, + "GNAME": { + "type": "string", + "description": "Group name" + }, + "NAME": { + "type": "string", + "description": "Name of the object" + }, + "TYPE": { + "type": "string", + "description": "Type identifier of the object" + }, + "PERMISSIONS": { "type": "object", - "description": "Cluster body information", + "description": "Permission bits for the object (U: Use, M: Manage, A: Admin)", "properties": { - "name": { + "OWNER_U": { "type": "string", - "description": "Cluster name" + "enum": [ + "0", + "1" + ] }, - "description": { + "OWNER_M": { "type": "string", - "description": "Cluster description" + "enum": [ + "0", + "1" + ] }, - "state": { + "OWNER_A": { "type": "string", - "description": "Current state of the cluster lifecycle", "enum": [ - "PENDING", - "PROVISIONING", - "RUNNING", - "SCALING", - "UPGRADING", - "DEPROVISIONING", - "DONE", - "PROVISIONING_FAILURE", - "SCALING_FAILURE", - "UPGRADING_FAILURE", - "DEPROVISIONING_FAILURE", - "WARNING" + "0", + "1" ] }, - "kubernetes_version": { + "GROUP_U": { "type": "string", - "description": "Desired Kubernetes version for the cluster" + "enum": [ + "0", + "1" + ] }, - "public_network": { - "type": "integer", - "description": "OpenNebula virtual network ID used as the public network" + "GROUP_M": { + "type": "string", + "enum": [ + "0", + "1" + ] }, - "private_network": { - "type": "integer", - "description": "OpenNebula virtual network ID used as the private network" + "GROUP_A": { + "type": "string", + "enum": [ + "0", + "1" + ] }, - "vrouter_id": { - "type": "integer", - "nullable": true, - "description": "Optional virtual router ID associated with the cluster" + "OTHER_U": { + "type": "string", + "enum": [ + "0", + "1" + ] }, - "control_plane": { - "description": "Control plane reference or expanded control plane group body. When expanded, control-plane-specific attributes such as `endpoint` may be present.", - "oneOf": [ - { - "$ref": "#/components/schemas/K8sGroupReference" - }, - { - "$ref": "#/components/schemas/K8sGroup" - } + "OTHER_M": { + "type": "string", + "enum": [ + "0", + "1" ] }, - "node_groups": { - "type": "array", - "description": "Nodegroups attached to the cluster. Entries are references in list mode and full group bodies when expanded.", - "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/K8sGroupReference" - }, - { - "$ref": "#/components/schemas/K8sGroup" + "OTHER_A": { + "type": "string", + "enum": [ + "0", + "1" + ] + } + } + }, + "TEMPLATE": { + "type": "object", + "properties": { + "CLUSTER_BODY": { + "type": "object", + "description": "Cluster body information", + "properties": { + "name": { + "type": "string", + "description": "Cluster name" + }, + "description": { + "type": "string", + "description": "Cluster description" + }, + "state": { + "type": "string", + "description": "Current state of the cluster lifecycle", + "enum": [ + "PENDING", + "PROVISIONING", + "RUNNING", + "SCALING", + "UPGRADING", + "DEPROVISIONING", + "DONE", + "PROVISIONING_FAILURE", + "SCALING_FAILURE", + "UPGRADING_FAILURE", + "DEPROVISIONING_FAILURE", + "WARNING" + ] + }, + "kubernetes_version": { + "type": "string", + "description": "Desired Kubernetes version for the cluster" + }, + "control_plane": { + "description": "Control plane reference or expanded control plane group body. When expanded, control-plane-specific attributes such as `endpoint` may be present.", + "oneOf": [ + { + "$ref": "#/components/schemas/K8sGroupReference" + }, + { + "$ref": "#/components/schemas/K8sGroup" + } + ] + }, + "node_groups": { + "type": "array", + "description": "Nodegroups attached to the cluster. Entries are references in list mode and full group bodies when expanded.", + "items": { + "oneOf": [ + { + "$ref": "#/components/schemas/K8sGroupReference" + }, + { + "$ref": "#/components/schemas/K8sGroup" + } + ] } - ] - } - }, - "registration_time": { - "type": "integer", - "format": "int64", - "description": "Unix timestamp indicating when the cluster was registered" - }, - "historic": { - "type": "array", - "description": "Historic lifecycle events registered for the cluster", - "items": { - "$ref": "#/components/schemas/HistoricEntry" - } + }, + "registration_time": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp indicating when the cluster was registered" + }, + "historic": { + "type": "array", + "description": "Historic lifecycle events registered for the cluster", + "items": { + "$ref": "#/components/schemas/HistoricEntry" + } + }, + "deployment": { + "$ref": "#/components/schemas/ClusterDeployment" + } + }, + "additionalProperties": true } - }, - "additionalProperties": true + } } } } - } - } }, "required": [ "DOCUMENT" @@ -1615,204 +1676,204 @@ "type": "object", "description": "OpenNebula JSON document representing a OneKS Kubernetes group, either a control plane or a nodegroup", "properties": { - "DOCUMENT": { - "type": "object", - "properties": { - "ID": { - "type": "string", - "description": "ID of the resource in OpenNebula" - }, - "UID": { - "type": "string", - "description": "User ID" - }, - "GID": { - "type": "string", - "description": "Group ID" - }, - "UNAME": { - "type": "string", - "description": "Username" - }, - "GNAME": { - "type": "string", - "description": "Group name" - }, - "NAME": { - "type": "string", - "description": "Name of the object" - }, - "TYPE": { - "type": "string", - "description": "Type identifier of the object" - }, - "PERMISSIONS": { + "DOCUMENT": { "type": "object", - "description": "Permission bits for the object (U: Use, M: Manage, A: Admin)", "properties": { - "OWNER_U": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "OWNER_M": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "OWNER_A": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "GROUP_U": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "GROUP_M": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "GROUP_A": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "OTHER_U": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "OTHER_M": { - "type": "string", - "enum": [ - "0", - "1" - ] - }, - "OTHER_A": { - "type": "string", - "enum": [ - "0", - "1" - ] - } - } - }, - "TEMPLATE": { - "type": "object", - "properties": { - "GROUP_BODY": { + "ID": { + "type": "string", + "description": "ID of the resource in OpenNebula" + }, + "UID": { + "type": "string", + "description": "User ID" + }, + "GID": { + "type": "string", + "description": "Group ID" + }, + "UNAME": { + "type": "string", + "description": "Username" + }, + "GNAME": { + "type": "string", + "description": "Group name" + }, + "NAME": { + "type": "string", + "description": "Name of the object" + }, + "TYPE": { + "type": "string", + "description": "Type identifier of the object" + }, + "PERMISSIONS": { "type": "object", - "description": "Group body information", + "description": "Permission bits for the object (U: Use, M: Manage, A: Admin)", "properties": { - "name": { + "OWNER_U": { "type": "string", - "description": "Group name" + "enum": [ + "0", + "1" + ] }, - "description": { + "OWNER_M": { "type": "string", - "description": "Group description" - }, - "cluster_id": { - "type": "integer", - "description": "Owning cluster ID" + "enum": [ + "0", + "1" + ] }, - "family": { + "OWNER_A": { "type": "string", - "description": "Group family name" + "enum": [ + "0", + "1" + ] }, - "flavour": { + "GROUP_U": { "type": "string", - "description": "Group flavour name" + "enum": [ + "0", + "1" + ] }, - "type": { + "GROUP_M": { "type": "string", - "description": "Group role", "enum": [ - "ControlPlane", - "NodeGroup" + "0", + "1" ] }, - "state": { + "GROUP_A": { "type": "string", - "description": "Current state of the group lifecycle", "enum": [ - "PENDING", - "BOOTSTRAPPING", - "PROVISIONING", - "RUNNING", - "SCALING", - "UPGRADING", - "DEPROVISIONING", - "DONE", - "WARNING", - "BOOTSTRAPPING_FAILURE", - "PROVISIONING_FAILURE", - "SCALING_FAILURE", - "UPGRADING_FAILURE", - "DEPROVISIONING_FAILURE" + "0", + "1" ] }, - "vms": { - "type": "array", - "description": "OpenNebula VM IDs currently associated with the group", - "items": { - "type": "integer" - } + "OTHER_U": { + "type": "string", + "enum": [ + "0", + "1" + ] }, - "dependencies": { - "type": "array", - "description": "Dependencies tracked by the group lifecycle manager", - "items": { - "$ref": "#/components/schemas/K8sDependency" - } + "OTHER_M": { + "type": "string", + "enum": [ + "0", + "1" + ] }, - "user_inputs_values": { + "OTHER_A": { + "type": "string", + "enum": [ + "0", + "1" + ] + } + } + }, + "TEMPLATE": { + "type": "object", + "properties": { + "GROUP_BODY": { "type": "object", - "description": "Resolved input values that define the desired size and capacity of the group", + "description": "Group body information", + "properties": { + "name": { + "type": "string", + "description": "Group name" + }, + "description": { + "type": "string", + "description": "Group description" + }, + "cluster_id": { + "type": "integer", + "description": "Owning cluster ID" + }, + "family": { + "type": "string", + "description": "Group family name" + }, + "flavour": { + "type": "string", + "description": "Group flavour name" + }, + "type": { + "type": "string", + "description": "Group role", + "enum": [ + "ControlPlane", + "NodeGroup" + ] + }, + "state": { + "type": "string", + "description": "Current state of the group lifecycle", + "enum": [ + "PENDING", + "BOOTSTRAPPING", + "PROVISIONING", + "RUNNING", + "SCALING", + "UPGRADING", + "DEPROVISIONING", + "DONE", + "WARNING", + "BOOTSTRAPPING_FAILURE", + "PROVISIONING_FAILURE", + "SCALING_FAILURE", + "UPGRADING_FAILURE", + "DEPROVISIONING_FAILURE" + ] + }, + "vms": { + "type": "array", + "description": "OpenNebula VM IDs currently associated with the group", + "items": { + "type": "integer" + } + }, + "dependencies": { + "type": "array", + "description": "Dependencies tracked by the group lifecycle manager", + "items": { + "$ref": "#/components/schemas/K8sDependency" + } + }, + "user_inputs_values": { + "type": "object", + "description": "Resolved input values that define the desired size and capacity of the group", + "additionalProperties": true + }, + "registration_time": { + "type": "integer", + "format": "int64", + "description": "Unix timestamp indicating when the group was registered" + }, + "historic": { + "type": "array", + "description": "Historic lifecycle events registered for the group", + "items": { + "$ref": "#/components/schemas/HistoricEntry" + } + }, + "endpoint": { + "type": "string", + "nullable": true, + "description": "Kubernetes API endpoint. This attribute is only populated for control plane groups." + } + }, "additionalProperties": true - }, - "registration_time": { - "type": "integer", - "format": "int64", - "description": "Unix timestamp indicating when the group was registered" - }, - "historic": { - "type": "array", - "description": "Historic lifecycle events registered for the group", - "items": { - "$ref": "#/components/schemas/HistoricEntry" - } - }, - "endpoint": { - "type": "string", - "nullable": true, - "description": "Kubernetes API endpoint. This attribute is only populated for control plane groups." } - }, - "additionalProperties": true + } } } } - } - } }, "required": [ "DOCUMENT" @@ -2090,13 +2151,8 @@ "type": "string", "description": "Kubernetes version to deploy" }, - "public_network": { - "type": "integer", - "description": "OpenNebula public network ID" - }, - "private_network": { - "type": "integer", - "description": "OpenNebula private network ID" + "deployment": { + "$ref": "#/components/schemas/ClusterDeployment" }, "spec": { "$ref": "#/components/schemas/ClusterControlPlaneSpec" @@ -2105,8 +2161,7 @@ "required": [ "name", "kubernetes_version", - "public_network", - "private_network", + "deployment", "spec" ] }, @@ -2229,6 +2284,65 @@ "description": "Kubeconfig content encoded as YAML text, sourced from the control plane group." } } + }, + "ClusterDeployment": { + "type": "object", + "description": "OpenNebula placement used by a OneKS cluster deployment.", + "properties": { + "cluster": { + "type": "object", + "description": "Target OpenNebula cluster where OneKS resources are deployed.", + "properties": { + "id": { + "type": "integer", + "description": "OpenNebula cluster ID." + } + }, + "required": [ + "id" + ] + }, + "networks": { + "type": "object", + "description": "Virtual Networks used by the OneKS cluster.", + "properties": { + "public": { + "type": "object", + "description": "Public Virtual Network used for external access and bootstrap connectivity.", + "properties": { + "id": { + "type": "integer", + "description": "OpenNebula public Virtual Network ID." + } + }, + "required": [ + "id" + ] + }, + "private": { + "type": "object", + "description": "Private Virtual Network used for internal Kubernetes communication.", + "properties": { + "id": { + "type": "integer", + "description": "OpenNebula private Virtual Network ID." + } + }, + "required": [ + "id" + ] + } + }, + "required": [ + "public", + "private" + ] + } + }, + "required": [ + "cluster", + "networks" + ] } }, "responses": { diff --git a/content/platform_services/oneks/getting_started/core_concepts.md b/content/platform_services/oneks/getting_started/core_concepts.md index aa0870f7..3e6ee280 100644 --- a/content/platform_services/oneks/getting_started/core_concepts.md +++ b/content/platform_services/oneks/getting_started/core_concepts.md @@ -39,8 +39,7 @@ A K8s Cluster includes: | `name` | K8s Cluster name. | | `description` | Optional human-readable description. | | `kubernetes_version` | Kubernetes version used by the K8s Cluster. | -| `public_network` | OpenNebula public Virtual Network ID. | -| `private_network` | OpenNebula private Virtual Network ID. | +| `deployment` | OpenNebula placement used by the K8s Cluster, including the target OpenNebula Cluster and public and private Virtual Networks. | | `spec` | Control-plane profile selection and input values. | | `state` | Current K8s Cluster lifecycle state. | | `control_plane` | Reference to the logical control-plane group. | diff --git a/content/platform_services/oneks/management/configuration.md b/content/platform_services/oneks/management/configuration.md index 564d5fa7..39fc399b 100644 --- a/content/platform_services/oneks/management/configuration.md +++ b/content/platform_services/oneks/management/configuration.md @@ -61,17 +61,14 @@ These options are used when OneKS runs Kubernetes commands from the Front-end Ho ## Readiness Check Configuration -The optional `:readiness` section enables the OneKS readiness check service. When it is enabled, users can validate the public and private Virtual Networks that will be used by a K8s Cluster before starting a deployment. +The optional `:readiness` section enables the OneKS readiness check service. When it is enabled, users can validate the full deployment placement that will be used by a K8s Cluster before starting a deployment. -On startup, OneKS verifies that the readiness appliance is available. If the appliance is not already imported, OneKS imports the configured marketplace appliance into the configured datastore, creating the OneKS readiness service VM template and its backing image as part of the import. +The readiness check uses the OneKS appliance dependency defined by the selected control-plane family. It deploys a temporary probe VM from the same appliance and image datastore resolution path used by the real K8s Cluster provisioning flow. Comment out the full `:readiness` section to disable the readiness check service. | Attribute | Default | Description | |-----------------------------------|-----------------------------------------|-------------| -| `:readiness` / `:appliance_name` | `OneKS Readiness Service` | Marketplace appliance name used when importing the readiness probe template if it is missing. | -| `:readiness` / `:appliance_id` | `97383e01-6150-4a1f-8830-fc5d745056e0` | Marketplace appliance UUID used to find or import the readiness probe VM template. By default, this value points to an Alpine 3.20 appliance from the OpenNebula Marketplace. | -| `:readiness` / `:appliance_ds` | `1` | Datastore ID where the readiness appliance image is imported. | | `:readiness` / `:external_url` | `https://get.rke2.io` | Public URL used by the probe VM to validate DNS resolution and outbound internet access. | | `:readiness` / `:timeout` | `60` | Maximum time, in seconds, to wait for the probe VM and each readiness check step. | @@ -203,9 +200,6 @@ OneKS relies on several OpenNebula services and network endpoints: ################################################################################ :readiness: - :appliance_name: 'OneKS Readiness Service' - :appliance_id: 97383e01-6150-4a1f-8830-fc5d745056e0 - :appliance_ds: 1 :external_url: 'https://get.rke2.io' :timeout: 60 diff --git a/content/platform_services/oneks/management/k8s_cluster_lifecycle_management.md b/content/platform_services/oneks/management/k8s_cluster_lifecycle_management.md index 251911a6..19f709a4 100644 --- a/content/platform_services/oneks/management/k8s_cluster_lifecycle_management.md +++ b/content/platform_services/oneks/management/k8s_cluster_lifecycle_management.md @@ -31,6 +31,7 @@ Before creating a K8s Cluster, verify that: * **OneKS Service**: The OneKS service is configured and running. * **OneGate Service**: OneGate is configured and reachable. * **Transparent Proxy**: `tproxy` is configured for the required OneGate and OpenNebula XML-RPC ports. +* **OpenNebula Cluster**: The target OpenNebula Cluster ID is known. * **Networks**: The OpenNebula public and private Virtual Network IDs are known. * **Profiles**: The required family and flavour are available. * **Kubernetes Version**: The target Kubernetes version is supported by the selected family. @@ -41,6 +42,8 @@ Before creating a K8s Cluster, verify that: For more detailed information about the basic configuration and requirements needed to create K8s Clusters, refer to the [Basic Configuration Guide]({{% relref "platform_services/oneks/getting_started/basic_configuration" %}}). {{< /alert >}} +Deployment options let you choose where each K8s Cluster is placed and which OpenNebula resources it uses. This makes it possible to provision independent K8s Clusters in different OpenNebula Clusters from the same OneKS service. For each deployment, you can select the target OpenNebula Cluster and the public and private Virtual Networks that will be used by the K8s Cluster. The selected networks must be available in the target OpenNebula Cluster. The OneKS appliance required by the selected control-plane family must also be available in an image datastore that can be used from that placement. + {{< tabpane text=true right=false >}} {{% tab header="**Interfaces**:" disabled=true /%}} @@ -54,6 +57,7 @@ alt="OneKS create Cluster step 1" align="center" width="90%" mb="20px" >}} The wizard guides you through the required configuration steps: * **General**: K8s Cluster name and optional description. +* **Select a OpenNebula Cluster ID**: The OpenNebula Cluster used for K8s Cluster placement. * **Select a Public Virtual Network**: Public network used for external connectivity and bootstrap paths. * **Select a Private Virtual Network**: Private network used for internal K8s Cluster communication. * **Kubernetes Version**: Kubernetes version to deploy. @@ -79,6 +83,14 @@ ID USER GROUP NAME CLUSTERS BRIDGE STATE 0 oneadmin oneadmin public 0 br1 rdy ``` +Also identify the OpenNebula Cluster where the K8s Cluster must be deployed: + +```shell +$ onecluster list +ID NAME HOSTS VNETS DATASTORES + 0 default 2 2 3 +``` + Launch the interactive K8s Cluster creation command. You can add `--wait` to subscribe to the deployment logs and keep the command attached until the operation completes or reaches a terminal state: ```shell @@ -88,10 +100,11 @@ oneks create cluster --wait The interactive CLI flow asks for: * **K8s Cluster Name**: The name used to identify the OneKS K8s Cluster. -* **Kubernetes Version**: The Kubernetes version to deploy. -* **K8s Cluster Flavour**: The control-plane flavour, such as `standalone` or `ha`. +* **OpenNebula Cluster ID**: The OpenNebula Cluster used for K8s Cluster placement. * **Public Network ID**: The OpenNebula public Virtual Network used by the K8s Cluster. * **Private Network ID**: The OpenNebula private Virtual Network used by the K8s Cluster. +* **Kubernetes Version**: The Kubernetes version to deploy. +* **K8s Cluster Flavour**: The control-plane flavour, such as `standalone` or `ha`. {{< image path="/images/oneks/light/k8s_cluster_create_cli.png" alt="K8s Cluster create CLI menu" align="center" width="60%" mb="20px" >}} @@ -108,8 +121,19 @@ Example `spec.json`: "name": "prod-cluster", "description": "Production Kubernetes cluster", "kubernetes_version": "v1.32.9", - "public_network": 12, - "private_network": 34, + "deployment": { + "cluster": { + "id": 0 + }, + "networks": { + "public": { + "id": 12 + }, + "private": { + "id": 34 + } + } + }, "spec": { "flavour": "ha" } @@ -130,8 +154,19 @@ curl -u "$(cat /var/lib/one/.one/one_auth)" \ "name": "prod-cluster", "description": "Production Kubernetes cluster", "kubernetes_version": "v1.32.9", - "public_network": 0, - "private_network": 1, + "deployment": { + "cluster": { + "id": 0 + }, + "networks": { + "public": { + "id": 0 + }, + "private": { + "id": 1 + } + } + }, "spec": { "flavour": "ha" } diff --git a/content/platform_services/oneks/management/monitoring_and_troubleshooting.md b/content/platform_services/oneks/management/monitoring_and_troubleshooting.md index 5c330fae..4d2c05bc 100644 --- a/content/platform_services/oneks/management/monitoring_and_troubleshooting.md +++ b/content/platform_services/oneks/management/monitoring_and_troubleshooting.md @@ -150,9 +150,9 @@ K8s Cluster provisioning can fail for different infrastructure or network-relate ### OneKS Readiness Check -If the OneKS readiness check service is enabled, use it to validate the public and private Virtual Networks used by a K8s Cluster. The check deploys a temporary lightweight probe VM and verifies the main requirements needed by OneKS provisioning, including OneGate access, internet connectivity, and private network paths. For configuration details, see the [Readiness Check Configuration]({{% relref "platform_services/oneks/management/configuration#readiness-check-configuration" %}}). For command syntax, see the [`oneks check` CLI reference]({{% relref "platform_services/oneks/references/oneks_cli#readiness-checks" %}}). +If the OneKS readiness check service is enabled, use it to validate the deployment placement used by a K8s Cluster. The check deploys a temporary probe VM from the same OneKS appliance used by provisioning and verifies the main requirements needed by OneKS, including the target OpenNebula Cluster, selected networks, appliance availability, OneGate access, internet connectivity, and private network paths. For configuration details, see the [Readiness Check Configuration]({{% relref "platform_services/oneks/management/configuration#readiness-check-configuration" %}}). For command syntax, see the [`oneks check` CLI reference]({{% relref "platform_services/oneks/references/oneks_cli#readiness-checks" %}}). -When a deployment fails, run the readiness check against the failed K8s Cluster. OneKS resolves the networks from the Cluster document: +When a deployment fails, run the readiness check against the failed K8s Cluster. OneKS resolves the deployment placement from the Cluster document: ```shell oneks check cluster @@ -172,10 +172,11 @@ When all checks pass, the command reports each validated step: [OK] All OneKS readiness checks passed ``` -You can also run the check before creating a K8s Cluster by passing the networks explicitly: +You can also run the check before creating a K8s Cluster by passing the deployment placement explicitly: ```shell -oneks check --public-network --private-network +oneks check --opennebula-cluster \ + --public-network --private-network ``` If the readiness check fails, the tool reports the failing step and the environment problem that must be fixed. For example, if the probe VM cannot access OneGate: diff --git a/content/platform_services/oneks/references/oneks_cli.md b/content/platform_services/oneks/references/oneks_cli.md index e3acb87a..9bbadee8 100644 --- a/content/platform_services/oneks/references/oneks_cli.md +++ b/content/platform_services/oneks/references/oneks_cli.md @@ -43,7 +43,7 @@ Some builds may expose node groups through the lower-level `group` resource in C * `oneks create nodegroup --cluster-id `: Create a node group. * `oneks recover cluster `: Recover a K8s Cluster from selected failure states. * `oneks recover nodegroup `: Recover a node group from selected failure states. -* `oneks check cluster `: Run the OneKS readiness check using the networks from an existing K8s Cluster. +* `oneks check cluster `: Run the OneKS readiness check using the deployment placement from an existing K8s Cluster. * `oneks delete cluster `: Delete a K8s Cluster. * `oneks delete nodegroup `: Delete a node group. * `oneks logs cluster `: Show K8s Cluster logs. @@ -98,7 +98,7 @@ Run OneKS readiness checks: ```shell oneks check cluster 42 -oneks check --public-network 105 --private-network 106 +oneks check --opennebula-cluster 0 --public-network 105 --private-network 106 ``` Inspect logs: From 579beefd01d30c12e5aeab5c13dc11b19a39d663 Mon Sep 17 00:00:00 2001 From: Victor Palma Date: Wed, 10 Jun 2026 12:17:55 +0200 Subject: [PATCH 2/3] M OpenNebula/one#7676: Replace shell screenshots with actual shell output text --- .../k8s_cluster_lifecycle_management.md | 82 +++++++++++++++---- 1 file changed, 67 insertions(+), 15 deletions(-) diff --git a/content/platform_services/oneks/management/k8s_cluster_lifecycle_management.md b/content/platform_services/oneks/management/k8s_cluster_lifecycle_management.md index 19f709a4..68af7876 100644 --- a/content/platform_services/oneks/management/k8s_cluster_lifecycle_management.md +++ b/content/platform_services/oneks/management/k8s_cluster_lifecycle_management.md @@ -106,7 +106,37 @@ The interactive CLI flow asks for: * **Kubernetes Version**: The Kubernetes version to deploy. * **K8s Cluster Flavour**: The control-plane flavour, such as `standalone` or `ha`. -{{< image path="/images/oneks/light/k8s_cluster_create_cli.png" alt="K8s Cluster create CLI menu" align="center" width="60%" mb="20px" >}} +```shell +$ oneks create cluster +> Cluster name: example-oneks-cluster + +DEPLOYMENT PLACEMENT +> OpenNebula cluster ID: 0 +> Public network ID: 0 +> Private network ID: 1 + +ONEKS SPEC +> Select a Kubernetes version for the Cluster: + 0: v1.33.7 + 1: v1.34.2 + + Select an option by number: 1 + +> Select a flavour for the Cluster: + 0: Single-Node Control Plane + Single Control Plane node deployment. + Suitable for development, evaluation, and non-critical workloads. + 1 node | 2 CPU | 2 vCPU | 4 GB RAM | 16 GB Storage + + 1: Highly Available Control Plane + Three-node Control Plane deployment with built-in redundancy. + Suitable for production and other environments that require higher availability. + 3 nodes | 2 CPU | 2 vCPU | 4 GB RAM | 16 GB Storage + + Select an option by number: 1 + +ID: 10 +``` You can also create a K8s Cluster from a JSON specification: @@ -120,7 +150,7 @@ Example `spec.json`: { "name": "prod-cluster", "description": "Production Kubernetes cluster", - "kubernetes_version": "v1.32.9", + "kubernetes_version": "v1.34.2", "deployment": { "cluster": { "id": 0 @@ -153,7 +183,7 @@ curl -u "$(cat /var/lib/one/.one/one_auth)" \ -d '{ "name": "prod-cluster", "description": "Production Kubernetes cluster", - "kubernetes_version": "v1.32.9", + "kubernetes_version": "v1.34.2", "deployment": { "cluster": { "id": 0 @@ -271,7 +301,29 @@ The command starts an interactive creation flow. You will be asked to provide: * **Flavour**: The worker node size profile to use. * **Count**: The number of worker nodes to create. -{{< image path="/images/oneks/light/oneks_create_nodegroup_cli.png" alt="OneKS create nodegroup CLI" align="center" width="60%" mb="20px" >}} +```shell +$ oneks create group --cluster-id 10 +> Nodegroup name: example-oneks-group +> Select a flavour for the Nodegroup: + 0: Small Worker Nodes + Small worker node profile for lightweight workloads. + 2 CPU | 2 vCPU | 4 GB RAM | 16 GB Storage + + 1: Medium Worker Nodes + Medium worker node profile for balanced workloads. + 4 CPU | 4 vCPU | 8 GB RAM | 32 GB Storage + + 2: Large Worker Nodes + Large worker node profile for demanding workloads. + 8 CPU | 8 vCPU | 16 GB RAM | 64 GB Storage + + Select an option by number: 2 +There are some parameters that require user input. + * (count) Number of Worker nodes [type: number] + Enter a number: 1 + +ID: 11 +``` Scale a node group by specifying its ID and the desired number of worker nodes: @@ -282,7 +334,7 @@ oneks scale nodegroup --target Example: ```shell -oneks scale nodegroup 7 --target 3 +oneks scale nodegroup 11 --target 3 ``` Validate the Kubernetes node list: @@ -290,10 +342,10 @@ Validate the Kubernetes node list: ```shell $ KUBECONFIG=./kubeconfig kubectl get nodes NAME STATUS ROLES AGE VERSION -test-cluster-control-plane Ready control-plane 9m v1.31.4 -test-cluster-worker-1 Ready 2m v1.31.4 -test-cluster-worker-2 Ready 2m v1.31.4 -test-cluster-worker-3 Ready 2m v1.31.4 +test-cluster-control-plane Ready control-plane 9m v1.34.2 +test-cluster-worker-1 Ready 2m v1.34.2 +test-cluster-worker-2 Ready 2m v1.34.2 +test-cluster-worker-3 Ready 2m v1.34.2 ``` {{% /tab %}} @@ -331,10 +383,10 @@ Validate the Kubernetes node list: ```shell $ KUBECONFIG=./kubeconfig kubectl get nodes NAME STATUS ROLES AGE VERSION -test-cluster-control-plane Ready control-plane 9m v1.31.4 -test-cluster-worker-1 Ready 2m v1.31.4 -test-cluster-worker-2 Ready 2m v1.31.4 -test-cluster-worker-3 Ready 2m v1.31.4 +test-cluster-control-plane Ready control-plane 9m v1.34.2 +test-cluster-worker-1 Ready 2m v1.34.2 +test-cluster-worker-2 Ready 2m v1.34.2 +test-cluster-worker-3 Ready 2m v1.34.2 ``` For further details about the API, see the [OneKS REST API Reference]({{% relref "platform_services/oneks/references/oneks_api/" %}}). @@ -381,7 +433,7 @@ oneks upgrade cluster --k8s-version Example: ```shell -oneks upgrade cluster 42 --k8s-version v1.32.9 +oneks upgrade cluster 42 --k8s-version v1.34.2 ``` After the upgrade starts, inspect the K8s Cluster state: @@ -405,7 +457,7 @@ curl -u "$(cat /var/lib/one/.one/one_auth)" \ -X POST http://:10780/api/v1/clusters//upgrade \ -H "Content-Type: application/json" \ -d '{ - "kubernetes_version": "v1.32.9" + "kubernetes_version": "v1.34.2" }' ``` From ad27734f6d18f7022227040041a0b105be483e2b Mon Sep 17 00:00:00 2001 From: Victor Palma Date: Mon, 15 Jun 2026 15:47:16 +0200 Subject: [PATCH 3/3] M OpenNebula/one#7676: Update whats new --- .../software/release_information/release_notes/whats_new.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/software/release_information/release_notes/whats_new.md b/content/software/release_information/release_notes/whats_new.md index b68a18a7..b7acf0ae 100644 --- a/content/software/release_information/release_notes/whats_new.md +++ b/content/software/release_information/release_notes/whats_new.md @@ -35,6 +35,10 @@ The OpenNebula team is excited to announce the availability of the **OpenNebula ## OpenNebula Form +## OpenNebula Elastic Kubernetes Service + +* Added multi-cluster deployment support in OneKS, allowing users to select the target OpenNebula cluster and deployment networks when creating Kubernetes Clusters. + ## Packaging ## Features Backported to 7.2.x