diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 3efaf4c..034676d 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -94,7 +94,7 @@ jobs: context: . file: build/Dockerfile build-args: | - RELEASE_VERSION_ARG="${{ join(steps.tags.outputs.result, ',') }}" + RELEASE_VERSION_ARG="${{ steps.tags.outputs.result }}" platforms: linux/amd64,linux/arm64 push: ${{ github.event_name != 'pull_request' || github.event.inputs.push == 'true' }} tags: ${{ steps.meta.outputs.tags }} @@ -110,16 +110,50 @@ jobs: Helm: runs-on: 'ubuntu-latest' needs: Build - if: github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/v') + if: github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/') env: DOC_GITHUB_TOKEN: '${{ secrets.DOC_TOKEN }}' steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 + if: startsWith(github.ref, 'refs/tags/') + with: + ref: master + + - uses: actions/checkout@v3 + if: github.ref == 'refs/heads/master' + + - name: Update versions + if: startsWith(github.ref, 'refs/tags/') + run: | + TAG="${{ steps.tags.outputs.result }}" + CURRENT_VERSION=$(grep "appVersion: " helm/easyhaproxy/Chart.yaml | sed 's#appVersion: "\(.*\)"#\1#g') + + if [ "$TAG" = "$CURRENT_VERSION" ]; then + echo "Skipping update version..." + else + sed -i "s#easy-haproxy:[a-zA-Z0-9\.]*#easy-haproxy:$TAG#g" deploy/docker/docker-compose.yml + sed -i "s#version: \"[a-zA-Z0-9\.]*\"#version: \"$TAG\"#g" deploy/kubernetes/easyhaproxy-*.yml + sed -i "s#easy-haproxy:[a-zA-Z0-9\.]*#easy-haproxy:$TAG#g" deploy/kubernetes/easyhaproxy-*.yml + + sed -i "s#easy-haproxy/[a-zA-Z0-9\.]*/#easy-haproxy/$TAG/#g" docs/kubernetes.md + sed -i "s#appVersion: \"[a-zA-Z0-9\.]*\"#appVersion: \"$TAG\"#g" helm/easyhaproxy/Chart.yaml + + VERSION=$(grep "version: " helm/easyhaproxy/Chart.yaml | sed 's#version: ##g') + NEW_VERSION=$(echo $VERSION | awk -F. '/[0-9]+\./{$NF++;print}' OFS=.) + + sed -i "s#version: [a-zA-Z0-9\.]*#version: $NEW_VERSION#g" helm/easyhaproxy/Chart.yaml + sed -i "s#chart: easyhaproxy-[a-zA-Z0-9\.]*#chart: easyhaproxy-$NEW_VERSION#g" deploy/kubernetes/easyhaproxy-*.yml + + git add . + git commit -m "[skip ci] Update from $CURRENT_VERSION to $TAG" + git push + fi + - run: curl https://opensource.byjg.com/add-helm.sh | bash /dev/stdin helm easyhaproxy Documentation: runs-on: 'ubuntu-latest' - needs: Build + needs: Helm if: github.ref == 'refs/heads/master' env: DOC_GITHUB_TOKEN: '${{ secrets.DOC_TOKEN }}' diff --git a/README.md b/README.md index 23cdd36..e4b2e2b 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,13 @@ [![GitHub license](https://img.shields.io/github/license/byjg/docker-easy-haproxy.svg)](https://opensource.byjg.com/opensource/licensing.html) [![GitHub release](https://img.shields.io/github/release/byjg/docker-easy-haproxy.svg)](https://github.com/byjg/docker-easy-haproxy/releases/) -![EasyHAProxy](easyhaproxy_logo.png) +![EasyHAProxy](docs/easyhaproxy_logo.png) ## 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,33 +20,36 @@ 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 |:----------:|:------------:|:------:|:-------: -| [![Kubernetes](easyhaproxy_kubernetes.png)](docs/kubernetes.md) | [![Docker Swarm](easyhaproxy_swarm.png)](docs/swarm.md) | [![Docker](easyhaproxy_docker.png)](docs/docker.md) | [![Static](easyhaproxy_static.png)](docs/static.md) +| [![Kubernetes](docs/easyhaproxy_kubernetes.png)](docs/kubernetes.md) | [![Docker Swarm](docs/easyhaproxy_swarm.png)](docs/swarm.md) | [![Docker](docs/easyhaproxy_docker.png)](docs/docker.md) | [![Static](docs/easyhaproxy_static.png)](docs/static.md) ---- diff --git a/deploy/docker/docker-compose.yml b/deploy/docker/docker-compose.yml index ad01297..bfd311e 100644 --- a/deploy/docker/docker-compose.yml +++ b/deploy/docker/docker-compose.yml @@ -2,7 +2,7 @@ version: "3" services: easyhaproxy: - image: byjg/easy-haproxy:master + image: byjg/easy-haproxy:4.2.0 volumes: - /var/run/docker.sock:/var/run/docker.sock - certs_letsencrypt:/certs/letsencrypt diff --git a/deploy/kubernetes/easyhaproxy-clusterip.yml b/deploy/kubernetes/easyhaproxy-clusterip.yml index ee8d8a7..438a2f8 100644 --- a/deploy/kubernetes/easyhaproxy-clusterip.yml +++ b/deploy/kubernetes/easyhaproxy-clusterip.yml @@ -9,7 +9,7 @@ metadata: helm.sh/chart: easyhaproxy-0.1.3 app.kubernetes.io/name: easyhaproxy app.kubernetes.io/instance: ingress - app.kubernetes.io/version: "master" + app.kubernetes.io/version: "4.2.0" app.kubernetes.io/managed-by: Helm --- # Source: easyhaproxy/templates/clusterrole.yaml @@ -22,7 +22,7 @@ metadata: helm.sh/chart: easyhaproxy-0.1.3 app.kubernetes.io/name: easyhaproxy app.kubernetes.io/instance: ingress - app.kubernetes.io/version: "master" + app.kubernetes.io/version: "4.2.0" app.kubernetes.io/managed-by: Helm rules: - apiGroups: @@ -88,7 +88,7 @@ metadata: helm.sh/chart: easyhaproxy-0.1.3 app.kubernetes.io/name: easyhaproxy app.kubernetes.io/instance: ingress - app.kubernetes.io/version: "master" + app.kubernetes.io/version: "4.2.0" app.kubernetes.io/managed-by: Helm roleRef: apiGroup: rbac.authorization.k8s.io @@ -110,7 +110,7 @@ metadata: helm.sh/chart: easyhaproxy-0.1.3 app.kubernetes.io/name: easyhaproxy app.kubernetes.io/instance: ingress - app.kubernetes.io/version: "master" + app.kubernetes.io/version: "4.2.0" app.kubernetes.io/managed-by: Helm annotations: {} @@ -142,7 +142,7 @@ metadata: helm.sh/chart: easyhaproxy-0.1.3 app.kubernetes.io/name: easyhaproxy app.kubernetes.io/instance: ingress - app.kubernetes.io/version: "master" + app.kubernetes.io/version: "4.2.0" app.kubernetes.io/managed-by: Helm spec: selector: diff --git a/deploy/kubernetes/easyhaproxy-daemonset.yml b/deploy/kubernetes/easyhaproxy-daemonset.yml index 7631fc0..a2ece4d 100644 --- a/deploy/kubernetes/easyhaproxy-daemonset.yml +++ b/deploy/kubernetes/easyhaproxy-daemonset.yml @@ -9,7 +9,7 @@ metadata: helm.sh/chart: easyhaproxy-0.1.3 app.kubernetes.io/name: easyhaproxy app.kubernetes.io/instance: ingress - app.kubernetes.io/version: "master" + app.kubernetes.io/version: "4.2.0" app.kubernetes.io/managed-by: Helm --- # Source: easyhaproxy/templates/clusterrole.yaml @@ -22,7 +22,7 @@ metadata: helm.sh/chart: easyhaproxy-0.1.3 app.kubernetes.io/name: easyhaproxy app.kubernetes.io/instance: ingress - app.kubernetes.io/version: "master" + app.kubernetes.io/version: "4.2.0" app.kubernetes.io/managed-by: Helm rules: - apiGroups: @@ -88,7 +88,7 @@ metadata: helm.sh/chart: easyhaproxy-0.1.3 app.kubernetes.io/name: easyhaproxy app.kubernetes.io/instance: ingress - app.kubernetes.io/version: "master" + app.kubernetes.io/version: "4.2.0" app.kubernetes.io/managed-by: Helm roleRef: apiGroup: rbac.authorization.k8s.io @@ -109,7 +109,7 @@ metadata: helm.sh/chart: easyhaproxy-0.1.3 app.kubernetes.io/name: easyhaproxy app.kubernetes.io/instance: ingress - app.kubernetes.io/version: "master" + app.kubernetes.io/version: "4.2.0" app.kubernetes.io/managed-by: Helm spec: selector: @@ -138,7 +138,7 @@ spec: - name: easyhaproxy securityContext: {} - image: "byjg/easy-haproxy:master" + image: "byjg/easy-haproxy:4.2.0" imagePullPolicy: Always ports: - name: http diff --git a/deploy/kubernetes/easyhaproxy-nodeport.yml b/deploy/kubernetes/easyhaproxy-nodeport.yml index 542d94b..3968165 100644 --- a/deploy/kubernetes/easyhaproxy-nodeport.yml +++ b/deploy/kubernetes/easyhaproxy-nodeport.yml @@ -9,7 +9,7 @@ metadata: helm.sh/chart: easyhaproxy-0.1.3 app.kubernetes.io/name: easyhaproxy app.kubernetes.io/instance: ingress - app.kubernetes.io/version: "master" + app.kubernetes.io/version: "4.2.0" app.kubernetes.io/managed-by: Helm --- # Source: easyhaproxy/templates/clusterrole.yaml @@ -22,7 +22,7 @@ metadata: helm.sh/chart: easyhaproxy-0.1.3 app.kubernetes.io/name: easyhaproxy app.kubernetes.io/instance: ingress - app.kubernetes.io/version: "master" + app.kubernetes.io/version: "4.2.0" app.kubernetes.io/managed-by: Helm rules: - apiGroups: @@ -88,7 +88,7 @@ metadata: helm.sh/chart: easyhaproxy-0.1.3 app.kubernetes.io/name: easyhaproxy app.kubernetes.io/instance: ingress - app.kubernetes.io/version: "master" + app.kubernetes.io/version: "4.2.0" app.kubernetes.io/managed-by: Helm roleRef: apiGroup: rbac.authorization.k8s.io @@ -110,7 +110,7 @@ metadata: helm.sh/chart: easyhaproxy-0.1.3 app.kubernetes.io/name: easyhaproxy app.kubernetes.io/instance: ingress - app.kubernetes.io/version: "master" + app.kubernetes.io/version: "4.2.0" app.kubernetes.io/managed-by: Helm annotations: {} @@ -142,7 +142,7 @@ metadata: helm.sh/chart: easyhaproxy-0.1.3 app.kubernetes.io/name: easyhaproxy app.kubernetes.io/instance: ingress - app.kubernetes.io/version: "master" + app.kubernetes.io/version: "4.2.0" app.kubernetes.io/managed-by: Helm spec: selector: @@ -171,7 +171,7 @@ spec: - name: easyhaproxy securityContext: {} - image: "byjg/easy-haproxy:master" + image: "byjg/easy-haproxy:4.2.0" imagePullPolicy: Always ports: - name: http 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/easyhaproxy_docker.png b/docs/easyhaproxy_docker.png similarity index 100% rename from easyhaproxy_docker.png rename to docs/easyhaproxy_docker.png diff --git a/easyhaproxy_kubernetes.png b/docs/easyhaproxy_kubernetes.png similarity index 100% rename from easyhaproxy_kubernetes.png rename to docs/easyhaproxy_kubernetes.png diff --git a/easyhaproxy_logo.png b/docs/easyhaproxy_logo.png similarity index 100% rename from easyhaproxy_logo.png rename to docs/easyhaproxy_logo.png diff --git a/easyhaproxy_static.png b/docs/easyhaproxy_static.png similarity index 100% rename from easyhaproxy_static.png rename to docs/easyhaproxy_static.png diff --git a/easyhaproxy_swarm.png b/docs/easyhaproxy_swarm.png similarity index 100% rename from easyhaproxy_swarm.png rename to docs/easyhaproxy_swarm.png diff --git a/docs/kubernetes.md b/docs/kubernetes.md index 7181454..7ecd388 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/4.2.0/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 8506234..ce63b97 100644 --- a/docs/static.md +++ b/docs/static.md @@ -2,11 +2,11 @@ ## Setup Docker EasyHAProxy -This method will use a static configuration, simpler and easier than HAProxy to create the `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 and changes are detected. +Another advantage is that EasyHAProxy will monitor for changes in this file and automatically reconfigure HAProxy when any changes are detected. First, Create a YAML: @@ -98,12 +98,12 @@ 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 ``` -*Note*: The only way to pass SSL certificates 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**: The only way to pass SSL certificates is to map the certificates to EasyHAProxy as a docker volume. Refer to the [SSL documentation](ssl.md) to learn how to do it. ---- [Open source ByJG](http://opensource.byjg.com) 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) diff --git a/helm/easyhaproxy/Chart.yaml b/helm/easyhaproxy/Chart.yaml index dcbbe33..3bcc5b0 100644 --- a/helm/easyhaproxy/Chart.yaml +++ b/helm/easyhaproxy/Chart.yaml @@ -15,10 +15,10 @@ type: application # This is the chart version. This version number should be incremented each time you make changes # to the chart and its templates, including the app version. # Versions are expected to follow Semantic Versioning (https://semver.org/) -version: 0.1.3 +version: 0.1.4 # This is the version number of the application being deployed. This version number should be # incremented each time you make changes to the application. Versions are not expected to # follow Semantic Versioning. They should reflect the version the application is using. # It is recommended to use it with quotes. -appVersion: "master" +appVersion: "4.2.0"