DOC: Add doc guide for the secondary haproxy config file

Author: Mo3m3n

documentation/secondary-config.md

@@ -0,0 +1,65 @@
+# Secondary HAProxy config file
+
+The ingress controller supports loading a secondary HAProxy configuration file where you can define additional sections such as resolvers, cache, etc
+
+The main configuration file, haproxy.cfg, which is generated by the ingress controller, reflects the state of services and ingress resources within your Kubernetes cluster. The secondary configuration file is loaded alongside it, but remains completely under your control.
+
+There are two main reasons to use the secondary configuration file:
+- Configure anything not supported by Ingress Controller annotations
+- Provide a stepping stone for migrating a legacy HAProxy config into one compatible with the HAProxy Kubernetes Ingress Controller.
+
+The secondary HAProxy config is expected to be mounted in  `/etc/haproxy/haproxy-aux.cfg` and Ingress Controller will monitor this file and reload haproxy when the file is updated.
+
+## Example: DNS runtime resolution
+
+In the following example, we define a secondary config file in order to configure runtime DNS resolution in HAProxy by creating a [resolvers section](https://www.haproxy.com/documentation/hapee/2-3r1/onepage/#5.3.2) named *mydns*.  
+DNS resolution at Runtime can be useful to handle kubernetes services of type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) or any other context where you want to target services by their DNS name.
+
+### Loading config file
+First, create a file named */tmp/haproxy-aux.cfg* in your local system and add a resolvers section to it, as shown in the following example configuration:
+```
+resolvers mydns          
+  nameserver local 127.0.0.1:53
+  nameserver google 8.8.8.8:53
+```
+
+Next, load the file into a ConfigMap:
+```bash
+$ kubectl create configmap haproxy-aux-cfg --from-file /tmp/haproxy-aux.cfg
+
+configmap/haproxy-aux-cfg created
+```
+
+Then mount the ConfigMap as a volume in the ingress controller pod by editing the pod YAML installation manifest to add **volumeMounts** and **volumes**.  
+The target mount location should be **/etc/haproxy/haproxy-aux.cfg** :
+```
+containers:
+  - name: haproxy-ingress             
+    image: haproxytech/kubernetes-ingress:latest
+    volumeMounts:
+      - name: haproxy-cfg-vol
+          mountPath: /etc/haproxy/haproxy-aux.cfg
+  volumes:
+    - name: haproxy-cfg-vol
+        configMap:
+          name: haproxy-aux-cfg
+```
+
+The resolvers section can then be referenced for example in the haproxy [default-server](https://www.haproxy.com/documentation/hapee/2-3r1/onepage/#5) directive via a [backend-config-snippet](./README.md#backend-config-snippet):
+```
+backend-config-snippet: default-server init-addr none resolvers mydns
+```
+This sets the default DNS resolution behavior for resolving the IP addresses of backend services:
+- They should start in a down state without any valid IP.
+- They should use resolvers from the mydns section.
+
+### Updating config file
+If you want to update the secondary config you will need to:
+1. Edit the config file
+2. Replace the ConfigMap:
+```bash
+$ kubectl create configmap haproxy-aux-cfg --from-file /tmp/haproxy-aux.cfg -o yaml --dry-run | kubectl replace -f -
+configmap/haproxy-aux-cfg replaced
+```
+After few seconds kubernetes will notice the updated ConfigMap and updates the mounted volume accordingly which will make Ingress Controller reload haproxy to take into account the new config file.
+