NLB-6740 docstrings updates

Updating the original NLK docstrings to bring them in line with the latest architectural changes.

Author: arussellf5

charts/nlk/values.yaml

@@ -33,7 +33,7 @@ nlk:
     ## trace,debug,info,warn,error,fatal,panic
     logLevel: "info"
 
-    ## the nginx hosts (comma-separated) to send upstream updates to
+    ## the nginx hosts to send upstream updates to. For multiple hosts, use a sequence
     nginxHosts: ""
     ## Sets the annotation value that NLK is looking for to watch a Service
     # serviceAnnotationMatch: nginxaas

internal/application/application_constants.go

@@ -5,20 +5,16 @@
 
 package application
 
-// These constants are intended for use in the Annotations field of the Service definition.
-// They determine which Border Server client will be used.
-// To use these values, add the following annotation to the Service definition:
+// These constants determine which Border Server client will be used. The name
+// of the port on the desired service needs to be formattted as follows:
+// "http-tea", where the first part is the protocol ("http" or "stream") and the
+// second part is the name of the upstream (in this case "tea").
 //
-//	annotations:
-//	  nginxinc.io/nlk-<upstream name>: <value>
-//
-// where <upstream name> is the name of the upstream in the NGINX Plus configuration
-// and <value> is one of the constants below.
-//
-// Note, this is an extensibility point. To add a Border Server client...
-// 1. Create a module that implements the BorderClient interface;
-// 2. Add a new constant to this group that acts as a key for selecting the client;
-// 3. Update the NewBorderClient factory method in border_client.go that returns the client;
+// Note, this is an extensibility point. To add a Border Server client... 1.
+// Create a module that implements the BorderClient interface; 2. Add a new
+// constant to this group that acts as a key for selecting the client; 3. Update
+// the NewBorderClient factory method in border_client.go that returns the
+// client;
 const (
 
 	// ClientTypeNginxStream creates a NginxStreamBorderClient that uses the Stream* methods of the NGINX Plus client.

internal/application/doc.go

@@ -3,32 +3,22 @@
  * Use of this source code is governed by the Apache License that can be found in the LICENSE file.
  */
 
-/*
-Package application includes support for applying updates to the Border servers.
-
-"Border Servers" are servers that are exposed to the outside world and direct traffic into the cluster.
-
-The BorderClient module defines an interface that can be implemented to support other Border Server types.
-To add a Border Server client...
-1. Create a module that implements the BorderClient interface;
-2. Add a new constant in application_constants.go that acts as a key for selecting the client;
-3. Update the NewBorderClient factory method in border_client.go that returns the client;
-
-At this time the only supported Border Servers are NGINX Plus servers.
+// Package application includes support for applying updates to the Border servers.
 
-The two Border Server clients for NGINX Plus are:
-- NginxHTTPBorderClient: updates NGINX Plus servers using HTTP Upstream methods on the NGINX Plus API.
-- NginxStreamBorderClient: updates NGINX Plus servers using Stream Upstream methods on the NGINX Plus API.
+// "Border Servers" are servers that are exposed to the outside world and direct traffic into the cluster.
 
-Both of these implementations use the NGINX Plus client module to communicate with the NGINX Plus server.
+// The BorderClient module defines an interface that can be implemented to support other Border Server types.
+// To add a Border Server client...
+// 1. Create a module that implements the BorderClient interface;
+// 2. Add a new constant in application_constants.go that acts as a key for selecting the client;
+// 3. Update the NewBorderClient factory method in border_client.go that returns the client;
 
-Selection of the appropriate client is based on the Annotations present on the Service definition, e.g.:
+// At this time the only supported Border Servers are NGINX Plus servers.
 
-	annotations:
-	  nginxinc.io/nlk-<upstream name>: <value>
+// The two Border Server clients for NGINX Plus are:
+// - NginxHTTPBorderClient: updates NGINX Plus servers using HTTP Upstream methods on the NGINX Plus API.
+// - NginxStreamBorderClient: updates NGINX Plus servers using Stream Upstream methods on the NGINX Plus API.
 
-where <upstream name> is the name of the upstream in the NGINX Plus configuration
-and <value> is one of the constants in application_constants.go.
-*/
+// Both of these implementations use the NGINX Plus client module to communicate with the NGINX Plus server.
 
 package application

internal/observation/watcher.go

@@ -21,9 +21,11 @@ import (
 	"k8s.io/client-go/tools/cache"
 )
 
-// Watcher is responsible for watching for changes to Kubernetes resources.
-// Particularly, Services in the namespace defined in the WatcherSettings::NginxIngressNamespace setting.
-// When a change is detected, an Event is generated and added to the Handler's queue.
+// Watcher is responsible for watching for changes to kubernetes services marked
+// with the correct annotation. NLK watches for changes to the services
+// themselves, but also changes to the nodes, endpoint slices and load balancers
+// associated with those services. When a change is detected, an Event is
+// generated and added to the synchronizer's queue.
 type Watcher struct {
 	synchronizer synchronization.Interface
 

internal/synchronization/doc.go

@@ -4,7 +4,7 @@
  */
 
 /*
-Package synchronization includes functionality to synchronize Ingress events to NGINX+ Configuration API commands.
+Package synchronization includes functionality to synchronize kubernetes service events to NGINX upstream updates.
 */
 
 package synchronization

internal/translation/doc.go

@@ -4,7 +4,7 @@
  */
 
 /*
-Package translation includes functionality to translate Ingress events to target system definitions.
+Package translation includes functionality to translate service events into NGINX upstream server updates.
 */
 
 package translation

internal/translation/translator.go

@@ -33,20 +33,19 @@ func NewTranslator(
 	}
 }
 
-// Translate transforms event data into an intermediate format that can be consumed by the BorderClient implementations
-// and used to update the Border Servers.
+// Translate transforms service events into upstream server updates that can be implemented by the border client.
 func (t *Translator) Translate(event *core.Event) (core.ServerUpdateEvents, error) {
 	slog.Debug("Translate::Translate")
 
 	return t.buildServerUpdateEvents(event.Service.Spec.Ports, event)
 }
 
-// buildServerUpdateEvents builds a list of ServerUpdateEvents based on the event type
-// The NGINX+ Client uses a list of servers for Created and Updated events.
-// The client performs reconciliation between the list of servers in the NGINX+ Client call
-// and the list of servers in NGINX+.
-// The NGINX+ Client uses a single server for Deleted events;
-// so the list of servers is broken up into individual events.
+// buildServerUpdateEvents builds a list of ServerUpdateEvents based on the
+// event type. The NGINX+ Client uses a list of servers for Created and Updated
+// events. The client performs reconciliation between the list of servers in the
+// NGINX+ Client call and the list of servers in NGINX+. If a delete event is
+// received, the translator generates an empty list of servers: the client
+// reconciliation will then cause all servers to be deleted.
 func (t *Translator) buildServerUpdateEvents(ports []v1.ServicePort, event *core.Event,
 ) (events core.ServerUpdateEvents, err error) {
 	slog.Debug("Translate::buildServerUpdateEvents", "ports", ports)