mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 20:31:30 +00:00
docs: deployment vendor matrix + per-connector deep-dive docs (NGINX + K8s + IIS + Apache + F5)
Phase 14 of the deploy-hardening II master bundle. The procurement- team headline doc + per-connector operator guides for the top 5 most-deployed connectors. NEW docs/deployment-vendor-matrix.md (~30 rows): - Per (connector × vendor-version) status: ✓ / CI / mock / pending / n/a - Known issues + workarounds + e2e test name reference - LTS + current-stable scope per frozen decision 0.1 - Quarterly re-pin cadence guidance for sidecar digests - "How to add a new vendor version" recipe Per frozen decision 0.14: a (connector × vendor-version) cell is "verified" only when ALL apply: ≥1 happy-path e2e green; ≥1 specific-quirk test green for that version; operator manual smoke completed at least once. Cells lacking the third criterion show "CI" status (auto-tests green but pending operator validation). Status snapshot at bundle close: - NGINX 1.25 + 1.27: CI - Apache 2.4: CI - HAProxy 2.6 + 2.8 + 3.0: CI - Traefik 2.x + 3.x: CI - Caddy 2.x: CI - Envoy 1.30 + 1.32: CI (file-mode SDS only; gRPC SDS V3-Pro) - Postfix 3.6 + 3.8: CI - Dovecot 2.3: CI - IIS 10 (2019, 2022): pending (Windows-host-only CI) - F5 v15.1 + v17.0 + v17.5: mock (real-F5 vagrant box documented) - SSH OpenSSH 8.x + 9.x: CI - WinCertStore (2019, 2022): pending (Windows-host-only) - JavaKeystore JDK 11 + 17 + 21: pending - K8s 1.28 + 1.30 + 1.31: CI NEW per-connector deep-dive docs: - docs/connector-nginx.md (~150 lines, 10 quirks documented) - docs/connector-k8s.md (~110 lines, 10 quirks) - docs/connector-iis.md (~120 lines, 10 quirks; Windows-host-only CI constraint loud) - docs/connector-apache.md (~80 lines, 10 quirks) - docs/connector-f5.md (~190 lines, 10 quirks; two-tier validation recipe for operator-supplied real-F5 vagrant box) Each doc follows the same structure: - Overview - Vendor versions tested - Per-quirk operator guidance (one section per TestVendorEdge_<vendor>_<edge>_E2E) - Troubleshooting matrix - V3-Pro deferrals - Related docs cross-refs Other connector docs (HAProxy, Traefik, Caddy, Envoy, Postfix, Dovecot, SSH, WinCertStore, JavaKeystore) live in docs/connectors.md + are referenced from the matrix. Phase 15 next: per-vendor CI matrix job in .github/workflows/ci.yml.
This commit is contained in:
@@ -0,0 +1,101 @@
|
||||
# Apache httpd Connector — Operator Deep-Dive
|
||||
|
||||
> Per Phase 14 of the deploy-hardening II master bundle.
|
||||
|
||||
## Overview
|
||||
|
||||
The Apache connector (`internal/connector/target/apache/`) deploys
|
||||
TLS certs to Apache 2.4 LTS via separate cert/chain/key files +
|
||||
`apachectl configtest` validate + `apachectl graceful` reload.
|
||||
Mirrors the canonical NGINX template (Bundle I Phase 5).
|
||||
|
||||
## Vendor versions tested
|
||||
|
||||
- **Apache httpd 2.4 LTS** (only LTS branch; 2.6 is dev branch)
|
||||
|
||||
## Per-quirk operator guidance
|
||||
|
||||
### Multi-vhost cert-by-vhost
|
||||
|
||||
`TestVendorEdge_Apache_MultiVhostCertByVhost_DeployIsolated_E2E`
|
||||
|
||||
When Apache has multiple `<VirtualHost>` blocks each with its own
|
||||
`SSLCertificateFile`, connector deploys to the matching vhost
|
||||
only. Other vhosts unchanged.
|
||||
|
||||
### `apachectl graceful-stop` drains cleanly
|
||||
|
||||
`TestVendorEdge_Apache_ApachectlGracefulStop_DrainsCleanly_E2E`
|
||||
|
||||
`apachectl graceful` (the connector default) preserves in-flight
|
||||
TLS connections. `apachectl restart` drops them.
|
||||
|
||||
### `mod_ssl` absent
|
||||
|
||||
`TestVendorEdge_Apache_ModSSLAbsent_DeployFailsWithActionableError_E2E`
|
||||
|
||||
If `mod_ssl` isn't loaded, `apachectl configtest` fails with
|
||||
"Invalid command 'SSLCertificateFile'". Connector surfaces this
|
||||
verbatim — operator action: `LoadModule ssl_module modules/mod_ssl.so`.
|
||||
|
||||
### `.htaccess` interactions
|
||||
|
||||
`TestVendorEdge_Apache_HtaccessRequireSSL_NotImpactedByDeploy_E2E`
|
||||
|
||||
`.htaccess` rules requiring SSL are not impacted by cert rotation.
|
||||
The `Require` directive evaluates per-request against the
|
||||
connection's TLS state, not the cert file.
|
||||
|
||||
### Apache 2.4 LTS reload semantics pinned
|
||||
|
||||
`TestVendorEdge_Apache_Apache24LTSReloadSemanticsPinned_E2E`
|
||||
|
||||
`apachectl graceful` semantics stable across 2.4.x patch versions.
|
||||
No per-version branch needed.
|
||||
|
||||
### Syntax error rollback
|
||||
|
||||
`TestVendorEdge_Apache_SyntaxErrorRollback_E2E`
|
||||
|
||||
`apachectl configtest` failure aborts before atomic rename. Live
|
||||
cert untouched.
|
||||
|
||||
### Per-vhost key ownership
|
||||
|
||||
`TestVendorEdge_Apache_PerVhostKeyOwnership_E2E`
|
||||
|
||||
When multiple vhosts share the same key file, ownership is
|
||||
preserved across rotation. When each vhost has its own key,
|
||||
per-file ownership is preserved per Bundle I Phase 5.
|
||||
|
||||
### Reload preserves connections
|
||||
|
||||
`TestVendorEdge_Apache_ReloadVsRestart_PreservesConnections_E2E`
|
||||
|
||||
In-flight TLS sessions survive `apachectl graceful` worker
|
||||
swap. Documented in `docs/deployment-atomicity.md`.
|
||||
|
||||
### SNI server_name binding
|
||||
|
||||
`TestVendorEdge_Apache_SNIServerNameDeployBindsCorrect_E2E`
|
||||
|
||||
When deploy specifies `server_name` metadata, connector targets
|
||||
the matching `<VirtualHost>` block.
|
||||
|
||||
### Cert chain ordering
|
||||
|
||||
`TestVendorEdge_Apache_ChainOrderingNormalized_E2E`
|
||||
|
||||
Apache requires leaf cert FIRST in `SSLCertificateFile` (or
|
||||
chain in `SSLCertificateChainFile`). Connector preserves operator-
|
||||
supplied ordering across rotation.
|
||||
|
||||
## V3-Pro deferrals
|
||||
|
||||
- Apache 2.6 (when it ships LTS).
|
||||
- mod_md (Apache's built-in ACME) interop.
|
||||
|
||||
## Related docs
|
||||
|
||||
- [Atomic deploy + post-verify + rollback](deployment-atomicity.md)
|
||||
- [Vendor compatibility matrix](deployment-vendor-matrix.md)
|
||||
Reference in New Issue
Block a user