Kubernetes - Nscale

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:

Pick a platform release with release list.
Create a cluster on an existing network with cluster create.
Add worker capacity with nodepool create.
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, the command prints the resource as it stands and exits non-zero, while the operation carries on server-side. Commands that act on one resource take its ID either as a positional argument or with --id. If you omit it, the CLI opens an interactive picker, so always pass it in scripts.

Subcommands

Clusters (aliases: cluster, clusters)

cluster list — List Kubernetes clusters
cluster get — Get Kubernetes cluster details
cluster create — Create a new Kubernetes cluster
cluster update — Update an existing Kubernetes cluster
cluster delete — Delete an existing Kubernetes cluster

Node pools (aliases: nodepool, nodepools)

nodepool list — List Kubernetes cluster node pools
nodepool get — Get Kubernetes cluster node pool details
nodepool create — Create a new Kubernetes cluster node pool
nodepool update — Update an existing Kubernetes cluster node pool
nodepool delete — Delete an existing Kubernetes cluster node pool

Platform releases (aliases: release, releases)

release list — List Kubernetes platform releases
release get — Get Kubernetes platform release details

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.

nscale kubernetes cluster list --org <org-id> [flags]

Flags

Flag	Description
Organization ID
Only show clusters in this project ID
Only show clusters in this region ID
Only show clusters attached to this network ID
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`)

Examples

nscale k8s cluster list --project <project-id>
nscale k8s cluster list --provisioning-status provisioned -q ".[].metadata.id"

cluster get

Get details for a specific cluster, including its platform release, API server endpoints, and status.

nscale kubernetes cluster get --id <cluster-id> --org <org-id>

Flags

Flag	Description
Organization ID
Cluster ID
Emit the full JSON payload (mutually exclusive with `-q`)
jq filter for value extraction (see Query output with `-q`)

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, network, platform release, pod and service networks, API server access, and addons. To trust an SSH certificate authority or add your own identity provider, use a file. 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.

nscale kubernetes cluster create --org <org-id> [flags]

Flags

Flag	Description
Organization ID
Path to a JSON file
Read JSON from standard input
Block until provisioning finishes
How long polls before giving up (default `30m0s`)
Preview the request 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

{
  "metadata": {
    "name": "demo-cluster",
    "description": "Demo Kubernetes cluster"
  },
  "spec": {
    "networkId": "<network-id>",
    "platformReleaseId": "<platform-release-id>",
    "clusterNetwork": {
      "podCidr": "10.240.0.0/12",
      "serviceCidr": "10.96.0.0/16"
    },
    "apiServer": {
      "publicIP": true,
      "allowedCidrs": ["203.0.113.0/24"]
    },
    "addons": {
      "hardware": {
        "enabled": true
      },
      "nodeHealth": {
        "enabled": true
      }
    }
  }
}

Field	Required	Description
`metadata.name`	Yes	Cluster name
`metadata.description`	No	Free-form description
`spec.networkId`	Yes	Network to attach the cluster to. Cannot be changed after creation
`spec.platformReleaseId`	Yes	Platform release to run, from `release list`
`spec.sshCertificateAuthorityId`	No	SSH certificate authority that the cluster’s workers trust. Cannot be changed after creation
`spec.clusterNetwork.podCidr`	No	IPv4 CIDR for pod addresses (default `10.240.0.0/12`)
`spec.clusterNetwork.serviceCidr`	No	IPv4 CIDR for service addresses (default `10.96.0.0/16`)
`spec.apiServer.publicIP`	No	Expose the API server on a public endpoint (default `false`)
`spec.apiServer.allowedCidrs`	No	Up to 32 source IPv4 CIDRs allowed to reach the API server, including private endpoints (default `0.0.0.0/0`)
`spec.apiServer.authentication`, `spec.apiServer.authorization`	No	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

Examples

nscale k8s cluster create --file cluster.json
nscale k8s cluster create --stdin < cluster.json
nscale k8s cluster create --file cluster.json --yes --wait

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. spec.networkId, spec.sshCertificateAuthorityId, and the API server’s authentication and authorization cannot change. The prompts carry these fields over from the cluster unchanged. The update is applied asynchronously.

nscale kubernetes cluster update --id <cluster-id> --org <org-id> [flags]

Flags

Flag	Description
Organization ID
Cluster ID
Path to a JSON file
Read JSON from standard input
Block until the update finishes
How long polls before giving up (default `30m0s`)
Preview the request 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

nscale k8s cluster update --id <cluster-id> --file cluster.json
nscale k8s cluster update --id <cluster-id> --stdin < cluster.json
nscale k8s cluster update --id <cluster-id> --file cluster.json --yes --wait

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.

nscale kubernetes cluster delete --id <cluster-id> --org <org-id> [flags]

Flags

Flag	Description
`--org string`	Organization ID
`--id string`	Cluster ID
`--wait`	Block until deletion finishes
`--wait-timeout duration`	How long `--wait` polls before giving up (default `30m0s`)
`--dry-run`	Preview the request payload without persisting
`-y, --yes`	Automatically confirm deletion

Examples

nscale k8s cluster delete --id <cluster-id>
nscale k8s cluster delete --id <cluster-id> --yes --wait

nodepool list

List the node pools in the organization. Pass --cluster to see only the pools of one cluster.

nscale kubernetes nodepool list --org <org-id> [flags]

Flags

Flag	Description
Organization ID
Only show node pools in this cluster ID
Only show node pools in this project ID
Only show node pools in this region ID
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`)

