CR-2026-02-25: AsciiDoc Attribute Refactor

Change Summary

CR ID

CR-2026-02-25-001

Date

2026-02-25

Priority

P2

Type

Documentation Refactor

Status

Approved

Objective

Convert hardcoded mutable values (IP addresses, hostnames, domain names) to AsciiDoc attributes in 20 runbook files within domus-infra-ops.

Justification

  1. Maintainability - Single source of truth for infrastructure values

  2. Consistency - Aligns with AsciiDoc standards documented in CLAUDE.md

  3. Accuracy - Prevents drift between docs and reality when IPs change

Current vs Target State

Type Current (Hardcoded) Target (Attribute)

IP Address

10.50.1.60

{vault-01-ip}

Hostname

vault-01.inside.domusdigitalis.dev

{vault-01-hostname}.inside.domusdigitalis.dev

Code Block

[source,bash]

[source,bash,subs=attributes+]

Scope

In Scope

  • 20 runbook files in pages/runbooks/

  • Prose text containing hardcoded IPs/hostnames

  • Code blocks with subs=attributes+ where attributes should resolve

Out of Scope

  • Example output blocks (literal values show what users will see)

  • Historical documentation (RCA evidence)

Affected Files

Priority 1 (Security-Critical)

  • k3s-deployment.adoc

  • vault-ssh-ca.adoc

  • vault-tls-external.adoc

  • vault-pki-cert-issuance.adoc

Priority 2 (Operational)

  • bind-dns-deployment.adoc

  • dns-operations.adoc

  • k3s-wazuh.adoc

  • k3s-prometheus-grafana.adoc

Priority 3 (Setup/Deployment)

  • ise-34-deployment.adoc

  • freeipa-deployment.adoc

  • kvm-ha-shared-storage.adoc

  • nas-share-management.adoc