Merge pull request #55 from byjg/issue/54

Improve documentation for issue #54

docs/docker.md

@@ -2,14 +2,19 @@
 
 ## Setup Docker EasyHAProxy
 
-This method will use a docker standalone installation to discover the containers and configure the HAProxy.
+This method involves using a standalone Docker installation to discover containers 
+and configure HAProxy.
 
-You cannot mix docker containers with swarm containers.
+EasyHAProxy inspects Docker containers and retrieves labels to configure HAProxy. 
+Once it identifies a container with at least the label 'easyhaproxy.http.host,' 
+it configures HAProxy to redirect traffic to that container. 
+To accomplish this, EasyHAProxy may need to attach the same network to its container.
 
-The only request is that containers and EasyHAProxy must be in the same docker network.
+It's recommended to create a network external to EasyHAProxy, although it's not mandatory.
-If you don't add to your services the same network EasyHAProxy is connected to, EasyHAProxy will attach it network to your container.
 
-Also, it is highly recommended you create a network external to EasyHAProxy.
+Limitations:
+ - You cannot mix Docker containers with Swarm containers.
+ - This method does not work with containers that use the '--network=host' option. (see [limitations](limitations.md))
 
 e.g.:
 

docs/kubernetes.md

@@ -2,15 +2,18 @@
 
 ## Setup Kubernetes EasyHAProxy
 
-EasyHAProxy for Kubernetes queries all ingress definitions with the annotation `kubernetes.io/ingress.class: easyhaproxy-ingress`. Once find the annotation, it will immediately set up HAProxy and start to serve it.
+EasyHAProxy for Kubernetes operates by querying all ingress definitions with the annotation 
+`kubernetes.io/ingress.class: easyhaproxy-ingress`. Upon finding this annotation, 
+EasyHAProxy immediately sets up HAProxy and begins serving traffic.
 
-There are three installation modes:
+For Kubernetes installations, there are three available installation modes:
+- DaemonSet: This mode exposes ports 80, 443, and 1936.
+- NodePort: Ports 31080, 31443, and 31936 are exposed.
+- ClusterIP: In this mode, no ports are exposed externally, and HAProxy is accessible only 
+  within the cluster.
 
-- DaemonSet: It will expose ports 80, 443 and 1936
+To install EasyHAProxy in your Kubernetes cluster, follow these steps:
-- NodePort: It will expose the ports 31080, 31443 and 31936
-- ClusterIP: it will node expose any port. The HAProxy will be accessible only inside the cluster.
 
-To install EasyHAProxy in your cluster, follow these steps:
 
 ### 1) Identify the node where your EasyHAProxy container will run
 

docs/limitations.md

@@ -1,13 +1,26 @@
-# Limitations
+# Limitations and Considerations
 
-EasyHAProxy currently expects to work in a single replica.
+## EasyHAProxy will not work with --network=host
 
-If more than one replica is running, EasyHAProxy will continue to work. However, each replica will discover the services independently.
+The --network=host option cannot be used with EasyHAProxy due to its networking requirements. 
+EasyHAProxy needs to inspect and interact with Docker containers from within the Docker network 
+where it's running. Using the --network=host option bypasses Docker networking, 
+preventing EasyHAProxy from accessing and configuring containers effectively.
 
-It means replicas can be out-of-sync for a few seconds because each replica will discover the pods separately.
+## Considerations for Multiple Replica Deployments in EasyHAProxy
 
-For Letsencrypt, this is worse because each replica will have a Letsencrypt certificate, and issuing a new one can fail because the
+EasyHAProxy currently operates under the assumption of a single replica deployment.
-letsencrypt challenge can be directed to the other replica. Also, you can hit the certificate issue limit. So if you intend to run multiple replicas **do not** activate letsencrypt.
+
+In the event of multiple replicas, EasyHAProxy can still operate; however, each replica will independently 
+discover services. This may lead to temporary inconsistencies among replicas as they may be out-of-sync 
+for a few seconds due to separate service discovery processes.
+
+However, it's crucial to highlight that running multiple replicas of EasyHAProxy can significantly 
+impact Letsencrypt certificate issuance. Each replica will possess its own Letsencrypt certificate, 
+potentially leading to challenges with certificate issuance. Challenges may be directed to different replicas,
+leading to potential failures in issuing new certificates and encountering certificate issuance limits. 
+Therefore, if you intend to run multiple replicas, it's advised to avoid activating Letsencrypt to mitigate 
+these issues.
 
 ----
 [Open source ByJG](http://opensource.byjg.com)

docs/microk8s.md

@@ -2,6 +2,7 @@
 
 Microk8s is a lightweight Kubernetes distribution that can run on a single machine. It is very easy to install and use.
 You can add custom addons to your Microk8s installation.
+
 Here are the steps to install EasyHAProxy on your Microk8s.
 
 ## Enabling EasyHAProxy on MicroK8s

docs/swarm.md

@@ -2,15 +2,21 @@
 
 ## Setup Docker EasyHAProxy
 
-This method will use a docker swarm installation to discover the containers and configure the HAProxy.
+This method involves using a Docker Swarm installation to discover containers and configure HAProxy.
-The advantage of this method is that you can discover containers in other nodes from the cluster.
 
-You cannot mix docker containers with swarm containers.
+EasyHAProxy inspects Docker containers within the Swarm and retrieves labels to configure HAProxy. Once it identifies a container with at least the label 'easyhaproxy.http.host,' it configures HAProxy to redirect traffic to that container. To accomplish this, EasyHAProxy may need to attach the same network to its container.
 
-The only request is that containers and EasyHAProxy must be in the same docker swarm network.
+Utilizing Docker Swarm offers several advantages, including:
-If you don't add to your services the same network EasyHAProxy is connected to, EasyHAProxy will attach it network to your container.
+ - Container Discovery: Docker Swarm facilitates the discovery of containers within the cluster, 
+   streamlining the process of identifying services for HAProxy configuration.
+ - Remote Node Management: Docker Swarm allows for the management of containers across multiple nodes, 
+   providing flexibility and scalability in deploying services while ensuring seamless HAProxy configuration across the cluster.
 
-Also, it is highly recommended you create a network external to EasyHAProxy.
+It's recommended to create a network external to EasyHAProxy.
+
+Limitations:
+ - You cannot mix Docker containers with Swarm containers.
+ - This method does not work with containers that use the '--network=host' option. (see [limitations](limitations.md))
 
 e.g.: