badblocks/docker-easy-haproxy
1
0
Fork 0
Code Activity

Fix English

Browse source
This commit is contained in:
Joao M 2022-09-01 16:42:46 +00:00
parent 19df0414c0
commit 483bb9a55e
10 changed files with 82 additions and 71 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/container-labels.md
View file

@ -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

12
docs/docker.md
View file

@ -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

36
docs/kubernetes.md
View file

@ -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 <none> 561d v1.21.13-3
node-02 Ready <none> 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
---

14
docs/letsencrypt.md
View file

@ -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

11
docs/limitations.md
View file

@ -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)

15
docs/other.md
View file

@ -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`.

20
docs/ssl.md
View file

@ -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

6
docs/static.md
View file

@ -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
```

18
docs/swarm.md
View file

@ -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)