> ## Documentation Index > Fetch the complete documentation index at: https://docs.nscale.com/llms.txt > Use this file to discover all available pages before exploring further. # Create cluster > Create a cluster. ## OpenAPI ````yaml /openapi/nks-openapi.yaml post /api/v1/clusters openapi: 3.0.3 info: title: NKS API description: |- The NKS API provides Kubernetes clusters, node pools, and platform release catalog entries. version: 0.1.0 servers: - url: https://nks.nks.europe-west4.nscale.com description: Production security: [] paths: /api/v1/clusters: description: Manages project-scoped Kubernetes clusters. post: tags: - Clusters summary: Create cluster description: Create a cluster. operationId: createCluster requestBody: $ref: '#/components/requestBodies/clusterV1CreateRequest' responses: '201': $ref: '#/components/responses/clusterV1Created' '400': $ref: '#/components/responses/badRequestResponse' '401': $ref: '#/components/responses/unauthorizedResponse' '403': $ref: '#/components/responses/forbiddenResponse' '413': $ref: '#/components/responses/requestEntityTooLargeResponse' '422': $ref: '#/components/responses/unprocessableContentResponse' '500': $ref: '#/components/responses/internalServerErrorResponse' security: - oauth2Authentication: [] components: requestBodies: clusterV1CreateRequest: description: Cluster creation request. required: true content: application/json: schema: $ref: '#/components/schemas/clusterV1Create' example: metadata: name: production-cluster description: Production Kubernetes cluster tags: - name: environment value: production spec: networkId: 61f0ad85-3001-41cb-824a-e6a047668dfe platformReleaseId: nks-1-32-3 apiServer: publicIP: false responses: clusterV1Created: description: >- A newly created cluster whose desired state has been persisted but not yet observed. headers: Location: $ref: '#/components/headers/locationHeader' content: application/json: schema: $ref: '#/components/schemas/clusterV1Read' example: metadata: id: 1e44f19a-21a9-43cc-a460-5d6f21247f65 generation: 1 name: production-cluster organizationId: 9a8c6370-4065-4d4a-9da0-7678df40cd9d projectId: e36c058a-8eba-4f5b-91f4-f6ffb983795c creationTime: '2026-05-14T10:00:00.000Z' provisioningStatus: provisioning healthStatus: unknown spec: networkId: 61f0ad85-3001-41cb-824a-e6a047668dfe platformReleaseId: nks-1-32-3 apiServer: publicIP: false addons: hardware: enabled: true nodeHealth: enabled: true status: regionId: uk-lon-1 badRequestResponse: description: |- Request body failed schema validation, or the request does not contain all the required fields. content: application/json: schema: $ref: '#/components/schemas/error' example: error: invalid_request error_description: request body invalid trace_id: 57bc14d9bd461f0b5a72db830149b67a unauthorizedResponse: description: Authentication failed or the access token has expired. content: application/json: schema: $ref: '#/components/schemas/error' example: error: access_denied error_description: authentication failed trace_id: 57bc14d9bd461f0b5a72db830149b67a forbiddenResponse: description: >- Request was denied by authorization, this may be caused by the authorization token not having the required scope for an API, or the user doesn't have the necessary privileges on the provider platform. content: application/json: schema: $ref: '#/components/schemas/error' example: error: forbidden error_description: user credentials do not have the required privileges trace_id: 57bc14d9bd461f0b5a72db830149b67a requestEntityTooLargeResponse: description: The request body exceeds the maximum accepted size. content: application/json: schema: $ref: '#/components/schemas/error' example: error: request_entity_too_large error_description: request body exceeds the maximum allowed size trace_id: 57bc14d9bd461f0b5a72db830149b67a unprocessableContentResponse: description: >- The provided request was syntactically correct but the instruction was unable to be processed due to semantic errors. content: application/json: schema: $ref: '#/components/schemas/error' example: error: unprocessable_content error_description: the request body was in the wrong format trace_id: 57bc14d9bd461f0b5a72db830149b67a internalServerErrorResponse: description: >- An unexpected or unhandled error occurred. This may be a transient error and may succeed on a retry. If this isn't the case, please report it as an issue. content: application/json: schema: $ref: '#/components/schemas/error' example: error: server_error error_description: failed to token claim trace_id: 57bc14d9bd461f0b5a72db830149b67a schemas: clusterV1Create: description: A cluster creation request. type: object required: - metadata - spec properties: metadata: $ref: '#/components/schemas/resourceMetadata' spec: $ref: '#/components/schemas/clusterCreateSpecV1' clusterV1Read: description: A Kubernetes cluster. type: object required: - metadata - spec - status properties: metadata: $ref: '#/components/schemas/projectScopedResourceReadMetadataV1' spec: $ref: '#/components/schemas/clusterSpecV1' status: $ref: '#/components/schemas/clusterStatusV1' error: description: Generic error message, compatible with oauth2. type: object required: - error - error_description properties: error: description: >- A terse error string expanding on the HTTP error code. Errors are based on the OAuth 2.02 specification, but are expanded with proprietary status codes for APIs other than those specified by OAuth 2.02. type: string enum: - invalid_request - server_error - access_denied - not_found - conflict - method_not_allowed - unsupported_media_type - request_entity_too_large - unprocessable_content - forbidden error_description: description: Verbose message describing the error. type: string trace_id: description: Unique trace identifier for the request. type: string resourceMetadata: description: Metadata required for all API resource reads and writes. required: - name properties: name: $ref: '#/components/schemas/kubernetesLabelValue' description: description: >- The resource description, this optionally augments the name with more context. type: string tags: $ref: '#/components/schemas/tagList' clusterCreateSpecV1: description: Desired cluster state for creation. type: object additionalProperties: false required: - networkId - platformReleaseId properties: networkId: description: Region network ID attached to the cluster. type: string platformReleaseId: description: Platform release selected for the cluster. type: string sshCertificateAuthorityId: description: >- Optional region SSH certificate authority trusted for cluster workers. type: string clusterNetwork: $ref: '#/components/schemas/clusterNetworkV1' apiServer: $ref: '#/components/schemas/clusterApiServerAccessV1' addons: $ref: '#/components/schemas/clusterAddonsCreateV1' projectScopedResourceReadMetadataV1: description: >- Project-scoped resource read metadata with Kubernetes generation freshness. type: object required: - id - name - organizationId - projectId - creationTime - generation - provisioningStatus - healthStatus properties: id: description: Unique resource ID. type: string name: $ref: '#/components/schemas/kubernetesLabelValue' description: description: Optional human-readable resource description. type: string tags: $ref: '#/components/schemas/tagList' organizationId: description: Organization identifier the resource belongs to. type: string projectId: description: Project identifier the resource belongs to. type: string creationTime: description: Time the resource was created. type: string format: date-time createdBy: description: User who created the resource. type: string modifiedTime: description: Time the resource was updated. type: string format: date-time modifiedBy: description: User who updated the resource. type: string deletionTime: description: Time deletion was requested. type: string format: date-time generation: description: Current desired-state generation of the resource. type: integer format: int64 minimum: 0 provisioningStatus: $ref: '#/components/schemas/resourceProvisioningStatus' provisioningStatusDetail: $ref: '#/components/schemas/provisioningStatusDetail' healthStatus: $ref: '#/components/schemas/resourceHealthStatus' healthStatusDetail: $ref: '#/components/schemas/healthStatusDetail' clusterSpecV1: description: Desired cluster state. type: object required: - networkId - platformReleaseId properties: networkId: description: Region network ID attached to the cluster. type: string platformReleaseId: description: Platform release selected for the cluster. type: string sshCertificateAuthorityId: description: >- Optional region SSH certificate authority trusted for cluster workers. type: string clusterNetwork: $ref: '#/components/schemas/clusterNetworkV1' apiServer: $ref: '#/components/schemas/clusterApiServerAccessV1' addons: $ref: '#/components/schemas/clusterAddonsV1' clusterStatusV1: description: Product-specific observed cluster state. type: object required: - regionId properties: regionId: description: Resolved region inherited from the attached network. type: string observedGeneration: description: >- Most recent resource generation coherently projected into status. Omitted until a status projection completes. type: integer format: int64 minimum: 0 kubernetesVersion: $ref: '#/components/schemas/clusterKubernetesVersionStatusV1' apiServer: $ref: '#/components/schemas/clusterApiServerStatusV1' controlPlane: $ref: '#/components/schemas/clusterControlPlaneSummaryV1' nodePools: $ref: '#/components/schemas/clusterNodePoolSummaryV1' addons: $ref: '#/components/schemas/clusterAddonsStatusV1' authorization: $ref: '#/components/schemas/clusterAuthorizationStatusV1' release: $ref: '#/components/schemas/clusterReleaseStatusV1' kubernetesLabelValue: description: >- A valid Kubernetes label value, typically used for resource names that can be indexed in the database. type: string pattern: ^[0-9A-Za-z](?:[0-9A-Za-z-_.]{0,61}[0-9A-Za-z])?$ tagList: description: A list of tags. type: array items: $ref: '#/components/schemas/tag' clusterNetworkV1: description: Kubernetes cluster pod and service network configuration. type: object properties: podCidr: description: IPv4 network CIDR used for Kubernetes pod addresses. type: string default: 10.240.0.0/12 serviceCidr: description: IPv4 network CIDR used for Kubernetes service addresses. type: string default: 10.96.0.0/16 clusterApiServerAccessV1: description: API server network exposure requested for a cluster. type: object properties: publicIP: description: Whether to expose the API server through a public endpoint. type: boolean default: false allowedCidrs: description: >- Source IPv4 CIDR allowlist for the cluster API endpoint, including private endpoints. If publicIP is true and this field is omitted, the API server is reachable from 0.0.0.0/0. type: array minItems: 1 maxItems: 32 uniqueItems: true default: - 0.0.0.0/0 items: type: string pattern: >- ^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)/([0-9]|[12][0-9]|3[0-2])$ authorization: $ref: '#/components/schemas/clusterApiServerAuthorizationV1' description: >- Tenant ClusterRoles bound to caller-specified subjects. After creation, role bindings and subjects may only be removed, including by omitting authorization entirely, and removing them needs create permission on the cluster's project; authorization cannot be added to a cluster created without it. authentication: $ref: '#/components/schemas/clusterApiServerAuthenticationV1' clusterAddonsCreateV1: description: Addon profiles requested during cluster creation. type: object properties: hardware: $ref: '#/components/schemas/clusterAddonProfileCreateV1' nodeHealth: $ref: '#/components/schemas/clusterAddonProfileCreateV1' resourceProvisioningStatus: description: The provisioning state of a resource. type: string enum: - pending - provisioning - provisioned - deprovisioning - error provisioningStatusDetail: description: |- Human-facing detail about the current provisioning state: a machine-classifiable reason drawn from a closed vocabulary, and a user-safe human-readable message. Derived from the resource's status and supplements the coarse provisioningStatus; never stored. type: object required: - reason - message properties: reason: $ref: '#/components/schemas/provisioningStatusReason' message: description: A user-safe, human-readable description of the provisioning state. type: string resourceHealthStatus: description: The health state of a resource. type: string enum: - unknown - healthy - degraded - error healthStatusDetail: description: >- Human-facing detail about the current health state: a machine-classifiable reason drawn from a closed vocabulary, and a user-safe human-readable message (e.g. "2/12 nodes are down"). Derived from the resource's status and supplements the coarse healthStatus; never stored. type: object required: - reason - message properties: reason: $ref: '#/components/schemas/healthStatusReason' message: description: A user-safe, human-readable description of the health state. type: string clusterAddonsV1: description: Addon profiles configured for a cluster. type: object properties: hardware: $ref: '#/components/schemas/clusterAddonProfileV1' nodeHealth: $ref: '#/components/schemas/clusterAddonProfileV1' clusterKubernetesVersionStatusV1: description: >- Kubernetes versions in the applied control-plane template and observed managed control plane. type: object additionalProperties: false properties: target: description: Kubernetes version applied to the cluster's control plane. type: string observed: description: Kubernetes version reported by the managed control plane. type: string clusterApiServerStatusV1: description: Credential-free Kubernetes API server connection data. type: object additionalProperties: false required: - certificateAuthorityData - endpoints properties: certificateAuthorityData: description: >- Complete Kubernetes API server CA bundle encoded as one base64 string. type: string minLength: 1 endpoints: $ref: '#/components/schemas/clusterApiServerEndpointsStatusV1' clusterControlPlaneSummaryV1: description: Observed control plane summary. type: object properties: readyReplicas: description: Number of ready control plane replicas. type: integer minimum: 0 desiredReplicas: description: Desired number of control plane replicas. type: integer minimum: 0 clusterNodePoolSummaryV1: description: >- Last-observed node pool summary. Replica totals retain values from each child NodePool's latest status while a new child generation is being projected. type: object properties: count: description: Number of node pools attached to the cluster. type: integer minimum: 0 totalDesiredReplicas: description: >- Sum of desired worker replicas from each child NodePool's latest status; omitted if any child has no observed value. type: integer minimum: 0 totalCurrentReplicas: description: >- Sum of current worker replicas from each child NodePool's latest status; omitted if any child has no observed value. type: integer minimum: 0 totalReadyReplicas: description: >- Sum of ready worker replicas from each child NodePool's latest status; omitted if any child has no observed value. type: integer minimum: 0 clusterAddonsStatusV1: description: >- Observed addon rollout state grouped by profile. Hardware and nodeHealth remain visible while a previous installation is being removed and are omitted only after removal is confirmed. nodeHealth is also omitted while the applied release provides no node-health profile. type: object required: - core properties: core: $ref: '#/components/schemas/clusterAddonProfileStatusV1' hardware: $ref: '#/components/schemas/clusterAddonProfileStatusV1' nodeHealth: $ref: '#/components/schemas/clusterAddonProfileStatusV1' clusterAuthorizationStatusV1: description: >- Observed API server authorization binding state. Present only when bindings are configured. type: object required: - status properties: status: $ref: '#/components/schemas/clusterAddonComponentStatusV1' reason: description: Stable machine-readable reason for the authorization state. type: string message: description: Human-readable customer-safe message for the authorization state. type: string clusterReleaseStatusV1: description: Applied platform release and observed upgrade eligibility. type: object additionalProperties: false required: - appliedId properties: appliedId: description: Platform release last observed as applied to the remote cluster. type: string deprecated: description: Whether the applied platform release is currently deprecated. type: boolean withdrawn: description: >- Whether operators have withdrawn the applied platform release. Like deprecation it is an explicit, reversible operator decision, but withdrawal also carries a reason and message. type: boolean withdrawalReason: $ref: '#/components/schemas/platformReleaseWithdrawalReasonV1' description: >- Stable machine-readable reason operators withdrew the applied platform release. withdrawalMessage: description: >- Customer-safe explanation of why operators withdrew the applied platform release. type: string maxLength: 32768 upgradeAvailable: description: Whether at least one eligible target was observed. type: boolean eligibleTargets: description: >- Eligible platform release IDs in upgrade order. Present as an empty array when eligibility was observed and no upgrade is available. type: array uniqueItems: true items: type: string tag: description: >- A tag mapping arbitrary names to values. These have no special meaning for any component are are intended for use by end users to add additional context to a resource, for example to categorize it. type: object required: - name - value properties: name: description: A unique tag name. type: string value: description: The value of the tag. type: string clusterApiServerAuthorizationV1: description: Tenant ClusterRoles bound to caller-specified subjects. type: object additionalProperties: false required: - clusterRoleBindings properties: clusterRoleBindings: description: >- Bindings from a built-in tenant ClusterRole to caller-specified subjects, one binding per role. type: array minItems: 1 maxItems: 4 uniqueItems: true items: $ref: '#/components/schemas/clusterRoleBindingV1' clusterApiServerAuthenticationV1: description: >- Kubernetes API server authentication configured for a cluster. After creation, external issuers may only be removed, and removing them needs create permission on the cluster's project; whether authentication is set, and the nscaleWebhook override, are fixed for the cluster's lifetime. type: object properties: nscaleWebhook: $ref: '#/components/schemas/clusterNscaleWebhookAuthenticationV1' externalIssuers: description: >- Additional external JWT/OIDC issuers the cluster's API server trusts. type: array maxItems: 8 items: $ref: '#/components/schemas/clusterExternalIssuerV1' clusterAddonProfileCreateV1: description: Requested configuration for a single addon profile. type: object properties: enabled: description: Whether the addon profile is enabled. Defaults to true when omitted. type: boolean default: true provisioningStatusReason: description: |- A closed, generic classification of a resource's provisioning state, finer-grained than provisioningStatus. This vocabulary is owned by the platform and is the same across all resources; domain-specific state (e.g. an instance's lifecycle phase) is carried on other mechanisms and never appears here. type: string enum: - Provisioning - Provisioned - Errored - Deprovisioning - Deprovisioned - DependencyNotReady - DependencyFailed - DependencyNotFound healthStatusReason: description: >- A closed, generic classification of a resource's health — the raw health condition reason, finer-grained than the coarse healthStatus. Owned by the platform and the same across all resources. type: string enum: - Healthy - Degraded - Unknown clusterAddonProfileV1: description: Configuration for a single addon profile. type: object properties: enabled: description: Whether the addon profile is enabled. type: boolean clusterApiServerEndpointsStatusV1: description: Customer-facing Kubernetes API server endpoints. type: object additionalProperties: false required: - private properties: private: $ref: '#/components/schemas/clusterApiServerEndpointStatusV1' public: $ref: '#/components/schemas/clusterApiServerEndpointStatusV1' clusterAddonProfileStatusV1: description: Observed addon profile rollout state. type: object required: - status - components properties: status: $ref: '#/components/schemas/clusterAddonComponentStatusV1' reason: description: Stable machine-readable reason for the profile state. type: string message: description: Human-readable customer-safe message for the profile state. type: string components: description: Observed addon component rollout states. type: array items: $ref: '#/components/schemas/clusterAddonComponentV1' clusterAddonComponentStatusV1: description: Observed addon component rollout status. type: string enum: - pending - installing - upgrading - ready - degraded - removing platformReleaseWithdrawalReasonV1: description: Stable machine-readable reason operators withdrew a platform release. type: string enum: - SecurityIssue - FunctionalRegression - CompatibilityIssue - ComplianceIssue - OperationalIssue - Other clusterRoleBindingV1: description: Binds a built-in tenant ClusterRole to caller-specified subjects. type: object additionalProperties: false required: - clusterRole - subjects properties: clusterRole: description: Built-in tenant ClusterRole to bind. type: string enum: - cluster-admin - admin - edit - view subjects: description: User/Group subjects bound to the role. type: array minItems: 1 maxItems: 32 uniqueItems: true items: $ref: '#/components/schemas/rbacSubjectV1' clusterNscaleWebhookAuthenticationV1: description: >- Per-cluster override of the cell-wide Nscale authentication webhook enablement decision. type: object properties: enabled: description: >- Overrides the cell-wide decision to enable the Nscale authentication webhook for this cluster. Omit to inherit the cell-wide default. type: boolean clusterExternalIssuerV1: description: An external JWT/OIDC issuer the cluster's API server trusts. type: object required: - issuerURL - audiences - usernamePrefix properties: issuerURL: description: Issuer URL clients present tokens from. type: string minLength: 1 maxLength: 2048 audiences: description: Acceptable token audiences for this issuer. type: array minItems: 1 maxItems: 8 uniqueItems: true items: type: string minLength: 1 maxLength: 256 usernameClaim: description: JWT claim mapped to the authenticated username. type: string maxLength: 256 default: sub usernamePrefix: description: >- Prepended to the username claim value. Required, non-empty, and must not itself start with, or be a prefix of, a reserved prefix (system:, kubeadm:, nks-management:, nks:, nscale.com/). type: string minLength: 1 maxLength: 256 groupsClaim: description: JWT claim mapped to the authenticated group list. type: string maxLength: 256 groupsPrefix: description: >- Prepended to each groups claim value. Required when groupsClaim is set; when set, must be non-empty and must not itself start with, or be a prefix of, a reserved prefix (system:, kubeadm:, nks-management:, nks:, nscale.com/). type: string minLength: 1 maxLength: 256 caCertificate: description: >- PEM-encoded CA certificate used to verify the issuer, when it is not signed by a well-known CA. type: string maxLength: 8192 clusterApiServerEndpointStatusV1: description: Customer-facing Kubernetes API server endpoint. type: object additionalProperties: false required: - address - port properties: address: description: IPv4, IPv6, or DNS address clients dial. type: string minLength: 1 port: description: TCP port clients dial. type: integer format: int32 minimum: 1 maximum: 65535 clusterAddonComponentV1: description: Observed addon component rollout state. type: object required: - name - version - status properties: name: description: Component name. type: string version: description: Component version selected for this cluster. type: string status: $ref: '#/components/schemas/clusterAddonComponentStatusV1' reason: description: Stable machine-readable reason for the component state. type: string message: description: Human-readable customer-safe message for the component state. type: string rbacSubjectV1: description: One RBAC subject bound to a tenant ClusterRole. type: object additionalProperties: false required: - kind - name properties: kind: description: Subject kind. type: string enum: - User - Group name: description: Subject name. type: string minLength: 1 maxLength: 2048 headers: locationHeader: description: Canonical URI of the newly created resource. schema: type: string format: uri-reference securitySchemes: oauth2Authentication: type: oauth2 flows: authorizationCode: authorizationUrl: /oauth2/v2/authorization tokenUrl: /oauth2/v2/token scopes: {} ````