Refine https documents (#1156)

* Refine https documents * Transform AutoCertManager to business controller * Fix broken links
easegress-io · Dec 8, 2023 · d0b0605 · d0b0605
1 parent c3ab195
commit d0b0605
Show file tree

Hide file tree

Showing 6 changed files with 92 additions and 82 deletions.
diff --git a/README.md b/README.md
@@ -119,7 +119,7 @@ $ easegress-server
 
 By default, Easegress opens ports 2379, 2380, and 2381; however, you can modify these settings along with other arguments either in the configuration file or via command-line arguments. For a complete list of arguments, please refer to the `easegress-server --help` command.
 
-After launching successfully, we could check the status of the one-node cluster. 
+After launching successfully, we could check the status of the one-node cluster.
 
 ```bash
 $ egctl get member
@@ -134,7 +134,7 @@ $ egctl describe member
 Assuming you have two backend HTTP services running at `127.0.0.1:9095` and `127.0.0.1:9096`, you can initiate an HTTP proxy from port 10080 to these backends using the following command:
 
 ```bash
-$ egctl create httpproxy demo --port 10080 \ 
+$ egctl create httpproxy demo --port 10080 \
  --rule="/pipeline=http:https://127.0.0.1:9095,http:https://127.0.0.1:9096"
 ```
 
@@ -168,7 +168,7 @@ The following examples show how to use Easegress for different scenarios.
 - [Performance](docs/03.Advanced-Cookbook/3.11.Performance.md) - Performance optimization - compression, caching etc.
 - [Pipeline](docs/02.Tutorials/2.3.Pipeline-Explained.md) - How to orchestrate HTTP filters for requests/responses handling
 - [Resilience and Fault Tolerance](docs/02.Tutorials/2.4.Resilience.md) - CircuitBreaker, RateLimiter, Retry, TimeLimiter, etc. (Porting from [Java resilience4j](https://github.com/resilience4j/resilience4j))
-- [Security](docs/02.Tutorials/2.5.HTTPS-Lets-Encrypt.md#security-verify-credential) - How to do authentication by Header, JWT, HMAC, OAuth2, etc.
+- [Security](docs/02.Tutorials/2.5.Traffic-Verification.md) - How to do authentication by Header, JWT, HMAC, OAuth2, etc.
 - [Service Registry](docs/03.Advanced-Cookbook/3.06.Service-Registry.md) - Supporting the Microservice registries - Zookeeper, Eureka, Consul, Nacos, etc.
 - [WebAssembly](docs/03.Advanced-Cookbook/3.07.WasmHost.md) - Using AssemblyScript to extend the Easegress
 - [WebSocket](docs/02.Tutorials/2.6.Websocket.md) - WebSocket proxy for Easegress

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -113,7 +113,7 @@
 - [高性能](docs/03.Advanced-Cookbook/3.11.Performance.md) - 性能优化，压缩、缓存等。
 - [管道编排](docs/02.Tutorials/2.3.Pipeline-Explained.md) - 如何编排 HTTP 过滤器来处理请求和应答。
 - [弹力和容错设计](docs/02.Tutorials/2.4.Resilience.md) - 断路器、速率限制、重试、时间限制等（移植自[Java resilience4j](https://github.com/resilience4j/resilience4j)
-- [安全](docs/02.Tutorials/2.5.HTTPS-Lets-Encrypt.md#security-verify-credential) - 如何通过标头、JWT、HMAC、OAuth2 等进行认证。
+- [安全](docs/02.Tutorials/2.5.Traffic-Verification.md) - 如何通过标头、JWT、HMAC、OAuth2 等进行认证。
 - [服务注册](docs/03.Advanced-Cookbook/3.06.Service-Registry.md) - 使用 Zookeeper、Eureka、Consul、Nacos 等进行服务注册。
 - [WebAssembly](docs/03.Advanced-Cookbook/3.07.WasmHost.md) - 使用 AssemblyScript 来扩展 Easegress。
 - [WebSocket](docs/02.Tutorials/2.6.Websocket.md) - Easegress 的 WebSocket 代理。

diff --git a/docs/02.Tutorials/2.5.HTTPS-Lets-Encrypt.md → .../02.Tutorials/2.5.Traffic-Verification.md b/docs/02.Tutorials/2.5.HTTPS-Lets-Encrypt.md → .../02.Tutorials/2.5.Traffic-Verification.md
@@ -1,7 +1,5 @@
 # Security <!-- omit from toc -->
 
-- [HTTPS](#https)
-- [Let's Encrypt](#lets-encrypt)
 - [Security: Verify Credential](#security-verify-credential)
  - [Header](#header)
  - [JWT](#jwt)
@@ -16,77 +14,6 @@
  - [Basic Auth](#basic-auth-1)
  - [Reference](#reference)
 
-
-## HTTPS
-
-Implementing HTTPS in `HTTPServer` is straightforward. You either provide the required certificates and keys, or employ `AutoCertManager` to handle them using services like `Let's Encrypt`.
-
-To activate HTTPS in your `HTTPServer`, toggle the `https` field to `true` and offer the relevant certificates and keys:
-
-```yaml
-name: demo
-kind: HTTPServer
-
-# Use HTTPS; default is false. 
-# If true, set autocert or provide certs and keys.
-https: true
-
-# Automated certificate management, such as Let's Encrypt.
-# More info in AutoCertManager
-autoCert: false
-
-# Public keys in PEM base64 format
-certs:
- cert1: <public-key-data>
- cert2: <public-key-data>
-# Corresponding private keys
-keys: 
- cert1: <private-key-data>
- cert2: <private-key-data>
-
-...
-```
-
-
-## Let's Encrypt
-
-In Easegress, `AutoCertManager` automatically manage HTTPS certificates. The config looks like:
-
-```yaml
-kind: AutoCertManager
-name: autocert
-
-# An email address for CA account.
-email: [email protected]
-
-# The endpoint of the CA directory, not required.
-# Default to use Let's Encrypt.
-directoryURL: https://acme-v02.api.letsencrypt.org/directory
-
-# A certificate will be renewed before this duration of its expire time.
-# Default 720h.
-renewBefore: 720h
-
-# Enable HTTP-01 challenge, default true.
-enableHTTP01: true
-
-# Enable TLS-ALPN-01 challenge, default true.
-enableTLSALPN01: true
-
-# Enable DNS-01 challenge, default true.
-enableDNS01: true
-
-# Domains to be managed, required.
-domains:
- - name: "*.megaease.com"
- dnsProvider:
- name: dnspod
- zone: megaease.com
- apiToken: <token value>
-```
-
-See more details about `AutoCertManager` in [here](../07.Reference/7.01.Controllers.md#autocertmanager).
-
 ## Security: Verify Credential
 
 As a production-ready cloud-native traffic orchestrator, Easegress cares about security and provides several features to ensure that.

diff --git a/docs/02.Tutorials/2.8.HTTPS-Lets-Encrypt.md b/docs/02.Tutorials/2.8.HTTPS-Lets-Encrypt.md
@@ -0,0 +1,83 @@
+# HTTPS and Let's Encrypt <!-- omit from toc -->
+
+- [Introduction](#introduction)
+- [Configuring HTTPS in HTTPServer](#configuring-https-in-httpserver)
+ - [Manual Configuration](#manual-configuration)
+ - [Using AutoCertManager](#using-autocertmanager)
+- [AutoCertManager Configuration](#autocertmanager-configuration)
+
+
+## Introduction
+
+Easegress offers both manual and automated approach to manage HTTPS certificates. The automated method is using business controller AutoCertManager. This tutorial will guide you through setting up HTTPS in HTTPServer and configuring AutoCertManager for certificate management with Let's Encrypt.
+
+## Configuring HTTPS in HTTPServer
+
+To implement HTTPS in HTTPServer, you have two options: manually providing certificates and keys, or using AutoCertManager for automated certificate management.
+
+### Manual Configuration
+
+For manual configuration, you need to set https to true and provide your certificates and keys.
+
+```yaml
+name: demo
+kind: HTTPServer
+https: true
+autoCert: false
+certs:
+ cert1: <public-key-data>
+ cert2: <public-key-data>
+keys:
+ cert1: <private-key-data>
+ cert2: <private-key-data>
+...
+```
+
+### Using AutoCertManager
+
+If you prefer automated management with Let's Encrypt, set autoCert to true. This will utilize the AutoCertManager.
+
+```yaml
+name: demo
+kind: HTTPServer
+https: true
+autoCert: true
+...
+```
+
+## AutoCertManager Configuration
+
+`AutoCertManager` is a business controller, which is more special than others. Because there can be at most one instance of AutoCerManager. It manages HTTPS certificates and handles challenge traffic from Let's Encrypt.
+
+```yaml
+kind: AutoCertManager
+name: AutoCertManager
+email: [email protected]
+directoryURL: https://acme-v02.api.letsencrypt.org/directory
+renewBefore: 720h
+enableHTTP01: true
+enableTLSALPN01: true
+enableDNS01: true
+domains:
+ - name: "*.megaease.com"
+ dnsProvider:
+ name: dnspod
+ zone: megaease.com
+ apiToken: <token value>
+```
+
+Explanation of Fields:
+
+- email: Email address for Let's Encrypt registration.
+- directoryURL: CA directory URL (default: Let's Encrypt official one).
+- renewBefore: Time before expiry to renew the certificate.
+- enableHTTP01, enableTLSALPN01, enableDNS01: Challenge types to enable.
+- domains: Domains to manage, along with their DNS provider configurations.
+
+Assuming we have saved the config in `acm.yaml`, we could use this command to update global AutoCertManager.
+
+```bash
+$ egctl apply -f acm.aml
+```
+
+See more details about `AutoCertManager` in [here](../07.Reference/7.01.Controllers.md#autocertmanager).
diff --git a/docs/02.Tutorials/README.md b/docs/02.Tutorials/README.md
@@ -4,6 +4,6 @@
 ### [HTTP Proxy Usage](2.2.HTTP-Proxy-Usage.md)
 ### [Pipeline Explained](2.3.Pipeline-Explained.md)
 ### [Advanced HTTP Proxy: Resilience](2.4.Resilience.md)
-### [HTTPS & Let's Encrypt & More](2.5.HTTPS-Lets-Encrypt.md)
+### [HTTPS & Let's Encrypt & More](2.5.Traffic-Verification.md)
 ### [Websocket](2.6.Websocket.md)
 ### [gRPC](2.7.gRPC.md)
diff --git a/docs/03.Advanced-Cookbook/3.02.Flash-Sale.md b/docs/03.Advanced-Cookbook/3.02.Flash-Sale.md
@@ -13,7 +13,7 @@
  - [6.2 Manage Shared Data](#62-manage-shared-data)
 - [7. Summary](#7-summary)
 
-A flash sale is a discount or promotion offered by an eCommerce store for a short period. The quantity is limited, which often means the discounts are higher or more significant than run-of-the-mill promotions. 
+A flash sale is a discount or promotion offered by an eCommerce store for a short period. The quantity is limited, which often means the discounts are higher or more significant than run-of-the-mill promotions.
 
 However, significant discounts, limited quantity, and a short period leading to a significant high traffic spike, which often results in slow service, denial of service, or even downtime.
 
@@ -93,7 +93,7 @@ registerProgramFactory((params: Map<string, string>) => {
 ```
 
 7 ) Build with the below command, if everything is right, `untouched.wasm` (the debug version) and `optimized.wasm` (the release version) will be generated at the `build` folder.
- 
+
 ```bash
 $ npm run asbuild
 ```
@@ -267,7 +267,7 @@ From the view of business, after we permit a lucky user to go forward, we should
 
 Fortunately, all users need to sign in before joining the flash sale, that's the requests will contain an identifier of the user, we can use this identifier to record the lucky users.
 
-As an example, we suppose the value of the `Authorization` header is the desired identifier (the identifier could be a JWT token, and the [Validator filter](../02.Tutorials/2.5.HTTPS-Lets-Encrypt.md#security-verify-credential) can be used to validate the token, but this is out of the scope of this document).
+As an example, we suppose the value of the `Authorization` header is the desired identifier (the identifier could be a JWT token, and the [Validator filter](../02.Tutorials/2.5.Traffic-Verification.md) can be used to validate the token, but this is out of the scope of this document).
 
 However, due to the `maxConcurrency` option in the filter configuration, using a `Set` the store all permitted users won't work.
 
@@ -346,7 +346,7 @@ class FlashSale extends Program {
  startTime: i64
  blockRatio: f64
 
- // maxPermission is the upper limits of permitted users 
+ // maxPermission is the upper limits of permitted users
  maxPermission: i32
 
  constructor(params: Map<string, string>) {