Cloud Providers /

Create cluster

Creates a new cluster.

Required permission

Account > Cloud > Clusters > Create

Request body

{object}

name
string required
The name of the cluster.
min length
3
max length
20
pattern
^[a-zA-Z]((-|\s)?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$
description
string
The description of the cluster.
max length
200
pattern
^[a-zA-Z0-9.,?\s\\/'"()[\];`%^&*\-_:!]+$
provider
string required
Cloud provider to be used for the selected resource
one of
aws, azure, civo, gcp, oci, byok
region
string required
Region of the cluster.
kubernetesVersion
string
Deprecated: This field is no longer used, the version is now set by the platform.
integrationId
string
Existing integration to use for this cluster.
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
nodePools
[array] required
An array of node pools.

{object}

nodeType
string required
Machine type to be used by the node pool.
oci
{object}
OCI instance specific settings. Must respect ratios as determined by the selected node type.

ocpu
integer required
min
1
memory
integer required
min
1

nodeCount
integer required
Number of nodes to the node pool should be provisioned with.
min
0
max
250
autoscaling
{object}
Auto scaling settings to use for the node pool. Requires that the cloud provider supports this feature.

enabled
boolean
min
integer
min
0
max
249
max
integer
min
1
max
250

computeResources
{object}

gpu
{object}

mig
{object}

enabled
boolean
partitions
[array]

string

timeslicing
{object}

enabled
boolean
numSlices
number
min
1

preemptible
boolean
Configures node pool with preemptible / spot instances if enabled.
diskType
string
The disk type to use.
diskSize
integer required
Disk size in GB
min
1
systemPool
boolean
When 'provider' is 'azure', at least one system node pool is required per cluster.
availabilityZones
[array] required
Zones in which the node pool should be provisioned.

string

subnets
(multiple options: oneOf)

[array]

Subnets in which the node pool should be provisioned.

string

scheduling
{object}
Define basic workload scheduling restrictions for this node pool

allowJobs
boolean
Allow jobs to schedule to this node pool
onlyGpuJobs
boolean
Restrict job scheduling to jobs which have GPU resources configured. Only relevant for GPU node pools.
allowServices
boolean
Allow services to schedule to this node pool
onlyGpuServices
boolean
Restrict service scheduling to services which have GPU resources configured. Only relevant for GPU node pools.
allowAddons
boolean
Allow addons to schedule to this node pool
allowBuilds
boolean
Allow builds to schedule to this node pool
onlyGpuBuilds
boolean
Restrict build scheduling to builds which have GPU resources configured. Only relevant for GPU node pools.
allowCeph
boolean
Allow the placement of Ceph pods

labels
{object}
Set of label keys and values that can be used for advanced scheduling in combination with resource tag scheduling rules.

settings
{object}

builds
{object}

mode
string
one of
paas, internal, build-cluster
plan
string
Plan to use for builds if they are run on the cluster
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
clusterId
string
Cluster to use for scheduling builds
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

registry
{object}

mode
string
one of
paas, self-hosted
registryId
string
Credentials to use for storing of images.
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

logging
{object}

mode
string
one of
paas, loki
loki
{object}
Required data for the loki mode setting.

s3BucketName
string required
s3AccessKey
string required
s3SecretKey
string required
s3Region
string required

vanityDomains
{object}

apps
{object}

zoneName
string required
integrationId
string required

customDomains
{object}

zoneName
string required
integrationId
string required

loadBalancers
{object}

zoneName
string required
integrationId
string required

infrastructure
{object}

workloads
{object}

runtimeClass
string
one of
none, gvisor, kata-clh, kata-qemu, katars-clh

builds
{object}

runtimeClass
string
one of
none, gvisor, kata-clh, kata-qemu, katars-clh

installKata
boolean
installGvisor
boolean
cleanupVolumes
boolean
cleanupSnapshots
boolean
cephStorageProvider
{object}

enabled
boolean
resources
{object}

cpu
number
Configure the CPU resources per Ceph replica
min
1
max
20
memory
number
Configure the memory resources per Ceph replica
min
5024
max
40960
storage
number
Configure the data disk size per Ceph replica
min
102400
max
5242880

enableErasureCoding
boolean
enableTopologyAwareScheduling
boolean

requestModifiers
{object}
Allows customising request modifier values.

services
{object}
Request modifiers for services

cpu
number required
min
0.2
max
1
memory
number required
min
0.4
max
1

jobs
{object}
Request modifiers for jobs

cpu
number required
min
0.2
max
1
memory
number required
min
0.4
max
1

builds
{object}
Request modifiers for builds

cpu
number required
min
0.1
max
1
memory
number required
min
0.1
max
1

addons
{object}
Request modifiers for addons

cpu
number required
min
0.2
max
1
memory
number required
min
0.4
max
1

gcp
{object}
GCP specific data. Required when `provider` is `gcp`.

projectId
string required
ID of the GCP project the cluster will be provisioned in.

aws
{object}
AWS specific data. Required when `provider` is `aws`.

enablePublicAccessCidrs
boolean
publicAccessCidrs
[array]

string
pattern
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/([0-9]|[1-2][0-9]|3[0-2]))$

subnetConfiguration
{object}

mode
string required
one of
default-subnets-for-azs, explicit-subnets
vpcId
(multiple options: oneOf)

string

subnets
[array] required
List of subnets the cluster should be created for. At least 2 must be specified.

string

vpcEgress
boolean
If egress traffic from the cluster should come from a single static egress IP.

oci
{object}
OCI specific data. Required when `provider` is `oci`.

vcnConfiguration
{object} required

vcnId
string required
subnetIdForKubernetesApi
string required
subnetIdsForServiceLBs
[array] required

string

azure
{object}
Azure specific data. Required when `provider` is `azure`.

enableAuthorizedIpRanges
boolean
authorizedIpRanges
[array]

string
pattern
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/([0-9]|[1-2][0-9]|3[0-2]))$

