Skip to navigation
Node Pools

Create a node pool

View as Markdown

Creates a worker node pool and starts provisioning. The pool takes the cluster’s Kubernetes version.

Returns 400 for, among others: parent cluster not found; a duplicate pool name in the cluster; missing nico.instanceTypeID or nico.release; not exactly one of subnetIDs and vpcPrefixIDs; a pod CIDR too small for the requested nodes.

Authentication

AuthorizationBearer

A JWT from an issuer the Operator has configured, carried as Authorization: Bearer <token>.

Request

The node pool to create.
clusterIDstringRequiredformat: "uuid"
Parent cluster.
namestringRequiredformat: "^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$"1-253 characters
Unique within the cluster. Immutable.
nodeNamePrefixstringRequired>=1 character

Prefix for generated node names: <cluster name>-<nodeNamePrefix>-<suffix>. The controller assigns suffix as a 4-digit decimal number (0000–9999). Generated names must fit within 63 characters (Kubernetes Node name limit). Maximum prefix length depends on cluster name length.

desiredNodeCountintegerRequired>=0

The desired number of nodes in the pool. For control-plane pools, aggregate capacity above 1 requires controlPlaneVIP on the cluster.

systemReservedMemorystringOptionalDefaults to 16Gi
Memory reserved for system daemons. Nodes reserve 16Gi when omitted.
kubeReservedMemorystringOptional
Memory reserved for Kubernetes components. Default 2Gi.
machineAnnotationsmap from strings to stringsOptional

Annotations set on CAPI Machines only when they are created, including Machines created during scale-out or replacement. Fixed at node-pool creation. 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.

machineLabelsmap from strings to stringsOptional

Labels set on CAPI Machines only when they are created, including Machines created during scale-out or replacement. Fixed at node-pool creation. 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.

nodeLabelsmap from strings to stringsOptional

Labels applied to the pool’s nodes at creation, as a map of keys to values. Keys under nvke.nvidia.com, nke.nvidia.com (legacy), nke.io (legacy), kubernetes.io, k8s.io and their subdomains are reserved, unless the deployment allows specific Kubernetes keys.

nodeTaintslist of objectsOptional

Taints applied to the pool’s nodes at creation. Not allowed on control-plane pools. Keys under nvke.nvidia.com, nke.nvidia.com (legacy), nke.io (legacy), kubernetes.io, k8s.io and their subdomains are reserved. Each key and effect pair may appear only once.

descriptionstringOptional

Free-text description.

autoProvisionDisabledbooleanOptionalDefaults to false
Disables automatic provisioning for the pool.
autoModeDisabledbooleanOptionalDefaults to false

Disables auto-mode (automatic node recycling).

provisioningMonitorDisabledbooleanOptionalDefaults to false
When true, nodes stuck in provisioning past the timeout are not recycled automatically.
recycleBudgetintegerOptional>=0Defaults to 0
Maximum number of nodes recycled at once.
nicoobjectOptional
NICo settings for a node pool. instanceTypeID and release are required, and exactly one of subnetIDs and vpcPrefixIDs is required.
launchLayerobjectOptional
LaunchLayer settings for a node pool. instanceType is required, and at most one of hostOSProfile and vmProfile may be set.

Response

Node pool created; provisioning has started

idstringformat: "uuid"
Node pool ID.
clusterIDstringformat: "uuid"
Parent cluster.
namestring
Node pool name. Unique within the cluster. Immutable.
nodeNamePrefixstring>=1 character

Node names are <cluster>-<prefix>-<NNNN> (four-digit suffix), at most 63 characters in total.

kubernetesVersionstring
Desired Kubernetes version for the pool's nodes. Inherits the cluster's version on create.
nodeLabelsmap from strings to strings
Labels applied to the pool's nodes, as a map of keys to values. Set at creation.
nodeTaintslist of objects
Taints applied to the pool's nodes. Set at creation.
conditionsobject

Lifecycle conditions: provisioning, provisioned, deleting.

desiredNodeCountinteger>=0
Number of nodes.
autoProvisionDisabledboolean
Disables automatic provisioning for the pool.
currentNodeSetIDstring or nullformat: "uuid"
The active NodeSet.
autoModeDisabledboolean

Disables auto-mode (automatic node recycling).

provisioningMonitorDisabledbooleanDefaults to false
When true, nodes stuck in provisioning past the timeout are not recycled automatically.
recycleBudgetinteger>=0
Maximum number of nodes recycled at once.
systemReservedMemorystringOptionalDefaults to 16Gi
Memory reserved for system daemons. Nodes reserve 16Gi when omitted.
kubeReservedMemorystringOptional
Memory reserved for Kubernetes components. Empty when the 2Gi default applies.
machineAnnotationsmap from strings to stringsOptional

Annotations set on CAPI Machines only when they are created, including Machines created during scale-out or replacement. Fixed at node-pool creation. 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.

machineLabelsmap from strings to stringsOptional

Labels set on CAPI Machines only when they are created, including Machines created during scale-out or replacement. Fixed at node-pool creation. 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.

descriptionstringOptional

Free-text description.

maxSurgeintegerOptional>=0Defaults to 0

Nodes allowed above desiredNodeCount during a rollout. 0 means sequential: each node is torn down before its replacement is provisioned.

nicoobjectOptional
NICo settings for the pool.
launchLayerobjectOptional
LaunchLayer settings for the pool.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
409
Conflict Error