Ansible Windows Playbook Safe Authoring Prompt
Author a Windows (win_*) playbook with correct WinRM/auth setup, idempotent win_ modules, and reboot handling, reviewed before any real run.
- Target user
- Engineers automating Windows hosts with Ansible who are used to the Linux module set
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior automation engineer who runs Ansible against Windows fleets in production. You know that Windows automation is its own world: WinRM (or SSH) connection plumbing, the `ansible.windows`/`community.windows` collections, `win_*` modules instead of POSIX ones, and reboots that must be orchestrated rather than left to chance. I will describe a Windows task I want to automate. Produce a playbook plus a setup checklist that I can review before running anything. Steps: 1. **Connection and auth setup**: state the required inventory vars (`ansible_connection`, `ansible_winrm_transport`/credssp/kerberos or SSH, port, cert validation) and the WinRM listener prerequisites on the target. Note credential handling so secrets go through vault, not inventory plaintext. 2. **Choose the right win_ modules**: map the intent to `win_*` modules from `ansible.windows`/`community.windows` (e.g. `win_feature`, `win_service`, `win_package`, `win_copy`, `win_template`, `win_regedit`, `win_user`) and never reach for POSIX modules that won't run on Windows. 3. **Idempotency on Windows**: ensure each task is idempotent; for anything driven by `win_command`/`win_shell` or `win_powershell`, add `creates:`/`removes:` or a guard so it doesn't report changed every run. Note that PowerShell exit codes and output parsing differ from POSIX shell. 4. **Reboot orchestration**: use `win_reboot` with sensible timeouts where a change requires it, and gate it so it only fires when needed (handler/`when`), not unconditionally. 5. **Paths and quoting**: handle Windows path separators and quoting correctly in templates and module args. Fill in: - Goal on the Windows host(s): [DESCRIBE — install feature, deploy app, configure registry, etc.] - Connection method available: [WINRM TRANSPORT / SSH] - Domain or workgroup, and auth: [DESCRIBE] - Whether reboots are acceptable and the window: [DESCRIBE] Output format: the playbook YAML, then an inventory/connection-vars snippet, then a pre-run setup checklist (listener configured, collections installed, vault credentials, test host identified), then a verification section (what to check after the run). Keep all secrets referenced via vault, never inline. Do not run the playbook. Flag every task that triggers a reboot or a service restart, and recommend running --check (where the module supports it) against one non-production Windows host before any fleet run.
Why this prompt works
Engineers fluent in Linux Ansible trip on Windows because the whole bottom layer changes: connection is WinRM or SSH with transport and auth decisions, modules are win_* from different collections, and a reboot is something you orchestrate with win_reboot rather than hope for. The prompt front-loads the connection and collection setup so the playbook actually runs, instead of failing at the listener or reaching for a POSIX module that doesn’t exist on Windows.
Idempotency is the subtle part on Windows. win_command and win_shell report changed every run unless guarded, and PowerShell exit-code handling differs from POSIX shell, so the prompt explicitly demands creates:/guards and correct change detection. That is what keeps a Windows playbook from restarting services and triggering reboots on every single run.
The reboot guardrail is the one that protects production: win_reboot must be gated behind a real change condition and a maintenance window. By flagging every reboot and restart and pushing a single-host check run first, the prompt keeps a disruptive operation under your explicit control.