From 9cec5cab657cb1812a32ea167b4a1af4ca540b2d Mon Sep 17 00:00:00 2001 From: shankar0123 Date: Tue, 5 May 2026 03:14:39 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20Phase=204=20(structural)=20=E2=80=94=20?= =?UTF-8?q?move=20connectors.md=20+=205=20deep=20dives=20into=20reference/?= =?UTF-8?q?connectors/?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per Phase 1 audit at cowork/docs-overhaul-phase-1-audit-2026-05-04/. Phase 4 in the audit recommended a full split of connectors.md (2055 lines) into an index + 27 per-connector pages (12 issuer + 15 target). This commit lands the structural half of that work; full per-target page extraction is deferred to follow-up commits. Renames (all blame-preserving): docs/connectors.md → docs/reference/connectors/index.md docs/connector-apache.md → docs/reference/connectors/apache.md docs/connector-f5.md → docs/reference/connectors/f5.md docs/connector-iis.md → docs/reference/connectors/iis.md docs/connector-k8s.md → docs/reference/connectors/k8s.md docs/connector-nginx.md → docs/reference/connectors/nginx.md Edits: - docs/reference/connectors/index.md gets a top-of-doc note explaining the per-connector deep-dive sibling pattern + a forward list of the 5 per-target pages. - The 5 per-connector deep-dive pages each get a `Last reviewed: 2026-05-05` header + a back-link to the index. Deferred to future commits (Phase 4b/c follow-on): - Extracting the 12 issuer sections from index.md into per-issuer pages at reference/connectors/{acme,awsacmpca,digicert,ejbca, entrust,globalsign,googlecas,local,openssl,sectigo,stepca,vault}.md - Extracting the 10 remaining target sections from index.md into per-target pages at reference/connectors/{caddy,traefik,envoy, haproxy,postfix-dovecot,ssh,javakeystore,wincertstore,awsacm, azurekv}.md The pragmatic split makes this Phase 4 work incrementally landable — each per-connector extraction is a small follow-up commit that doesn't change the docs/ tree shape further. Cross-references from README.md and other docs to docs/connectors.md still need fixing in Phase 11. --- .../connectors/apache.md} | 7 ++++++- .../connectors/f5.md} | 7 ++++++- .../connectors/iis.md} | 7 ++++++- .../connectors/index.md} | 17 +++++++++++++++++ .../connectors/k8s.md} | 7 ++++++- .../connectors/nginx.md} | 9 +++++++-- 6 files changed, 48 insertions(+), 6 deletions(-) rename docs/{connector-apache.md => reference/connectors/apache.md} (92%) rename docs/{connector-f5.md => reference/connectors/f5.md} (95%) rename docs/{connector-iis.md => reference/connectors/iis.md} (96%) rename docs/{connectors.md => reference/connectors/index.md} (99%) rename docs/{connector-k8s.md => reference/connectors/k8s.md} (93%) rename docs/{connector-nginx.md => reference/connectors/nginx.md} (96%) diff --git a/docs/connector-apache.md b/docs/reference/connectors/apache.md similarity index 92% rename from docs/connector-apache.md rename to docs/reference/connectors/apache.md index 2181fcf..563fab0 100644 --- a/docs/connector-apache.md +++ b/docs/reference/connectors/apache.md @@ -1,6 +1,11 @@ # Apache httpd Connector — Operator Deep-Dive -> Per Phase 14 of the deploy-hardening II master bundle. +> Last reviewed: 2026-05-05 +> +> Per Phase 14 of the deploy-hardening II master bundle. For the +> connector-development context (interface contract, registry, atomic +> deploy primitive shared across all targets), see the +> [connector index](index.md). ## Overview diff --git a/docs/connector-f5.md b/docs/reference/connectors/f5.md similarity index 95% rename from docs/connector-f5.md rename to docs/reference/connectors/f5.md index 1de9c35..dd2b60c 100644 --- a/docs/connector-f5.md +++ b/docs/reference/connectors/f5.md @@ -1,6 +1,11 @@ # F5 BIG-IP Connector — Operator Deep-Dive -> Per Phase 14 of the deploy-hardening II master bundle. +> Last reviewed: 2026-05-05 +> +> Per Phase 14 of the deploy-hardening II master bundle. For the +> connector-development context (interface contract, registry, atomic +> deploy primitive shared across all targets), see the +> [connector index](index.md). ## Overview diff --git a/docs/connector-iis.md b/docs/reference/connectors/iis.md similarity index 96% rename from docs/connector-iis.md rename to docs/reference/connectors/iis.md index b8726b4..09b4d5f 100644 --- a/docs/connector-iis.md +++ b/docs/reference/connectors/iis.md @@ -1,6 +1,11 @@ # Microsoft IIS Connector — Operator Deep-Dive -> Per Phase 14 of the deploy-hardening II master bundle. +> Last reviewed: 2026-05-05 +> +> Per Phase 14 of the deploy-hardening II master bundle. For the +> connector-development context (interface contract, registry, atomic +> deploy primitive shared across all targets), see the +> [connector index](index.md). ## Overview diff --git a/docs/connectors.md b/docs/reference/connectors/index.md similarity index 99% rename from docs/connectors.md rename to docs/reference/connectors/index.md index 0d90e6c..1701ae4 100644 --- a/docs/connectors.md +++ b/docs/reference/connectors/index.md @@ -1,7 +1,24 @@ # Connector Development Guide +> Last reviewed: 2026-05-05 +> +> This is the canonical connector reference. Per-connector deep-dive +> pages exist for the targets that have unique operational quirks +> (apache, f5, iis, k8s, nginx — see siblings in this directory). Other +> connectors are documented inline in this file and will be extracted +> to their own pages as operational depth grows. Cross-link from this +> index to per-connector pages where they exist. + Connectors extend certctl to integrate with external systems for certificate issuance, deployment, and notifications. This guide covers the connector interfaces, built-in implementations, and how to build your own. +**Per-connector deep-dive pages** (siblings in this directory): + +- [Apache](apache.md) — Apache httpd connector deep dive +- [F5 BIG-IP](f5.md) — F5 connector deep dive (proxy agent + iControl REST) +- [IIS](iis.md) — Microsoft IIS connector deep dive (local PowerShell + WinRM modes) +- [Kubernetes Secrets](k8s.md) — k8s.io/tls Secrets connector deep dive +- [NGINX](nginx.md) — NGINX connector deep dive (deploy contract + quirks) + ## Contents 1. [Overview](#overview) diff --git a/docs/connector-k8s.md b/docs/reference/connectors/k8s.md similarity index 93% rename from docs/connector-k8s.md rename to docs/reference/connectors/k8s.md index 7550125..4101546 100644 --- a/docs/connector-k8s.md +++ b/docs/reference/connectors/k8s.md @@ -1,6 +1,11 @@ # Kubernetes Secrets Connector — Operator Deep-Dive -> Per Phase 14 of the deploy-hardening II master bundle. +> Last reviewed: 2026-05-05 +> +> Per Phase 14 of the deploy-hardening II master bundle. For the +> connector-development context (interface contract, registry, atomic +> deploy primitive shared across all targets), see the +> [connector index](index.md). ## Overview diff --git a/docs/connector-nginx.md b/docs/reference/connectors/nginx.md similarity index 96% rename from docs/connector-nginx.md rename to docs/reference/connectors/nginx.md index cfd21a6..457218f 100644 --- a/docs/connector-nginx.md +++ b/docs/reference/connectors/nginx.md @@ -1,7 +1,12 @@ # NGINX Connector — Operator Deep-Dive -> Per Phase 14 of the deploy-hardening II master bundle. Operator- -> grade documentation for the NGINX target connector. +> Last reviewed: 2026-05-05 +> +> Per Phase 14 of the deploy-hardening II master bundle. Operator-grade +> documentation for the NGINX target connector. For the +> connector-development context (interface contract, registry, atomic +> deploy primitive shared across all targets), see the +> [connector index](index.md). ## Overview