Skip to content

ADR-0016: k3s namespace design — domain-based pattern over environment-based

Status

Accepted — 2026-04-03

Context

The k3s cluster is running with caneast-c1-node3 as control-plane and caneast-c1-node2 as worker node. Workloads span infrastructure tooling, monitoring, application services, OT-facing pipelines, and security. A namespace strategy is needed before deploying workloads.

Two patterns were evaluated: - Pattern A — environment-based: dev, staging, prod namespaces. Each environment contains all workloads. - Pattern B — domain/team-based: namespaces map to functional domains. Each namespace owns a category of workloads.

Decision

Pattern B — domain/team-based namespaces.

Namespace map

Namespace Purpose Example workloads
archon-infra Core platform tools AWX, Infisical agents, ArgoCD
archon-monitoring Observability stack Grafana, InfluxDB, Telegraf, Prometheus
archon-apps Application workloads Node-RED, peries.ca, Homepage
archon-ot OT-facing services MQTT bridge, OT data processors
archon-security Security tooling CrowdSec, Suricata, Falco, Conpot

Rationale

  • Maps directly to the IT/OT separation story established in ADR-0005 — OT workloads are isolated in archon-ot, security tooling in archon-security
  • Mirrors enterprise domain ownership model — each namespace has a clear owner and purpose, even in a single-operator platform
  • Supports per-namespace RBAC — when AWX (Phase 3) manages deployments, service accounts can be scoped to their domain namespace only
  • Enables per-namespace NetworkPolicies — archon-ot can restrict egress to MQTT broker and InfluxDB only, archon-security can access all namespaces for monitoring
  • Aligns with ArgoCD ApplicationSets — one Application per namespace, clean GitOps sync boundaries

Alternatives considered

Pattern A — environment-based (dev, staging, prod)

Rejected. Archon is a single-environment homelab — there is no staging or prod distinction at this scale. Creating dev/staging/prod namespaces would result in workloads only ever running in prod, with the other namespaces empty. Environment separation is better handled at the ADO pipeline level (environment gates) than at the namespace level.

Flat default namespace

Rejected. All workloads in default provides zero isolation, no RBAC granularity, and no NetworkPolicy boundaries. Impossible to reason about blast radius of a misconfigured deployment.

Exceptions

AWX Operator — awx namespace

The AWX Operator upstream (github.com/ansible/awx-operator/config/default) hardcodes the awx namespace in its kustomization manifests. Deploying to archon-infra was attempted but produced namespace mismatch errors on serviceaccount, role, rolebinding, configmap, service, and deployment resources — the operator's own RBAC and resource references assume awx and cannot be overridden cleanly via a downstream kustomization namespace field.

Decision: accept awx as a fixed upstream constraint, not a local naming choice. AWX deploys to the awx namespace. All other workloads follow the archon-* domain-based pattern.

Reference: https://github.com/ansible/awx-operator/issues/2002

Consequences

  • All k3s workloads must declare namespace explicitly in their manifests — no implicit default
  • No deployments to the default namespace — it remains empty
  • Helm charts and ArgoCD Applications must target a specific archon-* namespace
  • Namespace creation managed via k3s manifests in archon-platform/k3s/namespaces/
  • Future multi-environment support (if needed) would layer environment labels on resources within domain namespaces, not create parallel namespace trees

References

  • ADR-0005: IT/OT separation scope