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 by default for most accounts. 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 1 node, with 3 or more nodes recommended for high availability. Each node should have at least 4 vCPU and 8 GB memory.
• Use Cilium as its CNI plugin. 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 any of the following installed, as these are installed by Northflank during import:
  • Istio
  • Envoy Gateway
  • Prometheus
  • Promtail
  • Custom RuntimeClass resources

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 an informational label used for display purposes.

You can optionally enter geographic coordinates (latitude and longitude) for your cluster. These are used by CDN geo-routing to determine the nearest backend, and are required to use the cluster as a backend for geo-routed subdomains.

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
• Scheduling rules and labels (advanced)

If your cluster has GPU node pools, you can choose whether Northflank should handle GPU driver installation. This is a cluster-level setting that applies to all GPU node pools.

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

Start the import

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. Installation is expected to take a few minutes, typically around 5 minutes.

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, and certificates for Northflank-managed domains
• Logging and metrics: Prometheus, Promtail, Prometheus adapter, and metrics exporters
• Platform: Northflank platform services
• Runtime: RuntimeClass resources, and the GPU device plugin if Northflank-managed GPU driver installation is enabled

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 an imported cluster (BYOK), more of the cluster lifecycle remains your responsibility than with a cluster provisioned by Northflank (BYOC).

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.

Some Northflank platform features are not available on imported clusters, including:

• Node pool autoscaling
• Workload identity
• Static egress IPs
• Self-hosted log storage

These features may still work if your cluster or infrastructure supplies them, but Northflank does not set them up or manage them.

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.

Contact Northflank support if:

• The Import Cluster (BYOK) option is not available on your account
• Your cluster doesn't meet some of the requirements, or uses Kube-DNS instead of CoreDNS
• Your provider requires custom configuration, for example specific annotations on Service resources to provision L4 load balancers
• Storage detection or the import fails, or times out
• You need assistance during or after the import process