docs(acp): deliver ACP 4.4 on Immutable Infrastructure — common article + DCS / HCS / Bare Metal / vSphere with complete manifests

[chinameok]

What

Five ACP 4.4 articles for delivering ACP on Immutable Infrastructure (Alauda OS nodes). A delivery engineer fills in parameter files and applies the given manifests in order, with a check after each step. This replaces the earlier ACP 4.3 draft of the DCS article, which only orchestrated and linked product pages and had no YAML.

Article	Covers
How_to_Deliver_ACP_with_Immutable_Infrastructure.md (start here)	Provider-neutral: reference design, parameter files and render helpers, delivery flow, platform plugins (Machine Configuration, MetalLB, Ingress NGINX, VictoriaMetrics, ClickHouse + Keeper + Kafka logging), machine configuration, sizing, acceptance
How_to_Deliver_ACP_on_Huawei_DCS_with_Immutable_Infrastructure.md	DCS: global primary + standby (DR) and workload clusters; Self-built VIP (DCS Provider v1.0.22+)
How_to_Deliver_ACP_on_Huawei_Cloud_Stack_with_Immutable_Infrastructure.md	HCS: global primary + standby (DR) and workload clusters; provider-created ELB
How_to_Deliver_ACP_on_Bare_Metal_with_Immutable_Infrastructure.md	Bare Metal: global primary + standby (DR), global as the management cluster, workload clusters; Alive Self-built VIP
How_to_Deliver_ACP_on_VMware_vSphere_with_Immutable_Infrastructure.md	vSphere: workload clusters only (global runs on another provider); Self-built VIP (vSphere Provider v1.0.17+)

Suggested reading order: the common article's Reference design and Prepare the parameter files, then one provider article end to end, then the common article from Install the platform plugins on.

Conventions shared by all five

• One site.env plus one env file per cluster, using the same variable names (global-primary.env, global-standby.env, wl-<name>.env). Variable names follow the product docs.
• Manifests use ${VAR} placeholders. Every variable is listed in a parameter table with an obviously fake example.
• render substitutes only the variables defined in those files (envsubst with an explicit list, plus a Bash fallback), so a literal $ in embedded scripts survives. apply_rendered refuses leftover placeholders and runs a server-side dry run before applying.
• Credentials never appear in files or on command lines. Secrets are created from prompted values through process substitution, and a leak scan of the rendered set is part of acceptance.
• Main line: multi-cluster with DR and the consolidated infra pool. Single-cluster, dedicated pools and worker pools are given as variants.
• Provider manifests are numbered 00–49 and common-step manifests 50–79, all in per-cluster directories.

Validation status

• The manifests are assembled from the ACP 4.4 product documentation and the named provider versions. No real environment has run them yet; each article says to validate in a staging environment before a production delivery.
• Each article went through a separate write pass and an independent review pass against the product pages and CRD schemas. Every manifest was rendered with the helpers, and the rendered YAML/JSON was parsed and checked against the provider CRDs.
• Links and anchors to docs.alauda.io were checked against the pinned branches (immutable-infra 1.0, ACP 4.4, Logging Service 4.4, ClickHouse 4.4, Kafka 4.3).

Decisions applied after the first review (2026-10-18)

• Local storage is TopoLVM. The reference design names it, gives the console-driven install and the StorageClass values this delivery chooses, and states the node-local constraint the product documents. Two gaps are stated plainly: TopoLVM needs one unformatted disk per node and only vSphere documents how to provide one; the product's lvm2 prerequisite assumes a mutable node, which Alauda OS is not.
• The logging stack install is deferred while its deployment scheme is revised. The section keeps the placement, storage and sizing decisions and points at the Logging Service documentation; the manifests will return with the new scheme. The log pool, its nodes and its disks stay in the provider manifests.
• Disaster recovery no longer explains steps with "cpaas-system is excluded from synchronization" — that claim is in the product documentation but not in the implementation. The rule set works on etcd key prefixes with a maintained deny-list, so most objects cross, Secrets included. Each global side keeps its own plugins (ModuleInfo names starting with global- are excluded) and its own machine configuration, which is not synchronized at all; machine configuration is therefore applied on both sides.
• A cluster still needs the customer's worker pools before handover: the main line creates only the control plane and a tainted infra pool, so there is no untainted node until they are added.

Open questions for product / R&D

These are recorded in the articles as items to validate or confirm.

1. TopoLVM on Alauda OS: does the Alauda OS image provide lvm2 and the TopoLVM node components? The install page's prerequisite is to install the package on the node, which a read-only root filesystem does not allow. Without this, TopoLVM is unusable here.
2. An unformatted disk on DCS, HCS and Bare Metal: no provider mechanism is documented for leaving a declared disk unformatted. On Bare Metal the plausible path is to leave the disk out of spec.storage entirely. Hardware plans depend on the answer.
3. Self-built VIP ports: does the Self-built VIP serve 443 / 11443 / 2379 on global (and 11780 on workload clusters)? Should etcd-sync's Active Global Cluster ETCD Endpoints be the VIP or the node IPs?
4. Shared DR platform certificate: what is the field layout of the installer's console.cert.thirdParty block? It is mandatory for disaster recovery and documented nowhere.
5. HCS DR encryption key: a KubeadmControlPlane file entry (what the DR pages say) or HCSCluster.spec.encryptionProviderConfigRef (what the CRD calls "Required for disaster recovery")? Also whether BaremetalCluster really has that field, which its CRD does not show.
6. vSphere: is contentFrom.secret supported for the encryption config, and should the provider also be installed on the standby global?

Product documentation defects found while writing these articles are tracked separately, including a security one: several pages create Secrets with --dry-run=client -o yaml | kubectl apply, which records the key material in an annotation.

Twin product-doc work: the ACP 4.4 Communication Matrix that these articles link for port approvals is being rewritten in alauda/acp-docs#1196 (#1197 / #1198 for 4.3 / master).

🤖 Generated with Claude Code