# 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 by default for most accounts. 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 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](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 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

> [!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

- 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](#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.

## 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, 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.

## Managed by Northflank vs. managed by you

With an imported cluster (BYOK), more of the cluster lifecycle remains your responsibility than with a cluster provisioned by Northflank (BYOC).

| Area | BYOK | BYOC |
| --- | --- | --- |
| 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 |
| System components installed by Northflank ([see list](#what-northflank-installs)) | Northflank | Northflank |
| Workload orchestration and deployment | Northflank | Northflank |
| Cloud resources and billing | You | You |

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.

> [!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, all StatefulSets and all pods
> without an owner (even if they don't reference a persistent volume claim), and
> all Deployments, DaemonSets, and Jobs that reference a persistent volume
> claim. This includes volumes and workloads not managed by Northflank.

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

## Getting help

[Contact Northflank support](https://northflank.com/contact) if:

- The `Import Cluster (BYOK)` option is not available on your account

- Your cluster doesn't meet some of the [requirements](byoc-and-byok-requirements#byok-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

## Next steps

> [!note]
>
> Parts of the linked guides apply to clusters provisioned by Northflank (BYOC).
> On imported clusters, node provisioning, scaling, and deletion behaviour
> differ, see [managed by Northflank vs. managed by
> you](#managed-by-northflank-vs-managed-by-you).

- [Configure your Kubernetes cluster: Manage your clusters on other cloud providers using Northflank.](/v1/application/bring-your-own-cloud/configure-your-cluster)
- [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)