Serverless model changes on 11 December 2026: Qwen3.8-Flash-Next-FP8 and Qwen3-Embedding-8B are being retired, and Mistral-Large-3-675B-Instruct-2512-NVFP4 is moving to dedicated models. See what to do.
Manage Nscale Kubernetes Service clusters, node pools, platform releases, and kubeconfigs.
Aliases:kubernetes, k8sManage Nscale Kubernetes Service (NKS) clusters, the node pools that provide their worker capacity, and the platform releases they run on. Every command except token acts in the organization given by --org, or the one saved in your context.A typical workflow:
Cluster and node pool writes are asynchronous: the API accepts the request and does the work in the background. Pass --wait to block until the resource settles. If --wait-timeout runs out first, or you press Ctrl+C, the command prints the resource as it stands and exits non-zero, naming the get command to check on it later. The operation carries on server-side. If the resource reaches a failure state, the command prints nothing and exits non-zero, naming the get command that shows why.Commands that act on one resource take its ID or name either as a positional argument or with --id. If you omit it, the CLI opens an interactive picker, so always pass it in scripts.Every ID flag and positional argument, including --cluster, --project, --region, and --network, accepts a name as well as an ID. A name that matches no resource, or more than one, fails and lists the candidates.
Show at most N results (client-side; every result is still fetched). Cuts before -q. 0 for all
Examples
nscale k8s cluster list --project <project-id>nscale k8s cluster list --provisioning-status provisioned -q ".[].metadata.id"nscale k8s cluster list -q '.[].metadata.id' -q '.[].metadata.name'
cluster get
Get details for a specific cluster, including its platform release, API server endpoints, and status. The status includes status.serviceAccountIssuer, the cluster’s public OpenID Connect issuer URL for its service account tokens.
nscale kubernetes cluster get <cluster-id> --org <org-id>
Flags
Flag
Description
Organization ID or name
Cluster ID or name
Emit the full JSON payload (mutually exclusive with -q)
nscale k8s cluster get <cluster-id> -q '.metadata.provisioningStatus' -q '.metadata.healthStatus'nscale k8s cluster get <cluster-id> -q '.status.serviceAccountIssuer'
cluster create
Create a new Kubernetes cluster. Accepts input from a JSON file or stdin. With neither, the CLI prompts for the cluster’s name, description, network, SSH certificate authority, platform release, pod and service networks, API server access, API server authentication and authorization, and addons.Two of the prompts set fields that can’t be changed after creation:
SSH certificate authority. If the network’s project has any SSH certificate authorities, the CLI asks whether the workers should trust one and offers a picker. With none in the project, the question is skipped.
API server authentication and authorization. The CLI asks whether to configure them; most clusters answer no. Answer yes to choose whether the API server accepts Nscale credentials (the platform default, enabled, or disabled), add up to eight external OpenID Connect issuers, and bind users and groups to the built-in cluster-admin, admin, edit, and view cluster roles. For each issuer, the CLI asks for the HTTPS issuer URL, the token audiences, the username claim and the required username prefix, an optional groups claim with its prefix, and an optional CA certificate, read from a PEM file you pick. If you disable Nscale credentials, you must add at least one issuer, otherwise nobody could sign in. Role binding subjects must include the issuer’s username or groups prefix. See Use your own identity provider.
The cluster is attached to an existing network. Platform releases are regional, so pick one available in the network’s region. Use nscale networks list and release list to discover the IDs.
Let people sign in with your own OpenID Connect provider and bind them to built-in roles. Cannot be changed after creation. See Use your own identity provider
spec.addons.hardware.enabled
No
Install the drivers and plugins that GPUs and the HPC network need (default true). The core profile is always installed
spec.addons.nodeHealth.enabled
No
Detect and report problems with the cluster’s nodes (default true). Only applies when the platform release provides it
Update an existing cluster. Accepts input from a JSON file or stdin; with neither, the CLI prompts for each field, pre-filled from the cluster as it stands.The payload has the same shape as cluster create and replaces the cluster’s desired state, so include every field you want to keep. The cluster’s name, spec.networkId, spec.sshCertificateAuthorityId, and the API server’s authentication and authorization cannot change. The prompts don’t ask for these fields and carry them over from the cluster unchanged, starting at the description. The update is applied asynchronously.
nscale k8s nodepool get <node-pool-id> -q '.metadata.name' -q '.metadata.provisioningStatus'
nodepool create
Create a new node pool in a cluster. Accepts input from a JSON file or stdin; with neither, the CLI prompts for the cluster, name, description, capacity source, flavor or reservation, replica count, labels, and taints. Enter labels as a comma-separated key=value list, for example nscale.com/team=ml,gpu; a key on its own sets an empty value. To set a reservation pool’s placement policy, use a file.The flavor picker leaves out pinned-only flavors, which only reservations can use.Workers come either from a compute flavor or from reserved capacity in a reservation, chosen with spec.provisioningMode. For how the two kinds of pool differ, see Compute pools and reservation pools.
Update an existing node pool, for example to resize it or change its taints. Accepts input from a JSON file or stdin; with neither, the CLI prompts for each field, pre-filled from the node pool as it stands.The payload has the same shape as nodepool create and replaces the node pool’s desired state, so include every field you want to keep. The prompts ask for the same fields as nodepool create except the cluster and the name, pre-filled with the pool’s current values, including its labels. The cluster, the name, and the placement policy carry over unchanged, since node pools can’t be renamed. The update is applied asynchronously.Changing labels or taints rolls the pool’s existing workers, replacing them with new ones that carry the new values. The labels prompt warns you of this.
Only compute pools can be changed. A reservation pool’s host count, placement policy, taints, and labels are fixed when it’s created. To change any of them, create a new pool and delete the old one.
List the platform releases offered to the organization, including releases shared with every organization. Each release provides a Kubernetes version, the CPU architectures it supports, and the versions of its addon components. To see only the releases a new cluster should use, pass --deprecated=false --withdrawn=false.
nscale kubernetes release list --org <org-id> [flags]
Aliases:list, ls
Flags
Flag
Description
Organization ID or name
Only show releases available in this region (ID or name)
Only show releases supporting this CPU architecture — x86_64 or aarch64
Only show deprecated releases; pass for only non-deprecated ones
Only show withdrawn releases; pass for only available ones
Emit the full JSON payload (mutually exclusive with -q)
Show at most N results (client-side; every result is still fetched). Cuts before -q. 0 for all
Examples
nscale k8s release list --region <region-id> --deprecated=false --withdrawn=falsenscale k8s release list --withdrawn=false --deprecated=false -q '.[].metadata.id' -q '.[].status.kubernetesVersion'
release get
Get details for a specific platform release. Without an ID, the picker offers every release offered to the organization, including deprecated and withdrawn ones.
nscale kubernetes release get <platform-release-id> --org <org-id>
Flags
Flag
Description
Organization ID or name
Platform release ID or name
Emit the full JSON payload (mutually exclusive with -q)
nscale k8s release get <platform-release-id> -q '.status.kubernetesVersion'
kubeconfig get
Assemble a kubectl configuration for a cluster. By default the kubeconfig is written to stdout. Pass --output to write it to a file, or --merge to fold it into the kubeconfig kubectl already reads.The kubeconfig carries no credentials of its own. It names nscale kubernetes token as an exec credential plugin, so kubectl asks the CLI for a fresh token whenever it needs one. Sharing the file grants nobody access, and it does not go stale when your token rotates. If you pass --user or --context, the generated kubeconfig passes them on to nscale kubernetes token.
kubectl runs nscale to get a token, so the CLI must be on your PATH wherever you use the kubeconfig.
nscale kubernetes kubeconfig get <cluster-id> --org <org-id> [flags]
Flags
Flag
Description
--org string
Organization ID or name
--cluster string
Cluster ID or name. Can also be passed as a positional argument
--endpoint string
API server endpoint to use — public or private. Defaults to the public endpoint, falling back to the private one
-o, --output string
Write the kubeconfig to this file instead of stdout. With --merge, merge into this file instead of the default kubeconfig
--merge
Merge into the kubeconfig kubectl reads ($KUBECONFIG, or ~/.kube/config) rather than emitting a standalone one, leaving its other clusters untouched
--set-current-context
When merging, switch the current context to the new one; pass --set-current-context=false to leave it alone (default true)
--context-name string
Name for the generated cluster, user, and context entries (default nks-<cluster name>-<cluster ID prefix>)
Examples
# Merge into ~/.kube/config and switch to the new contextnscale k8s kubeconfig get <cluster-id> --mergekubectl get nodes# Write a standalone kubeconfignscale k8s kubeconfig get <cluster-id> --output kubeconfig.yamlKUBECONFIG=kubeconfig.yaml kubectl get nodes# Merge the private endpoint without switching the current contextnscale k8s kubeconfig get --cluster <cluster-id> --merge --endpoint private --set-current-context=false
Running the command again for the same cluster replaces its entries rather than duplicating them.
token
Print the current Nscale access token as a client.authentication.k8s.io ExecCredential.This command is run by kubectl, not by hand: the kubeconfig written by kubeconfig get names it as an exec credential plugin. It does not need an organization. Credentials are refreshed the same way as for every other command, and NSCALE_SERVICE_TOKEN is honored for CI.