CLEANUP/MINOR: doc: use same wording for custom annotations

Author: oktalz

cmd/docs/annotations.go

@@ -28,6 +28,10 @@ import (
 var header = `
 This is autogenerated from [doc.yaml](doc.yaml). Description can be found in [generator readme](gen/README.md)
 
+### Custom annotations
+
+more info about custom annotations can be found in [annotations-custom.md](annotations-custom.md)
+
 ### Available annotations
 
 > :information_source: Ingress and service annotations can have ` + "`ingress.kubernetes.io`, `haproxy.org` and `haproxy.com`" + ` prefixes

documentation/user-annotations.md documentation/annotations-custom.mddocumentation/user-annotations.md renamed to documentation/annotations-custom.md

@@ -1,14 +1,14 @@
-# User annotations
+# Custom annotations
 
-User annotations are custom annotations with full validation that user can create for frontend and backend side of HAProxy configuration. They can be limited for certain resources and they unlock all HAProxy options that might not be available with other options.
+Custom annotations are annotations with full validation that user can create for frontend and backend side of HAProxy configuration. They can be limited for certain resources and they unlock all HAProxy options that might not be available with other options. In background they use CRD (Custom resources definition) to validate its content and access.
 
 ## Why ?
 
 HAProxy has extensive number of powerful options to tweak load balancing: [docs.haproxy.org](https://docs.haproxy.org/). The best way to expose them in most reliable way is to provide a secure method to deploy them while still allowing full exposure of settings that HAProxy provides.
 
 ## What is the main difference if we compare them to CRDs ?
 
-They are pretty similar, both have validation and can potentially add almost everything HAProxy can offer. Main difference with CRDs is, that CRDs do not have granularity like we can have with user defined annotations.
+They are pretty similar, both have validation and can potentially add almost everything HAProxy can offer. Main difference with CRDs is, that CRDs do not have granularity like we can have with custom defined annotations.
 
 ## What is the main difference compared to config snippets
 
@@ -21,27 +21,27 @@ In short reliability, validation and security. While snippets allow really high
 The most important difference is security part of it. With custom annotations there is clear separation of two groups of people who configure and consume them:
 
 - Administrator
-  using pre defined CRD, administrator can define and limit usage of user annotations. This can be achieved with limiting annotation on certain HAProxy section, service, ingress or namespace if needed. Also, if a specific service or group needs a little more freedom in what to configure, administrator can create a user annotation that is specific to that team.
+  using pre defined CRD, administrator can define and limit usage of custom annotations. This can be achieved with limiting annotation on certain HAProxy section, service, ingress or namespace if needed. Also, if a specific service or group needs a little more freedom in what to configure, administrator can create a custom annotation that is specific to that team.
 
 - Developers/Teams
   Teams gets a list of all available annotations that admin created. If more is needed, request can be sent to admin to create additional annotation.
 
 ### Validation
 
-User defined annotations have validation. [Common Expression language](https://github.com/google/cel-spec) is used to write rules. Rules can be simple or strict. The more strict rule is there is less chance of accidental mistake.
+Custom annotations have validation. [Common Expression language](https://github.com/google/cel-spec) is used to write rules. Rules can be simple or strict. The more strict rule is there is less chance of accidental mistake.
 
 ### Speed of delivery
 
-While number of annotations have grown over time in this project, no two deployments are the same. Company A needs different customization than Company B. While purpose of this project is to cover all possible ideas and setups our users might need, it is not possible to cover all use cases with (in the end) limited number of resources and time. With user annotation there is no need to wait until new annotation is accepted, developed and released, we can simply create a new one, deploy it and start using it immediately after we deploy it.
+While number of annotations have grown over time in this project, no two deployments are the same. Company A needs different customization than Company B. While purpose of this project is to cover all possible ideas and setups our users might need, it is not possible to cover all use cases with (in the end) limited number of resources and time. With custom annotation there is no need to wait until new annotation is accepted, developed and released, we can simply create a new one, deploy it and start using it immediately after we deploy it.
 
 ### Monitoring
 
 We all read logs, right, right ?
 While we do have a log message with annotations where we can see if some annotations is not accepted due to xyz, user annotations have additional advantage. Even in case if validation was not successful it will still appear in configuration, but as comment on certain frontend or backend. Additionall, as a comment, error message will appear that will explain what went wrong.
 
-## How can I distinguish user annotations from 'regular' ones ?
+## How can I distinguish custom annotations from 'regular' ones ?
 
-As seen in [annotations.md](https://github.com/haproxytech/kubernetes-ingress/blob/master/documentation/annotations.md), HAProxy annotations can have `ingress.kubernetes.io`, `haproxy.org` and `haproxy.com` prefixes. User annotations can have any prefix we define. For example a 'famous' example.com corporation can use `example.com` prefix. How exactly structure is defined we will see next.
+As seen in [annotations.md](https://github.com/haproxytech/kubernetes-ingress/blob/master/documentation/annotations.md), HAProxy annotations can have `ingress.kubernetes.io`, `haproxy.org` and `haproxy.com` prefixes. Custom annotations can have any prefix we define. For example a 'famous' example.com corporation can use `example.com` prefix. How exactly structure is defined we will see next.
 
 ## Is there any downside ?
 
@@ -51,7 +51,7 @@ Not really, but we always need to keep in mind that adding/modifying annotation
 
 ### CRD
 
-We need to write a CRD where we will define all user annotations.
+We need to write a CRD where we will define all custom annotations.
 
 ```yaml
 apiVersion: ingress.v3.haproxy.org/v3 # yes, you are right, CRD updates are lovely
@@ -60,7 +60,7 @@ metadata:
   name: example-validationrules
   namespace: haproxy-controller
 spec:
-  prefix: "example.com" # company prefix for user defined annotations
+  prefix: "example.com" # company prefix for custom annotations
   validation_rules: # list of user defined annotations
     # Rule for 'timeout-server' accepting duration values
     timeout-server:
@@ -252,7 +252,7 @@ there are several values we can use in template that are predefined
       section: backend
       template: |
         # ==============================================
-          # user annotation, owner: {{.owner}} - Reason: {{.reason}} for {{.BACKEND}}
+          # custom annotation, owner: {{.owner}} - Reason: {{.reason}} for {{.BACKEND}}
           # namespace {{.NAMESPACE}}, ingress {{.INGRESS}}, service {{.SERVICE}}
           # POD_NAME {{.POD_NAME}}, POD_NAMESPACE {{.POD_NAMESPACE}}, POD_IP {{.POD_IP}}
           # ==============================================
@@ -275,7 +275,7 @@ usage (as you see while rule and template is complex, usage is simple)
     backend.example.com/timeouts: |
       {
         "owner": "oktalz",
-        "reason": "user annotations demo",
+        "reason": "custom annotations demo",
         "server": "51s",
         "server_fin": "20s",
         "tarpit": "5s"
@@ -287,7 +287,7 @@ config
 ```txt
   ### example.com/timeouts ###
   # ==============================================
-  # user annotation, owner: oktalz - Reason: user annotations demo for default_svc_http-echo_http
+  # custom annotation, owner: oktalz - Reason: custom annotations demo for default_svc_http-echo_http
   # namespace default, ingress http-echo, service http-echo
   # POD_NAME haproxy-ingress-56ml56gs, POD_NAMESPACE haproxy-controller, POD_IP 10.8.0.2
   # ==============================================
@@ -308,7 +308,7 @@ config
         - <name>
       ingresses: # limit usage to specific ingresses
         - <name>
-      order_priority: 100 # order of user annotations in config. higher is more priority
+      order_priority: 100 # order of custom annotations in config. higher is more priority
       template: "timeout server {{.}}" # template we can use (golang templates)
       type: duration # expected data type for conversion (duration;int;uint;bool;string;float;json;)
       rule: "value > duration('42s') && value <= duration('42m')" # CEL expression
@@ -339,12 +339,12 @@ its similar as with other configuration values, except we define it as configmap
 
 ### Structure
 
-`frontend.<frontend-name>.<org>/<user-annotation-name>`
+`frontend.<frontend-name>.<org>/<custom-annotation-name>`
 
-the only difference is extra information what frontend this settings belong to. With HAProxy Ingress controller, you have 3 different frontends: `http`, `https` and `stats`, each can be customized with user annotations.
+the only difference is extra information what frontend this settings belong to. With HAProxy Ingress controller, you have 3 different frontends: `http`, `https` and `stats`, each can be customized with custom annotations.
 
 
-## Where can user annotations can be defined ?
+## Where can custom annotations can be defined ?
 
 ### Frontend Annotations
 
@@ -357,7 +357,7 @@ metadata:
   name: haproxy-kubernetes-ingress
   namespace: haproxy-controller
   annotations:
-    frontend.<frontend-name>.<org>/<user-annotation-name>: <value>
+    frontend.<frontend-name>.<org>/<custom-annotation-name>: <value>
 ```
 
 ### Backend Annotations
@@ -366,8 +366,8 @@ you can define them on:
 
 - `configmap` - this will be applied for each backend
 - ⚠ `ingress` - this will be applied on services used in ingress. **use with precaution.**
-  - setting user annotations on ingress level is disabled by default!
-  - use `--enable-user-annotations-on-ingress` to enable it. Setting different annotation values in different ingresses for same service will trigger **inconsistencies**, so this is not encouraged. use `service` annotations.
+  - setting custom annotations on ingress level is disabled by default!
+  - use `--enable-custom-annotations-on-ingress` to enable it. Setting different annotation values in different ingresses for same service will trigger **inconsistencies**, so this is not encouraged. use `service` annotations.
 - `service` - this will be applied just on service
 
 #### what happens if you try to use same annotation on multiple places

documentation/annotations.md

@@ -4,6 +4,10 @@
 ## HAProxy kubernetes ingress controller 3.0
 This is autogenerated from [doc.yaml](doc.yaml). Description can be found in [generator readme](gen/README.md)
 
+### Custom annotations
+
+more info about custom annotations can be found in [annotations-custom.md](annotations-custom.md)
+
 ### Available annotations
 
 > :information_source: Ingress and service annotations can have `ingress.kubernetes.io`, `haproxy.org` and `haproxy.com` prefixes

documentation/controller.md

@@ -50,7 +50,7 @@ Image can be run with arguments:
 | [`--input-file`](#--input-file) :construction:(dev) |  |
 | [`--output-file`](#--output-file) :construction:(dev) |  |
 | [`--disable-ingress-status-update`](#--disable-ingress-status-update) | `false` |
-| [`--enable-user-annotations-on-ingress`](#--enable-user-annotations-on-ingress) :construction:(dev) |  |
+| [`--enable-custom-annotations-on-ingress`](#--enable-custom-annotations-on-ingress) :construction:(dev) |  |
 
 
 ### `--configmap`
@@ -907,12 +907,12 @@ Example:
 
 ***
 
-### `--enable-user-annotations-on-ingress`
+### `--enable-custom-annotations-on-ingress`
 
 
   > :construction: this is only available from next version, currently available in dev build
 
-  Enable support for user annotations on ingress resources.
+  Enable support for custom annotations on ingress resources.
 Use with caution when using the same annotation on multiple ingresses for same service.
 
 Possible values:
@@ -922,7 +922,7 @@ Possible values:
 Example:
 
 ```yaml
---enable-user-annotations-on-ingress
+--enable-custom-annotations-on-ingress
 ```
 
 <p align='right'><a href='#haproxy-kubernetes-ingress-controller'>:arrow_up_small: back to top</a></p>

documentation/doc.yaml

@@ -430,11 +430,11 @@ image_arguments:
     default: false
     version_min: "3.0"
     example: --disable-ingress-status-update
-  - argument: --enable-user-annotations-on-ingress
+  - argument: --enable-custom-annotations-on-ingress
     description: |-
-        Enable support for user annotations on ingress resources.
+        Enable support for custom annotations on ingress resources.
         Use with caution when using the same annotation on multiple ingresses for same service.
-    example: --enable-user-annotations-on-ingress
+    example: --enable-custom-annotations-on-ingress
     version_min: "3.2"
     values:
       - Boolean value, just need to declare the flag

pkg/k8s/informers.go

@@ -637,7 +637,7 @@ func (k k8s) addIngressHandlers(eventChan chan k8ssync.SyncDataEvent, informer c
 	_, err := informer.AddEventHandler(
 		cache.ResourceEventHandlerFuncs{
 			AddFunc: func(obj interface{}) {
-				item, err := store.ConvertToIngress(obj, osArgs.EnableUserAnnotationsIngress)
+				item, err := store.ConvertToIngress(obj, osArgs.EnableCustomAnnotationsOnIngress)
 				if err != nil {
 					logger.Errorf("%s: Invalid data from k8s api, %s", k8ssync.INGRESS, obj)
 					return
@@ -654,7 +654,7 @@ func (k k8s) addIngressHandlers(eventChan chan k8ssync.SyncDataEvent, informer c
 				eventChan <- ToSyncDataEvent(item, item, uid, resourceVersion)
 			},
 			DeleteFunc: func(obj interface{}) {
-				item, err := store.ConvertToIngress(obj, osArgs.EnableUserAnnotationsIngress)
+				item, err := store.ConvertToIngress(obj, osArgs.EnableCustomAnnotationsOnIngress)
 				if err != nil {
 					logger.Errorf("%s: Invalid data from k8s api, %s", k8ssync.INGRESS, obj)
 					return
@@ -671,7 +671,7 @@ func (k k8s) addIngressHandlers(eventChan chan k8ssync.SyncDataEvent, informer c
 				eventChan <- ToSyncDataEvent(item, item, uid, resourceVersion)
 			},
 			UpdateFunc: func(oldObj, newObj interface{}) {
-				item, err := store.ConvertToIngress(newObj, osArgs.EnableUserAnnotationsIngress)
+				item, err := store.ConvertToIngress(newObj, osArgs.EnableCustomAnnotationsOnIngress)
 				if err != nil {
 					logger.Errorf("%s: Invalid data from k8s api, %s", k8ssync.INGRESS, oldObj)
 					return

pkg/utils/flags.go

@@ -123,5 +123,5 @@ type OSArgs struct {
 	CRDInputFile                      string         `long:"input-file" description:"The file path of a CRD manifest to convert"`
 	CRDOutputFile                     string         `long:"output-file" description:"The file path of the converted (to the most recent version) CRD manifest"`
 	DisableIngressStatusUpdate        bool           `long:"disable-ingress-status-update" description:"If true, disables updating the status field of Ingress resources"`
-	EnableUserAnnotationsIngress      bool           `long:"enable-user-annotations-on-ingress" description:"allow custom user annotations on ingress"`
+	EnableCustomAnnotationsOnIngress  bool           `long:"enable-custom-annotations-on-ingress" description:"allow custom user annotations on ingress"`
 }