Skip to content

Authoring Contract

All operational procedures in this site must follow the same runbook contract.

This page defines how execution content becomes an approved standard in this repository.

Required sections

  1. Task ID and Title
  2. Objective
  3. Inputs
  4. Target State
  5. Prechecks
  6. Current State Verification
  7. Execution
  8. Validation
  9. Evidence
  10. Rollback

Writing rules

  • Use imperative steps.
  • Keep values authoritative and explicit.
  • Use placeholders only where customer variation is expected.
  • Avoid undocumented assumptions.
  • Prefer tables for target state, IP plans, and VM specs.
  • Include exact commands where feasible.
  • Include expected outcomes for every critical command or action.
  • For any runbook that changes infrastructure state, verify the live state first at every relevant layer before executing changes.
  • In Proxmox-backed runbooks, verify both the hypervisor-side state and the in-guest state before taking action.
  • If verification proves the prerequisite state is missing, the runbook must stop or branch explicitly instead of continuing optimistically.
  • The lab is the source of truth. Validate the procedure successfully in the lab first, then document the exact working process.
  • Do not publish a runbook as a standard based on theory alone. The documented workflow must reflect a proven implementation path.
  • Prefer PowerShell for Windows-side automation so the same operational logic can be reused across Proxmox, Hyper-V, VMware, and similar platforms.
  • Prefer Windows Server Core for Windows infrastructure roles whenever the workload and support model allow it.
  • If a runbook uses Desktop Experience for a server role, document the reason explicitly instead of assuming GUI-based servers by default.
  • When a runbook automates Windows configuration, document the actual PowerShell script in the runbook, not just an ad hoc one-off command sequence.
  • Treat the execution transport and the automation logic as separate concerns:
  • the automation logic should live in reusable PowerShell
  • the transport may be QGA, console, WinRM, Hyper-V PowerShell Direct, VMware guest operations, or another platform-specific method
  • If a runbook uses QGA in the lab, state clearly that QGA is the validated transport for the pilot and not a permanent requirement of the automation design.
  • Scripts copied from the documentation must be adjustable by an administrator for a real customer deployment without rewriting the core logic from scratch.
  • Prefer parameterized or clearly editable variables at the top of each script so customer adaptation is controlled and predictable.
  • Avoid embedding platform-specific orchestration logic into the Windows configuration script unless that dependency is genuinely required.

Automation stance

The project standard is:

  • Lab first
  • PowerShell-first for Windows configuration logic
  • transport-specific execution documented separately
  • pilot execution can use QEMU Guest Agent
  • production execution may use any supported transport on the target platform
  • daily Windows server administration should be performed from a dedicated management workstation, not by depending on local GUI access on each server

Examples:

  • In the pilot lab, an OU deployment script may be executed through QGA on Proxmox.
  • In a customer deployment, that same script may be executed through a console session, WinRM, Hyper-V, or VMware guest tooling after the administrator adjusts the customer-specific variables.

This keeps the documentation portable while still allowing the lab to be fully validated on the current platform.

Standards versus runbooks

Keep this distinction explicit:

  • Standards define approved design decisions, naming, structure, and publication rules.
  • Runbooks define executable procedures that change or validate live infrastructure.

Examples of content that belongs in Standards:

  • identity naming rules
  • OU structure design
  • placeholder conventions
  • validation contract

Examples of content that belongs in Runbooks:

  • deploy HQ-CHR01
  • build a golden image
  • promote HQ-DC01
  • join a workstation to the domain

Do not put a design-only topic into Runbooks just to force a phase number onto it.

Publication sequence

Every operational standard in this repository should follow this order:

  1. validate in the lab
  2. correct the implementation until it is repeatable
  3. capture the exact working PowerShell logic
  4. document the validated execution path
  5. run documentation validation checks
  6. commit and push

This prevents the site from drifting into aspirational documentation that has not yet been proven in the real lab.

Runbook skeleton

# PXX-TYY - Task Name

## Objective

State the outcome in operational terms.

## Inputs

| Key | Value |
| --- | --- |
| CLIENT_CODE | `CLIENT_CODE` |

## Target State

| Property | Value |
| --- | --- |
| Example | Example |

## Prechecks

- Confirm prerequisite system state.

## Current State Verification

- Inspect the live state before making changes.

## Execution

1. Perform the task in a reproducible order.

## Validation

- State pass/fail checks.

## Evidence

- Record expected outputs and screenshots if required.

## Rollback

- Explain how to return to the last safe state.