> This page is for NVIDIA Kubernetes Engine. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nvke/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nvke/_mcp/server. # List clusters GET https://nvke.acme.example/api/clusters Returns all clusters, or the cluster whose name matches `name`. Reference: https://docs.nvidia.com/nvke/rest-api-reference/clusters/list-clusters ## Authentication - `Authorization` header (bearer token, required) — A JWT from an issuer the Operator has configured, carried as `Authorization: Bearer `. ## Request ### Query parameters - `name` (string, optional) — Filter clusters by name (exact match) ## Response ### 200 A list of clusters - `clusters` (list of Cluster, required) — Clusters. ## Errors ### 401 Unauthorized Error No valid bearer token was presented. - `message` (string, required) — What went wrong. ### 403 Forbidden Error The token verified, but its subject matches no admission rule. - `message` (string, required) — What went wrong. ## Types ### Cluster A Kubernetes cluster. Holds the Kubernetes version, network, CNI, etcd encryption, control-plane configuration and conditions. - `id` (string, required) — Cluster ID. - `name` (string, required) — Cluster name. - `controlPlaneKubernetesVersion` (string, required) — Desired control-plane Kubernetes version. The running version is in ControlPlaneStatus. - `cniPlugin` (string, required) — CNI plugin. - `cniVersion` (string, required) — CNI version. - `etcdEncrypted` (boolean, required) — Whether etcd is encrypted at rest. - `network` (ClusterNetwork, required) — Pod and service network. - `createdAt` (datetime, required) — Creation time. - `conditions` (ClusterConditions, required) — Lifecycle conditions. - `controlPlaneVIP` (string, optional) — API server VIP, if configured. - `enableCPNodeRecycling` (boolean, optional, default: false) — When true, control-plane upgrades and configuration changes replace nodes automatically. When false, nodes needing replacement are reported as pending and wait for an operator. - `controlPlaneConfig` (ControlPlaneConfig, optional) — Current control-plane configuration. - `nico` (NicoClusterProvider, optional) — NICo identifiers. - `launchLayer` (LaunchLayerClusterProvider, optional) — LaunchLayer identifiers. - `nodeAgentUpgrade` (NodeAgentUpgradeStatus, optional) — The active agent upgrade and latest retry error. ### ClusterNetwork Pod and service network in effect. Both fields are always present. - `podCIDR` (string, required) — Comma-separated IPv4 pod CIDRs in effect. - `serviceCIDR` (string, required) — IPv4 service CIDR in effect. ### ClusterConditions Lifecycle conditions of a cluster. Each is a Condition. - `provisioning` (Condition, required) — The cluster is provisioning. - `provisioned` (Condition, required) — The cluster is provisioned. - `deleting` (Condition, required) — The cluster is being deleted. - `cpNodesRecycling` (Condition, optional) — Control-plane nodes are being replaced. - `controlPlaneUpgrading` (Condition, optional) — The control plane is being upgraded. - `updateInProgress` (UpdateInProgress, optional) — The mutually exclusive cluster operation in progress, if any. Absent when none. - `updateFailed` (Condition, optional) — The most recent cluster update failed. ### ControlPlaneConfig The control-plane configuration in effect, including the desired node-agent version. - `configurationId` (string, optional) — ID of the current configuration snapshot. - `desiredCount` (integer, optional) — The desired number of cluster-level control plane nodes. Creating a cluster with or increasing this count above 1 requires controlPlaneVIP on the cluster. - `maxSurge` (integer, optional) — Extra control-plane nodes allowed during a rollout (0 or 1). - `provisioningMonitorDisabled` (boolean, optional) — When true, nodes stuck in provisioning past the timeout are not replaced automatically. - `systemReservedMemory` (string, optional) — Memory reserved for system daemons. Nodes reserve 16Gi when omitted. - `machineAnnotations` (map from string to string, optional) — Annotations applied to control-plane CAPI Machines at creation, including scale-out and replacement Machines. Fixed at cluster creation and not reconciled after provisioning. Keys under nke.nvidia.com, nke.io, nvke.nvidia.com, kubernetes.io, k8s.io, cluster.x-k8s.io and their subdomains require an explicit deployment allowlist entry for this metadata type. - `machineLabels` (map from string to string, optional) — Labels applied to control-plane CAPI Machines at creation, including scale-out and replacement Machines. Fixed at cluster creation and not reconciled after provisioning. Keys under nke.nvidia.com, nke.io, nvke.nvidia.com, kubernetes.io, k8s.io, cluster.x-k8s.io and their subdomains require an explicit deployment allowlist entry for this metadata type. - `nodeLabels` (map from string to string, optional) — Labels applied to control-plane nodes, as a map of keys to values. Set at creation. - `nico` (NicoControlPlaneProvider, optional) — NICo settings for control-plane nodes. - `launchLayer` (LaunchLayerControlPlaneProvider, optional) — LaunchLayer settings for control-plane nodes. - `nodeAgentConfig` (NodeAgentConfig, optional) — Desired control-plane node-agent configuration. ### NicoClusterProvider NICo identifiers for the cluster. Fixed at creation. - `orgID` (string, optional) — Organization that owns the cluster. - `siteID` (string, optional) — NICo site ID. - `vpcID` (string, optional) — NICo VPC ID. ### LaunchLayerClusterProvider LaunchLayer identifiers for the cluster. Exactly one of vpcID or orgID must be set, and siteID is required. All fields are fixed at creation. - `siteID` (string, required) — Names the LaunchLayer datahall this cluster's machines come from. - `vpcID` (string, optional) — An existing LaunchLayer VPC that CAPLL observes but never deletes. - `orgID` (string, optional) — Organization in which CAPLL creates a VPC when vpcID is omitted. - `vpcType` (enum, optional) — Network type for a managed or existing VPC. When omitted, CAPLL treats the VPC as VIRTUALIZED. A VIRTUALIZED security group needs a VIRTUALIZED VPC. - Allowed values: `BARE_METAL`, `VIRTUALIZED` - `cloudProviderEnabled` (boolean, optional) — Set true where a cloud controller manager runs, so CAPLL leaves the Node's provider ID to it. NVKE runs no CCM, so true is rejected. - `owner` (LaunchLayerClusterOwner, optional) — The LaunchLayer identity requests are attributed to. - `securityGroups` (list of LaunchLayerSecurityGroup, optional) — Security groups CAPLL creates with the cluster and deletes with it. ### NodeAgentUpgradeStatus The active agent upgrade and latest retry error. - `nodeId` (string, required) — ID of the selected control-plane node. - `targetVersion` (string, required) — Exact version accepted for this upgrade. - `method` (string, required) — Installation method from the controller configuration. - `phase` (enum, required) — Pending before installation starts. Running includes retries. - Allowed values: `Pending`, `Running` - `errorMessage` (string, required) — Latest failure message while retries continue. ### Condition A status, when it last changed, and a message. - `status` (enum, required) — Condition status. - Allowed values: `True`, `False`, `Unknown` - `lastTransitionTime` (datetime, required) — When the status last changed. - `message` (string, required) — Human-readable detail. May be empty. ### UpdateInProgress The mutually exclusive cluster operation in progress. Absent when none. - `type` (enum, required) — Operation in progress. - Allowed values: `etcd_encryption`, `k8s_upgrade`, `cp_nodes_recycling`, `oidc_enable` - `startedAt` (datetime, required) — Start time. - `message` (string, optional) — Detail. ### NicoControlPlaneProvider NICo settings for the control-plane nodes, as reported on read. Requests use NicoControlPlaneProviderCreate and NicoControlPlaneProviderUpdate, which omit the fields that direction cannot set. - `instanceTypePreference` (list of string, optional) — Ordered list of acceptable NICo instance types; index 0 is the highest priority. - `subnetIDs` (list of string, optional) — Subnets, for sites without native networking. - `vpcPrefixIDs` (list of string, optional) — VPC prefixes, for sites with native networking. - `release` (string, optional) — Name of a release the Operator has supplied to the management plane. - `diskSelectionStrategy` (enum, optional) — Always smallest for control-plane nodes. Not configurable through the API. - Allowed values: `smallest`, `largest` - `sshKeyGroupIDs` (list of string, optional) — SSH key groups for node access. Can be updated. ### LaunchLayerControlPlaneProvider LaunchLayer settings for the control-plane nodes. Same shape as LaunchLayerNodePoolProvider — control-plane nodes are still LaunchLayer machines. Fixed at creation. - `instanceType` (string, required) — Requests capacity of a given shape, for example "vm200". - `hostOSProfile` (string, optional) — Bare-metal profile, as "\" or "\:\". Mutually exclusive with vmProfile. - `vmProfile` (string, optional) — Virtual profile, as "\" or "\:\". Mutually exclusive with hostOSProfile. - `fulfillmentStrategy` (enum, optional) — Controls how the Compute Allocation Operator places the request. - Allowed values: `BEST_EFFORT`, `ALL_OR_NOTHING`, `WAIT_FOR_RESOURCE` - `securityGroupRefs` (LaunchLayerSecurityGroupRefs, optional) — Names of the owning cluster's managed security groups to attach, per network interface. Mutually exclusive with securityGroups (existing group IDs) per interface — CAPLL supports both but NVKE always creates groups through the cluster, so NVKE only exposes refs. ### NodeAgentConfig Desired control-plane node-agent configuration. - `version` (string, optional) — Exact agent release version. An empty value disables agent convergence. ### LaunchLayerClusterOwner The LaunchLayer identity requests are attributed to. - `userID` (string, optional) — LaunchLayer user ID. - `username` (string, optional) — LaunchLayer username. ### LaunchLayerSecurityGroup A security group LaunchLayer creates with the cluster and deletes with it. - `name` (string, required) — Security group name, referenced by node pools via securityGroupRefs. A DNS label of at most 24 characters, unique within the cluster. - `type` (enum, required) — Immutable. A virtual VPC can contain both kinds of groups. - Allowed values: `BARE_METAL`, `VIRTUALIZED` - `networkType` (enum, optional) — Required for a VIRTUALIZED group and rejected for a BARE_METAL group. - Allowed values: `primary`, `secondary` ### LaunchLayerSecurityGroupRefs Names of the owning cluster's managed security groups to attach, per network interface. Mutually exclusive with securityGroups (existing group IDs) per interface — CAPLL supports both but NVKE always creates groups through the cluster, so NVKE only exposes refs. - `primaryNetworkInterface` (list of string, optional) — Managed security group names to attach to the primary network interface. - `gpuNetworkInterface` (list of string, optional) — Managed security group names to attach to the GPU network interface. ## Examples **Request** ```json {} ``` **Response** ```json { "clusters": [ { "id": "a3f1c2d4-5e6b-7890-abcd-ef1234567890", "name": "tenant-a-prod", "controlPlaneKubernetesVersion": "1.29.3", "cniPlugin": "ovn-kubernetes", "cniVersion": "2.4.2", "etcdEncrypted": true, "network": { "podCIDR": "192.168.0.0/16", "serviceCIDR": "10.96.0.0/12" }, "createdAt": "2024-01-15T09:30:00Z", "conditions": { "provisioning": { "status": "False", "lastTransitionTime": "2024-01-15T09:45:00Z", "message": "Cluster provisioning completed successfully" }, "provisioned": { "status": "True", "lastTransitionTime": "2024-01-15T09:45:00Z", "message": "All control-plane nodes are ready" }, "deleting": { "status": "False", "lastTransitionTime": "2024-01-15T09:30:00Z", "message": "" }, "cpNodesRecycling": { "status": "False", "lastTransitionTime": "2024-01-15T09:45:00Z", "message": "" }, "controlPlaneUpgrading": { "status": "False", "lastTransitionTime": "2024-01-15T09:45:00Z", "message": "" }, "updateInProgress": { "type": "k8s_upgrade", "startedAt": "2024-03-20T14:00:00Z", "message": "Upgrading control plane from 1.28.7 to 1.29.3" }, "updateFailed": { "status": "False", "lastTransitionTime": "2024-01-15T09:45:00Z", "message": "" } }, "controlPlaneVIP": "10.10.0.50", "enableCPNodeRecycling": false, "controlPlaneConfig": { "configurationId": "b7e2d1a0-3c4f-4e8a-9b12-cd5678901234", "desiredCount": 3, "maxSurge": 1, "provisioningMonitorDisabled": false, "systemReservedMemory": "16Gi", "machineAnnotations": {}, "machineLabels": {}, "nodeLabels": {}, "nico": { "instanceTypePreference": [ "c1d2e3f4-a5b6-7890-abcd-111122223333" ], "subnetIDs": [ "d4e5f6a7-b8c9-0123-def0-444455556666" ], "vpcPrefixIDs": [ "e7f8a9b0-c1d2-3456-ef01-777788889999" ], "release": "example-ubuntu-24.04-amd64", "diskSelectionStrategy": "smallest", "sshKeyGroupIDs": [ "f0a1b2c3-d4e5-6789-f012-aaaabbbbcccc" ] }, "launchLayer": { "instanceType": "vm200", "hostOSProfile": "ubuntu-24.04-amd64", "vmProfile": "standard-vm:1.2.0", "fulfillmentStrategy": "BEST_EFFORT", "securityGroupRefs": { "primaryNetworkInterface": [ "cp-primary-sg" ], "gpuNetworkInterface": [ "cp-gpu-sg" ] } }, "nodeAgentConfig": { "version": "1.5.2" } }, "nico": { "orgID": "dipfedrcvjiw", "siteID": "11223344-5566-7788-99aa-bbccddeeff00", "vpcID": "aabbccdd-eeff-0011-2233-445566778899" }, "launchLayer": { "siteID": "datahall-us-west-1", "vpcID": "vpc-0a1b2c3d4e5f67890", "orgID": "org-acme-infra", "vpcType": "BARE_METAL", "cloudProviderEnabled": false, "owner": { "userID": "usr-7f8e9d0c1b2a3456", "username": "platform-admin" }, "securityGroups": [ { "name": "cp-primary-sg", "type": "BARE_METAL", "networkType": "primary" } ] }, "nodeAgentUpgrade": { "nodeId": "cc112233-4455-6677-8899-aabbccddeeff", "targetVersion": "1.5.2", "method": "apt", "phase": "Running", "errorMessage": "connection timeout on attempt 2, retrying" } } ] } ``` **SDK Code** ```python import requests url = "https://nvke.acme.example/api/clusters" payload = {} headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.get(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://nvke.acme.example/api/clusters'; const options = { method: 'GET', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://nvke.acme.example/api/clusters" payload := strings.NewReader("{}") req, _ := http.NewRequest("GET", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://nvke.acme.example/api/clusters") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://nvke.acme.example/api/clusters") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('GET', 'https://nvke.acme.example/api/clusters', [ 'body' => '{}', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://nvke.acme.example/api/clusters"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://nvke.acme.example/api/clusters")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```