|
| 1 | +# Usage |
| 2 | + |
| 3 | +## Provision pods with NetBird access |
| 4 | + |
| 5 | +1. Create a Setup Key in your [NetBird console](https://docs.netbird.io/how-to/register-machines-using-setup-keys#using-setup-keys). |
| 6 | +1. Create a Secret object in the namespace where you need to provision NetBird access (secret name and field can be anything). |
| 7 | +```yaml |
| 8 | +apiVersion: v1 |
| 9 | +stringData: |
| 10 | + setupkey: EEEEEEEE-EEEE-EEEE-EEEE-EEEEEEEEEEEE |
| 11 | +kind: Secret |
| 12 | +metadata: |
| 13 | + name: test |
| 14 | +``` |
| 15 | +1. Create an NBSetupKey object referring to your secret. |
| 16 | +```yaml |
| 17 | +apiVersion: netbird.io/v1 |
| 18 | +kind: NBSetupKey |
| 19 | +metadata: |
| 20 | + name: test |
| 21 | +spec: |
| 22 | + # Optional, overrides management URL for this setupkey only |
| 23 | + # defaults to https://api.netbird.io |
| 24 | + managementURL: https://netbird.example.com |
| 25 | + secretKeyRef: |
| 26 | + name: test # Required |
| 27 | + key: setupkey # Required |
| 28 | +``` |
| 29 | +1. Annotate the pods you need to inject NetBird into with `netbird.io/setup-key`. |
| 30 | +```yaml |
| 31 | +kind: Deployment |
| 32 | +... |
| 33 | +spec: |
| 34 | +... |
| 35 | + template: |
| 36 | + metadata: |
| 37 | + annotations: |
| 38 | + netbird.io/setup-key: test # Must match the name of an NBSetupKey object in the same namespace |
| 39 | +... |
| 40 | + spec: |
| 41 | + containers: |
| 42 | +... |
| 43 | +``` |
| 44 | + |
| 45 | +## Provisioning Networks (Ingress Functionality) |
| 46 | + |
| 47 | +### Granting controller access to NetBird Management |
| 48 | + |
| 49 | +> [!IMPORTANT] |
| 50 | +> The NetBird Kubernetes operator generates configurations using NetBird API; editing or deleting these configurations in the NetBird console may cause temporary network disconnection until the operator reconciles the configuration. |
| 51 | + |
| 52 | +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). |
| 53 | +1. Create an access token for the Service User (Must be Admin). [Doc](https://docs.netbird.io/how-to/access-netbird-public-api#creating-a-service-user). |
| 54 | +1. Add access token to your helm values file under `netbirdAPI.key`. |
| 55 | + 1. Alternatively, provision secret in the same namespace as the operator and set the key `NB_API_KEY` to the access token generated. |
| 56 | + 1. Set `netbirdAPI.keyFromSecret` to the name of the secret created. |
| 57 | +1. Set `ingress.enabled` to `true`. |
| 58 | + 1. Optionally, to provision the network immediately, set `ingress.router.enabled` to `true`. |
| 59 | + 1. Optionally, to provision 1 network per > The NetBird Kubernetes operator generates configurations using NetBird API; editing or deleting these configurations in the NetBird console may cause temporary network disconnection until the operator reconciles the configuration. namespace, set `ingress.namespacedNetworks` to `true`. |
| 60 | +1. Run `helm install` or `helm upgrade`. |
| 61 | + |
| 62 | +Minimum values.yaml example: |
| 63 | +```yaml |
| 64 | +netbirdAPI: |
| 65 | + key: "nbp_XXxxxxxxXXXXxxxxXXXXXxxx" |
| 66 | +
|
| 67 | +ingress: |
| 68 | + enabled: true |
| 69 | +cluster: |
| 70 | + name: kubernetes |
| 71 | +``` |
| 72 | + |
| 73 | +### Exposing a Service |
| 74 | + |
| 75 | +> [!IMPORTANT] |
| 76 | +> Ingress DNS Resolution requires DNS Wildcard Routing to be enabled and at least one DNS Nameserver configured for clients. |
| 77 | + |
| 78 | +|Annotation|Description|Default|Valid Values| |
| 79 | +|---|---|---|---| |
| 80 | +|`netbird.io/expose`| Expose service using NetBird Network Resource ||(`null`, `true`)| |
| 81 | +|`netbird.io/groups`| Comma-separated list of group names to assign to Network Resource |`{ClusterName}-{Namespace}-{Service}`|Any comma-separated list of strings.| |
| 82 | +|`netbird.io/resource-name`| Network Resource name |`{Namespace}-{Service}`|Any valid network resource name, make sure they're unique!| |
| 83 | +|`netbird.io/policy`| Name of NBPolicy to propagate service ports as destination. ||Name of any NBPolicy resource| |
| 84 | +|`netbird.io/policy-ports`| Narrow down exposed ports in a policy. Leave empty for all ports. ||Comma-separated integer list, integers must be between 0-65535| |
| 85 | +|`netbird.io/policy-protocol`| Narrow down protocol for use in a policy. Leave empty for all protocols. ||(`tcp`,`udp`)| |
| 86 | + |
| 87 | +Example service: |
| 88 | +```yaml |
| 89 | +apiVersion: apps/v1 |
| 90 | +kind: Deployment |
| 91 | +metadata: |
| 92 | + name: nginx-deployment |
| 93 | +spec: |
| 94 | + replicas: 0 |
| 95 | + selector: |
| 96 | + matchLabels: |
| 97 | + app: nginx |
| 98 | + template: |
| 99 | + metadata: |
| 100 | + labels: |
| 101 | + app: nginx |
| 102 | + spec: |
| 103 | + containers: |
| 104 | + - name: nginx |
| 105 | + image: nginx:latest |
| 106 | + ports: |
| 107 | + - containerPort: 80 |
| 108 | +
|
| 109 | +--- |
| 110 | +apiVersion: v1 |
| 111 | +kind: Service |
| 112 | +metadata: |
| 113 | + name: nginx-service |
| 114 | + annotations: |
| 115 | + netbird.io/expose: "true" |
| 116 | + netbird.io/groups: "groupA,groupB" |
| 117 | +spec: |
| 118 | + selector: |
| 119 | + app: nginx |
| 120 | + ports: |
| 121 | + - protocol: TCP |
| 122 | + port: 8080 |
| 123 | + targetPort: 80 |
| 124 | + type: ClusterIP |
| 125 | +``` |
| 126 | +### Notes |
| 127 | +* `netbird.io/expose` will interpret any string as a `true` value; the only `false` value is `null`. |
| 128 | +* The operator does **not** handle duplicate resource names within the same network, it is up to you to ensure resource names are unique within the same network. |
| 129 | +* While the NetBird console will allow group names to contain commas, this is not allowed in `netbird.io/groups` annotation as commas are used as separators. |
| 130 | +* If a group already exists on NetBird console with the same name, NetBird Operator will use that group ID instead of creating a new group. |
| 131 | +* NetBird Operator will attempt to clean up any resources created, including groups created for resources. |
| 132 | + * If a group is used by resources that the operator cannot clean up, the operator will eventually ignore the group in NetBird. |
| 133 | + * It's recommended that unique groups be used per NetBird Operator installation to remove any possible conflicts. |
| 134 | +* The Operator does not validate service annotations on updates, as this may cause unnecessary overhead on any Service update. |
| 135 | + |
| 136 | +### Managing Policies |
| 137 | + |
| 138 | +Simply add policies under `ingress.policies`, for example: |
| 139 | +1. Add the following configuration in your `values.yaml` file. |
| 140 | +```yaml |
| 141 | +ingress: |
| 142 | + policies: |
| 143 | + default: |
| 144 | + name: Kubernetes Default Policy # Required, name of policy in NetBird console |
| 145 | + description: Default # Optional |
| 146 | + sourceGroups: # Required, name of groups to assign as source in Policy. |
| 147 | + - All |
| 148 | + ports: # Optional, resources annotated 'netbird.io/policy=default' will append to this. |
| 149 | + - 443 |
| 150 | + protocols: # Optional, restricts protocols allowed to resources, defaults to ['tcp', 'udp']. |
| 151 | + - tcp |
| 152 | + - udp |
| 153 | + bidirectional: true # Optional, defaults to true |
| 154 | +``` |
| 155 | +2. Reference policy in Services using `netbird.io/policy=default`, this will add relevant ports and destination groups to policy. |
| 156 | +3. (Optional) Limit specific ports in exposed service by adding `netbird.io/policy-ports=443`. |
| 157 | +4. (Optional) Limit specific protocol in exposed service by adding `netbird.io/policy-protocol=tcp`. |
| 158 | + |
| 159 | +#### Notes |
| 160 | +* Each NBPolicy will only create policies in the NetBird console when the information provided is enough to create one. If no services act as a destination or specified services do not conform to the protocol(s) defined, the policy will not be created. |
| 161 | +* Each NBPolicy will create one policy in the NetBird console per protocol specified as long as the protocol has destinations; this ensures better-secured policies by separating ports for TCP and UDP. |
| 162 | +* Policies currently do not support ICMP protocol, as ICMP is not supported in Kubernetes services, and there are [no current plans to support it](https://discuss.kubernetes.io/t/icmp-support-for-kubernetes-service/21738). |
0 commit comments