# 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)](use-other-cloud-providers-with-northflank), 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](#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](https://northflank.com/contact). > [!warning] > **We strongly recommend importing a new, dedicated cluster.** Do not import clusters that run production workloads or business-critical applications, or that are shared with other systems or teams. The installation may fail and leave the cluster in an unhealthy state, and there is currently no full deinstallation process. ## Cluster requirements Before importing a cluster, make sure it meets the [BYOK requirements](byoc-and-byok-requirements#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](https://northflank.com/contact). ## Add your cluster credentials to Northflank Navigate to `Cloud → Provider links → Create provider link` and select `Import Cluster (BYOK)` as the provider type. Or use the direct link: > [!note] > [Click here](https://app.northflank.com/s/account/cloud/integrations/new/byok) to create a new BYOK integration. 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. > [!note] > An integration can only be used to import one cluster. Create a new integration for each cluster you want to import. ## Import your cluster Navigate to `Cloud → Clusters → Create cluster` and select `Import Cluster (BYOK)` as the provider. Or use the direct link: > [!note] > [Click here](https://app.northflank.com/s/account/cloud/clusters/new/byok) to import a cluster. 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 > [!note] > The storage configuration cannot be changed after the cluster has been imported. ### 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. > [!note] Example node pool mapping > With the node pool cluster label identifier set to `node.northflank.com/node-pool-id`, you could define these pools: | Node pool user ID | Node pool cluster ID label value | Fall back default node pool | | --- | --- | --- | | `workers` | `worker-pool` | yes | | `gpu` | `gpu-pool` | no | A node labelled `node.northflank.com/node-pool-id=gpu-pool` is assigned to the pool `gpu`. Nodes with any other value, or without the label, are assigned to the fall back default node pool `workers`. 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](#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. ## What Northflank installs 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. ## Managed by Northflank vs. managed by you With BYOK, more of the cluster lifecycle remains your responsibility than with BYOC, where Northflank provisions and manages the cluster. | Area | BYOK (imported cluster) | BYOC (provisioned cluster) | | --- | --- | --- | | Cluster provisioning | You | Northflank | | Kubernetes control plane & version upgrades | You | Northflank | | Node provisioning, scaling, and OS updates | You | Northflank | | CNI (Cilium) installation and upgrades | You | Northflank | | CSI driver, storage classes, and upgrades | You | Northflank | | Northflank system components (Istio, Envoy Gateway, Prometheus, Promtail, CoreDNS configuration) | Northflank | Northflank | | Workload orchestration and deployment | Northflank | Northflank | | Cloud resources and billing | You | You (via your cloud account) | 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. > [!warning] > Unless volume cleanup is disabled in the cluster settings (`cleanupVolumes`, enabled by default), deleting an imported cluster also deletes all persistent volume claims in all namespaces on the cluster, together with the workloads that reference them. This includes volumes and workloads not managed by Northflank. We strongly recommend not running anything besides Northflank-managed workloads on an imported cluster. ## Next steps - [Configure your Kubernetes cluster: Manage your clusters on other cloud providers using Northflank.](/v1/application/bring-your-own-cloud/configure-your-cluster) - [Deploy node pools: Configure and deploy node pools on a Kubernetes cluster with Northflank.](/v1/application/bring-your-own-cloud/deploy-and-scale-node-pools) - [Deploy workloads to your cluster: Deploy services, jobs, and addons to your own cluster, and configure workloads to schedule on specific node pools.](/v1/application/bring-your-own-cloud/deploy-workloads-to-your-cluster) - [Run GPU workloads: Deploy GPU workloads on Northflank for AI, machine learning, HPC workloads, and other tasks.](/v1/application/gpu-workloads/gpus-on-northflank)