Examples

nscale k8s nodepool list
nscale k8s nodepool list --cluster <cluster-id>

nodepool get

Get details for a specific node pool.

nscale kubernetes nodepool get --id <node-pool-id> --org <org-id>

Flags

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

nodepool create

Create a new node pool in a cluster. Accepts input from a JSON file or stdin; with neither, the CLI prompts for each field, offering pickers for the cluster, flavor, or reservation. To set labels or a placement policy, use a file. 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.

nscale kubernetes nodepool create --org <org-id> [flags]

Flags

Flag	Description
Organization ID
Path to a JSON file
Read JSON from standard input
Block until provisioning finishes
How long polls before giving up (default `30m0s`)
Preview the request 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

{
  "metadata": {
    "name": "gpu-workers",
    "description": "GPU node pool"
  },
  "spec": {
    "clusterId": "<cluster-id>",
    "provisioningMode": "compute",
    "replicas": 2,
    "compute": {
      "flavorId": "<flavor-id>"
    },
    "labels": {
      "accelerator": "nvidia-h100"
    },
    "taints": [
      {
        "key": "nvidia.com/gpu",
        "value": "true",
        "effect": "NoSchedule"
      }
    ]
  }
}

A node pool drawing on reserved capacity:

nodepool-reservation.json

{
  "metadata": {
    "name": "reserved-workers"
  },
  "spec": {
    "clusterId": "<cluster-id>",
    "provisioningMode": "reservation",
    "replicas": 2,
    "reservation": {
      "reservationId": "<reservation-id>",
      "constraints": {
        "policy": "spread",
        "maxSkew": 1,
        "whenUnsatisfiable": "fail"
      }
    }
  }
}

Field	Required	Description
`metadata.name`	Yes	Node pool name
`metadata.description`	No	Free-form description
`spec.clusterId`	Yes	Cluster the node pool belongs to
`spec.provisioningMode`	Yes	Capacity source — `compute` or `reservation`
`spec.replicas`	Yes	Number of workers. For a reservation pool, the number of hosts to take from the reservation
`spec.compute.flavorId`	When `compute`	Compute flavor for the workers
`spec.reservation.reservationId`	When `reservation`	Reservation to draw capacity from
`spec.reservation.constraints.policy`	No	Placement policy — `pack` fills topology domains in turn, `spread` distributes hosts across them. Cannot be changed after creation
`spec.reservation.constraints.maxSkew`	No	Largest allowed difference in host count between domains. `spread` only
`spec.reservation.constraints.minDomains`	No	Minimum number of domains that receive a host. `spread` only
`spec.reservation.constraints.whenUnsatisfiable`	No	`fail` rejects a spread that can’t be satisfied, `bestEffort` picks the closest layout. `spread` only
`spec.labels`	No	Up to 64 Kubernetes labels applied to the workers, as key-value pairs
`spec.taints`	No	Up to 64 Kubernetes taints applied to the workers
`spec.taints[].key`	Yes	Taint key
`spec.taints[].value`	No	Taint value
`spec.taints[].effect`	Yes	`NoSchedule`, `PreferNoSchedule`, or `NoExecute`

