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, cloudflare, 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.
pattern
^((org|team)\/)?[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
storage
{object}

storageEnabled
boolean
snapshotsEnabled
boolean
storageClasses
[array]

{object}

id
string required
name
string required
description
string
platformMapping
string required
one of
ssd, hdd
kubernetesName
string required
defaultSnapshotClass
string

snapshotClasses
[array]

{object}

id
string required
name
string required
description
string
kubernetesName
string required

nodePools
[array] required

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
pattern
^((org|team)\/)?[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.
pattern
^((org|team)\/)?[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.

storageType
string required
one of
s3, gcs
s3BucketName
(multiple options: oneOf)

string

s3AccessKey
(multiple options: oneOf)

string

s3SecretKey
(multiple options: oneOf)

string

s3Region
(multiple options: oneOf)

string

gcsBucketName
(multiple options: oneOf)

string

gcpIntegrationId
(multiple options: oneOf)

string

pattern

^((org|team)\/)?[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

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
4096
max
40960
storage
number
Configure the data disk size per Ceph replica
min
102400
max
5242880

enableMultiReadWriteStorage
boolean
Configure Ceph to be enable use of multi read write storage for persistent volumes on the cluster.
enableSingleReadWriteStorage
boolean
Configure Ceph to be used as default storage class for single read write storage. This will replace the default storage of the cloud provider.
enableErasureCoding
boolean
Configure Ceph to be set up with erasure coding. This will be less fault tolerant but more cost effective.
enableTopologyAwareScheduling
boolean
Configure Ceph to be set up with topology aware scheduling, enforcing deployment across multiple zones.

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

restrictions
{object}
BYOC restrictions configuration for controlling team access

enabled
boolean required
Enable or disable BYOC restrictions for this entity
teams
[array]
List of teams that have access to this BYOC cluster

{object}

teamId
string required
The ID of the team that has access to this BYOC cluster
min length
3
max length
45
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

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

networking
{object}

network
string
subnetwork
string

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]))$

projectId
string
GCP Project ID
pattern
^[a-z][a-z0-9-]{4,28}[a-z0-9]$

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
The mode of the AWS subnet configuration
one of
default-subnets-for-azs, explicit-subnets
vpcId
string
Id of the VPC
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`.

networking
{object}

vnetConfiguration
{object}

mode
string required
The vnet mode to use for this cluster. Use this to switch between creation of a new vnet per cluster or specifying a custom vnet.
one of
create-default, custom-vnet
vnetId
string
Azure vnetId that should be used for this cluster. By default a new vnet will be created.

networkPluginMode
string
Optional setting to configure overlay mode on Azure.
one of
overlay

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]))$

byok
{object}
BYOK specific data. Required when `provider` is `byok`.

nodePoolProviderIdLabel
string required

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, cloudflare, 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.
pattern
^((org|team)\/)?[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
storage
{object}

storageEnabled
boolean
snapshotsEnabled
boolean
storageClasses
[array]

{object}

id
string required
name
string required
description
string
platformMapping
string required
one of
ssd, hdd
kubernetesName
string required
defaultSnapshotClass
string

snapshotClasses
[array]

{object}

id
string required
name
string required
description
string
kubernetesName
string required

nodePools
[array] required

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
pattern
^((org|team)\/)?[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.
pattern
^((org|team)\/)?[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.

storageType
string required
one of
s3, gcs
s3BucketName
(multiple options: oneOf)

string

s3AccessKey
(multiple options: oneOf)

string

s3SecretKey
(multiple options: oneOf)

string

s3Region
(multiple options: oneOf)

string

gcsBucketName
(multiple options: oneOf)

string

gcpIntegrationId
(multiple options: oneOf)

string

pattern

^((org|team)\/)?[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

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
4096
max
40960
storage
number
Configure the data disk size per Ceph replica
min
102400
max
5242880

enableMultiReadWriteStorage
boolean
Configure Ceph to be enable use of multi read write storage for persistent volumes on the cluster.
enableSingleReadWriteStorage
boolean
Configure Ceph to be used as default storage class for single read write storage. This will replace the default storage of the cloud provider.
enableErasureCoding
boolean
Configure Ceph to be set up with erasure coding. This will be less fault tolerant but more cost effective.
enableTopologyAwareScheduling
boolean
Configure Ceph to be set up with topology aware scheduling, enforcing deployment across multiple zones.

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

restrictions
{object}
BYOC restrictions configuration for controlling team access

enabled
boolean required
Enable or disable BYOC restrictions for this entity
teams
[array]
List of teams that have access to this BYOC cluster

{object}

teamId
string required
The ID of the team that has access to this BYOC cluster
min length
3
max length
45
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

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

networking
{object}

network
string
subnetwork
string

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]))$

projectId
string
GCP Project ID
pattern
^[a-z][a-z0-9-]{4,28}[a-z0-9]$

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
The mode of the AWS subnet configuration
one of
default-subnets-for-azs, explicit-subnets
vpcId
string
Id of the VPC
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`.

networking
{object}

vnetConfiguration
{object}

mode
string required
The vnet mode to use for this cluster. Use this to switch between creation of a new vnet per cluster or specifying a custom vnet.
one of
create-default, custom-vnet
vnetId
string
Azure vnetId that should be used for this cluster. By default a new vnet will be created.

networkPluginMode
string
Optional setting to configure overlay mode on Azure.
one of
overlay

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]))$

byok
{object}
BYOK specific data. Required when `provider` is `byok`.

nodePoolProviderIdLabel
string required

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.
updatedAt
string required
The time the cluster was last updated.
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","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}}},"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",
    "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
        }
      }
    },
    "aws": {
      "subnetConfiguration": {
        "subnets": [
          "eu-west-1a"
        ]
      }
    },
    "id": "gcp-cluster-1",
    "status": {
      "state": {
        "state": "initial",
        "transitionTime": "2024-05-03T16:40:38.198Z"
      }
    },
    "dns": "xxxxxxxxxx",
    "updatedAt": "2021-01-20T11:19:53.175Z",
    "createdAt": "2021-01-20T11:19:53.175Z",
    "deletionRequested": false
  }
}