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

Conversion Rules

Convert to Attributes

// Prose text
The server at 10.50.1.60
→ The server at \{vault-01-ip}

// Inline code
`vault-01.inside.domusdigitalis.dev`
→ `\{vault-01-hostname}`

// Code blocks - add subs=attributes+
[source,bash,subs=attributes+]

Escape Shell Variables

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

CLI Mastery: Attribute Verification

Find All Attributes in antora.yml

grep -E "^\s+[a-z]+-[a-z]+:" docs/asciidoc/antora.yml | head -50

Verify Attribute Exists Before Using

grep -i "vault" docs/asciidoc/antora.yml

Find Undefined Attributes in Document

grep -oE '\{[a-z0-9-]+\}' document.adoc | \
  tr -d '{}' | sort -u | while read attr; do
    grep -q "^\s*${attr}:" docs/asciidoc/antora.yml && \
      echo "✓ $attr" || echo "✗ $attr MISSING"
  done

Build and Check for Warnings

make 2>&1 | grep -c "missing attribute"
# Expected: 0

Key Lessons

Topic Lesson

Never hardcode IPs in prose

Use {attribute} references exclusively

Code blocks need subs=attributes+

Without this, {attr} renders literally

Shell variables need escaping

${VAR} to prevent Antora expansion

Build before commit

make catches attribute warnings early

Related Documentation