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
The nginx-loadbalancer-kubernetes runs in a Kubernetes Cluster and responds to changes in resources of interest, updating designated NGINX Plus hosts with the appropriate configuration.
3
+
The nginx-loadbalancer-kubernetes runs in a Kubernetes cluster and responds to changes in specified services by issuing requests to the designated NGINX Plus hosts to update the appropriate upstreams.
4
4
5
5
## Basic Architecture
6
6
7
-
The controller is deployed in a Kubernetes Cluster. Upon startup, it registers interest in changes to Service resources in the "nginx-ingress" namespace.
8
-
The Handler accepts the events raised by the Cluster and calls the Translator to convert the events into event definitions that are used to update NGINX Plus hosts.
9
-
Next, the Handler calls the Synchronizer with the list of translated events which are fanned-out for each NGINX host.
10
-
Lastly, the Synchronizer calls the [NGINX+ Configuration API](https://docs.nginx.com/nginx/admin-guide/load-balancer/dynamic-configuration-api/) using the [NGINX Plus Go client](https://github.com/nginxinc/nginx-plus-go-client) to update the target NGINX Plus host(s).
7
+
The controller is deployed in a Kubernetes cluster. Upon startup, it registers interest in changes to services with the appropriate annotation.
8
+
The Watcher listens for events raised by the cluster and then adds these events to the Synchronizer's queue. The Synchronizer makes use of the Translator to transform the events into specific updates that will be sent to the NGINX Plus hosts.
9
+
Lastly, the Synchronizer calls the [NGINX+ Configuration API](https://docs.nginx.com/nginx/admin-guide/load-balancer/dynamic-configuration-api/) using the [NGINX Plus Go client](https://github.com/nginxinc/nginx-plus-go-client) to update the target NGINX Plus host(s).
The Settings module is responsible for loading the configuration settings from the "nlk-config" ConfigMap resource in the "nlk" namespace.
30
-
The Settings are loaded when the controller starts and are reloaded when the "nlk-config" ConfigMap resource is updated.
27
+
The Settings module is responsible for loading the configuration settings when the controller starts. Any changes made to the settings through helm at runtime will cause nginx-loadbalancer-kubernetes to be restarted.
31
28
32
29
### Watcher
33
30
34
-
The Watcher is responsible for monitoring changes to Service resources in the "nginx-ingress" namespace.
35
-
It registers methods that handle each event type. Events are handled by creating a `core.Event` instance and adding it to the "nlk-handler" queue.
36
-
When adding the event to the queue, the Watcher also retrieves the list of Node IPs and adds the list to the event.
37
-
The master node ip is excluded from the list. (NOTE: This should be configurable.)
38
-
39
-
### Handler
40
-
41
-
The Handler is responsible for taking the `core.Event` instances from the "nlk-handler" queue and calling the Translator to convert the event into a `core.ServerUpdateEvent` instance,
42
-
adding each `core.ServerUpdateEvent` to the "nlk-synchronizer" queue.
31
+
The Watcher is responsible for monitoring changes to Service resources that are annotated by the user.
32
+
It registers methods that handle each event type. An event is created for a particular service and is added to the "nlk-synchronizer" queue.
43
33
44
34
### Translator
45
35
46
-
The Translator is responsible for converting the `core.Event` event into an `nginxClient.UpstreamServer` event.
47
-
This involves filtering out the `core.Event` instances that are not of interest to the controller by accepting only Port names starting with the NlkPrefix value (currently _nlk-_).
48
-
The event is then fanned-out based on the defined Ports, one event per defined Port. Each port is then augmented with the Ingress name (the name configured in the Port definition with the NlkPrefix value removed),
49
-
and the list of the Node's IP addresses.
36
+
The Translator is responsible for converting a `core.Event` event into an `nginxClient.UpstreamServer` event.
50
37
51
-
The Translator passes the list of events to the Synchronizer by calling the `AddEvents` method.
38
+
The Translator assembles a list of IP addresses for the Kubernetes service, routing traffic to the NodePorts, ClusterIPs or external load balancer, depending on the Kubernetes service type. If the service is of type NodePort, the Translator excludes the master node IP from the list of the addresses. (NOTE: This should be configurable.)
39
+
40
+
The Translator uses the port name to determine the protocol and the name of the user's upstream. For example, if the user has named their service port "http-tea", the translator will create an update event for the HTTP upstream named "tea".
52
41
53
42
**NOTE: It is important that the Port names match the name of the defined NGINX Plus Upstreams.**
54
43
55
-
In the following example the NGINX Plus Upstreams are named "nlk-nginx-lb-http" and "nlk-nginx-lb-https". These match the name in the NGINX Plus configuration.
44
+
In the following example the service uses the `nginx.com/nginxaas: nginxaas` annotation so that NLK knows to monitor the service. NGINX Plus Upstreams are named "ingress" and "ingress-tls". These match the upstream names specified in the NGINX configuration on the NGINX Plus host.
56
45
57
46
```yaml
58
47
apiVersion: v1
59
48
kind: Service
60
49
metadata:
50
+
annotations:
51
+
nginx.com/nginxaas: nginxaas
61
52
name: nginx-ingress
62
53
namespace: nginx-ingress
63
54
spec:
@@ -66,48 +57,29 @@ spec:
66
57
- port: 80
67
58
targetPort: 80
68
59
protocol: TCP
69
-
name: nlk-nginx-lb-http
60
+
name: http-ingress
70
61
- port: 443
71
62
targetPort: 443
72
63
protocol: TCP
73
-
name: nlk-nginx-lb-https
64
+
name: http-ingress-tls
74
65
selector:
75
66
app: nginx-ingress
76
67
```
77
68
78
69
### Synchronizer
79
70
80
71
The Synchronizer is responsible for fanning-out the given list of `core.ServerUpdateEvent` events, one for each configured NGINX Plus host.
81
-
The NGINX Plus hosts are configured using a ConfigMap resource named "nlk-config" in the "nlk" namespace. An example of the ConfigMap is shown below.
72
+
The NGINX Plus hosts are configured through the helm chart `nlk.config.nginxHosts` value. Use a string for a single host and a sequence for multiple hosts. See the comments in `charts/nlk/values.yaml` for details.
This example includes two NGINX Plus hosts to support High Availability.
95
-
96
-
Additionally, the Synchronizer is responsible for taking the `core.ServerUpdateEvent` instances from the "nlk-synchronizer" queue and updating the target NGINX Plus host.
97
74
The Synchronizer uses the [NGINX Plus Go client](https://github.com/nginxinc/nginx-plus-go-client) to communicate with each NGINX Plus host.
98
75
99
-
100
76
#### Retry Mechanism
101
77
102
-
The Synchronizer uses a retry mechanism to handle failures when updating the NGINX Plus hosts.
103
-
The retry mechanism is implemented in the workqueue using the `workqueue.NewItemExponentialFailureRateLimiter`,
78
+
The Synchronizer uses a retry mechanism to handle failures when updating the NGINX Plus hosts.
79
+
The retry mechanism is implemented in the workqueue using the `workqueue.NewItemExponentialFailureRateLimiter`,
104
80
having defaults set to a base of 2 seconds, and a maximum of 60 seconds.
105
81
106
-
### Jitter
107
-
108
-
The Synchronizer uses a jitter mechanism to avoid thrashing the NGINX Plus hosts. Each `core.ServerUpdateEvent` instance
109
-
is added to the "nlk-synchronizer" queue with a random jitter value between 250 and 750 milliseconds.
110
-
111
82
## Authors
83
+
112
84
- Steve Wagner - Solutions Architect - Community and Alliances @ F5, Inc.
113
85
- Chris Akker - Solutions Architect - Community and Alliances @ F5, Inc.
0 commit comments