Bootstrap a Windows Node with Chef over WinRM (Knife Windows Guide)

Bootstrapping a Windows node with Chef over WinRM installs Chef Infra Client on the target host, registers it with Chef Server, and applies an initial run list. This revised guide is for DevOps engineers who want a clean, repeatable baseline command and a safer way to operate it.

Originally published on 2015-08-21; fully revised and updated.

The original note emphasized that the knife windows plugin is required and used knife bootstrap windows winrm to onboard a node. References preserved from the original post: original permalink and knife windows plugin documentation link.

Prerequisites for Windows bootstrap over WinRM

• A workstation with Chef and knife configured to reach your Chef Server.
• The Windows target host reachable over WinRM.
• A WinRM-capable account (the original example used administrator).
• A planned Chef node name and initial run list (for example, recipe[snc_firefox]).
• The knife windows plugin available on the workstation, as called out in the source post.

Bootstrap workflow

flowchart TD
    A[Collect host, credentials, and run list] --> B[Confirm WinRM access]
    B --> C[Run knife bootstrap windows winrm]
    C --> D[Install Chef Infra Client on Windows node]
    D --> E[Register node and client in Chef Server]
    E --> F[Apply initial run list]
    F --> G[Verify node registration]

Command variants from the original post

The source contained both a long-option and short-option style command. The password has been intentionally replaced with a placeholder, and the obvious typo nife has been corrected to knife.

Long-form command example

knife bootstrap windows winrm windows-host.example.com \
  --winrm-user Administrator \
  --winrm-password "$WINRM_PASSWORD" \
  --node-name firefox_win \
  --run-list 'recipe[snc_firefox]'Code language: PHP (php)

Short-form command example

knife bootstrap windows winrm windows-host.example.com \
  -x Administrator \
  -P "$WINRM_PASSWORD" \
  --node-name firefox_win \
  --run-list 'recipe[snc_firefox]'Code language: PHP (php)

Post-bootstrap validation commands

knife node show firefox_win
knife client show firefox_win
knife node listCode language: PHP (php)

Common pitfalls

• Storing WinRM passwords directly in shell history instead of using environment variables or a secret manager.
• WinRM connectivity failures caused by network path, host resolution, or endpoint configuration issues.
• Using an incorrect run list or recipe name during first converge.
• Assuming short flags always map the same way across knife versions.
• Simple command typos (for example, nife instead of knife).

Best practices

• Prefer long-form flags in automation for clarity and auditability.
• Inject credentials at runtime (for example, environment variables) rather than hardcoding.
• Run knife bootstrap windows winrm --help on your workstation to confirm exact option behavior for your installed version.
• Validate node and client objects immediately after bootstrap to catch registration issues early.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.