Labels and taints are applied when a worker joins the cluster, and are not kept in sync on running nodes afterward.

Examples

nscale k8s nodepool create --file nodepool.json
nscale k8s nodepool create --stdin < nodepool.json
nscale k8s nodepool create --file nodepool.json --yes --wait

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 carry the pool’s labels and placement policy over unchanged. 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.

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.

nscale kubernetes nodepool update --id <node-pool-id> --org <org-id> [flags]

Flags

Flag	Description
Organization ID
Node pool ID
Path to a JSON file
Read JSON from standard input
Block until the update finishes
How long polls before giving up (default `30m0s`)
Preview the request 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

nscale k8s nodepool update --id <node-pool-id> --file nodepool.json
nscale k8s nodepool update --id <node-pool-id> --stdin < nodepool.json
nscale k8s nodepool update --id <node-pool-id> --file nodepool.json --yes --wait

nodepool delete

Delete a node pool, along with the workers it runs. Teardown is asynchronous.

nscale kubernetes nodepool delete --id <node-pool-id> --org <org-id> [flags]

Flags

Flag	Description
`--org string`	Organization ID
`--id string`	Node pool ID
`--wait`	Block until deletion finishes
`--wait-timeout duration`	How long `--wait` polls before giving up (default `30m0s`)
`--dry-run`	Preview the request payload without persisting
`-y, --yes`	Automatically confirm deletion

Examples

nscale k8s nodepool delete --id <node-pool-id>
nscale k8s nodepool delete --id <node-pool-id> --yes --wait

release list

List the platform releases available to clusters. 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]

Flags

Flag	Description
Organization ID
Only show releases available in this region ID
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`)

Example

nscale k8s release list --region <region-id> --deprecated=false --withdrawn=false

release get

Get details for a specific platform release.

nscale kubernetes release get --id <platform-release-id> --org <org-id>

Flags

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

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 <cluster-id> --org <org-id> [flags]

Flags

Flag	Description
`--org string`	Organization ID
`--cluster string`	Cluster ID. 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 context
nscale k8s kubeconfig get --cluster <cluster-id> --merge
kubectl get nodes

# Write a standalone kubeconfig
nscale k8s kubeconfig get --cluster <cluster-id> --output kubeconfig.yaml
KUBECONFIG=kubeconfig.yaml kubectl get nodes

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.

nscale kubernetes token

​Subcommands

​cluster list

​Flags

​Examples

​cluster get

​Flags

​cluster create

​Flags

​Payload

​Examples

​cluster update

​Flags

​Examples

​cluster delete

​Flags

​Examples

​nodepool list

​Flags

​Examples

​nodepool get

​Flags

​nodepool create

​Flags

​Payload

​Examples

​nodepool update

​Flags

​Examples

​nodepool delete

​Flags

​Examples

​release list

​Flags

​Example

​release get

​Flags

​kubeconfig get

​Flags

​Examples

​token

Subcommands

cluster list

Flags

Examples

cluster get

Flags

cluster create

Flags

Payload

Examples

cluster update

Flags

Examples

cluster delete

Flags

Examples

nodepool list

Flags

Examples

nodepool get

Flags

nodepool create

Flags

Payload

Examples

nodepool update

Flags

Examples

nodepool delete

Flags

Examples

release list

Flags

Example

release get

Flags

kubeconfig get

Flags

Examples

token