CR-2026-02-25 - Convert Hardcoded Values to AsciiDoc Attributes

Change Request Summary

Field Value

CR ID

CR-2026-02-25-001

Status

Approved

Priority

P2

Requester

evanusmodestus

Date

2026-02-25

Description

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

Current State: Runbooks contain literal IP addresses like 10.50.1.60 and hostnames like vault-01.inside.domusdigitalis.dev.

Target State: Runbooks use attributes like 10.50.1.60 and vault-01.inside.domusdigitalis.dev.inside.domusdigitalis.dev that resolve from antora.yml.

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

  4. Technical debt - Identified during Antora build warning cleanup session

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, changelog observations)

  • ip-addressing.adoc canonical reference (may be addressed separately)

Affected Files

Priority 1 (Security-Critical)

File Patterns Status

k3s-deployment.adoc

vault-ip, bind-ip, pfsense-ip

[ ]

vault-ssh-ca.adoc

vault-01-ip, domain

[ ]

vault-tls-external.adoc

vault-01-ip, domain

[ ]

vault-pki-cert-issuance.adoc

vault-01-ip, domain

[ ]

Priority 2 (Operational)

File Patterns Status

bind-dns-deployment.adoc

bind-ip, pfsense-ip, domain

[ ]

dns-operations.adoc

bind-ip, domain

[ ]

k3s-wazuh.adoc

wazuh-*-vip, domain

[ ]

k3s-prometheus-grafana.adoc

grafana-vip, prometheus-vip

[ ]

k3s-metallb.adoc

IP ranges

[ ]

k3s-operations.adoc

k3s-master-ip

[ ]

Priority 3 (Setup/Deployment)

File Patterns Status

ise-34-deployment.adoc

ise-01-ip, domain

[ ]

freeipa-deployment.adoc

ipa-ip, domain

[ ]

kvm-ha-shared-storage.adoc

nas-ip, kvm-ip

[ ]

kvm-network-discovery.adoc

Various IPs

[ ]

nas-share-management.adoc

nas-ip

[ ]

network-infrastructure-discovery.adoc

Various IPs

[ ]

server-rename-vault-01.adoc

vault-01-ip, domain

[ ]

terraform-iac.adoc

Various IPs

[ ]

diagram-validation.adoc

Various IPs

[ ]

documentation-hub-setup.adoc

Various IPs

[ ]

Implementation Plan

Phase 1: P1 Files (Security-Critical)

  1. Review each file for hardcoded values

  2. Verify attributes exist in antora.yml (add if missing)

  3. Convert prose text to use attributes

  4. Add subs=attributes+ to code blocks where needed

  5. Escape shell variables: ${VAR} → $\\{VAR\\}

  6. Run make to verify 0 warnings

  7. Commit with descriptive message

Phase 2: P2 Files (Operational)

Same process as Phase 1.

Phase 3: P3 Files (Setup/Deployment)

Same process as Phase 1.

Rollback Plan

Git revert if issues discovered:

git revert <commit-hash>

Testing

After each file conversion:

cd /home/evanusmodestus/atelier/_bibliotheca/domus-infra-ops
make 2>&1 | grep -c '"level":"warn"'
# Expected: 0

Conversion Rules

Convert to Attributes

  • Prose text: The server at 10.50.1.60 → The server at 10.50.1.60

  • Inline code: \`vault-01.inside.domusdigitalis.dev` → \vault-01.inside.domusdigitalis.dev\``

  • Code commands: Add subs=attributes+ and use attributes

Leave as Literal

  • Example output blocks

  • Historical evidence in RCAs

  • Error messages showing actual values

Escape Shell Variables

# In code blocks with subs=attributes+
${HOSTNAME}  →  $\{HOSTNAME\}
${USER}      →  $\{USER\}
%{http_code} →  %\{http_code\}

Approval

Role Name Date

Requester

evanusmodestus

2026-02-25

Approver

evanusmodestus

2026-02-25

Related