From 63048adf0fcb1c092977d3f3cd62506f0cc5ff12 Mon Sep 17 00:00:00 2001 From: Joao Gilberto Magalhaes Date: Mon, 3 Jul 2023 15:26:56 -0500 Subject: [PATCH] Minor Fix Pre-Merge --- docs/acme.md | 82 ++++++++++++++++--- docs/docker.md | 2 +- ...environment.md => environment-variable.md} | 8 +- docs/kubernetes.md | 2 +- docs/letsencrypt.md | 55 ------------- docs/static.md | 2 +- docs/swarm.md | 2 +- 7 files changed, 78 insertions(+), 75 deletions(-) rename docs/{docker-environment.md => environment-variable.md} (72%) delete mode 100644 docs/letsencrypt.md diff --git a/docs/acme.md b/docs/acme.md index 5c24fdf..f695726 100644 --- a/docs/acme.md +++ b/docs/acme.md @@ -6,28 +6,34 @@ allowing the automated deployment of public key infrastructure. Most of the issuers offers Automatic Issuing free of cost. +## Environment Variables + To enable the ACME protocol we need to enable Certbot in EasyHAProxy by setting up to 4 environment variables: -- EASYHAPROXY_CERTBOT_AUTOCONFIG (optional): Will use pre-sets for your Certificate Authority (CA). See table below. -- EASYHAPROXY_CERTBOT_EMAIL (required): Your email in the certificate authority. -- EASYHAPROXY_CERTBOT_SERVER (optional): The ACME Endpoint of your certificate authority. If you use AUTOCONFIG, it is set automatically. See table below. -- EASYHAPROXY_CERTBOT_EAB_KID (optional): External Account Binding (EAB) Key Identifier (KID) provided by your certificate authority. Some CA require it. See table below. -- EASYHAPROXY_CERTBOT_EAB_HMAC_KEY (optional): External Account Binding (EAB) HMAC Key provided by your certificate authority. Some CA require it. See table below. -- EASYHAPROXY_CERTBOT_RETRY_COUNT (optional): Wait 'n' requests before retrying issue invalid requests. Default 60. +| Environment Variable | Required? | Description | +|----------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------| +| EASYHAPROXY_CERTBOT_EMAIL | YES | Your email in the certificate authority. | +| EASYHAPROXY_CERTBOT_AUTOCONFIG | - | Will use pre-sets for your Certificate Authority (CA). See table below. | +| EASYHAPROXY_CERTBOT_SERVER | - | The ACME Endpoint of your certificate authority. If you use AUTOCONFIG, it is set automatically. See table below. | +| EASYHAPROXY_CERTBOT_EAB_KID | - | External Account Binding (EAB) Key Identifier (KID) provided by your certificate authority. Some CA require it. See table below. | +| EASYHAPROXY_CERTBOT_EAB_HMAC_KEY | - | External Account Binding (EAB) HMAC Key provided by your certificate authority. Some CA require it. See table below. | +| EASYHAPROXY_CERTBOT_RETRY_COUNT | - | Wait 'n' requests before retrying issue invalid requests. Default 60. | + +## Auto Config Certificate Authority (CA) Here are detailed instructions per Certificate Authority (CA). If anyone is missing, please let's know. | CA | Auto Config | Free? | Account Required? | EAB KID? | EAB HMAC Key? | More Info | |----------------------|------------------|-------|--------------------|----------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Let's Encrypt | - | Yes | No | No | No | [Link](letsencrypt.md) | -| Let's Encrypt (Test) | letsencrypt_test | Yes | No | No | No | [Link](letsencrypt.md) | +| Let's Encrypt | - | Yes | No | No | No | - | +| 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) | | BuyPass (test) | buypass_test | Yes | No | No | No | [Link](https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints-updated-14-05-2020) | | Google | google | Yes | Yes | Yes | Yes | [Link](https://cloud.google.com/blog/products/identity-security/automate-public-certificate-lifecycle-management-via--acme-client-api) | | Google Test | google_test | Yes | Yes | Yes | Yes | [Link](https://cloud.google.com/blog/products/identity-security/automate-public-certificate-lifecycle-management-via--acme-client-api) | -| SSLCOM RCA | sslcom_rca | Yes | No. Keys by email. | Yes | Yes | [Link](https://www.ssl.com/blogs/sslcom-supports-acme-protocol-ssl-tls-certificate-automation/) | -| SSLCOM ECC | sslcom_ecc | Yes | No. Keys by email. | Yes | Yes | [Link](https://www.ssl.com/blogs/sslcom-supports-acme-protocol-ssl-tls-certificate-automation/) | +| SSLCOM RCA | sslcom_rca | Trial | EAB Keys by email. | Yes | Yes | [Link](https://www.ssl.com/blogs/sslcom-supports-acme-protocol-ssl-tls-certificate-automation/) | +| SSLCOM ECC | sslcom_ecc | Trial | EAB Keys by email. | Yes | Yes | [Link](https://www.ssl.com/blogs/sslcom-supports-acme-protocol-ssl-tls-certificate-automation/) | | Digicert | - | No | Yes | Yes | Yes | [Link](https://docs.digicert.com/en/certcentral/certificate-tools/certificate-lifecycle-automation-guides/use-a-third-party-acme-client-for-host-automations.html) | | Entrust | - | No | Yes | Yes | Yes | [Link](https://www.entrust.com/knowledgebase/ssl/how-to-use-acme-to-install-ssl-tls-certificates-in-entrust-certificate-services-apache) | | Sectigo | - | No | Yes | Yes | Yes | [Link](https://www.sectigo.com/resource-library/sectigos-acme-automation) | @@ -35,3 +41,59 @@ Here are detailed instructions per Certificate Authority (CA). If anyone is miss This configuration is global. After set up ACME properly, is necessary enable for each domain the certificate request. To do that add the label: `easyhaproxy..certbot=true`. See the method of installation you are using to learn how to set up properly. + +## Example + +### Setting up EasyHAProxy + +Run the EasyHAProxy container: + +```bash +docker run \ + ... \ + -e EASYHAPROXY_CERTBOT_AUTOCONFIG=zerossl \ + -e EASYHAPROXY_CERTBOT_EMAIL=john@doe.com \ + -p 80:80 \ + -p 443:443 \ + -v /path/to/guest/certbot/certs:/certs/certbot \ + ... \ + byjg/easy-haproxy +``` + +Notes: + +- 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. + +If you are using Let's Encrypt, be aware of it rate limits: + +- https://letsencrypt.org/docs/duplicate-certificate-limit/ +- https://letsencrypt.org/docs/rate-limits/ + + +## Setting up your container to use the ACME CA + +```bash +docker run \ + ... \ + --label easyhaproxy.express.port=80 \ + --label easyhaproxy.express.localport=3000 \ + --label easyhaproxy.express.host=example.org \ + --label easyhaproxy.express.certbot=true \ + ... \ + some/myimage +``` + +Requirements: + +- Your container **must** listen to port 80. The CA will not issue the certificate if `easyhaproxy..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. + +---- +[Open source ByJG](http://opensource.byjg.com) \ No newline at end of file diff --git a/docs/docker.md b/docs/docker.md index ce0c5cd..362b309 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -55,7 +55,7 @@ Please follow the [docker label configuration](container-labels.md) to see other ## 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 [environment variable guide](environment-variable.md) ## Setup certificates with ACME (e.g. Letsencrypt) diff --git a/docs/docker-environment.md b/docs/environment-variable.md similarity index 72% rename from docs/docker-environment.md rename to docs/environment-variable.md index b9f4d33..b00bacf 100644 --- a/docs/docker-environment.md +++ b/docs/environment-variable.md @@ -4,13 +4,9 @@ |----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| | EASYHAPROXY_DISCOVER | How the services will be discovered to create `haproxy.cfg`: `static`, `docker`, `swarm` or `kubernetes` | **required** | | EASYHAPROXY_LABEL_PREFIX | (Optional) The key will search for matching resources. | `easyhaproxy` | -| EASYHAPROXY_CERTBOT_EMAIL | (Optional) The email will be used to request the certificate to Certbot | *empty* | -| EASYHAPROXY_CERTBOT_SERVER | (Optional) Can be `staging` or 'schema://domain.tld', if using other service than Letsencrypt. Might be necessary set EASYHAPROXY_CERTBOT_EAB_KID and EASYHAPROXY_CERTBOT_EAB_HMAC_KEY | *empty* | -| EASYHAPROXY_CERTBOT_EAB_KID | (Optional) eab-kid configuration when required. | *empty* | -| EASYHAPROXY_CERTBOT_EAB_HMAC_KEY | (Optional) eab-kid-hmac-key configuration when required. | *empty* | -| EASYHAPROXY_CERTBOT_RETRY_COUNT | (Optional) Wait 'n' requests before try re-issue invalid calls | +| EASYHAPROXY_CERTBOT_* | (Optional) Enable Let's Encrypt or any other ACME certificate. See more: [acme](acme.md) | *empty* | | EASYHAPROXY_SSL_MODE | (Optional) `strict` supports only the most recent TLS version; `default` good SSL integration with recent browsers; `loose` supports all old SSL protocols for old browsers (not recommended). | `default` | -| EASYHAPROXY_REFRESH_CONF | (Optional) Check configuration every N seconds. | 10 | +| EASYHAPROXY_REFRESH_CONF | (Optional) Check for new containers/services every N seconds. | 10 | | EASYHAPROXY_LOG_LEVEL | (Optional) The log level for EasyHAproxy messages. Available: TRACE,DEBUG,INFO,WARN,ERROR,FATAL | DEBUG | | CERTBOT_LOG_LEVEL | (Optional) The log level for Certbot messages. Available: TRACE,DEBUG,INFO,WARN,ERROR,FATAL | DEBUG | | HAPROXY_LOG_LEVEL | (Optional) The log level for HAProxy messages. Available: TRACE,DEBUG,INFO,WARN,ERROR,FATAL | DEBUG | diff --git a/docs/kubernetes.md b/docs/kubernetes.md index b3fac3c..a7f4e6f 100644 --- a/docs/kubernetes.md +++ b/docs/kubernetes.md @@ -39,7 +39,7 @@ kubectl apply -f \ https://raw.githubusercontent.com/byjg/docker-easy-haproxy/4.3.1-rc1/deploy/kubernetes/easyhaproxy-daemonset.yml ``` -If necessary, you can configure 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 [environment variable guide](environment-variable.md) ## Running containers diff --git a/docs/letsencrypt.md b/docs/letsencrypt.md deleted file mode 100644 index acecae0..0000000 --- a/docs/letsencrypt.md +++ /dev/null @@ -1,55 +0,0 @@ -# Letsencrypt - -EasyHAProxy can issue a letsencrypt certificate. Follow the steps below: - -## Setting up EasyHAProxy - -Run the EasyHAProxy container: - -```bash -docker run \ - ... \ - -e EASYHAPROXY_CERTBOT_EMAIL=john@doe.com \ - -p 80:80 \ - -p 443:443 \ - -v /path/to/guest/certbot/certs:/certs/certbot \ - ... \ - byjg/easy-haproxy -``` - -Notes: - -- 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/) - -Be aware of Letsencrypt issue rate limits: - -- https://letsencrypt.org/docs/duplicate-certificate-limit/ -- https://letsencrypt.org/docs/rate-limits/ - -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, Let's encrypt will not work properly. - - -## Setting up your container to use Let's Encrypt - -```bash -docker run \ - ... \ - --label easyhaproxy.express.port=80 \ - --label easyhaproxy.express.localport=3000 \ - --label easyhaproxy.express.host=example.org \ - --label easyhaproxy.express.certbot=true \ - ... \ - some/myimage -``` - -Requirements: - -- Your container **must** listen to port 80. Letsencrypt will not issue the certificate if `easyhaproxy..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. - ----- -[Open source ByJG](http://opensource.byjg.com) diff --git a/docs/static.md b/docs/static.md index ff6ee32..53cb2d6 100644 --- a/docs/static.md +++ b/docs/static.md @@ -72,7 +72,7 @@ docker run -d \ byjg/easy-haproxy ``` -You can find other informations on [docker label configuration](container-labels.md) and [docker container environment](docker-environment.md) +You can find other informations on [docker label configuration](container-labels.md) and [environment variable guide](environment-variable.md) ## Yaml Definition diff --git a/docs/swarm.md b/docs/swarm.md index 9ab29c4..16fe71c 100644 --- a/docs/swarm.md +++ b/docs/swarm.md @@ -91,7 +91,7 @@ Please follow the [docker label configuration](container-labels.md) to see other ## 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 [environment variable guide](environment-variable.md) ## More information