docs: refresh role readmes for v4.5

Author: Vonng

README.md

@@ -2,7 +2,7 @@
 
 [![Website: pigsty.io](https://img.shields.io/badge/website-pigsty.io-slategray?style=flat&logo=cilium&logoColor=white)](https://pigsty.io)
 [![CN: pigsty.cc](https://img.shields.io/badge/CN-pigsty.cc-slategray?style=flat&logo=cilium&logoColor=white)](https://pigsty.cc)
-[![Version: v4.5.0](https://img.shields.io/badge/version-v4.5.0-slategray?style=flat&logo=cilium&logoColor=white)](https://github.com/pgsty/pigsty/releases)
+[![Version: v4.4.0](https://img.shields.io/badge/version-v4.4.0-slategray?style=flat&logo=cilium&logoColor=white)](https://github.com/pgsty/pigsty/releases)
 [![License: Apache-2.0](https://img.shields.io/github/license/pgsty/pigsty?logo=opensourceinitiative&logoColor=green&color=slategray)](https://pigsty.io/docs/about/license/)
 [![GitHub Stars](https://img.shields.io/github/stars/pgsty/pigsty?style=flat&logo=github&logoColor=black&color=slategray)](https://star-history.com/#pgsty/pigsty&Date)
 [![Extensions: 555](https://img.shields.io/badge/extensions-555-%233E668F?style=flat&logo=postgresql&logoColor=white&labelColor=3E668F)](https://pigsty.io/ext/list)
@@ -16,10 +16,10 @@ Enterprise-Grade Open-Source **PostgreSQL** Distribution with HA, PITR, IaC, Mon
 
 [![banner](https://pigsty.io/img/pigsty/banner.png)](https://pigsty.io)
 
-Pigsty scales from [**laptop**](https://pigsty.io/docs/setup) to [**datacenter**](https://pigsty.io/docs/deploy). Enterprise-grade. Developer-friendly. [**Get Started**](https://pigsty.io/docs/setup/install) with the latest [**v4.5.0**](https://github.com/pgsty/pigsty/releases/tag/v4.5.0):
+Pigsty scales from [**laptop**](https://pigsty.io/docs/setup) to [**datacenter**](https://pigsty.io/docs/deploy). Enterprise-grade. Developer-friendly. [**Get Started**](https://pigsty.io/docs/setup/install) with the latest [**v4.4.0**](https://github.com/pgsty/pigsty/releases/tag/v4.4.0):
 
 ```bash
-curl -fsSL https://repo.pigsty.io/get | bash -s v4.5.0
+curl -fsSL https://repo.pigsty.io/get | bash -s v4.4.0
 ```
 
 
@@ -81,7 +81,7 @@ And gather the synergistic superpowers of all [**555 PostgreSQL Extensions**](ht
 [![EL Support: 8/9/10](https://img.shields.io/badge/EL-8/9/10-red?style=flat&logo=redhat&logoColor=red)](https://pigsty.io/docs/ref/linux#el)
 [![Debian Support: 12/13](https://img.shields.io/badge/Debian-12/13-%23A81D33?style=flat&logo=debian&logoColor=%23A81D33)](https://pigsty.io/docs/ref/linux#debian)
 [![Ubuntu Support: 22/24/26](https://img.shields.io/badge/Ubuntu-22/24/26-%23E95420?style=flat&logo=ubuntu&logoColor=%23E95420)](https://pigsty.io/docs/ref/linux#ubuntu)
-[![Docker Image](https://img.shields.io/badge/Docker-v4.5.0-%232496ED?style=flat&logo=docker&logoColor=white)](https://pigsty.io/docs/setup/docker)
+[![Docker Image](https://img.shields.io/badge/Docker-v4.4.0-%232496ED?style=flat&logo=docker&logoColor=white)](https://pigsty.io/docs/setup/docker)
 
 [**Prepare**](https://pigsty.io/docs/deploy/prepare) a fresh `x86_64` / `aarch64` node runs any [**compatible**](https://pigsty.io/docs/ref/linux) **Linux** OS Distros, then [**Install**](https://pigsty.io/docs/setup/install#install) **Pigsty** with:
 
@@ -121,24 +121,24 @@ pig sty deploy   # run the deploy.yml playbook
 <details><summary>Install with get script</summary><br>
 
 ```bash
-[root@pg-meta ~]# curl -fsSL https://repo.pigsty.io/get | bash -s v4.5.0
-[v4.5.0] ===========================================
+[root@pg-meta ~]# curl -fsSL https://repo.pigsty.io/get | bash -s v4.4.0
+[v4.4.0] ===========================================
 $ curl -fsSL https://repo.pigsty.io/get | bash
 [Docs] https://pigsty.io/docs
 [Demo] https://demo.pigsty.io
 [Repo] https://github.com/pgsty/pigsty
 [Download] ===========================================
-[ OK ] version = v4.5.0 (from arg)
-curl -fSL https://repo.pigsty.io/src/pigsty-v4.5.0.tgz -o /tmp/pigsty-v4.5.0.tgz
+[ OK ] version = v4.4.0 (from arg)
+curl -fSL https://repo.pigsty.io/src/pigsty-v4.4.0.tgz -o /tmp/pigsty-v4.4.0.tgz
 ######################################################################## 100.0%
-[ OK ] md5sums = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  /tmp/pigsty-v4.5.0.tgz
+[ OK ] md5sums = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  /tmp/pigsty-v4.4.0.tgz
 [Install] ===========================================
 [WARN] os user = root , it's recommended to use a non-root sudo-able admin
-[ OK ] install = /root/pigsty, from /tmp/pigsty-v4.5.0.tgz
+[ OK ] install = /root/pigsty, from /tmp/pigsty-v4.4.0.tgz
 
 [Bootstrap] ===========================================
 [WARN] ansible = not found, bootstrap
-bootstrap pigsty v4.5.0 begin
+bootstrap pigsty v4.4.0 begin
 [ OK ] region = china
 [ OK ] kernel  = Linux
 [ OK ] machine = x86_64
@@ -175,7 +175,7 @@ proceed with ./configure
 > HINT: To install a specific version, pass the version string as the first parameter:
 >
 > ```bash
-> curl -fsSL https://repo.pigsty.io/get | bash -s v4.5.0
+> curl -fsSL https://repo.pigsty.io/get | bash -s v4.4.0
 > ```
 
 </details>
@@ -186,7 +186,7 @@ proceed with ./configure
 You can also download the pigsty source with `git`, remember to check out a specific version tag, the `main` branch is for development.
 
 ```bash
-git clone https://github.com/pgsty/pigsty; cd pigsty; git checkout v4.5.0
+git clone https://github.com/pgsty/pigsty; cd pigsty; git checkout v4.4.0
 ```
 
 </details>

roles/ca/README.md

@@ -2,10 +2,10 @@
 
 > Create and Manage Self-Signed Certificate Authority
 
-| **Module**        | [INFRA](https://pigsty.io/docs/infra)    |
-|-------------------|------------------------------------------|
-| **Docs**          | https://pigsty.io/docs/infra/cert        |
-| **Related Roles** | [`infra`](../infra), [`pgsql`](../pgsql) |
+| **Module**        | [INFRA](https://pigsty.io/docs/infra) |
+|-------------------|---------------------------------------|
+| **Docs**          | https://pigsty.io/docs/infra/cert     |
+| **Related Roles** | `infra`, `pgsql`                      |
 
 
 ## Overview
@@ -17,21 +17,24 @@ The `ca` role creates a **self-signed Certificate Authority (CA)** for Pigsty:
 - Create PKI directory structure for all modules
 
 The CA is used to sign certificates for:
+
 - PostgreSQL server/client SSL
 - Patroni REST API
 - etcd cluster communication
 - MinIO cluster communication
+- Kafka cluster communication
+- MySQL cluster communication
 - Nginx HTTPS (self-signed fallback)
 - Infrastructure services
 - FerretDB/MongoDB TLS
 
 
 ## Playbooks
 
-| Playbook                       | Description                              |
-|--------------------------------|------------------------------------------|
-| [`infra.yml`](../../infra.yml) | Infrastructure deployment (includes CA)  |
-| [`cert.yml`](../../cert.yml)   | Issue additional certificates with CA    |
+| Playbook    | Description                             |
+|-------------|-----------------------------------------|
+| `infra.yml` | Infrastructure deployment (includes CA) |
+| `cert.yml`  | Issue additional certificates with CA   |
 
 
 ## File Structure
@@ -83,7 +86,7 @@ ca (full role)
 
 | Variable         | Default      | Description                                |
 |------------------|--------------|--------------------------------------------|
-| `ca_create`      | `true`       | Create CA if not exists, or abort          |
+| `ca_create`      | `true`       | Allow creation of a missing CA private key |
 | `ca_cn`          | `pigsty-ca`  | CA certificate common name                 |
 | `cert_validity`  | `7300d`      | Default validity for issued certificates   |
 
@@ -92,7 +95,7 @@ ca (full role)
 Controls CA creation behavior:
 
 - `true` (default): Create new CA if `files/pki/ca/ca.key` doesn't exist
-- `false`: Abort if CA files don't exist (use external CA)
+- `false`: Require an existing CA private key; create the certificate if missing
 
 ### ca_cn
 
@@ -118,6 +121,8 @@ files/pki/
 │   └── *.crt, *.key          # Miscellaneous certificates (cert.yml output)
 ├── etcd/
 │   └── *.crt, *.key          # ETCD server certificates
+├── kafka/
+│   └── *.crt, *.key          # Kafka server certificates
 ├── pgsql/
 │   └── *.crt, *.key          # PostgreSQL server certificates
 ├── minio/
@@ -126,8 +131,10 @@ files/pki/
 │   └── *.crt, *.key          # Infrastructure certificates
 ├── nginx/
 │   └── *.crt, *.key          # Nginx HTTPS certificates
-└── mongo/
-    └── *.crt, *.key          # FerretDB/MongoDB certificates
+├── mongo/
+│   └── *.crt, *.key          # FerretDB/MongoDB certificates
+└── mysql/
+    └── *.crt, *.key          # MySQL server certificates
 ```
 
 > **Security Note**: The `files/pki/ca/` directory contains sensitive CA private key. Ensure proper backup and access control. The CA key should never be exposed or committed to version control.
@@ -152,24 +159,28 @@ files/pki/
 CA key exists?  CA cert exists?  Action
 ───────────────────────────────────────
 No              No               Create new CA key and cert
+No              Yes              Create a new key; keep the existing cert*
 Yes             No               Create cert using existing key
 Yes             Yes              Reuse existing CA (no changes)
 ```
 
+`*` This state produces a mismatched pair. Always provide the CA key and
+certificate together.
+
 ### ca_create = false
 
 ```
 CA key exists?  CA cert exists?  Action
 ───────────────────────────────────────
 Yes             Yes              Reuse existing CA
+Yes             No               Create cert using existing key
 No              *                ABORT (fail the playbook)
-*               No               ABORT (fail the playbook)
 ```
 
 
-## Using External CA
+## Using an Existing CA
 
-To use your own enterprise or public CA:
+To provide an existing CA key pair:
 
 1. Set `ca_create: false` in your configuration:
 
@@ -198,7 +209,7 @@ To use your own enterprise or public CA:
 
 ## Issuing Additional Certificates
 
-Use [`cert.yml`](../../cert.yml) to issue additional certificates with the CA:
+Use `cert.yml` to issue additional certificates with the CA:
 
 ```bash
 # Issue a client certificate for database user
@@ -273,8 +284,8 @@ chmod 644 files/pki/ca/ca.crt
 
 ## See Also
 
-- [`infra`](../infra): Infrastructure deployment
-- [`pgsql`](../pgsql): PostgreSQL deployment (uses CA)
-- [`etcd`](../etcd): ETCD deployment (uses CA)
-- [`minio`](../minio): MinIO deployment (uses CA)
+- `infra`: Infrastructure deployment
+- `pgsql`: PostgreSQL deployment (uses CA)
+- `etcd`: ETCD deployment (uses CA)
+- `minio`: MinIO deployment (uses CA)
 - [Certificate Guide](https://pigsty.io/docs/infra/cert): SSL/TLS configuration

roles/cache/README.md

@@ -2,10 +2,10 @@
 
 > Create Offline Package Cache Tarball for Distribution
 
-| **Module**        | [INFRA](https://pigsty.io/docs/infra)  |
-|-------------------|----------------------------------------|
-| **Docs**          | https://pigsty.io/docs/setup/offline   |
-| **Related Roles** | [`repo`](../repo), [`infra`](../infra) |
+| **Module**        | [INFRA](https://pigsty.io/docs/infra) |
+|-------------------|---------------------------------------|
+| **Docs**          | https://pigsty.io/docs/setup/offline  |
+| **Related Roles** | `repo`, `infra`                       |
 
 
 ## Overview
@@ -37,9 +37,9 @@ Before running the cache role:
 
 ## Playbooks
 
-| Playbook                       | Description                    |
-|--------------------------------|--------------------------------|
-| [`cache.yml`](../../cache.yml) | Create offline package tarball |
+| Playbook    | Description                    |
+|-------------|--------------------------------|
+| `cache.yml` | Create offline package tarball |
 
 ```bash
 # Create offline package from infra node
@@ -254,7 +254,7 @@ ls -la /www/pigsty/
 
 ## See Also
 
-- [`repo`](../repo): Build local repository (must run before cache)
-- [`infra`](../infra): Full infrastructure deployment
+- `repo`: Build local repository (must run before cache)
+- `infra`: Full infrastructure deployment
 - [Offline Installation](https://pigsty.io/docs/setup/offline): Complete offline setup guide
 - [Bootstrap](https://pigsty.io/docs/setup/install/#bootstrap): Bootstrap process documentation

roles/docker/README.md

@@ -2,10 +2,10 @@
 
 > Deploy Docker Container Runtime
 
-| **Module**        | [DOCKER](https://pigsty.io/docs/docker)     |
-|-------------------|---------------------------------------------|
-| **Docs**          | https://pigsty.io/docs/docker/              |
-| **Related Roles** | [`node`](../node), [`infra`](../infra)      |
+| **Module**        | [DOCKER](https://pigsty.io/docs/docker) |
+|-------------------|-----------------------------------------|
+| **Docs**          | https://pigsty.io/docs/docker/          |
+| **Related Roles** | `node`, `infra`                         |
 
 
 ## Overview
@@ -25,9 +25,9 @@ Docker is used to run stateless applications alongside Pigsty.
 
 ## Playbooks
 
-| Playbook                           | Description          |
-|------------------------------------|----------------------|
-| [`docker.yml`](../../docker.yml)   | Deploy Docker        |
+| Playbook     | Description   |
+|--------------|---------------|
+| `docker.yml` | Deploy Docker |
 
 
 ## File Structure
@@ -162,19 +162,28 @@ The role generates `/etc/docker/daemon.json`:
 {
   "data-root": "/data/docker",
   "exec-opts": ["native.cgroupdriver=systemd"],
+  "storage-driver": "overlay2",
   "log-driver": "json-file",
   "log-opts": { "max-size": "100m" },
-  "storage-driver": "overlay2",
-  "metrics-addr" : "0.0.0.0:9323",
-  "experimental" : true,
-  "max-concurrent-downloads": 8,
-  "registry-mirrors" : []
+  "metrics-addr": "<inventory-host>:9323",
+  "experimental": true,
+  "registry-mirrors": [],
+  "default-ulimits": {
+    "nofile": {
+      "Hard": 1048576,
+      "Soft": 1048576,
+      "Name": "nofile"
+    }
+  },
+  "max-concurrent-downloads": 8
 }
 ```
 
+When `proxy_env` is defined, the role also renders Docker's `proxies` block.
+
 
 ## See Also
 
-- [`node`](../node): Node provisioning
-- [`infra`](../infra): Infrastructure deployment
+- `node`: Node provisioning
+- `infra`: Infrastructure deployment
 - [Docker Guide](https://pigsty.io/docs/docker/): Configuration documentation

roles/etcd/README.md

@@ -2,10 +2,10 @@
 
 > Deploy ETCD Distributed Key-Value Store Cluster
 
-| **Module**        | [ETCD](https://pigsty.io/docs/etcd)                                 |
-|-------------------|---------------------------------------------------------------------|
-| **Docs**          | https://pigsty.io/docs/etcd/                                        |
-| **Related Roles** | [`etcd_remove`](../etcd_remove), [`pgsql`](../pgsql), [`ca`](../ca) |
+| **Module**        | [ETCD](https://pigsty.io/docs/etcd) |
+|-------------------|-------------------------------------|
+| **Docs**          | https://pigsty.io/docs/etcd/        |
+| **Related Roles** | `etcd_remove`, `pgsql`, `ca`        |
 
 
 ## Overview
@@ -24,10 +24,10 @@ ETCD is used by Patroni for PostgreSQL HA consensus.
 
 ## Playbooks
 
-| Playbook                           | Description         |
-|------------------------------------|---------------------|
-| [`etcd.yml`](../../etcd.yml)       | Deploy ETCD cluster |
-| [`etcd-rm.yml`](../../etcd-rm.yml) | Remove ETCD cluster |
+| Playbook      | Description         |
+|---------------|---------------------|
+| `etcd.yml`    | Deploy ETCD cluster |
+| `etcd-rm.yml` | Remove ETCD cluster |
 
 
 ## File Structure
@@ -89,20 +89,25 @@ etcd (full role)
 
 ### Configuration
 
-| Variable         | Default      | Description             |
-|------------------|--------------|-------------------------|
-| `etcd_port`      | `2379`       | Client port             |
-| `etcd_peer_port` | `2380`       | Peer port               |
-| `etcd_data`      | `/data/etcd` | Data directory          |
-| `etcd_init`      | `new`        | Init mode: new/existing |
-| `etcd_learner`   | `false`      | Add as learner node     |
+| Variable                  | Default      | Description                   |
+|---------------------------|--------------|-------------------------------|
+| `etcd_port`               | `2379`       | Client port                   |
+| `etcd_peer_port`          | `2380`       | Peer port                     |
+| `etcd_data`               | `/data/etcd` | Data directory                |
+| `etcd_init`               | `new`        | Init mode: new/existing       |
+| `etcd_learner`            | `false`      | Add as learner node           |
+| `etcd_election_timeout`   | `1000`       | Election timeout in ms        |
+| `etcd_heartbeat_interval` | `100`        | Heartbeat interval in ms      |
+
+The backend quota is fixed at 8 GiB in the managed configuration.
 
 ### Security
 
-| Variable             | Default     | Description                |
-|----------------------|-------------|----------------------------|
-| `etcd_root_password` | `Etcd.Root` | Root user password         |
-| `etcd_safeguard`     | `false`     | Prevent accidental removal |
+| Variable             | Default     | Description        |
+|----------------------|-------------|--------------------|
+| `etcd_root_password` | `Etcd.Root` | Root user password |
+
+Removal protection is controlled by `etcd_safeguard` in the `etcd_remove` role.
 
 
 ## Cluster Topology
@@ -147,6 +152,6 @@ To add a new member:
 
 ## See Also
 
-- [`etcd_remove`](../etcd_remove): Remove ETCD cluster
-- [`pgsql`](../pgsql): PostgreSQL (uses ETCD for HA)
+- `etcd_remove`: Remove ETCD cluster
+- `pgsql`: PostgreSQL (uses ETCD for HA)
 - [ETCD Guide](https://pigsty.io/docs/etcd/): Configuration documentation