Merge pull request #63 from byjg/claude/audit-docs-sidebar-position-011CUyCPndSvfgQT9p3YFcn7
Audit and organize Docusaurus documentation structure
This commit is contained in:
Joao Gilberto Magalhaes
GitHub
commit
fdb6ddf3b9
16 changed files with 228 additions and 119 deletions
19
README.md
19
README.md
|
|
@ -11,13 +11,14 @@
|
|||
|
||||
## Service discovery for HAProxy
|
||||
|
||||
EasyHAProxy dynamically creates the `haproxy.cfg` based on the labels defined in docker containers.
|
||||
EasyHAProxy dynamically creates the `haproxy.cfg` based on metadata collected from your workloads (Docker labels, Swarm service labels, or Kubernetes ingress annotations).
|
||||
|
||||
EasyHAProxy can detect and configure HAProxy automatically on the following platforms:
|
||||
|
||||
- Docker
|
||||
- Docker Swarm
|
||||
- Kubernetes
|
||||
- Static YAML definitions (`EASYHAPROXY_DISCOVER=static`)
|
||||
|
||||
## Who is using?
|
||||
|
||||
|
|
@ -34,12 +35,12 @@ Easy to set up and low configuration to numerous features.
|
|||
|
||||
## 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:
|
||||
EasyHAProxy will discover services based on Docker (or Swarm) labels and Kubernetes ingress annotations, then dynamically build the `haproxy.cfg`. Below, EasyHAProxy main features:
|
||||
|
||||
- Support Automatic Certificate Management Environment (ACME) protocol compatible with Let's encrypt and others CA.
|
||||
- Support Automatic Certificate Management Environment (ACME) protocol compatible with Let's Encrypt and other CAs.
|
||||
- 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.
|
||||
- Set SSL policies (`strict`, `default`, `loose`) via `EASYHAPROXY_SSL_MODE`.
|
||||
- Set up HAProxy to listen to TCP.
|
||||
- Add redirects.
|
||||
- Enable/disable Stats on port 1936 with a custom password.
|
||||
|
|
@ -80,6 +81,16 @@ If you already set up the EasyHAProxy, is time to go deeper:
|
|||
- [Custom SSL](docs/ssl.md)
|
||||
- [Automatic Certificate Issuing](docs/acme.md) (e.g. Letsencrypt)
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
Detailed configuration guides for advanced setups:
|
||||
|
||||
- [Container Labels](docs/container-labels.md) - Configure Docker/Swarm containers with labels
|
||||
- [Environment Variables](docs/environment-variable.md) - Configure EasyHAProxy behavior
|
||||
- [Volumes](docs/volumes.md) - Map volumes for certificates, config, and custom files
|
||||
- [Other Configurations](docs/other.md) - Additional configurations (ports, custom errors, etc.)
|
||||
- [Limitations](docs/limitations.md) - Important limitations and considerations
|
||||
|
||||
## See EasyHAProxy in action
|
||||
|
||||
Click on the image to see the videos (use HD for better visualization)
|
||||
|
|
|
|||
42
docs/acme.md
42
docs/acme.md
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
sidebar_position: 10
|
||||
---
|
||||
|
||||
# SSL - Automatic Certificate Management Environment (ACME)
|
||||
|
||||
The Automatic Certificate Management Environment (ACME) protocol
|
||||
|
|
@ -13,9 +17,11 @@ Easy HAProxy supports the following ACME challenge types:
|
|||
- **HTTP-01 Challenge (Default and Only)**
|
||||
The ACME server validates ownership by making an HTTP request to a temporary endpoint served on port 80. Easy HAProxy provisions a standalone Certbot responder on an internal port and routes `/.well-known/acme-challenge/` traffic to it.
|
||||
|
||||
> Note:
|
||||
> - TLS-ALPN-01 is not supported natively by Easy HAProxy.
|
||||
> - DNS-01 (often used for wildcard certificates) is not supported natively. If you need DNS-01, obtain certificates externally and mount them via `sslcert` as static certificates.
|
||||
:::info Challenge Support
|
||||
- **HTTP-01**: Fully supported (default)
|
||||
- **TLS-ALPN-01**: Not supported natively by Easy HAProxy
|
||||
- **DNS-01**: Not supported natively. If you need DNS-01 for wildcard certificates, obtain certificates externally and mount them via `sslcert` as static certificates.
|
||||
:::
|
||||
|
||||
## How ACME works with Easy HAProxy
|
||||
|
||||
|
|
@ -69,7 +75,7 @@ Possible values for: `EASYHAPROXY_CERTBOT_AUTOCONFIG`
|
|||
|
||||
| CA | Auto Config | Free? | Account Required? | EAB KID? | EAB HMAC Key? | More Info |
|
||||
|----------------------|------------------|-------|--------------------|----------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| Let's Encrypt | - | Yes | No | No | No | - |
|
||||
| Let's Encrypt | letsencrypt | Yes | No | No | No | Default when no AUTOCONFIG is set |
|
||||
| Let's Encrypt (Test) | letsencrypt_test | Yes | No | No | No | - |
|
||||
| ZeroSSL | zerossl | Yes | No | No | No | [Link](https://zerossl.com/documentation/acme/) |
|
||||
| BuyPass | buypass | Yes | No | No | No | [Link](https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints-updated-14-05-2020) |
|
||||
|
|
@ -104,16 +110,18 @@ docker run \
|
|||
byjg/easy-haproxy
|
||||
```
|
||||
|
||||
Notes:
|
||||
:::note Configuration Notes
|
||||
- The `EASYHAPROXY_CERTBOT_AUTOCONFIG` is not required for Let's Encrypt (it's the default). In this example, the certificate will be issued by ZeroSSL.
|
||||
- If you don't set the `EASYHAPROXY_CERTBOT_EMAIL` environment variable, EasyHAProxy will fail silently and **will not request** certificates.
|
||||
- Ports 80 and 443 must be accessible through the internet as a [Let's Encrypt requirement](https://letsencrypt.org/docs/allow-port-80/)
|
||||
:::
|
||||
|
||||
- The `EASYHAPROXY_CERTBOT_AUTOCONFIG` is not required for Let's Encrypt. In this example, the certificate will be issued by ZeroSSL.
|
||||
- If you don't setup `EASYHAPROXY_CERTBOT_EMAIL` environment variable, EasyHAProxy will fail silently and **will not request** a certificate.
|
||||
- The ports 80 and 443 needs to accessible through the internet as [Let's Encrypt requirement](https://letsencrypt.org/docs/allow-port-80/)
|
||||
|
||||
In order to avoid several certificate issuing,
|
||||
**It is required you to persist the container folder `/certs/certbot` outside the container.**
|
||||
You cannot delete or change it contents.
|
||||
If you do not persist, or change/delete the contents, Issue a certificate might not work properly and hit rate limit.
|
||||
:::danger Important: Persist Certbot Certificates
|
||||
To avoid hitting rate limits and certificate issuing problems:
|
||||
- **You must persist** the container folder `/certs/certbot` outside the container
|
||||
- **Never delete or modify** its contents manually
|
||||
- If you don't persist this folder, or if you delete/modify its contents, certificate issuing may not work properly and you may hit rate limits
|
||||
:::
|
||||
|
||||
If you are using Let's Encrypt, be aware of it rate limits:
|
||||
|
||||
|
|
@ -134,10 +142,10 @@ docker run \
|
|||
some/myimage
|
||||
```
|
||||
|
||||
Requirements:
|
||||
|
||||
- Your container **must** listen to port 80. The CA will not issue the certificate if `easyhaproxy.<definition>.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.
|
||||
:::warning ACME Requirements
|
||||
- Your container **must** be configured to listen on port 80 (`easyhaproxy.<definition>.port=80`). The CA will not issue certificates if using another port, and EasyHAProxy will fail silently.
|
||||
- Do not set port 443 for the container when using ACME, because EasyHAProxy will create the HTTPS binding automatically once the certificate is issued.
|
||||
:::
|
||||
|
||||
----
|
||||
[Open source ByJG](http://opensource.byjg.com)
|
||||
|
|
@ -1,8 +1,12 @@
|
|||
---
|
||||
sidebar_position: 11
|
||||
---
|
||||
|
||||
# Container Labels
|
||||
|
||||
## Container (Docker or Swarm) labels
|
||||
|
||||
| Tag | Description | Default | Example |
|
||||
| Label | Description | Default | Example |
|
||||
|---------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|--------------|------------------------------------------------------------------------------------------------------------------|
|
||||
| easyhaproxy.[definition].host | Host(s) HAProxy is listening. More than one host use comma as delimiter | **required** | somehost.com OR host1.com,host2.com |
|
||||
| easyhaproxy.[definition].mode | (Optional) Is this `http` or `tcp` mode in HAProxy. | http | http or tcp |
|
||||
|
|
@ -14,27 +18,29 @@
|
|||
| easyhaproxy.[definition].ssl-check | (Optional) `ssl`, enable health check via SSL in `mode tcp` | *empty* | ssl |
|
||||
| easyhaproxy.[definition].certbot | (Optional) Generate certificate with certbot. Do not use with `sslcert` parameter. More info [here](acme.md). | false | true OR false |
|
||||
| easyhaproxy.[definition].redirect_ssl | (Optional) Redirect all requests to https | false | true OR false |
|
||||
| easyhaproxy.[definition].clone_to_ssl | (Optional) It copies the configuration to HTTPS(443) and disable SSL from the current config. **Do not use* this with `ssl` or `certbot` parameters | false | true OR false |
|
||||
| easyhaproxy.[definition].clone_to_ssl | (Optional) It copies the configuration to HTTPS(443) and disable SSL from the current config. **Do not use** this with `ssl` or `certbot` parameters | false | true OR false |
|
||||
| easyhaproxy.[definition].balance | (Optional) HAProxy balance algorithm. See [HAProxy documentation](https://cbonte.github.io/haproxy-dconv/1.8/configuration.html#4.2-balance) | roundrobin | roundrobin, source, uri, url_param, hdr, rdp-cookie, leastconn, first, static-rr, rdp-cookie, hdr_dom, map-based |
|
||||
|
||||
The `definition` is a string that will group all configurations togethers. Different `definition` will create different configurations.
|
||||
:::info Understanding Definitions
|
||||
The `[definition]` is a string identifier that groups related configuration labels together. Different definitions create separate HAProxy configurations.
|
||||
|
||||
The container can have more than one definition.
|
||||
A single container can have multiple definitions to expose different services or ports.
|
||||
:::
|
||||
|
||||
## Configuations
|
||||
## Configurations
|
||||
|
||||
### Single Definition
|
||||
|
||||
```bash
|
||||
```bash title="Single service configuration"
|
||||
docker run \
|
||||
--label easyhaproxy.webapi.port=80\
|
||||
--label easyhaproxy.webapi.host=byjg.com.br \
|
||||
....
|
||||
```
|
||||
|
||||
### Multiples Definitions on the same container
|
||||
### Multiple Definitions on the same container
|
||||
|
||||
```bash
|
||||
```bash title="Multiple services on one container"
|
||||
docker run \
|
||||
--label easyhaproxy.express.port=80 \
|
||||
--label easyhaproxy.express.localport=3000 \
|
||||
|
|
@ -47,9 +53,9 @@ docker run \
|
|||
some/myimage
|
||||
```
|
||||
|
||||
### Multiples hosts on the same container
|
||||
### Multiple hosts on the same container
|
||||
|
||||
```bash
|
||||
```bash title="Multiple hosts for one service"
|
||||
docker run \
|
||||
--label easyhaproxy.express.port=80 \
|
||||
--label easyhaproxy.express.localport=3000 \
|
||||
|
|
@ -78,7 +84,7 @@ services:
|
|||
|
||||
Set `easyhaproxy.[definition].mode=tcp` if your application uses TCP protocol instead of HTTP.
|
||||
|
||||
```bash
|
||||
```bash title="TCP mode configuration"
|
||||
docker run \
|
||||
--label easyhaproxy.example.mode=tcp \
|
||||
--label easyhaproxy.example.port=3306
|
||||
|
|
@ -89,7 +95,7 @@ docker run \
|
|||
|
||||
### Redirect Domains
|
||||
|
||||
```bash
|
||||
```bash title="Domain redirect configuration"
|
||||
docker run \
|
||||
--label easyhaproxy.[definition].redirect='{"www.byjg.com.br":"http://byjg.com.br","byjg.com":"http://byjg.com.br"}'
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
sidebar_position: 8
|
||||
---
|
||||
|
||||
# DigitalOcean
|
||||
|
||||
DigitalOcean is a cloud infrastructure provider focused on simplifying web infrastructure for software developers.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# Docker
|
||||
|
||||
## Setup Docker EasyHAProxy
|
||||
|
|
@ -12,19 +16,20 @@ To accomplish this, EasyHAProxy may need to attach the same network to its conta
|
|||
|
||||
It's recommended to create a network external to EasyHAProxy, although it's not mandatory.
|
||||
|
||||
Limitations:
|
||||
:::warning 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))
|
||||
- This method does not work with containers that use the `--network=host` option. See [limitations](limitations.md) for details.
|
||||
:::
|
||||
|
||||
e.g.:
|
||||
For example:
|
||||
|
||||
```bash
|
||||
```bash title="Create EasyHAProxy network"
|
||||
docker network create easyhaproxy
|
||||
```
|
||||
|
||||
And then run the EasyHAProxy
|
||||
And then run the EasyHAProxy:
|
||||
|
||||
```bash
|
||||
```bash title="Run EasyHAProxy container"
|
||||
docker run -d \
|
||||
--name easy-haproxy-container \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
|
|
@ -41,9 +46,9 @@ Mapping to `/var/run/docker.sock` is necessary to discover the docker containers
|
|||
|
||||
## Running containers
|
||||
|
||||
To make your containers "discoverable" by EasyHAProxy, that is the minimum configuration you need:
|
||||
To make your containers "discoverable" by EasyHAProxy, this is the minimum configuration you need:
|
||||
|
||||
```bash
|
||||
```bash title="Run container with EasyHAProxy labels"
|
||||
docker run -d \
|
||||
--label easyhaproxy.http.host=example.org \
|
||||
--label easyhaproxy.http.port=80 \
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
sidebar_position: 7
|
||||
---
|
||||
|
||||
# Dokku
|
||||
|
||||
Dokku is a Docker powered mini-Heroku in around 100 lines of Bash. It is the smallest PaaS implementation you've ever seen, weighing in at a little over 100 MB of memory usage and about 80 MB of disk space.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
sidebar_position: 12
|
||||
---
|
||||
|
||||
# Docker environment variables
|
||||
|
||||
| Environment Variable | Description | Default |
|
||||
|
|
@ -15,6 +19,9 @@
|
|||
| HAPROXY_STATS_PORT | (Optional) The HAProxy port to the statistics. If set to `false`, disable statistics | `1936` |
|
||||
| HAPROXY_CUSTOMERRORS | (Optional) If HAProxy will use custom HTML errors. true/false. | `false` |
|
||||
|
||||
:::note ACME/Certbot Environment Variables
|
||||
For ACME/Certbot configuration (Let's Encrypt, ZeroSSL, etc.), see the [ACME documentation](acme.md#environment-variables) for the complete list of `EASYHAPROXY_CERTBOT_*` variables.
|
||||
:::
|
||||
|
||||
----
|
||||
[Open source ByJG](http://opensource.byjg.com)
|
||||
|
|
|
|||
18
docs/helm.md
18
docs/helm.md
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Helm 3
|
||||
|
||||
Helm is a package manager for Kubernetes. It allows you to install and manage applications on Kubernetes.
|
||||
|
|
@ -6,9 +10,11 @@ Helm is a package manager for Kubernetes. It allows you to install and manage ap
|
|||
|
||||
### 1) Identify the node where your EasyHAProxy container will run
|
||||
|
||||
EasyHAProxy will be limited to a single node. To understand that see [limitations](limitations.md) page.
|
||||
:::warning Single Node Deployment
|
||||
EasyHAProxy will be limited to a single node. To understand why, see the [limitations](limitations.md) page.
|
||||
:::
|
||||
|
||||
```bash
|
||||
```bash title="List available nodes"
|
||||
$ kubectl get nodes
|
||||
|
||||
NAME STATUS ROLES AGE VERSION
|
||||
|
|
@ -18,15 +24,15 @@ node-02 Ready <none> 561d v1.21.13-3
|
|||
|
||||
Add the EasyHAProxy label to the node.
|
||||
|
||||
```bash
|
||||
```bash title="Label the node for EasyHAProxy"
|
||||
kubectl label nodes node-01 "easyhaproxy/node=master"
|
||||
```
|
||||
|
||||
### 2) Install EasyHAProxy
|
||||
|
||||
Minimal configuration
|
||||
Minimal configuration:
|
||||
|
||||
```bash
|
||||
```bash title="Install with Helm (minimal)"
|
||||
helm repo add byjg https://opensource.byjg.com/helm
|
||||
helm repo update byjg
|
||||
kubectl create namespace easyhaproxy
|
||||
|
|
@ -39,7 +45,7 @@ helm upgrade --install ingress byjg/easyhaproxy \
|
|||
|
||||
Customizing Helm Values:
|
||||
|
||||
```yaml
|
||||
```yaml title="values.yaml"
|
||||
easyhaproxy:
|
||||
stats:
|
||||
username: admin
|
||||
|
|
|
|||
|
|
@ -1,10 +1,16 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Kubernetes
|
||||
|
||||
## Setup Kubernetes EasyHAProxy
|
||||
|
||||
:::info How it works
|
||||
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.
|
||||
:::
|
||||
|
||||
For Kubernetes installations, there are three available installation modes:
|
||||
- DaemonSet: This mode exposes ports 80, 443, and 1936.
|
||||
|
|
@ -17,9 +23,11 @@ To install EasyHAProxy in your Kubernetes cluster, follow these steps:
|
|||
|
||||
### 1) Identify the node where your EasyHAProxy container will run
|
||||
|
||||
EasyHAProxy will be limited to a single node. To understand that see [limitations](limitations.md) page.
|
||||
:::warning Single Node Deployment
|
||||
EasyHAProxy will be limited to a single node. To understand why, see the [limitations](limitations.md) page.
|
||||
:::
|
||||
|
||||
```bash
|
||||
```bash title="List available nodes"
|
||||
$ kubectl get nodes
|
||||
|
||||
NAME STATUS ROLES AGE VERSION
|
||||
|
|
@ -29,13 +37,13 @@ node-02 Ready <none> 561d v1.21.13-3
|
|||
|
||||
Add the EasyHAProxy label to the node.
|
||||
|
||||
```bash
|
||||
```bash title="Label the node for EasyHAProxy"
|
||||
kubectl label nodes node-01 "easyhaproxy/node=master"
|
||||
```
|
||||
|
||||
### 2) Install EasyHAProxy with Kubernetes Manifest
|
||||
|
||||
```bash
|
||||
```bash title="Install EasyHAProxy"
|
||||
kubectl create namespace easyhaproxy
|
||||
|
||||
kubectl apply -f \
|
||||
|
|
@ -74,11 +82,11 @@ Once the container is running, EasyHAProxy will detect automatically and start t
|
|||
|
||||
You don't need to expose any port in your container.
|
||||
|
||||
Notes:
|
||||
|
||||
- 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.
|
||||
:::note Important Limitations
|
||||
- The implementation doesn't support all ingress properties or wildcard domains at this time.
|
||||
- The ingress will publish ports 80 and 443, plus 1936 if stats are enabled.
|
||||
- EasyHAProxy will read all `spec.rules[].host` specifications, 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
|
||||
|
||||
|
|
@ -89,7 +97,7 @@ Notes:
|
|||
| easyhaproxy.certbot | (optional) Boolean. It will request certbot 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 |
|
||||
| easyhaproxy.listen_port | (optional) Override the HTTP listen port created for that ingress | 80 | 8081 |
|
||||
|
||||
**Important**: The annotations are per ingress and applied to all hosts in that ingress configuration.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,26 +1,38 @@
|
|||
---
|
||||
sidebar_position: 15
|
||||
---
|
||||
|
||||
# Limitations and Considerations
|
||||
|
||||
## EasyHAProxy will not work with --network=host
|
||||
|
||||
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.
|
||||
:::danger Network Mode Incompatibility
|
||||
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.
|
||||
:::
|
||||
|
||||
## Considerations for Multiple Replica Deployments in EasyHAProxy
|
||||
|
||||
EasyHAProxy currently operates under the assumption of a single replica deployment.
|
||||
:::warning Single Replica Deployment Recommended
|
||||
EasyHAProxy is designed for 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.
|
||||
### What happens with multiple replicas?
|
||||
|
||||
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.
|
||||
EasyHAProxy can still operate with multiple replicas; however:
|
||||
|
||||
1. **Service Discovery**: Each replica will independently discover services, which may lead to temporary inconsistencies among replicas (out-of-sync for a few seconds).
|
||||
|
||||
2. **ACME/Certificate Issues**: Running multiple replicas creates significant problems with Let's Encrypt and other ACME certificate issuance:
|
||||
- Each replica will attempt to obtain its own certificate
|
||||
- ACME challenges may be directed to different replicas, causing failures
|
||||
- You may quickly hit certificate issuance rate limits
|
||||
- Certificate renewal may fail unpredictably
|
||||
|
||||
:::danger Recommendation
|
||||
If you need to run multiple replicas for high availability, **do not activate ACME/Let's Encrypt**. Instead, use manually managed certificates or an external certificate management solution.
|
||||
:::
|
||||
|
||||
----
|
||||
[Open source ByJG](http://opensource.byjg.com)
|
||||
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
sidebar_position: 6
|
||||
---
|
||||
|
||||
# Microk8s Add-ons
|
||||
|
||||
Microk8s is a lightweight Kubernetes distribution that can run on a single machine. It is very easy to install and use.
|
||||
|
|
@ -9,9 +13,9 @@ Here are the steps to install EasyHAProxy on your Microk8s.
|
|||
|
||||
EasyHAProxy is being part of official MicroK8s Community edition since MicroK8s version 1.27.
|
||||
|
||||
Just enable the community add-on
|
||||
Just enable the community add-on:
|
||||
|
||||
```
|
||||
```bash title="Enable community addons"
|
||||
microk8s enable community
|
||||
```
|
||||
|
||||
|
|
@ -30,7 +34,7 @@ addons:
|
|||
|
||||
However, if you are using MicroK8s before 1.27 you need to enable it directly from the ByJG repository by accessing the microk8s host machine and run:
|
||||
|
||||
```shell
|
||||
```bash title="Add ByJG addon repository"
|
||||
microk8s addons repo add byjg https://github.com/byjg/microk8s-addons.git
|
||||
```
|
||||
|
||||
|
|
@ -54,19 +58,21 @@ Once you have enable the EasyHAProxy from the community repository or from ByJG
|
|||
|
||||
Usage:
|
||||
|
||||
Install as a Daemonset
|
||||
Install as a Daemonset:
|
||||
|
||||
```shell
|
||||
```bash title="Install as DaemonSet"
|
||||
microk8s enable easyhaproxy
|
||||
```
|
||||
|
||||
Install as a NodePort
|
||||
Install as a NodePort:
|
||||
|
||||
```shell
|
||||
```bash title="Install as NodePort"
|
||||
microk8s enable easyhaproxy --nodeport
|
||||
```
|
||||
|
||||
**Remember**: you need to disable any ingress controller you have previously installed, for example, nginx, traefik, etc. before install EasyHaProxy.
|
||||
:::warning Disable Other Ingress Controllers
|
||||
You need to disable any ingress controller you have previously installed (e.g., nginx, traefik, etc.) before installing EasyHAProxy to avoid conflicts.
|
||||
:::
|
||||
|
||||
For more parameters you can refer to the [Kubernetes](kubernetes.md) page.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
sidebar_position: 14
|
||||
---
|
||||
|
||||
# Other configurations
|
||||
|
||||
## Exposing Ports
|
||||
|
|
@ -8,9 +12,9 @@ Some ports on the EasyHAProxy container and in the firewall are required to be o
|
|||
- 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.
|
||||
For example:
|
||||
|
||||
```bash
|
||||
```bash title="Expose required ports"
|
||||
docker run \
|
||||
/* other parameters */
|
||||
-p 80:80 \
|
||||
|
|
@ -23,7 +27,7 @@ docker run \
|
|||
|
||||
The docker volume or a way to call the API needs to pass to the EasyHAProxy container.
|
||||
|
||||
```bash
|
||||
```bash title="Mount Docker socket"
|
||||
docker run \
|
||||
/* other parameters */
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
|
|
@ -34,7 +38,7 @@ docker run \
|
|||
|
||||
You can concatenate valid HAProxy `.cfg` files to the dynamically generated `haproxy.cfg` by mapping the folder `/etc/haproxy/conf.d`.
|
||||
|
||||
```bash
|
||||
```bash title="Mount custom config directory"
|
||||
docker run \
|
||||
/* other parameters */
|
||||
-v /your/local/conf.d:/etc/haproxy/conf.d \
|
||||
|
|
|
|||
16
docs/ssl.md
16
docs/ssl.md
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
sidebar_position: 9
|
||||
---
|
||||
|
||||
# Setup custom certificates
|
||||
|
||||
You can use your own certificates with EasyHAProxy. You just need to let EasyHAProxy know that certificate.
|
||||
|
|
@ -11,7 +15,7 @@ There are two ways to do that.
|
|||
|
||||
1. Create a single PEM from the certificate and key.
|
||||
|
||||
```bash
|
||||
```bash title="Combine certificate and key"
|
||||
cat example.com.crt example.com.key > single.pem
|
||||
|
||||
cat single.pem
|
||||
|
|
@ -29,7 +33,7 @@ MIIEojCCA4qgAwIBAgIUegW2BimwuL4RzRZ2WYkHA6U5nkAwDQYJKoZIhvcNAQEL
|
|||
|
||||
2. Convert the `single.pem` to BASE64 in a single line:
|
||||
|
||||
```bash
|
||||
```bash title="Convert to BASE64"
|
||||
cat single.pem | base64 -w0
|
||||
```
|
||||
|
||||
|
|
@ -43,7 +47,7 @@ EasyHAProxy stores the certificates inside the container folder `/certs/haproxy`
|
|||
|
||||
1. Run EasyHAProxy with the volume for the certificates:
|
||||
|
||||
```bash
|
||||
```bash title="Create and mount certificate volume"
|
||||
docker volume create certs_haproxy
|
||||
|
||||
docker run \
|
||||
|
|
@ -54,7 +58,7 @@ docker run \
|
|||
|
||||
2. Create a single PEM from the certificate and the key.
|
||||
|
||||
```bash
|
||||
```bash title="Combine certificate and key"
|
||||
cat example.com.crt example.com.key > single.pem
|
||||
|
||||
cat single.pem
|
||||
|
|
@ -70,9 +74,9 @@ MIIEojCCA4qgAwIBAgIUegW2BimwuL4RzRZ2WYkHA6U5nkAwDQYJKoZIhvcNAQEL
|
|||
-----END PRIVATE KEY-----
|
||||
```
|
||||
|
||||
3. Copy this certificate to EasyHAProxy volume
|
||||
3. Copy this certificate to EasyHAProxy volume:
|
||||
|
||||
```bash
|
||||
```bash title="Copy certificate to container"
|
||||
docker cp single.pem easyhaproxy:/certs/haproxy
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Static File
|
||||
|
||||
## Setup Docker EasyHAProxy
|
||||
|
|
@ -6,9 +10,11 @@ This method will use a static configuration, which is simpler and easier than cr
|
|||
|
||||
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.
|
||||
:::tip Live Reload
|
||||
EasyHAProxy monitors this file for changes and automatically reconfigures HAProxy when any changes are detected.
|
||||
:::
|
||||
|
||||
First, Create a YAML:
|
||||
First, create a YAML configuration:
|
||||
|
||||
```yaml
|
||||
stats:
|
||||
|
|
@ -56,12 +62,11 @@ easymapping:
|
|||
- domain:8181
|
||||
```
|
||||
|
||||
Then map this file to `/etc/haproxy/static/config.yml` in your EasyHAProxy container as:
|
||||
Then map this file to `/etc/haproxy/static/config.yml` in your EasyHAProxy container:
|
||||
|
||||
```bash
|
||||
```bash title="Run EasyHAProxy with static configuration"
|
||||
docker run -d \
|
||||
--name easy-haproxy-container \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||||
-v /my/static/:/etc/haproxy/static/ \
|
||||
-e EASYHAPROXY_DISCOVER="static" \
|
||||
# + Environment Variables \
|
||||
|
|
@ -72,7 +77,11 @@ docker run -d \
|
|||
byjg/easy-haproxy
|
||||
```
|
||||
|
||||
You can find other informations on [docker label configuration](container-labels.md) and [environment variable guide](environment-variable.md)
|
||||
:::tip Docker Socket Optional
|
||||
Mounting `/var/run/docker.sock` is not required in static discovery mode. Add it only if you are simultaneously discovering Docker containers.
|
||||
:::
|
||||
|
||||
You can find other information on [docker label configuration](container-labels.md) and [environment variable guide](environment-variable.md)
|
||||
|
||||
## Yaml Definition
|
||||
|
||||
|
|
@ -115,8 +124,9 @@ easymapping:
|
|||
www.host1.com.br: http://host1.com.br
|
||||
```
|
||||
|
||||
**Note**: The only way to pass SSL certificates in the static configuration file is to map the certificates
|
||||
to EasyHAProxy as a docker volume. Refer to the [SSL documentation](ssl.md) to learn how to do it.
|
||||
:::note SSL Certificates in Static Mode
|
||||
The only way to provide SSL certificates in static configuration mode is to map the certificates to EasyHAProxy as a docker volume. Refer to the [SSL documentation](ssl.md) to learn how to configure this.
|
||||
:::
|
||||
|
||||
----
|
||||
[Open source ByJG](http://opensource.byjg.com)
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Swarm
|
||||
|
||||
## Setup Docker EasyHAProxy
|
||||
|
|
@ -6,21 +10,21 @@ This method involves using a Docker Swarm installation to discover containers an
|
|||
|
||||
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.
|
||||
|
||||
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.
|
||||
:::tip Docker Swarm Advantages
|
||||
- **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.
|
||||
:::
|
||||
|
||||
It's recommended to create a network external to EasyHAProxy.
|
||||
|
||||
Limitations:
|
||||
:::warning 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))
|
||||
- This method does not work with containers that use the `--network=host` option. See [limitations](limitations.md) for details.
|
||||
:::
|
||||
|
||||
e.g.:
|
||||
For example:
|
||||
|
||||
```bash
|
||||
```bash title="Create overlay network"
|
||||
docker network create -d overlay --attachable easyhaproxy
|
||||
```
|
||||
|
||||
|
|
@ -31,7 +35,7 @@ version: "3"
|
|||
|
||||
services:
|
||||
haproxy:
|
||||
image: byjg/easy-haproxy:4.3.1-rc1
|
||||
image: byjg/easy-haproxy:4.6.0
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
deploy:
|
||||
|
|
@ -55,15 +59,17 @@ networks:
|
|||
external: true
|
||||
```
|
||||
|
||||
And then:
|
||||
Deploy the stack:
|
||||
|
||||
```bash
|
||||
```bash title="Deploy EasyHAProxy stack"
|
||||
docker stack deploy --compose-file docker-compose.yml easyhaproxy
|
||||
```
|
||||
|
||||
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.
|
||||
:::danger Single Replica Only
|
||||
**Do not** add more than one replica for EasyHAProxy. To understand why, see the [limitations](limitations.md) page.
|
||||
:::
|
||||
|
||||
## Running containers
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,13 @@
|
|||
---
|
||||
sidebar_position: 13
|
||||
---
|
||||
|
||||
# Volumes
|
||||
|
||||
:::info Volume Mapping
|
||||
These volumes allow you to persist certificates, provide custom configurations, and extend EasyHAProxy functionality.
|
||||
:::
|
||||
|
||||
You can map the following volumes:
|
||||
|
||||
| Volume | Description |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue