kubernetes-operator

README

NetBird Kubernetes Operator

For easily provisioning access to Kubernetes resources using NetBird.

https://github.com/user-attachments/assets/5472a499-e63d-4301-a513-ad84cfe5ca7b

Description

This operator easily provides NetBird access on Kubernetes clusters, allowing users to access internal resources directly.

Getting Started

Prerequisites

• (Recommended) helm version 3+
• kubectl version v1.11.3+.
• Access to a Kubernetes v1.11.3+ cluster.
• (Recommended) Cert Manager.

Deployment

1. Add helm repository.

helm repo add netbirdio https://netbirdio.github.io/kubernetes-operator

1. (Recommended) Install cert-manager for k8s API to communicate with the NetBird operator.

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.0/cert-manager.yaml

1. Add NetBird API token

kubectl create namespace netbird
kubectl -n netbird create secret generic netbird-mgmt-api-key --from-literal=NB_API_KEY=$(cat ~/nb-pat.secret)

1. (Recommended) Create a values.yaml file, check helm show values netbirdio/kubernetes-operator for more info.
2. Install using helm install --create-namespace -f values.yaml -n netbird netbird-operator netbirdio/kubernetes-operator.
3. (Recommended) Check pod status using kubectl get pods -n netbird.
4. (Optional) Create an exposed-nginx.yaml file to create a Nginx service for testing.
5. (Optional) Apply the Nginx service:

kubectl apply -f exposed-nginx.yaml

Learn more about the values.yaml options here and Granting controller access to NetBird Management.

Uninstallation

[!IMPORTANT] Most operator resources are annotated with finalizers, attempting to delete the namespace will result in hanged deletion.

1. (If ingress mode is enabled) Remove all instances of netbird.io/expose annotation on Services.
2. Run helm uninstall -n netbird netbird-operator.
3. Wait for all deletion jobs to finish.

Version

We have developed and executed tests against Kubernetes v1.31, but it should work with most recent Kubernetes version.

Latest operator version: v0.1.1.

Tested against:

Distribution	Test status	Kubernetes Version
Google GKE	Pass	1.31.5
AWS EKS	Pass	1.31
Azure AKS	Not tested	N/A
OpenShift	Not tested	N/A

We would love community feedback to improve the test matrix. Please submit a PR with your test results.

Usage

Check the usage of usage.md and examples.

Contributing

Prerequisites

To be able to develop this project, you need to have the following tools installed:

• Git.
• Make.
• Go programming language.
• Docker CE.
• Kubernetes cluster (v1.16+). KIND is recommended.
• Kubebuilder.

Running tests

Running unit tests

make test

Running E2E tests

kind create cluster # If not already created, you can check with `kind get clusters`
make test-e2e