WIP

Author: mohamed-essam

README.md

@@ -94,8 +94,62 @@ spec:
       containers:
       - image: yourimage
         name: container
+```
+
+## Provisioning Networks (Ingress Functionality)
+
+### Granting controller access to NetBird Management
+
+#### Using Helm
+
+1. Create a Service User on your NetBird dashboard (Must be Admin). [Doc](https://docs.netbird.io/how-to/access-netbird-public-api#creating-a-service-user).
+1. Create access token for the Service User (Must be Admin). [Doc](https://docs.netbird.io/how-to/access-netbird-public-api#creating-a-service-user).
+1. Add access token to your helm values file under `netbirdAPI.key`.
+    1. Alternatively, provision secret in the same namespace as the operator and set the key `NB_API_KEY` to the access token generated.
+    1. Then set `netbirdAPI.keyFromSecret` to the name of the secret created.
+1. Set `ingress.enabled` to `true`.
+    1. Optionally, to provision network immediately, set `ingress.router.enabled` to `true`.
+    1. Optionally, to provision 1 network per kubernetes namespace, set `ingress.namespacedNetworks` to `true`.
+1. Run `helm install` or `helm upgrade`.
+
+#### Without Helm
 
+1. Create access token.
+1. Expose access token to controller deployment with flag `--netbird-api-key`.
+
+### Exposing a Service
+
+> [!IMPORTANT]  
+> Ingress DNS Resolution requires DNS Wildcard Routing to be enabled, and at least one DNS Nameserver configured for clients.
+
+|Annotation|Description|Default|
+|---|---|---|
+|`netbird.io/expose`|Expose service using NetBird Network Resource||
+|`netbird.io/groups`|Comma-separated list of group names to assign to Network Resource|`{ClusterName}-{Namespace}-{Service}`|
+|`netbird.io/resource-name`|Network Resource name|`{Namespace}-{Service}`|
+|`netbird.io/policy`|Name of NBPolicy to propagate service ports as destination.||
+|`netbird.io/policy-ports`|Narrow down exposed ports in policy, leave empty for all ports.||
+|`netbird.io/policy-protocol`|Narrow down protocol for use in policy, leave empty for all protocols.||
+
+### Managing Policies
+
+1. Simply add policies under `ingress.policies`, for example.
+```yaml
+ingress:
+  policies:
+    default:
+      name: Kubernetes Default Policy # Required
+      description: Default # Optional
+      sourceGroups: # Required
+      - All
+      ports: # Optional, resources annotated 'netbird.io/policy=default' will append to this
+      - 443
+      protocols: # Optional, restricts protocols allowed to resources, defaults to ['tcp', 'udp']
+      - tcp
+      - udp
+      bidirectional: true # Optional, defaults to true
 ```
+2. Reference policy in Services using `netbird.io/policy=default`, this will add relevant ports and destination groups to Policy.
 
 ## Contributing
 

examples/ingress/exposed-nginx.yaml

@@ -0,0 +1,47 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    app: test
+  name: test
+  namespace: default
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: test
+  strategy:
+    rollingUpdate:
+      maxSurge: 25%
+      maxUnavailable: 25%
+    type: RollingUpdate
+  template:
+    metadata:
+      labels:
+        app: test
+    spec:
+      containers:
+      - image: nginx
+        imagePullPolicy: Always
+        name: nginx
+---
+apiVersion: v1
+kind: Service
+metadata:
+  annotations:
+    netbird.io/expose: "true"
+    netbird.io/policy: default
+    netbird.io/resource-name: nginx
+  labels:
+    app: test
+  name: test
+  namespace: default
+spec:
+  ports:
+  - name: http
+    port: 80
+    protocol: TCP
+    targetPort: 80
+  selector:
+    app: test
+  type: ClusterIP

examples/ingress/values.yaml

@@ -0,0 +1,12 @@
+ingress:
+  enabled: true
+  router:
+    enabled: true
+  policies:
+    default:
+      name: Kubernetes Default Policy
+      sourceGroups:
+      - All
+
+netbirdAPI:
+  key: "nbp_m0LM9ZZvDUzFO0pY50iChDOTxJgKFM3DIqmZ" # Replace with valid NetBird Service Account token