Skip to main content
Aliases: kubernetes, k8s Manage 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:
  1. Pick a platform release with release list.
  2. Create a cluster on an existing network with cluster create.
  3. Add worker capacity with nodepool create.
  4. Point kubectl at the cluster with kubeconfig get.
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.

Subcommands

Clusters (aliases: cluster, clusters) Node pools (aliases: nodepool, nodepools) Platform releases (aliases: release, releases) Access (aliases for kubeconfig: kubeconfig, config)
  • kubeconfig get — Get a kubeconfig for a Kubernetes cluster
  • token — Print a Kubernetes ExecCredential for the current Nscale credentials

cluster list

List Kubernetes clusters, optionally filtered by project, region, network, name, or status.
Aliases: list, ls

Flags

FlagDescription
Organization ID or name
Only show clusters in this project (ID or name)
Only show clusters in this region (ID or name)
Only show clusters attached to this network (ID or name)
Only show clusters with this exact name
Only show clusters in this provisioning state — pending, provisioning, provisioned, deprovisioning, or error
Only show clusters in this health state — healthy, degraded, error, or unknown
Emit the full JSON payload (mutually exclusive with -q)
jq filter for value extraction (see Query output with -q)
Show at most N results (client-side; every result is still fetched). Cuts before -q. 0 for all

Examples


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.

Flags

FlagDescription
Organization ID or name
Cluster ID or name
Emit the full JSON payload (mutually exclusive with -q)
jq filter for value extraction (see Query output with -q)

Examples


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.

Flags

FlagDescription
Organization ID or name
Path to a JSON file
Read JSON from standard input
Block until provisioning finishes
How long polls before giving up (default 30m0s)
Preview actions and payload without persisting
Automatically confirm cluster creation
Emit the full JSON payload (mutually exclusive with -q)
jq filter for value extraction (see Query output with -q)

Payload

cluster.json

Examples


cluster update

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.

Flags

FlagDescription
Organization ID or name
Cluster ID or name
Path to a JSON file
Read JSON from standard input
Block until the update finishes
How long polls before giving up (default 30m0s)
Preview actions and payload without persisting
Automatically confirm cluster update
Emit the full JSON payload (mutually exclusive with -q)
jq filter for value extraction (see Query output with -q)

Examples


cluster delete

Delete an existing cluster, along with its node pools. Teardown is asynchronous.
Deleting a cluster is permanent. All of its node pools, nodes, and ephemeral data are removed.
Aliases: delete, rm, remove

Flags

Examples


nodepool list

List the node pools in the organization. Pass --cluster to see only the pools of one cluster.
Aliases: list, ls

Flags

FlagDescription
Organization ID or name
Only show node pools in this cluster (ID or name)
Only show node pools in this project (ID or name)
Only show node pools in this region (ID or name)
Only show node pools with this exact name
Only show node pools in this provisioning state — pending, provisioning, provisioned, deprovisioning, or error
Only show node pools in this health state — healthy, degraded, error, or unknown
Emit the full JSON payload (mutually exclusive with -q)
jq filter for value extraction (see Query output with -q)
Show at most N results (client-side; every result is still fetched). Cuts before -q. 0 for all

Examples


nodepool get

Get details for a specific node pool.

Flags

FlagDescription
Organization ID or name
Node pool ID or name
Emit the full JSON payload (mutually exclusive with -q)
jq filter for value extraction (see Query output with -q)

Example


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.

Flags

FlagDescription
Organization ID or name
Path to a JSON file
Read JSON from standard input
Block until provisioning finishes
How long polls before giving up (default 30m0s)
Preview actions and payload without persisting
Automatically confirm node pool creation
Emit the full JSON payload (mutually exclusive with -q)
jq filter for value extraction (see Query output with -q)

Payload

A node pool backed by a compute flavor:
nodepool.json
A node pool drawing on reserved capacity:
nodepool-reservation.json
Labels and taints are applied when a worker joins the cluster, and are not kept in sync on running nodes afterward.

Examples


nodepool update

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.

Flags

FlagDescription
Organization ID or name
Node pool ID or name
Path to a JSON file
Read JSON from standard input
Block until the update finishes
How long polls before giving up (default 30m0s)
Preview actions and payload without persisting
Automatically confirm node pool update
Emit the full JSON payload (mutually exclusive with -q)
jq filter for value extraction (see Query output with -q)

Examples


nodepool delete

Delete a node pool, along with the workers it runs. Teardown is asynchronous.
Aliases: delete, rm, remove

Flags

Examples


release list

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.
Aliases: list, ls

Flags

FlagDescription
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)
jq filter for value extraction (see Query output with -q)
Show at most N results (client-side; every result is still fetched). Cuts before -q. 0 for all

Examples


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.

Flags

FlagDescription
Organization ID or name
Platform release ID or name
Emit the full JSON payload (mutually exclusive with -q)
jq filter for value extraction (see Query output with -q)

Example


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.

Flags

Examples

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.