Response body

{object}
Response object.

data
{object} required
Result data.

name
string required
The name of the cluster.
min length
3
max length
20
pattern
^[a-zA-Z]((-|\s)?[a-zA-Z0-9]+((-|\s)[a-zA-Z0-9]+)*)?$
description
string
The description of the cluster.
max length
200
pattern
^[a-zA-Z0-9.,?\s\\/'"()[\];`%^&*\-_:!]+$
provider
string required
Cloud provider to be used for the selected resource
one of
aws, azure, civo, gcp, oci, byok
region
string required
Region of the cluster.
kubernetesVersion
string
Deprecated: This field is no longer used, the version is now set by the platform.
integrationId
string
Existing integration to use for this cluster.
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
nodePools
[array] required
An array of node pools.

{object}

nodeType
string required
Machine type to be used by the node pool.
oci
{object}
OCI instance specific settings. Must respect ratios as determined by the selected node type.

ocpu
integer required
min
1
memory
integer required
min
1

nodeCount
integer required
Number of nodes to the node pool should be provisioned with.
min
0
max
250
autoscaling
{object}
Auto scaling settings to use for the node pool. Requires that the cloud provider supports this feature.

enabled
boolean
min
integer
min
0
max
249
max
integer
min
1
max
250

computeResources
{object}

gpu
{object}

mig
{object}

enabled
boolean
partitions
[array]

string

timeslicing
{object}

enabled
boolean
numSlices
number
min
1

preemptible
boolean
Configures node pool with preemptible / spot instances if enabled.
diskType
string
The disk type to use.
diskSize
integer required
Disk size in GB
min
1
systemPool
boolean
When 'provider' is 'azure', at least one system node pool is required per cluster.
availabilityZones
[array] required
Zones in which the node pool should be provisioned.

string

subnets
(multiple options: oneOf)

[array]

Subnets in which the node pool should be provisioned.

string

scheduling
{object}
Define basic workload scheduling restrictions for this node pool

allowJobs
boolean
Allow jobs to schedule to this node pool
onlyGpuJobs
boolean
Restrict job scheduling to jobs which have GPU resources configured. Only relevant for GPU node pools.
allowServices
boolean
Allow services to schedule to this node pool
onlyGpuServices
boolean
Restrict service scheduling to services which have GPU resources configured. Only relevant for GPU node pools.
allowAddons
boolean
Allow addons to schedule to this node pool
allowBuilds
boolean
Allow builds to schedule to this node pool
onlyGpuBuilds
boolean
Restrict build scheduling to builds which have GPU resources configured. Only relevant for GPU node pools.
allowCeph
boolean
Allow the placement of Ceph pods

labels
{object}
Set of label keys and values that can be used for advanced scheduling in combination with resource tag scheduling rules.

settings
{object}

builds
{object}

mode
string
one of
paas, internal, build-cluster
plan
string
Plan to use for builds if they are run on the cluster
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
clusterId
string
Cluster to use for scheduling builds
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

registry
{object}

mode
string
one of
paas, self-hosted
registryId
string
Credentials to use for storing of images.
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

logging
{object}

mode
string
one of
paas, loki
loki
{object}
Required data for the loki mode setting.

s3BucketName
string required
s3AccessKey
string required
s3SecretKey
string required
s3Region
string required

vanityDomains
{object}

apps
{object}

zoneName
string required
integrationId
string required

customDomains
{object}

zoneName
string required
integrationId
string required

loadBalancers
{object}

zoneName
string required
integrationId
string required

infrastructure
{object}

workloads
{object}

runtimeClass
string
one of
none, gvisor, kata-clh, kata-qemu, katars-clh

builds
{object}

runtimeClass
string
one of
none, gvisor, kata-clh, kata-qemu, katars-clh

installKata
boolean
installGvisor
boolean
cleanupVolumes
boolean
cleanupSnapshots
boolean
cephStorageProvider
{object}

enabled
boolean
resources
{object}

cpu
number
Configure the CPU resources per Ceph replica
min
1
max
20
memory
number
Configure the memory resources per Ceph replica
min
5024
max
40960
storage
number
Configure the data disk size per Ceph replica
min
102400
max
5242880

enableErasureCoding
boolean
enableTopologyAwareScheduling
boolean

requestModifiers
{object}
Allows customising request modifier values.

services
{object}
Request modifiers for services

cpu
number required
min
0.2
max
1
memory
number required
min
0.4
max
1

jobs
{object}
Request modifiers for jobs

cpu
number required
min
0.2
max
1
memory
number required
min
0.4
max
1

builds
{object}
Request modifiers for builds

cpu
number required
min
0.1
max
1
memory
number required
min
0.1
max
1

addons
{object}
Request modifiers for addons

cpu
number required
min
0.2
max
1
memory
number required
min
0.4
max
1

gcp
{object}
GCP specific data. Required when `provider` is `gcp`.

projectId
string required
ID of the GCP project the cluster will be provisioned in.

aws
{object}
AWS specific data. Required when `provider` is `aws`.

enablePublicAccessCidrs
boolean
publicAccessCidrs
[array]

string
pattern
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/([0-9]|[1-2][0-9]|3[0-2]))$

