netbird-docs/src/pages/how-to/routing-peers-and-kubernetes.mdx

import {Note} from "@/components/mdx";

# Deploy routing peers to a Kubernetes cluster
This guide provides instructions on how to use NetBird agent within a Kubernetes cluster to establish secure, peer-to-peer
networking between your Kubernetes pods and external services or other clusters.

## Prerequisites
- Access to a Kubernetes cluster
- Kubernetes CLI (kubectl) installed and configured
- Access to the NetBird management dashboard

## Use Case Scenario
Imagine you're running a multi-cloud Kubernetes environment where your application components are distributed across
different cloud providers, including on-premise Kubernetes clusters. Your goal is to securely access your kubernetes services
from hosts running on a Hetzner without exposing them to the public internet.

## Step-by-Step guide
### Step 1: Create a setup key
Navigate to Setup Keys in the NetBird management dashboard and click on "Create setup key".

Choose a name, e.g. `Kubernetes routing peers`, mark the key as `reusable` and enable `Ephemeral peers`. This option is
ideal for stateless workloads like containers, where peers that are offline for over 10 minutes are automatically removed.

Create or add group called `kubernetes-routers` to the `Auto-assigned groups` list. This designation can be adjusted to
suit your needs.

See the screenshot below for reference:
<p>
    <img src="/docs-static/img/how-to-guides/k8s-create-setup-key.png" alt="k8s-create-setup-key" width="400" className="imagewrapper"/>
</p>

With your setup key created, note it down for the next steps.

### Step 2: Add a network route
Navigate to Network Routes in the NetBird management dashboard and click on `Add Route`.

Set your kubernetes pod range as the destination network, and select the `Peer group` option, choosing the
"kubernetes-routers" group. This configuration allows for scaling pods as necessary within your Kubernetes cluster.

Set the distribution group to `hetzner-servers`. This group is used to distribute the route to all servers in the group.

See the screenshot below for reference:
<p>
    <img src="/docs-static/img/how-to-guides/k8s-add-network-route.png" alt="k8s-add-network-route" width="400" className="imagewrapper"/>
</p>

Click on Name & Description to give your route a name and description. Then click on `Add Route` to save your changes.
<p>
    <img src="/docs-static/img/how-to-guides/k8s-name-network-route.png" alt="k8s-name-network-route" width="400" className="imagewrapper"/>
</p>

### Step 3: Create an access control policy
Navigate to Access Control Policies in the NetBird management dashboard and click on `Add Policy`.

Set the source group to `hetzner-servers` and the destination group to `kubernetes-routers`. This configuration allows
the Hetzner servers to access the kubernetes pods.
<p>
    <img src="/docs-static/img/how-to-guides/k8s-add-access-control-policy.png" alt="k8s-add-access-control-policy" width="400" className="imagewrapper"/>
</p>

Click on Name & Description to give your policy a name and description. Then click on `Add Policy` to save your changes.
<p>
    <img src="/docs-static/img/how-to-guides/k8s-name-access-control-policy.png" alt="k8s-name-access-control-policy" width="400" className="imagewrapper"/>
</p>

### Step 4: Deploy the NetBird agent
You can deploy the NetBird agent using a daemon set or a deployment. Below is an example of a deployment configuration with 1 replica.

```yaml
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: netbird
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: netbird
  template:
    metadata:
      labels:
        app: netbird
    spec:
      containers:
        - name: netbird
          image: netbirdio/netbird:latest
          env:
            - name: NB_SETUP_KEY
              value: "0000000000-0000-0000-0000-0000000000" # replace with your setup key
            - name: NB_HOSTNAME
              value: "netbird-k8s-router" # name that will appear in the management UI
            - name: NB_LOG_LEVEL
              value: "info"
          securityContext:
            capabilities:
              add:
                - NET_ADMIN
                - SYS_RESOURCE
                - SYS_ADMIN
```

Edit your deployment.yml file, incorporating the setup key into the relevant sections.

Apply the updated deployment file to your Kubernetes cluster using the following command:
```shell
kubectl apply -f deployment.yml
```

<Note>
    In this example the setup key is passed as an environment variable. You should use a secret to pass the setup key.
</Note>

### Step 5: Make the deployment highly available
NetBird network routes support multiple routing peers running in a fail-over mode, where one routing peer will be select
as gateway for a network and when this peer becomes unavailable other routing peer will be select for the role, proving a
highly available network route.

To make the deployment highly available, you can increase the number of replicas in the deployment configuration to 3 or more.

```yaml
---
...
spec:
  replicas: 3
...
```
Apply the updated deployment file to your Kubernetes cluster using the following command:
```shell
kubectl apply -f deployment.yml
```
### Step 6: Verify the deployment
After deploying the NetBird agent, you can verify that the agent is running by checking the logs of the pods.

```shell
kubectl logs -l app=netbird
```

You can also verify that the agent is connected to the NetBird management dashboard by checking the dashboard.
<p>
    <img src="/docs-static/img/how-to-guides/k8s-netbird-agent-connected.png" alt="k8s-netbird-agent-connected" className="imagewrapper-big"/>
</p>

## Conclusion
By following these steps, you've successfully integrated Netbird within your Kubernetes cluster, enabling secure,
peer-to-peer networking between your Kubernetes pods and external services. This setup is particularly beneficial for
hybrid, multi-cloud environments and remote access, ensuring seamless connectivity and security across your infrastructure.