Skip to content
fzymgc-house Cluster Docs

Mosquitto PR 798 Followups Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Address review findings for PR 798 by documenting the Mosquitto service and ensuring TLS certificates cover external access.

Architecture: Keep Mosquitto deployed via Kustomize in argocd/app-configs/mosquitto. Update documentation for service and secrets. Adjust TLS certificate SANs to include external DNS names used by clients (or switch to internal-only access if external DNS is not used).

Tech Stack: ArgoCD, Kustomize, cert-manager, ExternalSecrets, Vault, Kubernetes Service/Certificate resources.

Task 1: Document Mosquitto service and Vault secret

Section titled “Task 1: Document Mosquitto service and Vault secret”

Files:

  • Modify: docs/reference/services.md
  • Modify: docs/reference/secrets.md

Step 1: Read existing docs for structure

Read:

  • docs/reference/services.md
  • docs/reference/secrets.md

Step 2: Add Mosquitto service entry

Update docs/reference/services.md to include Mosquitto with:

  • Purpose: MQTT broker for IoT/Home Assistant
  • Namespace: mosquitto
  • External access: TLS on 8883 (MQTTS)

Step 3: Add Vault secret entry

Update docs/reference/secrets.md to include:

  • Path: fzymgc-house/cluster/mosquitto
  • Key: passwd
  • Note: content must be pre-hashed mosquitto_passwd file content

Step 4: Validate formatting

Run:

Terminal window
rg "mosquitto" docs/reference/services.md docs/reference/secrets.md

Expected: New entries present.

Step 5: Commit

Terminal window
git add docs/reference/services.md docs/reference/secrets.md
git commit -m "docs(mosquitto): document service and Vault secret"

Task 2: Fix Mosquitto TLS SANs for external access

Section titled “Task 2: Fix Mosquitto TLS SANs for external access”

Files:

  • Modify: argocd/app-configs/mosquitto/certificate.yaml
  • Modify (if needed): argocd/app-configs/mosquitto/service.yaml

Step 1: Identify external DNS pattern

Search for existing service DNS patterns or certs:

Terminal window
rg "external-dns|dnsNames|commonName" argocd/app-configs

Identify the external DNS name(s) used for LoadBalancer services (e.g., *.fzymgc.house).

Step 2: Update Certificate SANs

Update certificate.yaml to include the external DNS name(s) in dnsNames for the Mosquitto service.

If no external DNS name exists or service should be internal only, switch the Service to internal-only access and keep SANs cluster-local. Document the decision in docs/reference/services.md.

Step 3: Validate Kustomize output

Run:

Terminal window
kubectl --context fzymgc-house apply --dry-run=client -k argocd/app-configs/mosquitto

Expected: Dry-run succeeds.

Step 4: Commit

Terminal window
git add argocd/app-configs/mosquitto/certificate.yaml argocd/app-configs/mosquitto/service.yaml
git commit -m "fix(mosquitto): align TLS SANs with external access"

Task 3: Final validation

Section titled “Task 3: Final validation”

Step 1: Check git status

Terminal window
git status -sb

Step 2: Push branch

Terminal window
git push

Step 3: Update PR summary if needed

  • Add a brief PR comment if external DNS name changed.