Skip to navigation
Clusters

Create a cluster

View as Markdown

Creates a cluster and starts provisioning. The cluster is returned before provisioning completes.

Returns 400 for, among others: a duplicate cluster name; missing nico.orgID, siteID or vpcID; an unsupported cniPlugin; a missing controlPlaneConfig.nico.release; a control-plane maxSurge greater than 1; a pod CIDR too small for the requested nodes plus surge; a controlPlaneVIP inside the pod or service CIDR.

Authentication

AuthorizationBearer

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

Request

The cluster to create.
namestringRequiredformat: "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"1-55 characters
Cluster name. Lowercase DNS label, unique per management plane. Node names are derived from it.
controlPlaneKubernetesVersionstringRequiredformat: "^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$"
Kubernetes version for the cluster, as X.Y.Z with no leading "v".
etcdEncryptedbooleanRequired

Encrypt etcd at rest. Can be turned on later with enableEtcdEncryption; cannot be turned off.

controlPlaneVIPstringOptionalformat: "ipv4"

Virtual IP for the API server through kube-vip. Omit to skip kube-vip and use the first control-plane node’s IP as the API server endpoint. Must not fall inside the pod or service CIDR. An explicit empty string is rejected. Without a VIP, a new cluster must have exactly one desired control-plane node. Control-plane scale-up above one node, upgrades, and configuration changes that replace control-plane nodes require a VIP. Recreate a no-VIP cluster with controlPlaneVIP to make those operations available.

networkobjectOptional
Pod and service network. Immutable after creation. Defaults apply when omitted.
nodePoolslist of objectsOptional
Initial worker node pools.
controlPlaneConfigobjectOptional

Writable cluster-level control plane configuration supplied at cluster creation. Required when you create a cluster. nico carries the NICo settings for the control-plane nodes; it is required for a NICo cluster. launchLayer is required for a LaunchLayer cluster.

nicoobjectOptional
NICo identifiers for the cluster. Fixed at creation.
launchLayerobjectOptional
LaunchLayer identifiers for the cluster. Exactly one of vpcID or orgID must be set, and siteID is required. All fields are fixed at creation.

Response

Cluster created; provisioning has started

idstringformat: "uuid"
Cluster ID.
namestring
Cluster name.
controlPlaneKubernetesVersionstring

Desired control-plane Kubernetes version. The running version is in ControlPlaneStatus.

cniPluginstring
CNI plugin.
cniVersionstring
CNI version.
etcdEncryptedboolean
Whether etcd is encrypted at rest.
networkobject
Pod and service network.
createdAtdatetime
Creation time.
conditionsobject
Lifecycle conditions.
controlPlaneVIPstringOptionalformat: "ipv4"
API server VIP, if configured.
enableCPNodeRecyclingbooleanOptionalDefaults to 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.

controlPlaneConfigobjectOptional

Current control-plane configuration.

nicoobjectOptional
NICo identifiers.
launchLayerobjectOptional
LaunchLayer identifiers.
nodeAgentUpgradeobjectOptional
The active agent upgrade and latest retry error.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error