Import an existing cluster (BYOK)

You can import an existing Kubernetes cluster (BYOK, bring your own Kubernetes) to deploy and manage workloads on it with Northflank. Northflank installs its system components on your cluster and manages workloads, networking, and observability, while you retain control of the underlying cluster and infrastructure.

BYOK differs from bring your own cloud (BYOC), where Northflank provisions and manages a new Kubernetes cluster in your cloud account. With BYOK you are responsible for provisioning and operating the cluster itself, see managed by Northflank vs. managed by you.

Cluster import is enabled per account. If the Import Cluster (BYOK) option is not available on your account, contact Northflank.

Before importing a cluster, make sure it meets the BYOK requirements. In summary, your cluster must:

• Run a supported Kubernetes version: currently 1.34 and 1.35. Newer versions may work, but are not officially supported.
• Have at least 3 nodes, with a combined minimum of 12 vCPU and 24 GB memory (4 vCPU and 8 GB memory per node)
• Use Cilium as its CNI plugin. There is no strict version requirement, but we recommend a recent version. The following Cilium flags must be enabled for L7 networking features (for example L7 network policies and port-level security policies):
  • enable-l7-proxy: "true"
  • enable-envoy-config: "true"
• Have a CSI driver installed that supports persistent volumes
• Have CoreDNS installed in kube-system, with the DNS Service named kube-dns (the Kubernetes default). Northflank replaces the CoreDNS installation with its own managed CoreDNS during import.
• Have its Kubernetes API reachable from the Northflank control plane
• Be able to provision external, public IPs for LoadBalancer services (L4 load balancers)
• Not have Istio, Envoy Gateway, Prometheus, Promtail, or custom RuntimeClass resources installed, as these are installed by Northflank during import

If your cluster doesn't meet some of these requirements, or your provider requires custom configuration, contact Northflank support.

Navigate to Cloud → Provider links → Create provider link and select Import Cluster (BYOK) as the provider type. Or use the direct link:

In the credentials section, upload the kubeconfig file for your cluster.

Your kubeconfig file must:

• Contain exactly one context, cluster, and user, with a valid current context. The context must not specify a namespace.
• Include the authentication token directly. Kubeconfig files that rely on authentication helpers are not supported.
• Authenticate as a user with cluster-admin permissions on the cluster
• Contain a token that is valid for long enough to complete the integration setup. We recommend a TTL of at least 1 hour.

When you create the integration, Northflank connects to your cluster and creates a dedicated service account in the kube-system namespace with a cluster-admin role binding. Northflank uses this service account to manage your cluster from then on, so the token in your kubeconfig file only needs to remain valid until the integration is created. Do not delete the service account created by Northflank, as this will break access to your cluster.

You can edit the integration at any time to upload a new kubeconfig file, if required.

Navigate to Cloud → Clusters → Create cluster and select Import Cluster (BYOK) as the provider. Or use the direct link:

Enter a name for the cluster and choose the integration for the cluster you want to import. Enter the region your cluster is deployed in, for example us-east-1. The region is informational and used for display and geo-routing purposes.

Configure storage

Click detect available storage configurations to fetch the storage classes and snapshot classes available on your cluster.

You can then define the storage and snapshot classes Northflank should use when provisioning volumes and addons on your cluster. For each storage class definition:

• Select the Kubernetes storage class it maps to, and optionally a default snapshot class
• Enter a name (display name), ID (used as reference in specs and templates), and description
• Configure the available access modes and enable capabilities: expansion (increase volume size after provisioning) and snapshots (point-in-time snapshotting of volumes)
• Select the supported resources (addons, volumes, build cache)
• Optionally configure minimum, maximum, and suggested volume sizes

Configure node pools

Node pools on an imported cluster map your cluster's existing nodes to pools in Northflank, they do not provision any nodes. You choose one node label key for the whole cluster, and each pool claims one value of that label: a node belongs to the pool whose value matches its label.

Set the node pool cluster label identifier to the label key to match nodes by. You can use a label your Kubernetes provider already applies to nodes to identify its node pools or groups, or label your nodes yourself, for example with node.northflank.com/node-pool-id.

For each node pool, set the node pool cluster ID label value to the label value that assigns nodes to it. Enable fall back default node pool on exactly one pool: nodes that don't match any defined node pool are assigned to it.

The node pool user ID identifies the pool when interacting with Northflank through the API, CLI, and infrastructure-as-code. It doesn't affect how nodes are matched.

For each pool you can also configure:

• Whether the pool consists of spot instances
• GPU settings, if the pool consists of GPU nodes: GPU type, memory, and count, and optionally time slicing. You can also choose whether Northflank should handle GPU driver installation.
• Scheduling rules and labels (advanced)

Node pools can be added, edited, and removed after importing your cluster.

Import your cluster

When you create the cluster, Northflank will begin installing system components on your cluster (see what Northflank installs).

The cluster will show as Installing and transition to Ready once the installation has completed and your cluster is ready to deploy workloads.

During the import process, Northflank installs the system components required to manage your cluster and provide networking, observability, and runtime capabilities:

• Networking: CoreDNS configuration, Istio service mesh, Envoy Gateway, certificates for Northflank-managed domains
• Logging and metrics: Prometheus, Promtail
• Runtime: RuntimeClass resources, GPU device plugin (for GPU node pools)

Northflank installs its components into namespaces it creates (northflank-*, istio-system, envoy-gateway-system, opentelemetry) and into kube-system, where it replaces an existing CoreDNS installation with its own managed CoreDNS and reconfigures the kube-dns service to route to it.

Northflank does not install or modify:

• Your CNI plugin (Cilium): your existing installation is used as-is
• Your CSI driver and storage classes: Northflank only uses the storage classes you configure during import

These components are managed by Northflank after import. Do not modify or uninstall them, or any other resources in Northflank-managed namespaces, as this can leave your cluster in an unhealthy state.

With BYOK, more of the cluster lifecycle remains your responsibility than with BYOC, where Northflank provisions and manages the cluster.

As Northflank does not provision infrastructure for imported clusters, node pools are not autoscaled: you are responsible for scaling your cluster's nodes to match your workloads.

The following features are not available on imported clusters: node pool autoscaling, workload identity, static egress IPs, self-hosted log storage, and runtime sandboxes (gVisor and Kata).

When you delete an imported cluster in Northflank, Northflank removes its ingress load balancers. Volume snapshots are not deleted. Other installed system components remain on the cluster, and the cluster itself and its infrastructure are never deleted.

We strongly recommend not running anything besides Northflank-managed workloads on an imported cluster.