v1
ApplicationAPI & CLI
Double column
API
CLI
JS Client

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

    • storage

      (multiple options: oneOf)
      • {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.

          • 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

    • 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`.

      • 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

    • 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

            • OR

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

    • 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, 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

        (multiple options: oneOf)
        • {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.

            • 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

      • 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`.

        • 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

      • 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

              • OR

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

      • 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
  }
}

© 2025 Northflank Ltd. All rights reserved.

northflank.comTermsPrivacyfeedback@northflank.com