Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 14 additions & 9 deletions docs/skills/homelab-profile.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.<domain>`) 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.<domain>`) 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
Expand All @@ -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.

Expand Down
7 changes: 4 additions & 3 deletions files/homelab/manifests/45-cert-manager/23-gateway-cert.yaml
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -13,5 +14,5 @@ spec:
- "mcp.${HOMELAB_DOMAIN}"
- "kubestellar.${HOMELAB_DOMAIN}"
issuerRef:
name: homelab-ca
name: "${HOMELAB_GATEWAY_ISSUER}"
kind: ClusterIssuer
4 changes: 4 additions & 0 deletions files/homelab/sysext/bluefin-homelab-apply
Original file line number Diff line number Diff line change
Expand Up @@ -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._/-]+$'
Expand All @@ -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
Expand Down
5 changes: 5 additions & 0 deletions files/homelab/sysext/homelab.conf.example
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
23 changes: 23 additions & 0 deletions tests/unit/bluefin-homelab-apply_test.bats
Original file line number Diff line number Diff line change
Expand Up @@ -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" \
Expand Down
23 changes: 23 additions & 0 deletions tests/unit/test_homelab_addons.py
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down Expand Up @@ -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]

Expand Down
Loading