You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> Learn more about the values.yaml options [here](helm/netbird-operator/values.yaml) and [Granting controller access to NetBird Management](docs/values.md#granting-controller-access-to-netbird-management).
33
34
#### Using install.yaml
34
35
35
36
> [!IMPORTANT]
36
-
> install.yaml only includes a very basic template for deploying a strippeddown version of kubernetes-operator.
37
-
> This excludes any and all configuration for ingress capabilities, and requires cert-manager to be installed.
37
+
> install.yaml only includes a very basic template for deploying a stripped-down version of Kubernetes-operator.
38
+
> This excludes any and all configurations for ingress capabilities and requires the cert-manager to be installed.
Copy file name to clipboardExpand all lines: docs/usage.md
+69-21Lines changed: 69 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -47,41 +47,89 @@ spec:
47
47
### Granting controller access to NetBird Management
48
48
49
49
> [!IMPORTANT]
50
-
> 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.
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
51
52
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 access token for the Service User (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
54
1. Add access token to your helm values file under `netbirdAPI.key`.
55
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
56
1. Set `netbirdAPI.keyFromSecret` to the name of the secret created.
57
57
1. Set `ingress.enabled` to `true`.
58
-
1. Optionally, to provision network immediately, set `ingress.router.enabled` to `true`.
59
-
1. Optionally, to provision 1 network per kubernetes namespace, set `ingress.namespacedNetworks` 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
60
1. Run `helm install` or `helm upgrade`.
61
61
62
+
Minimum values.yaml example:
63
+
```yaml
64
+
netbirdAPI:
65
+
key: "nbp_XXxxxxxxXXXXxxxxXXXXXxxx"
66
+
67
+
ingress:
68
+
enabled: true
69
+
```
70
+
62
71
### Exposing a Service
63
72
64
73
> [!IMPORTANT]
65
-
> Ingress DNS Resolution requires DNS Wildcard Routing to be enabled, and at least one DNS Nameserver configured for clients.
74
+
> Ingress DNS Resolution requires DNS Wildcard Routing to be enabled and at least one DNS Nameserver configured for clients.
66
75
67
76
|Annotation|Description|Default|Valid Values|
68
77
|---|---|---|---|
69
-
|`netbird.io/expose`|Expose service using NetBird Network Resource||(`null`, `true`)|
70
-
|`netbird.io/groups`|Comma-separated list of group names to assign to Network Resource|`{ClusterName}-{Namespace}-{Service}`|Any comma-separated list of strings.|
|`netbird.io/policy`|Name of NBPolicy to propagate service ports as destination.||Name of any NBPolicy resource|
73
-
|`netbird.io/policy-ports`|Narrow down exposed ports in policy, leave empty for all ports.||Comma-separated integer list, integers must be between 0-65535|
74
-
|`netbird.io/policy-protocol`|Narrow down protocol for use in policy, leave empty for all protocols.||(`tcp`,`udp`)|
78
+
|`netbird.io/expose`| Expose service using NetBird Network Resource ||(`null`, `true`)|
79
+
|`netbird.io/groups`| Comma-separated list of group names to assign to Network Resource |`{ClusterName}-{Namespace}-{Service}`|Any comma-separated list of strings.|
80
+
|`netbird.io/resource-name`| Network Resource name |`{Namespace}-{Service}`|Any valid network resource name, make sure they're unique!|
81
+
|`netbird.io/policy`| Name of NBPolicy to propagate service ports as destination. ||Name of any NBPolicy resource|
82
+
|`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|
83
+
|`netbird.io/policy-protocol`| Narrow down protocol for use in a policy. Leave empty for all protocols. ||(`tcp`,`udp`)|
84
+
85
+
Example service:
86
+
```yaml
87
+
apiVersion: apps/v1
88
+
kind: Deployment
89
+
metadata:
90
+
name: nginx-deployment
91
+
spec:
92
+
replicas: 0
93
+
selector:
94
+
matchLabels:
95
+
app: nginx
96
+
template:
97
+
metadata:
98
+
labels:
99
+
app: nginx
100
+
spec:
101
+
containers:
102
+
- name: nginx
103
+
image: nginx:latest
104
+
ports:
105
+
- containerPort: 80
75
106
107
+
---
108
+
apiVersion: v1
109
+
kind: Service
110
+
metadata:
111
+
name: nginx-service
112
+
annotations:
113
+
netbird.io/expose: "true"
114
+
netbird.io/groups: "groupA,groupB"
115
+
spec:
116
+
selector:
117
+
app: nginx
118
+
ports:
119
+
- protocol: TCP
120
+
port: 8080
121
+
targetPort: 80
122
+
type: ClusterIP
123
+
```
76
124
### Notes
77
-
* `netbird.io/expose` will interpret any string as true value, the only false value is `null`.
125
+
* `netbird.io/expose` will interpret any string as a `true` value; the only `false` value is `null`.
78
126
* 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.
79
127
* 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.
80
128
* 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.
81
129
* NetBird Operator will attempt to clean up any resources created, including groups created for resources.
82
-
* In case a group is used by resources that cannot be cleaned up by the operator, the operator will eventually ignore the group in NetBird.
83
-
* It's recommended to use unique groups per NetBird Operator installation to remove any possible conflicts.
84
-
* NetBird Operator does not validate service annotations on update, as this may cause unnecessary overhead on any Service update.
130
+
* If a group is used by resources that the operator cannot clean up, the operator will eventually ignore the group in NetBird.
131
+
* It's recommended that unique groups be used per NetBird Operator installation to remove any possible conflicts.
132
+
* The Operator does not validate service annotations on updates, as this may cause unnecessary overhead on any Service update.
85
133
86
134
### Managing Policies
87
135
@@ -102,11 +150,11 @@ ingress:
102
150
- udp
103
151
bidirectional: true # Optional, defaults to true
104
152
```
105
-
2. Reference policy in Services using `netbird.io/policy=default`, this will add relevant ports and destination groups to Policy.
106
-
3. (Optional) limit specific ports in exposed service by adding `netbird.io/policy-ports=443`.
107
-
4. (Optional) limit specific protocol in exposed service by adding `netbird.io/policy-protocol=tcp`.
153
+
2. Reference policy in Services using `netbird.io/policy=default`, this will add relevant ports and destination groups to policy.
154
+
3. (Optional) Limit specific ports in exposed service by adding `netbird.io/policy-ports=443`.
155
+
4. (Optional) Limit specific protocol in exposed service by adding `netbird.io/policy-protocol=tcp`.
108
156
109
157
#### Notes
110
-
* Each NBPolicy will only create policies in NetBird console when information provided is enough to create one. If there are no services acting as destination, or specified services do not conform to the protocol(s) defined, policy will not be created.
111
-
* Each NBPolicy will create one Policy in NetBird console per protocol specified as long as protocol has destinations, this ensures bettersecured policies by separating ports for TCP and UDP.
112
-
* 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).
158
+
* 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.
159
+
* 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.
160
+
* 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