diff --git a/README.md b/README.md index 3688d93..e4b2e2b 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,9 @@ ## Service discovery for HAProxy -The main objective of EasyHAProxy is dynamically create the `haproxy.cfg` based on the labels defined in docker containers. +EasyHAProxy dynamically creates the `haproxy.cfg` based on the labels defined in docker containers. -EasyHAProxy can detect and configure automatically HAProxy on the folowing platforms: +EasyHAProxy can detect and configure HAProxy automatically on the following platforms: - Docker - Docker Swarm @@ -20,29 +20,32 @@ EasyHAProxy can detect and configure automatically HAProxy on the folowing platf ## Features -EasyHAProxy will discover the services based on the Docker Tags of the running containers in a Docker host or Docker Swarm cluster and dynamically set up the `haproxy.cfg`. Below, EasyHAProxy main features: +EasyHAProxy will discover the services based on the Docker Tags of the containers running on a Docker host or Docker Swarm cluster and dynamically set up the `haproxy.cfg`. Below, EasyHAProxy main features: - Use Letsencrypt with HAProxy. - Set your custom SSL certificates - Balance traffic between multiple replicas - Set SSL with three different levels of validations and according to the most recent definitions. -- Setup HAProxy to listen to TCP. +- Set up HAProxy to listen to TCP. - Add redirects. - Enable/disable Stats on port 1936 with a custom password. - Enable/disable custom errors. Also, it is possible to set up HAProxy from a simple Yaml file instead of creating `haproxy.cfg` file. -## How It Works? +## How Does It Works? You don't need to change your current infrastructure and don't need to learn the HAProxy configuration. -You need run the EasyHAProxy container, add some labels to your existing container and EasyHAProxy will -automatically detect them and setup HAProxy for you. +The steps are: + +- Run the EasyHAProxy container; +- Add some labels to the containers you want to be parsed by EasyHAProxy (see detailed instructions below); +- EasyHAProxy will automatically detect the containers, set up, and reload the HAProxy configurations for you without downtime. ## Detailed Instructions -For detailed instructions on how to use EasyHAProxy follow the instructions for the platform you want to use: +For detailed instructions on how to use EasyHAProxy, follow the instructions for the platform you want to use: | Kubernetes | Docker Swarm | Docker | Static |:----------:|:------------:|:------:|:-------: diff --git a/docs/container-labels.md b/docs/container-labels.md index 97988d5..384542b 100644 --- a/docs/container-labels.md +++ b/docs/container-labels.md @@ -18,7 +18,7 @@ The `definition` is a string that will group all configurations togethers. Different `definition` will create different configurations. -The container can have more than one defintion. +The container can have more than one definition. ## Configuations diff --git a/docs/docker.md b/docs/docker.md index a195129..0ea1950 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -4,7 +4,7 @@ This method will use a docker standalone installation to discover the containers and configure the HAProxy. -The only requirement is that containers and EasyHAProxy must be in the same docker network in order to HAProxy be able direct the traffic to the containers. +The only requirement is that containers and EasyHAProxy must be in the same docker network. e.g.: @@ -27,11 +27,11 @@ docker run -d \ byjg/easy-haproxy ``` -The mapping to `/var/run/docker.sock` is necessary to discover the docker containers and get the labels; +Mapping to `/var/run/docker.sock` is necessary to discover the docker containers and get the labels; ## Running containers -To make your containers "discoverable" by EasyHAProxy that is minimum configuration you need: +To make your containers "discoverable" by EasyHAProxy, that is the minimum configuration you need: ```bash docker run -d \ @@ -42,15 +42,15 @@ docker run -d \ my/image:tag ``` -Once the container is running EasyHAProxy will detect automatically and start to redirect all traffic from `example.org:80` to your container. +Once the container is running, EasyHAProxy will detect automatically and start to redirect all traffic from `example.org:80` to your container. You don't need to expose any port in your container. -There a list of other parameters you can to configure your container. Please follow the [docker label configuration](container-labels.md) +Please follow the [docker label configuration](container-labels.md) to see other configurations available. ## Setup the EasyHAProxy container -You can configure the behavior of the EasyHAProxy by setup specific environment variables. To get a list of the variables please follow the [docker container environment](docker-environment.md) +You can configure the behavior of the EasyHAProxy by setup specific environment variables. To get a list of the variables, please follow the [docker container environment](docker-environment.md) ## Setup certificates with Letsencrypt diff --git a/docs/kubernetes.md b/docs/kubernetes.md index 7181454..5279bf2 100644 --- a/docs/kubernetes.md +++ b/docs/kubernetes.md @@ -2,19 +2,19 @@ ## Setup Kubernetes EasyHAProxy -EasyHAProxy query all ingress definitions with the annotation `kubernetes.io/ingress.class: easyhaproxy-ingress`.Once find the annotation, it will immediatelly setup HAProxy and start to serve it. +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. There are three installation modes: -- DaemonSet: It will expose the ports 80, 443 and 1936 +- 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. +- ClusterIP: it will node expose any port. The HAProxy will be accessible only inside the cluster. -To install the daemonset in your cluster follow these steps: +To install EasyHAProxy in your cluster, follow these steps: ### 1) Identify the node where your EasyHAProxy container will run. -Doesn't matter if you choose DaemonSet or ClusterIP, EasyHAProxy will be limited to a single node. To understand that see [limitations](limitations.md) page. +EasyHAProxy will be limited to a single node. To understand that see [limitations](limitations.md) page. ```bash $ kubectl get nodes @@ -24,7 +24,7 @@ node-01 Ready 561d v1.21.13-3 node-02 Ready 561d v1.21.13-3 ``` -Add the EasyHAProxy label to the node +Add the EasyHAProxy label to the node. ```bash kubectl label nodes node-01 "easyhaproxy/node=master" @@ -32,7 +32,7 @@ kubectl label nodes node-01 "easyhaproxy/node=master" ### 2) Install EasyHAProxy -There are two ways to install EasyHAProxy in a Kubernetes cluster. You can use Kubernetes Manifest or Helm 3. +You can install EasyHAProxy in a Kubernetes cluster using Kubernetes Manifest or Helm 3. #### 2.1.) Using Kubernetes Manifest @@ -40,10 +40,10 @@ There are two ways to install EasyHAProxy in a Kubernetes cluster. You can use K kubectl create namespace easyhaproxy kubectl apply -f \ - https://raw.githubusercontent.com/byjg/docker-easy-haproxy/kubernetes/deploy/kubernetes/easyhaproxy-daemonset.yml + https://raw.githubusercontent.com/byjg/docker-easy-haproxy/master/deploy/kubernetes/easyhaproxy-daemonset.yml ``` -You can configure the behavior of the EasyHAProxy by setup specific environment variables. To get a list of the variables please follow the [docker container environment](docker-environment.md) +If necessary, you can configure environment variables. To get a list of the variables, please follow the [docker container environment](docker-environment.md) #### 2.2) Using HELM 3 @@ -76,7 +76,7 @@ easyhaproxy: haproxy: DEBUG service: - create: false # If false, it will create a Daemonset with hostPort. The easiest. + create: false # If false, it will create a DaemonSet with hostPort. The easiest. type: ClusterIP # or NodePort annotations: {} @@ -96,7 +96,7 @@ masterNode: ## Running containers -The only requirement is that you have an ingress properly setup and with the annotation `kubernetes.io/ingress.class: easyhaproxy-ingress`. +Your container only requires creating an ingress with the annotation `kubernetes.io/ingress.class: easyhaproxy-ingress` pointing to your service. e.g. @@ -120,14 +120,14 @@ spec: pathType: ImplementationSpecific ``` -Once the container is running EasyHAProxy will detect automatically and start to redirect all traffic from `example.org:80` to your container. +Once the container is running, EasyHAProxy will detect automatically and start to redirect all traffic from `example.org:80` to your container at port 8080. You don't need to expose any port in your container. Caveats: -- At this point, the implementation don't support all ingress properties nor wildcard domains. -- The ingress will publish externally only the ports 80 and 443, plus 1936 if stats is enable. +- At this point, the implementation doesn't support all ingress properties or wildcard domains. +- The ingress will publish the ports 80 and 443, plus 1936 if stats are enabled. - EasyHAProxy will read all `spec.rules[].host` spec, however it will parse only the first path `spec.rules[].http.paths[0].port.number` for each rule, and ignore the other paths. ## Kubernetes annotations @@ -135,9 +135,9 @@ Caveats: | annotation | Description | Default | Example | |-----------------------------|-----------------------------------------------------------------------------------------|--------------|--------------| | kubernetes.io/ingress.class | (required) Activate EasyHAProxy. | **required** | easyhaproxy-ingress -| easyhaproxy.redirect_ssl | (optional) Boolean. Force redirect all endpoints to https. | false | true or false -| easyhaproxy.letsencrypt | (optional) Boolean. It will request letsencript certificates for the ingresses domains. | false | true or false -| easyhaproxy.redirect | (optional) Json. Specific a domain and its destination. | *empty* | {"domain":"redirect_url"} +| easyhaproxy.redirect_ssl | (optional) Boolean. Force redirect all endpoints to HTTPS. | false | true or false +| easyhaproxy.letsencrypt | (optional) Boolean. It will request letsencrypt certificates for the ingresses domains. | false | true or false +| easyhaproxy.redirect | (optional) JSON. Key pair with a domain and its destination. | *empty* | {"domain":"redirect_url"} | easyhaproxy.mode | (optional) Set the HTTP mode for that connection. | http | http or tcp | easyhaproxy.listen_port | (optional) Set the an additional port for that ingress | http | http or tcp @@ -163,7 +163,7 @@ Make sure your cluster is accessible both through ports 80 and 443. ## Custom SSL Certificates -You need to create a secret with your certificate and key, and associate them in your ingress. +Create a secret with your certificate and key and associate them with your ingress. ```yaml --- diff --git a/docs/letsencrypt.md b/docs/letsencrypt.md index 6dfcc38..7b83c77 100644 --- a/docs/letsencrypt.md +++ b/docs/letsencrypt.md @@ -1,6 +1,6 @@ # Letsencrypt -EasyHAProxy can issue a letsencrypt certificate. The command is as below: +EasyHAProxy can issue a letsencrypt certificate. Follow the steps below: Run the EasyHAProxy: @@ -25,19 +25,17 @@ docker run \ Requirements: -- Your container **must** listen to the port 80. Besides no error, the certificate won't be issued if in a different port. -- You cannot set the port 443 for the container with the Letsencrypt because EasyHAProxy will handle this automatically once the certificate is issued. -- You have to setup the `EASYHAPROXY_LETSENCRYPT_EMAIL` environment variable on EasyHAProxy. If you don't setup, EasyHAProxy **will not request** a certificate. +- Your container **must** listen to port 80. Letsencrypt will not issue the certificate if `easyhaproxy.express.port` is in another port, and EasyHAProxy will fail silently. +- You cannot set port 443 for the container with the Letsencrypt because EasyHAProxy will create this port automatically once the certificate is issued. +- `EASYHAPROXY_LETSENCRYPT_EMAIL` environment variable is required to be set. If you don't set it up, EasyHAProxy **will not request** a certificate. Be aware of Letsencrypt issue limits - https://letsencrypt.org/docs/duplicate-certificate-limit/ and https://letsencrypt.org/docs/rate-limits/ ## Persist your Letsencrypt certificates -It is a good idea to store the letsencrypt certificate in a persistent storage, even you knowing you can issue again in case your lost the certificate. +It is a good idea to store the letsencrypt certificate in persistent storage because of the limit on how many certificates can be issued for the same domain in a period. -However, there is a limit in how many certificates can be issue for the same domain in a period of time. - -To avoid this, map the folder `/certs/letsencrypt` to a docker volume. +To do this, map the folder `/certs/letsencrypt` to a docker volume. ```bash docker volume create certs_letsencrypt diff --git a/docs/limitations.md b/docs/limitations.md index 3f64701..a839672 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -2,15 +2,12 @@ EasyHAProxy currently expects to work in a single replica. -If more than one replica is running, EasyHAProxy will continue to work, however each replica will discover -the services independently. +If more than one replica is running, EasyHAProxy will continue to work. However, each replica will discover the services independently. -It means replicas can be out-of-sync for a few seconds because each replica will discover the pods -separately. +It means replicas can be out-of-sync for a few seconds because each replica will discover the pods separately. -For Letsencrypt this is worse because each replica will a Letsencrypt certificate and 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. +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. ---- [Open source ByJG](http://opensource.byjg.com) \ No newline at end of file diff --git a/docs/other.md b/docs/other.md index 5f93002..37fea53 100644 --- a/docs/other.md +++ b/docs/other.md @@ -2,10 +2,10 @@ ## Exposing Ports -You must expose some ports on the EasyHAProxy container and in the firewall. However, you don't need to expose the other container ports because EasyHAProxy will handle that. +Some ports on the EasyHAProxy container and in the firewall are required to be open. However, you don't need to expose the other container ports because EasyHAProxy will handle that. - The ports `80` and `443`. -- If you enable the HAProxy statistics, you must also expose the port defined in `HAPROXY_STATS_PORT` environment variable (default 1936). Be aware that statististics are enabled by default with no password. +- If you enable the HAProxy statistics, you must also expose the port defined in `HAPROXY_STATS_PORT` environment variable (default 1936). Be aware that statistics are enabled by default with no password. - Every port defined in `easyhaproxy.[definitions].port` also should be exposed. e.g. @@ -19,6 +19,17 @@ docker run \ -d byjg/easy-haproxy ``` +## Mapping Docker Volume + +The docker volume or a way to call the API needs to pass to the EasyHAProxy container. + +```bash +docker run \ + /* other parameters */ + -v /var/run/docker.sock:/var/run/docker.sock \ + -d byjg/easy-haproxy +``` + ## Mapping custom .cfg files You can concatenate valid HAProxy `.cfg` files to the dynamically generated `haproxy.cfg` by mapping the folder `/etc/haproxy/conf.d`. diff --git a/docs/ssl.md b/docs/ssl.md index 9baffd3..4384bbf 100644 --- a/docs/ssl.md +++ b/docs/ssl.md @@ -1,12 +1,12 @@ -# Setup your own certificates +# Setup custom certificates You can use your certificates with EasyHAProxy. -There is two ways to do that. +There are two ways to do that. ## Setup certificate as a label definition in docker container -1. First, Create a single PEM from the certificate and the key. +### Create a single PEM from the certificate and key. ```bash cat example.com.crt example.com.key > single.pem @@ -24,19 +24,21 @@ MIIEojCCA4qgAwIBAgIUegW2BimwuL4RzRZ2WYkHA6U5nkAwDQYJKoZIhvcNAQEL -----END PRIVATE KEY----- ``` -2. Convert the `single.pem` to BASE64 in a single line: +### Convert the `single.pem` to BASE64 in a single line: ```bash cat single.pem | base64 -w0 ``` -3. Use this string to define the label `easyhaproxy.[definition].sslcert` +### Map the BASE64 to your container -## Map the certificate as docker volume +Add the Base64 string you generated before to the label `easyhaproxy.[definition].sslcert` + +## Map the certificate as a docker volume EasyHAProxy stores the certificates inside the folder `/certs/haproxy`. -1. Run EasyHAProxy with the volume for the certificates: +### Run EasyHAProxy with the volume for the certificates: ```bash docker volume create certs_haproxy @@ -47,7 +49,7 @@ docker run \ -d byjg/easy-haproxy ``` -2. Create a single PEM from the certificate and the key. +### Create a single PEM from the certificate and the key. ```bash cat example.com.crt example.com.key > single.pem @@ -65,7 +67,7 @@ MIIEojCCA4qgAwIBAgIUegW2BimwuL4RzRZ2WYkHA6U5nkAwDQYJKoZIhvcNAQEL -----END PRIVATE KEY----- ``` -3. Copy this certificate to EasyHAProxy volume +### Copy this certificate to EasyHAProxy volume ```bash docker cp single.pem easyhaproxy:/certs/haproxy diff --git a/docs/static.md b/docs/static.md index d3774e0..ce63b97 100644 --- a/docs/static.md +++ b/docs/static.md @@ -2,9 +2,9 @@ ## Setup Docker EasyHAProxy -This method will use a static configuration, simpler and easier than create a `haproxy.cfg` +This method will use a static configuration, which is simpler and easier than creating a `haproxy.cfg` -You can use this configuration to setup external servers not related to docker or kubernetes. +You can use this configuration to set up external servers unrelated to docker or Kubernetes. Another advantage is that EasyHAProxy will monitor for changes in this file and automatically reconfigure HAProxy when any changes are detected. @@ -98,7 +98,7 @@ easymapping: letsencrypt: true # Optional. it will request a letsencrypt certiticate redirect_ssl: true # Optional. It will redirect this site to it SSL. ssl: true # Optional. Inform this port will listen to SSL, instead of HTTP - clone_to_ssl: true # Optional. Default False. You clone these hosts to it equivalent SSL. + clone_to_ssl: true # Optional. Default False. You clone these hosts to its equivalent SSL. redirect: www.host1.com.br: http://host1.com.br ``` diff --git a/docs/swarm.md b/docs/swarm.md index 9d26245..b6844a5 100644 --- a/docs/swarm.md +++ b/docs/swarm.md @@ -3,9 +3,9 @@ ## 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 container in other nodes from cluster. +The advantage of this method is that you can discover containers in other nodes from the cluster. -The only requirement is that containers and EasyHAProxy must be in the same docker swarm network in order to HAProxy be able direct the traffic to the containers. +The only requirement is that containers and EasyHAProxy must be in the same docker swarm network. e.g.: @@ -44,19 +44,19 @@ networks: external: true ``` -and then: +And then: ```bash docker stack deploy --compose-file docker-compose.yml easyhaproxy ``` -The mapping to `/var/run/docker.sock` is necessary to discover the docker containers and get the labels; +Mapping to `/var/run/docker.sock` is necessary to discover the docker containers and get the labels; **Do not** add more than one replica for EasyHAProxy. To understand that see [limitations](limitations.md) page. ## Running containers -To make your containers "discoverable" by EasyHAProxy that is minimum configuration you need: +To make your containers "discoverable" by EasyHAProxy, that is the minimum configuration you need: ```yaml version: "3" @@ -78,19 +78,19 @@ networks: external: true ``` -Once the container is running EasyHAProxy will detect automatically and start to redirect all traffic from `example.org:80` to your container. +Once the container is running, EasyHAProxy will detect automatically and start to redirect all traffic from `example.org:80` to your container. You don't need to expose any port in your container. -There a list of other parameters you can to configure your container. Please follow the [docker label configuration](container-labels.md) +Please follow the [docker label configuration](container-labels.md) to see other configurations available. ## Setup the EasyHAProxy container -You can configure the behavior of the EasyHAProxy by setup specific environment variables. To get a list of the variables please follow the [docker container environment](docker-environment.md) +You can configure the behavior of the EasyHAProxy by setup specific environment variables. To get a list of the variables, please follow the [docker container environment](docker-environment.md) ## More information -You can refer the [Docker Documentation](docker.md) to get other detailed instructions. +You can refer to the [Docker Documentation](docker.md) to get other detailed instructions. ---- [Open source ByJG](http://opensource.byjg.com)