feat(k3s): add cert-manager addon support

docs/k3s-role-map.md

@@ -35,7 +35,7 @@ Responsibilities:
   - connect the node to the GitOps repository
 - `k3s_platform_addon`
   - install platform-side shared components into Kubernetes
-  - examples: `external-secrets`, `reloader`, `caddy`, `apisix`, `external-dns`
+  - examples: `cert-manager`, `external-secrets`, `reloader`, `caddy`, `apisix`, `external-dns`
 - `GitOps`
   - own dynamic platform configuration
   - own workload manifests
@@ -205,10 +205,17 @@ When adding new capabilities:
 - host-level baseline belongs in `common`
 - k3s installation and Flux bootstrap belong in `k3s_platform_bootstrap`
 - platform shared addons belong in `k3s_platform_addon`
+  - TLS issuers and namespace-local certificate lifecycle should also live there
 - server and agent lifecycle actions belong in `k3s-cluster-server` or `k3s-cluster-agent`
 - dynamic service configuration belongs in GitOps
 - reset and cleanup behavior belongs in `k3s-reset`
 
+GitOps certificate rule of thumb:
+
+- use `cert-manager` to own the `Certificate` in the namespace that consumes it
+- avoid cross-namespace Secret sync jobs when the same certificate can be declared directly in each namespace
+- keep `external-secrets` for Vault-sourced app credentials, cloud API keys, and image pull secrets
+
 Do not add new functionality to:
 
 - `vhosts/k3s`

roles/vhosts/k3s_platform_addon/defaults/main.yml

@@ -5,6 +5,7 @@ k3s_platform_ghcr_token: "{{ lookup('env', 'GHCR_TOKEN') }}"
 # Default ACME email for Caddy; pipeline input.env can override via CADDY_ACME_EMAIL.
 k3s_platform_caddy_acme_email: "{{ lookup('env', 'CADDY_ACME_EMAIL') | default('manbuzhe2009@qq.com', true) }}"
 
+k3s_platform_cert_manager_chart_version: "v1.20.0"
 k3s_platform_external_secrets_chart_version: "0.20.4"
 k3s_platform_reloader_chart_version: "1.3.0"
 k3s_platform_caddy_chart_version: "1.2.0"
@@ -14,6 +15,9 @@ k3s_platform_external_dns_chart_repo_url: "https://kubernetes-sigs.github.io/ext
 
 k3s_platform_values:
   components:
+    certManager:
+      enabled: true
+      releaseName: cert-manager
     externalSecrets:
       enabled: true
     reloader:

roles/vhosts/k3s_platform_addon/tasks/main.yml

@@ -1,3 +1,42 @@
+- name: Install cert-manager directly with Helm
+  ansible.builtin.shell: |
+    set -euo pipefail
+    export KUBECONFIG="{{ k3s_platform_kubeconfig_path }}"
+    chart_dir="$(mktemp -d /tmp/cert-manager.XXXXXX)"
+    cleanup() {
+      rm -rf "$chart_dir"
+    }
+    trap cleanup EXIT
+
+    attempt=1
+    max_attempts=6
+    while true; do
+      rm -rf "$chart_dir"/*
+      if helm pull oci://quay.io/jetstack/charts/cert-manager \
+        --version "{{ k3s_platform_cert_manager_chart_version }}" \
+        --untar \
+        --untardir "$chart_dir"; then
+        break
+      fi
+      if [ "$attempt" -ge "$max_attempts" ]; then
+        echo "failed to download cert-manager after $attempt attempts" >&2
+        exit 1
+      fi
+      sleep "$((attempt * 30))"
+      attempt=$((attempt + 1))
+    done
+
+    helm upgrade --install "{{ k3s_platform_values.components.certManager.releaseName }}" "$chart_dir/cert-manager" \
+      --namespace cert-manager \
+      --create-namespace \
+      --set crds.enabled=true \
+      --wait \
+      --timeout 10m
+  args:
+    executable: /bin/bash
+  when:
+    - k3s_platform_values.components.certManager.enabled | default(true)
+
 - name: Install external-secrets directly with Helm
   ansible.builtin.shell: |
     set -euo pipefail