From 0ef20e5dc3bd87bbe87efcd43c1a68bef645a4b5 Mon Sep 17 00:00:00 2001 From: Philip Laine Date: Wed, 13 May 2026 12:43:27 +0200 Subject: [PATCH] Move docs to NetBird documentation website. (#247) We should not keep duplicate documentation so this change updates the README and removes the docs from the repository. --- README.md | 52 ++++++--------- docs/getting-started.md | 42 ------------- docs/usage.md | 136 ---------------------------------------- 3 files changed, 20 insertions(+), 210 deletions(-) delete mode 100644 docs/getting-started.md delete mode 100644 docs/usage.md diff --git a/README.md b/README.md index 67564be..9022da3 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,30 @@ # NetBird Kubernetes Operator -The NetBird Kubernetes Operator automates the provisioning of NetBird network access for services running in your cluster. +The NetBird Kubernetes Operator automates the provisioning of NetBird network access for services running in your cluster. It extends the Kubernetes API with CRDs, letting you manage NetBird peers, routes, and groups declaratively, the same way you manage the rest of your infrastructure. -## Documentation +# Features -- [Getting Started](/docs/getting-started.md) -- [Usage](/docs/usage.md) -- [API Reference](/docs/api-reference.md) +* Declarative peer management - define NetBird peers as Kubernetes resources and let the operator handle provisioning and lifecycle +* Automatic secret management - setup keys and credentials are stored and rotated as Kubernetes secrets +* Namespace-scoped or cluster-wide - deploy per-namespace for multi-tenant clusters or cluster-wide for full coverage +* Works with any NetBird deployment - compatible with NetBird Cloud and self-hosted instances -## How It Works +## Getting Started -A `NetworkRouter` registers a NetBird router peer for a given DNS zone in your cluster. +For full setup instructions, see the [Getting Started](https://docs.netbird.io/manage/integrations/kubernetes) documentation. -```yaml -apiVersion: netbird.io/v1alpha1 -kind: NetworkRouter -metadata: - name: prod - namespace: netbird -spec: - dnsZoneRef: - name: prod.company.internal +Once your secret is configured, install the operator with Helm. + +```shell +helm upgrade --install --create-namespace -n netbird netbird-operator oci://ghcr.io/netbirdio/helm-charts/netbird-operator ``` -A `NetworkResource` then exposes a Kubernetes service through that router to one or more NetBird groups. +## API -```yaml -apiVersion: netbird.io/v1alpha1 -kind: NetworkResource -metadata: - name: nginx - namespace: default -spec: - networkRouterRef: - name: prod - namespace: netbird - serviceRef: - name: nginx - groups: - - name: All -``` +| Kind | API Version | +|------|-------------| +| [Group](docs/api-reference.md#group) | `netbird.io/v1alpha1` | +| [NetworkResource](docs/api-reference.md#networkresource) | `netbird.io/v1alpha1` | +| [NetworkRouter](docs/api-reference.md#networkrouter) | `netbird.io/v1alpha1` | +| [SetupKey](docs/api-reference.md#setupkey) | `netbird.io/v1alpha1` | +| [SidecarProfile](docs/api-reference.md#sidecarprofile) | `netbird.io/v1alpha1` | diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index c14a021..0000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,42 +0,0 @@ -# Getting Started - -## Prerequisites - -- A NetBird [service user access token](https://docs.netbird.io/manage/public-api). -- Access to Kubernetes cluster. -- Kubectl and Helm installed locally. - -## Steps - -Add the Helm repository. - -```sh -helm repo add netbirdio https://netbirdio.github.io/helms -``` - -Install cert-manager, it is recommended so the Kubernetes API can communicate with the operator's admission webhooks. Skip this step if you already have cert-manager installed. - -```sh -kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.0/cert-manager.yaml -``` - -Create the NetBird namespace and API secret. The operator needs a NetBird personal access token to authenticate with the NetBird Management API. - -```sh -kubectl create namespace netbird -kubectl -n netbird create secret generic netbird-mgmt-api-key --from-literal=NB_API_KEY=${ACCESS_TOKEN} -``` - -Install the Netbird operator. - -```sh -helm install netbird-operator netbirdio/kubernetes-operator --create-namespace --namespace netbird -``` - -Verify the installation. All pods should be in a `Running` state before continuing. - -```sh -kubectl get pods -n netbird -``` - -Once the operator is running, see the [usage guide](/docs/usage.md) to start exposing services to your NetBird network. diff --git a/docs/usage.md b/docs/usage.md deleted file mode 100644 index 328dc89..0000000 --- a/docs/usage.md +++ /dev/null @@ -1,136 +0,0 @@ -# Usage - -## Exposing Services - -The operator exposes Kubernetes services to your NetBird network by combining two resources, a `NetworkRouter` and a `NetworkResource`. - -### NetworkRouter - -A `NetworkRouter` creates a network in NetBird and deploys routing peer pods in the cluster. These pods are configured as routing peers for the network, handling traffic between NetBird clients and services running in the cluster. - -Before creating a `NetworkRouter`, you must first create a custom DNS zone in the [NetBird dashboard](https://docs.netbird.io/manage/dns/custom-zones). The DNS zone must exist before the operator can register it. - -```yaml -apiVersion: netbird.io/v1alpha1 -kind: NetworkRouter -metadata: - name: prod - namespace: netbird -spec: - dnsZoneRef: - name: prod.company.internal -``` - -### NetworkResource - -A `NetworkResource` exposes a Kubernetes service in NetBird by creating a matching resource in the routers network. The cluster IP of the service will be used as the resource IP. A record in the routers zone will also be created using the name and namespace of the service. The following example creates an nignx deployment and exposes the service with the record `nginx.default.prod.company.internal`. - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: nginx - namespace: default - labels: - app: nginx -spec: - replicas: 1 - selector: - matchLabels: - app: nginx - strategy: - rollingUpdate: - maxSurge: 25% - maxUnavailable: 25% - type: RollingUpdate - template: - metadata: - labels: - app: nginx - spec: - containers: - - image: nginx - imagePullPolicy: Always - name: nginx ---- -apiVersion: v1 -kind: Service -metadata: - name: nginx - namespace: default - labels: - app: nginx -spec: - type: ClusterIP - ports: - - name: http - port: 80 - protocol: TCP - targetPort: 80 - selector: - app: nginx ---- -apiVersion: netbird.io/v1alpha1 -kind: NetworkResource -metadata: - name: nginx - namespace: default -spec: - networkRouterRef: - name: prod - namespace: netbird - serviceRef: - name: nginx - groups: - - name: All -``` - -Members of the `All` NetBird group can now reach the nginx service at `nginx.default.prod.company.internal` through the NetBird network. - -## Client Sidecar - -In certain situations we may want to have a pod act like a peer in the Netbird network instead of exposing it through a routing peer. In these cases a Netbird client container has to be added as a sidecar to the pod. - -Sidecars are appended to pods when created if they match the selector of a sidecar profile. A sidecar profile defines the configuration of the sidecar, like the setup key to be used along with other parameters. An empty selector will match with all pods in the namespace. The sidecar profile needs to be created first before any pod is created. - -```yaml -apiVersion: netbird.io/v1alpha1 -kind: SetupKey -metadata: - name: sidecar - namespace: default -spec: - name: sidecar - ephemeral: true ---- -apiVersion: netbird.io/v1alpha1 -kind: SidecarProfile -metadata: - name: test - namespace: default -spec: - setupKeyRef: - name: sidecar - podSelector: - matchLabels: - app: ubuntu -``` - -When a pod matching the selector is created it will receive a netbird sidecar container. - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: ubuntu - namespace: default - labels: - app: ubuntu -spec: - containers: - - name: ubuntu - image: ubuntu:latest - command: ["sleep", "infinity"] -``` - -Once both containers have started the pod should show up like a peer in the Netbird dashboard.