YuzuZensai/netbird-kubernetes-operator
1
0
Fork 0
mirror of https://github.com/YuzuZensai/netbird-kubernetes-operator.git synced 2026-09-13 10:49:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation with refactored resources (#204)

Browse Source 
This updates the documentation and examples to use the new resources. It
also adds automatic documentation creation for the api reference.

Signed-off-by: Philip Laine <philip.laine@gmail.com>
This commit is contained in:
Philip Laine
2026-04-24 16:22:04 +02:00
committed by GitHub
parent fe715ae40c
commit dd054d50ec
19 changed files with 642 additions and 464 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+31 -86
View File
@@ -1,97 +1,42 @@
# NetBird Kubernetes Operator
For easily provisioning access to Kubernetes resources using NetBird.
https://github.com/user-attachments/assets/5472a499-e63d-4301-a513-ad84cfe5ca7b
The NetBird Kubernetes Operator automates the provisioning of NetBird network access for services running in your cluster.
## Description
## Documentation
This operator easily provides NetBird access on Kubernetes clusters, allowing users to access internal resources directly.
- [Getting Started](/docs/getting-started.md)
- [Usage](/docs/usage.md)
- [API Reference](/docs/api-reference.md)
## Getting Started
## How It Works
### Prerequisites
- (Recommended) helm version 3+
- kubectl version v1.11.3+.
- Access to a Kubernetes v1.11.3+ cluster.
- (Recommended) Cert Manager.
A `NetworkRouter` registers a NetBird router peer for a given DNS zone in your cluster.
### Deployment
1. Add helm repository.
```sh
helm repo add netbirdio https://netbirdio.github.io/kubernetes-operator
```
2. (Recommended) Install [cert-manager](https://cert-manager.io/docs/installation/#default-static-install) for k8s API to communicate with the NetBird operator.
```sh
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.0/cert-manager.yaml
```
3. Add NetBird API token
```shell
kubectl create namespace netbird
kubectl -n netbird create secret generic netbird-mgmt-api-key --from-literal=NB_API_KEY=$(cat ~/nb-pat.secret)
```
4. (Recommended) Create a [`values.yaml`](examples/ingress/values.yaml) file, check `helm show values netbirdio/kubernetes-operator` for more info.
5. Install using `helm install --create-namespace -f values.yaml -n netbird netbird-operator netbirdio/kubernetes-operator`.
6. (Recommended) Check pod status using `kubectl get pods -n netbird`.
6. (Optional) Create an [`exposed-nginx.yaml`](examples/ingress/exposed-nginx.yaml) file to create a Nginx service for testing.
7. (Optional) Apply the Nginx service:
```sh
kubectl apply -f exposed-nginx.yaml
```yaml
apiVersion: netbird.io/v1alpha1
kind: NetworkRouter
metadata:
name: prod
namespace: netbird
spec:
dnsZoneRef:
name: prod.company.internal
```
> Learn more about the values.yaml options [here](helm/kubernetes-operator/values.yaml) and [Granting controller access to NetBird Management](docs/usage.md#granting-controller-access-to-netbird-management).
A `NetworkResource` then exposes a Kubernetes service through that router to one or more NetBird groups.
### 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](docs/usage.md) and examples.
## Contributing
### Prerequisites
To be able to develop this project, you need to have the following tools installed:
- [Git](https://git-scm.com/).
- [Make](https://www.gnu.org/software/make/).
- [Go programming language](https://golang.org/dl/).
- [Docker CE](https://www.docker.com/community-edition).
- [Kubernetes cluster (v1.16+)](https://kubernetes.io/docs/setup/). [KIND](https://github.com/kubernetes-sigs/kind) is recommended.
- [Kubebuilder](https://book.kubebuilder.io/).
### Running tests
**Running unit tests**
```sh
make test
```yaml
apiVersion: netbird.io/v1alpha1
kind: NetworkResource
metadata:
name: nginx
namespace: default
spec:
networkRouterRef:
name: prod
namespace: netbird
serviceRef:
name: nginx
groups:
- name: All
```
**Running E2E tests**
```sh
kind create cluster # If not already created, you can check with `kind get clusters`
make test-e2e
```