mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-16 07:26:35 +00:00
add documentation for k8s operator gateway api beta (#668)
This commit is contained in:
Nicolas Frati
@@ -456,6 +456,7 @@ export const docsNavigation = [
|
||||
isOpen: true,
|
||||
links: [
|
||||
{ title: 'Operator', href: '/manage/integrations/kubernetes' },
|
||||
{ title: 'Gateway API beta', href: '/manage/integrations/kubernetes/gateway-api-beta' },
|
||||
],
|
||||
},
|
||||
],
|
||||
@@ -796,7 +797,7 @@ function NavigationGroup({ group, className, hasChildren }) {
|
||||
onClick={() => {
|
||||
setIsOpen(!isOpen)
|
||||
if (!isOpen) {
|
||||
if (!isActiveGroup) router.push(group.links[0].href)
|
||||
if (!isActiveGroup && group.links[0]?.href) router.push(group.links[0].href)
|
||||
setActiveHighlight()
|
||||
} else {
|
||||
setActiveHighlight(group.title)
|
||||
|
||||
@@ -0,0 +1,253 @@
|
||||
# Kubernetes Gateway API Integration <Badge status="experimental" text="Beta" />
|
||||
|
||||
The NetBird Kubernetes operator supports the [Gateway API](https://gateway-api.sigs.k8s.io/) as an alternative to annotation-based service exposure. Using standard Gateway API resources, you can:
|
||||
|
||||
- **Expose services publicly** via reverse proxy using `HTTPRoute` resources with the public gateway class
|
||||
- **Expose services privately** to your NetBird network using `TCPRoute` resources with the private gateway class
|
||||
|
||||
The operator watches for these Gateway API resources and automatically creates the corresponding [Networks and Resources](/manage/networks) in your NetBird account.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, ensure you have the following:
|
||||
|
||||
- **Helm** version 3+ (recommended)
|
||||
- **kubectl** version v1.11.3+
|
||||
- Access to a **Kubernetes** v1.11.3+ cluster
|
||||
- **Cert Manager** (recommended) — for secure communication between the k8s API and the operator
|
||||
- A **NetBird API token** — you can create a PAT by following the steps [here](/manage/public-api#creating-a-service-user)
|
||||
|
||||
## Installation
|
||||
|
||||
### Step 1: Add the Helm repository
|
||||
|
||||
```shell
|
||||
helm repo add netbirdio https://netbirdio.github.io/helms
|
||||
```
|
||||
|
||||
### Step 2: Install Cert Manager
|
||||
|
||||
This is recommended for the k8s API to communicate securely with the NetBird operator.
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.0/cert-manager.yaml
|
||||
```
|
||||
|
||||
### Step 3: Install the Gateway API CRDs
|
||||
|
||||
The operator requires the experimental Gateway API CRDs to be installed in your cluster.
|
||||
|
||||
```shell
|
||||
kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/experimental-install.yaml
|
||||
```
|
||||
|
||||
### Step 4: Create the NetBird API secret
|
||||
|
||||
Create a namespace for the operator and store your API token as a Kubernetes secret.
|
||||
|
||||
```shell
|
||||
kubectl create namespace netbird
|
||||
kubectl -n netbird create secret generic netbird-mgmt-api-key --from-literal=NB_API_KEY=$(cat ~/nb-pat.secret)
|
||||
```
|
||||
|
||||
<Note>
|
||||
Replace `~/nb-pat.secret` with the path to your NetBird API key.
|
||||
</Note>
|
||||
|
||||
### Step 5: Install the operator
|
||||
|
||||
<Warning>
|
||||
The operator version 0.3.0-rc.2 is subject to breaking changes. Values and behavior may change in future releases.
|
||||
</Warning>
|
||||
|
||||
```shell
|
||||
helm upgrade --install kubernetes-operator netbirdio/kubernetes-operator \
|
||||
--namespace netbird \
|
||||
--create-namespace \
|
||||
--version 0.3.0-rc.2 \
|
||||
-f - <<EOF
|
||||
|
||||
gatewayAPI:
|
||||
enabled: true
|
||||
|
||||
webhook:
|
||||
enableCertManager: false
|
||||
|
||||
netbirdAPI:
|
||||
keyFromSecret:
|
||||
name: "netbird-mgmt-api-key"
|
||||
key: "NB_API_KEY"
|
||||
|
||||
EOF
|
||||
```
|
||||
|
||||
### Step 6: Verify the installation
|
||||
|
||||
```bash
|
||||
kubectl -n netbird get pods
|
||||
# Expected: netbird-operator-kubernetes-operator-xxxxx 1/1 Running
|
||||
```
|
||||
|
||||
## Configure Routing Peers and Gateways
|
||||
|
||||
Once the operator is running, deploy the routing peers and gateway resources. The operator supports two gateway classes:
|
||||
|
||||
- **`netbird-public`** — exposes services through a reverse proxy, making them accessible via a public hostname using `HTTPRoute` resources
|
||||
- **`netbird-private`** — exposes services as private network resources, accessible only to peers within your NetBird network using `TCPRoute` resources
|
||||
|
||||
```bash
|
||||
cat <<EOF | kubectl apply -f -
|
||||
|
||||
apiVersion: netbird.io/v1
|
||||
kind: NBRoutingPeer
|
||||
metadata:
|
||||
name: netbird
|
||||
namespace: netbird
|
||||
spec: {}
|
||||
---
|
||||
apiVersion: gateway.networking.k8s.io/v1
|
||||
kind: Gateway
|
||||
metadata:
|
||||
name: private
|
||||
namespace: netbird
|
||||
spec:
|
||||
gatewayClassName: netbird-private
|
||||
listeners:
|
||||
- protocol: gateway.netbird.io/NBRoutingPeer
|
||||
name: netbird
|
||||
port: 1
|
||||
---
|
||||
apiVersion: gateway.networking.k8s.io/v1
|
||||
kind: Gateway
|
||||
metadata:
|
||||
name: public
|
||||
namespace: netbird
|
||||
spec:
|
||||
gatewayClassName: netbird-public
|
||||
listeners:
|
||||
- protocol: gateway.netbird.io/NBRoutingPeer
|
||||
name: netbird
|
||||
port: 1
|
||||
|
||||
EOF
|
||||
```
|
||||
|
||||
## Expose Services via Reverse Proxy (Public Gateway)
|
||||
|
||||
Use `HTTPRoute` resources with the **public** gateway to expose Kubernetes services through a reverse proxy. You can optionally add the `hostnames` field to make the service accessible via a specific domain.
|
||||
|
||||
<Note>
|
||||
If using a custom hostname, make sure that the domain name is properly configured in your DNS settings.
|
||||
</Note>
|
||||
|
||||
The following example deploys a demo application and creates an `HTTPRoute` with a custom hostname pointing to the public gateway:
|
||||
|
||||
```bash
|
||||
export DEPLOYMENT_NAME=demo-nb-k8s; export DEPLOYMENT_IMAGE=ghcr.io/netbirdio/kubernetes-demo; cat <<EOF | kubectl apply -f -
|
||||
apiVersion: gateway.networking.k8s.io/v1
|
||||
kind: HTTPRoute
|
||||
metadata:
|
||||
name: $DEPLOYMENT_NAME
|
||||
namespace: default
|
||||
labels:
|
||||
app: $DEPLOYMENT_NAME
|
||||
spec:
|
||||
hostnames:
|
||||
# Optional: omit this field if you don't want to expose this through the reverse proxy
|
||||
- demo-nb-k8s.eu1.netbird.services
|
||||
parentRefs:
|
||||
- name: public
|
||||
namespace: netbird
|
||||
rules:
|
||||
- backendRefs:
|
||||
- name: $DEPLOYMENT_NAME
|
||||
port: 80
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: $DEPLOYMENT_NAME
|
||||
namespace: default
|
||||
labels:
|
||||
app: $DEPLOYMENT_NAME
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: $DEPLOYMENT_NAME
|
||||
strategy:
|
||||
rollingUpdate:
|
||||
maxSurge: 25%
|
||||
maxUnavailable: 25%
|
||||
type: RollingUpdate
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: $DEPLOYMENT_NAME
|
||||
spec:
|
||||
containers:
|
||||
- image: $DEPLOYMENT_IMAGE
|
||||
imagePullPolicy: Always
|
||||
name: demo
|
||||
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: $DEPLOYMENT_NAME
|
||||
namespace: default
|
||||
labels:
|
||||
app: $DEPLOYMENT_NAME
|
||||
spec:
|
||||
type: ClusterIP
|
||||
selector:
|
||||
app: $DEPLOYMENT_NAME
|
||||
ports:
|
||||
- name: http
|
||||
port: 80
|
||||
protocol: TCP
|
||||
targetPort: 80
|
||||
EOF
|
||||
```
|
||||
|
||||
## Expose Private Resources (Private Gateway)
|
||||
|
||||
Use `TCPRoute` resources with the **private** gateway to expose services as private network resources, accessible only to peers within your NetBird network.
|
||||
|
||||
The following example exposes the Kubernetes API server to your NetBird peers:
|
||||
|
||||
```bash
|
||||
cat <<EOF | kubectl apply -f -
|
||||
apiVersion: gateway.networking.k8s.io/v1alpha2
|
||||
kind: TCPRoute
|
||||
metadata:
|
||||
name: kubernetes
|
||||
namespace: default
|
||||
spec:
|
||||
parentRefs:
|
||||
- name: private
|
||||
namespace: netbird
|
||||
rules:
|
||||
- backendRefs:
|
||||
- name: kubernetes
|
||||
port: 443
|
||||
EOF
|
||||
```
|
||||
|
||||
## Work in progress features
|
||||
|
||||
We know the operator is not yet feature complete, but we thought you would like to hear that we're working on:
|
||||
- ACL policy attachment
|
||||
- Reverse Proxy authentication configuration
|
||||
- Multi-cluster support
|
||||
- Kubernetes API RBAC support
|
||||
|
||||
## Get started
|
||||
<div style={{textAlign: "center"}}>
|
||||
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
|
||||
</div>
|
||||
|
||||
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
|
||||
- Follow us [on X](https://x.com/netbird)
|
||||
- Join our [Slack Channel](/slack-url)
|
||||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|
||||
@@ -25,10 +25,14 @@ helm repo add netbirdio https://netbirdio.github.io/helms
|
||||
```shell
|
||||
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.0/cert-manager.yaml
|
||||
```
|
||||
3. Add NetBird API token. You can create a PAT by following the steps [here](/manage/public-api#creating-a-service-user).
|
||||
3. Install the Gateway API CRDs.
|
||||
```shell
|
||||
kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/experimental-install.yaml
|
||||
```
|
||||
4. Add NetBird API token. You can create a PAT by following the steps [here](/manage/public-api#creating-a-service-user).
|
||||
```shell
|
||||
kubectl create namespace netbird
|
||||
kubectl -n netbird create secret generic netbird-mgmt-api-key --from-literal=NB_API_KEY=$(cat ~/nb-pat.secret)
|
||||
kubectl -n netbird create secret generic netbird-mgmt-api-key --from-literal=NB_API_KEY=nbp_iVkOxFHOpx5K3Gc7qMqwCTqBWkHRpH2KunpX
|
||||
```
|
||||
<Note>
|
||||
Replace `~/nb-pat.secret` with your NetBird API key.
|
||||
|
||||
Reference in New Issue
Block a user