diff --git a/docs/skills/homelab-profile.md b/docs/skills/homelab-profile.md index 4d456574..ebabc806 100644 --- a/docs/skills/homelab-profile.md +++ b/docs/skills/homelab-profile.md @@ -104,11 +104,12 @@ port 443 of its MetalLB address, see "TLS" below) by host name under (`sectionName: https`), so a bearer token, the Console's login password and its session cookie never cross the LAN in cleartext; on port 80 the add-on names answer with a 301 to `https://` (`40-envoy-gateway/21-http-redirect.yaml`). -The certificate (`homelab-tls` in `envoy-gateway-system`, for `argo.`, `mcp.` -and `kubestellar.`) comes from the `homelab-ca` ClusterIssuer: a -self-signed CA that cert-manager creates once (ten years) and keeps in -`cert-manager/homelab-ca`; the leaf renews by itself and Envoy picks it up. -Browsers warn until you trust that CA, once per device: +By default the certificate (`homelab-tls` in `envoy-gateway-system`, for +`argo.`, `mcp.` and `kubestellar.`) comes from the `homelab-ca` +ClusterIssuer: a self-signed CA that cert-manager creates once (ten years) +and keeps in `cert-manager/homelab-ca`; the leaf renews by itself and Envoy +picks it up. To sign it with a ClusterIssuer of your own, set +`HOMELAB_GATEWAY_ISSUER` (below). Trust that CA once per device: ```bash kubectl -n cert-manager get secret homelab-ca -o jsonpath='{.data.ca\.crt}' | base64 -d > homelab-ca.crt @@ -120,10 +121,14 @@ the add-on routes send `Strict-Transport-Security: max-age=31536000` (deliberately without `includeSubDomains`, which would pin every device under the domain), and once a browser has that header it turns a certificate warning for these names into a hard error with no -click-through. The Gateway does not use the `acme` ClusterIssuer: -HTTP-01 needs every name reachable from the internet, which a LAN domain -such as `home.arpa` never is, and a certificate that cannot be issued would -leave the add-ons unreachable. `HOMELAB_CERT_MANAGER=no` does the same: +click-through. `HOMELAB_GATEWAY_ISSUER` must name a ClusterIssuer (the +`kind` is fixed) that can validate the add-on names — for LAN-only names +that means DNS-01. That is why the Gateway does not use the bundled `acme` +ClusterIssuer by default: its HTTP-01 needs every name reachable from the +internet, which a LAN domain such as `home.arpa` never is, and a certificate +that cannot be issued would leave the add-ons unreachable. While issuance +from the named issuer is pending (or failing), the certificate already in +`homelab-tls` keeps being served. `HOMELAB_CERT_MANAGER=no` does the same: the `https` listener has no certificate, and the applier warns for every add-on it applies behind it. diff --git a/files/homelab/manifests/45-cert-manager/23-gateway-cert.yaml b/files/homelab/manifests/45-cert-manager/23-gateway-cert.yaml index d14c41ee..19e827b7 100644 --- a/files/homelab/manifests/45-cert-manager/23-gateway-cert.yaml +++ b/files/homelab/manifests/45-cert-manager/23-gateway-cert.yaml @@ -1,6 +1,7 @@ # The homelab Gateway's certificate for the add-on host names, from the -# homelab CA, in the Secret homelab-tls its https listener reads. Keep the -# names in step with the add-on HTTPRoutes. +# HOMELAB_GATEWAY_ISSUER ClusterIssuer (default: homelab-ca), in the Secret +# homelab-tls its https listener reads. Keep the names in step with the +# add-on HTTPRoutes. apiVersion: cert-manager.io/v1 kind: Certificate metadata: @@ -13,5 +14,5 @@ spec: - "mcp.${HOMELAB_DOMAIN}" - "kubestellar.${HOMELAB_DOMAIN}" issuerRef: - name: homelab-ca + name: "${HOMELAB_GATEWAY_ISSUER}" kind: ClusterIssuer diff --git a/files/homelab/sysext/bluefin-homelab-apply b/files/homelab/sysext/bluefin-homelab-apply index b13d48df..a491c9b1 100755 --- a/files/homelab/sysext/bluefin-homelab-apply +++ b/files/homelab/sysext/bluefin-homelab-apply @@ -46,6 +46,9 @@ declare -A PATTERN=( [METALLB_ADDRESSES]='^[0-9A-Fa-f.:/, -]+$' [ACME_EMAIL]='^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+$' [ACME_SERVER]='^https://[A-Za-z0-9./_-]+$' + # The Gateway certificate's issuer: an RFC 1123 subdomain (a + # ClusterIssuer name, lowercase). + [GATEWAY_ISSUER]='^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$' [ARGOCD_ROOT_REPO]='^(https://|http://|ssh://|git@)[A-Za-z0-9._~:/@+-]+$' [ARGOCD_ROOT_REVISION]='^[A-Za-z0-9._/-]+$' [ARGOCD_ROOT_PATH]='^[A-Za-z0-9._/-]+$' @@ -64,6 +67,7 @@ declare -A PATTERN=( ) declare -A DEFAULT=( [ACME_SERVER]=https://acme-v02.api.letsencrypt.org/directory + [GATEWAY_ISSUER]=homelab-ca [ARGOCD_ROOT_REVISION]=HEAD [ARGOCD_ROOT_PATH]=. [KURED_TIME_ZONE]=UTC diff --git a/files/homelab/sysext/homelab.conf.example b/files/homelab/sysext/homelab.conf.example index 5dab43e4..61382d62 100644 --- a/files/homelab/sysext/homelab.conf.example +++ b/files/homelab/sysext/homelab.conf.example @@ -39,6 +39,11 @@ # there. #HOMELAB_ACME_EMAIL=you@example.com #HOMELAB_ACME_SERVER=https://acme-staging-v02.api.letsencrypt.org/directory +# The ClusterIssuer that signs the Gateway's certificate (default +# homelab-ca). It must be able to validate the add-on names, which for +# LAN-only names means DNS-01; the bundled "acme" issuer is HTTP-01-only +# (homelab-profile.md, TLS). +#HOMELAB_GATEWAY_ISSUER=homelab-ca # Argo CD: an app-of-apps root Application "homelab-root". #HOMELAB_ARGOCD_ROOT_REPO=https://example.com/you/homelab.git diff --git a/tests/unit/bluefin-homelab-apply_test.bats b/tests/unit/bluefin-homelab-apply_test.bats index a3b85836..d5bf7723 100644 --- a/tests/unit/bluefin-homelab-apply_test.bats +++ b/tests/unit/bluefin-homelab-apply_test.bats @@ -215,6 +215,29 @@ EOF ! ls "${APPLIED}"/*-23-gateway-cert.yaml } +@test "the Gateway certificate issuer defaults to homelab-ca and accepts a dotted name" { + kubeadm_node + run_applier + [ "$status" -eq 0 ] + grep -q 'name: "homelab-ca"' "${APPLIED}"/*-23-gateway-cert.yaml + rm -f "${APPLIED}"/* + run_applier HOMELAB_GATEWAY_ISSUER=letsencrypt.example.com + [ "$status" -eq 0 ] + grep -q 'name: "letsencrypt.example.com"' "${APPLIED}"/*-23-gateway-cert.yaml +} + +@test "an invalid Gateway certificate issuer warns and skips the certificate" { + kubeadm_node + for issuer in Bad_Name a..b -x; do + rm -f "${APPLIED}"/* + run_applier HOMELAB_GATEWAY_ISSUER="${issuer}" + [ "$status" -eq 0 ] + [[ "$output" == *"ignoring HOMELAB_GATEWAY_ISSUER=${issuer}: does not match"* ]] + [[ "$output" == *"cert-manager: skipping 23-gateway-cert.yaml: HOMELAB_GATEWAY_ISSUER not set in /etc/bluefin/homelab.conf"* ]] + ! ls "${APPLIED}"/*-23-gateway-cert.yaml + done +} + @test "configured inputs are validated and substituted" { kubeadm_node run_applier HOMELAB_METALLB_ADDRESSES="192.0.2.240-192.0.2.250, 198.51.100.0/28" \ diff --git a/tests/unit/test_homelab_addons.py b/tests/unit/test_homelab_addons.py index 5a0d9c2b..e86f01da 100644 --- a/tests/unit/test_homelab_addons.py +++ b/tests/unit/test_homelab_addons.py @@ -153,6 +153,16 @@ def test_placeholders_are_applier_inputs_and_stay_strings() -> None: assert re.search(r"\[DOMAIN\]=home\.arpa", APPLIER.read_text()), "RFC 8375's home network domain" +def test_component_placeholders_are_applier_inputs() -> None: + # The addons net above, for the components' own manifests: a placeholder + # the applier cannot fill leaves the literal text behind, so the file is + # skipped, on every run. + used = set() + for path in (HOMELAB / "manifests").rglob("*.yaml"): + used |= set(re.findall(r"\$\{HOMELAB_([A-Z0-9_]+)\}", path.read_text())) + assert used <= applier_inputs() + + HSTS = [ {"type": "ResponseHeaderModifier", "responseHeaderModifier": {"set": [ @@ -200,6 +210,19 @@ def test_each_ui_is_routed_through_the_homelab_gateway(directory, namespace, hos assert any(d["kind"] == "Gateway" and d["metadata"]["name"] == "homelab" for d in docs(gateway)) +def test_the_gateway_certificate_issuer_is_configurable() -> None: + # HOMELAB_GATEWAY_ISSUER (default homelab-ca, set by the applier) picks + # the issuer; the kind is fixed, so the value must name a ClusterIssuer. + [certificate] = [d for d in docs(HOMELAB / "manifests" / "45-cert-manager" / "23-gateway-cert.yaml") + if d["kind"] == "Certificate"] + assert certificate["spec"]["secretName"] == "homelab-tls" + assert certificate["spec"]["issuerRef"] == {"name": "${HOMELAB_GATEWAY_ISSUER}", "kind": "ClusterIssuer"} + # Configurable, not just spelled: the applier must know the input, and + # unset it renders homelab-ca, as before the key existed. + assert "GATEWAY_ISSUER" in applier_inputs() + assert re.search(r"\[GATEWAY_ISSUER\]=homelab-ca", APPLIER.read_text()) + + def container(directory: str, kind: str, name: str) -> dict: return find(directory, kind, name)["spec"]["template"]["spec"]["containers"][0]