subnetConfiguration
{object}

mode
string required
one of
default-subnets-for-azs, explicit-subnets
vpcId
(multiple options: oneOf)

string

subnets
[array] required
List of subnets the cluster should be created for. At least 2 must be specified.

string

vpcEgress
boolean
If egress traffic from the cluster should come from a single static egress IP.

oci
{object}
OCI specific data. Required when `provider` is `oci`.

vcnConfiguration
{object} required

vcnId
string required
subnetIdForKubernetesApi
string required
subnetIdsForServiceLBs
[array] required

string

azure
{object}
Azure specific data. Required when `provider` is `azure`.

enableAuthorizedIpRanges
boolean
authorizedIpRanges
[array]

string
pattern
^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/([0-9]|[1-2][0-9]|3[0-2]))$

id
string required
The ID of cluster
status
{object}

state
{object}

state
string
transitionTime
string

nextUpdateAfter
string

dns
string
Auto-generated dns identifier for this cluster.
createdAt
string required
The time the cluster was created.
deletionRequested
boolean required
Indicates if provider resource deletion has been requested.

API

CLI

JS Client

POST /v1/cloud-providers/clusters

Example request

Request body

curl

curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request POST \
  --data '{"name":"GCP Cluster 1","description":"This is a new cluster.","provider":"gcp","region":"europe-west2","kubernetesVersion":"1.30","integrationId":"gcp-integration","nodePools":[{"nodeType":"n2-standard-8","nodeCount":3,"autoscaling":{"enabled":true,"min":0,"max":10},"preemptible":false,"diskSize":100}],"settings":{"builds":{"plan":"nf-compute-200"},"registry":{"registryId":"my-registry-credentials"},"requestModifiers":{"services":{"cpu":0.5,"memory":0.8},"jobs":{"cpu":0.5,"memory":0.8},"builds":{"cpu":0.2,"memory":0.5},"addons":{"cpu":0.5,"memory":0.8}}},"gcp":{"projectId":"example-project-id"},"aws":{"subnetConfiguration":{"subnets":["eu-west-1a"]}}}' \
  https://api.northflank.com/v1/cloud-providers/clusters

Example response

200 OK

Details about the created cluster.

JSON

{
  "data": {
    "name": "GCP Cluster 1",
    "description": "This is a new cluster.",
    "provider": "gcp",
    "region": "europe-west2",
    "kubernetesVersion": "1.30",
    "integrationId": "gcp-integration",
    "nodePools": [
      {
        "nodeType": "n2-standard-8",
        "nodeCount": 3,
        "autoscaling": {
          "enabled": true,
          "min": 0,
          "max": 10
        },
        "preemptible": false,
        "diskSize": 100
      }
    ],
    "settings": {
      "builds": {
        "plan": "nf-compute-200"
      },
      "registry": {
        "registryId": "my-registry-credentials"
      },
      "requestModifiers": {
        "services": {
          "cpu": 0.5,
          "memory": 0.8
        },
        "jobs": {
          "cpu": 0.5,
          "memory": 0.8
        },
        "builds": {
          "cpu": 0.2,
          "memory": 0.5
        },
        "addons": {
          "cpu": 0.5,
          "memory": 0.8
        }
      }
    },
    "gcp": {
      "projectId": "example-project-id"
    },
    "aws": {
      "subnetConfiguration": {
        "subnets": [
          "eu-west-1a"
        ]
      }
    },
    "id": "gcp-cluster-1",
    "status": {
      "state": {
        "state": "initial",
        "transitionTime": "2024-05-03T16:40:38.198Z"
      }
    },
    "dns": "xxxxxxxxxx",
    "createdAt": "2021-01-20T11:19:53.175Z",
    "deletionRequested": false
  }
}