From f9e94c7d2cccb817bb7836aa455a0fcfbb524c71 Mon Sep 17 00:00:00 2001 From: Joao Gilberto Magalhaes Date: Thu, 22 Feb 2024 16:47:22 -0600 Subject: [PATCH] Improve documentation for issue #54 --- docs/docker.md | 11 ++++++----- docs/kubernetes.md | 14 ++++++++------ docs/limitations.md | 25 +++++++++++++++++++------ docs/microk8s.md | 1 + docs/swarm.md | 18 ++++++++++++------ 5 files changed, 46 insertions(+), 23 deletions(-) diff --git a/docs/docker.md b/docs/docker.md index 362b309..b35ae23 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -2,14 +2,15 @@ ## 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. -If you don't add to your services the same network EasyHAProxy is connected to, EasyHAProxy will attach it network to your container. +It's recommended to create a network external to EasyHAProxy. -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. e.g.: diff --git a/docs/kubernetes.md b/docs/kubernetes.md index 170fb21..bd2526a 100644 --- a/docs/kubernetes.md +++ b/docs/kubernetes.md @@ -2,15 +2,17 @@ ## 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 -- 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 Kubernetes cluster, follow these steps: -To install EasyHAProxy in your cluster, follow these steps: ### 1) Identify the node where your EasyHAProxy container will run diff --git a/docs/limitations.md b/docs/limitations.md index a839672..309ea52 100644 --- a/docs/limitations.md +++ b/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 -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. +EasyHAProxy currently operates under the assumption of a single replica deployment. + +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) \ No newline at end of file diff --git a/docs/microk8s.md b/docs/microk8s.md index b06d329..b4880f5 100644 --- a/docs/microk8s.md +++ b/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 diff --git a/docs/swarm.md b/docs/swarm.md index d8dc749..30bf810 100644 --- a/docs/swarm.md +++ b/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. -The advantage of this method is that you can discover containers in other nodes from the cluster. +This method involves using a Docker Swarm installation to discover containers and configure HAProxy. -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. -If you don't add to your services the same network EasyHAProxy is connected to, EasyHAProxy will attach it network to your container. +Utilizing Docker Swarm offers several advantages, including: + - 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." e.g.: