Example `ranger.yml` Configuration¶

A complete, annotated ranger.yml you can copy, fill in the [REQUIRED] fields, and run immediately. Every key maps to a section in the Configuration Reference.

Note

kv-ranger throughout this example is a placeholder vault name, not a vault Ranger creates or requires. Substitute your actual Key Vault. v2.6.3 (#292) removed these placeholders from the runtime default config.

The same file lives under samples/configs/ranger.yml and can be regenerated at any time with:

New-AzureLocalRangerConfig -Path .\ranger.yml

Full example¶

# AzureLocalRanger configuration file
# Generated by New-AzureLocalRangerConfig
#
# Fields marked [REQUIRED] must be updated before running Invoke-AzureLocalRanger.
# Run: Invoke-AzureLocalRanger -ConfigPath <this file>
# Resolution precedence: parameter > config file > interactive prompt > default > error

environment:
  name: prod-azlocal-01          # [REQUIRED] Short identifier used in report filenames
  clusterName: azlocal-prod-01   # Friendly cluster display name for reports
  description: Primary production Azure Local instance

targets:
  cluster:
    fqdn: azlocal-prod-01.contoso.com     # [REQUIRED] FQDN of the cluster name object (CNO)
    nodes:
      - azl-node-01.contoso.com           # [REQUIRED] At least one node FQDN or NetBIOS name
      - azl-node-02.contoso.com           # Add/remove entries to match your cluster
  azure:
    subscriptionId: 00000000-0000-0000-0000-000000000000  # [REQUIRED] Azure subscription ID
    resourceGroup: rg-azlocal-prod-01                     # [REQUIRED] Resource group of the Arc-enabled HCI resource
    tenantId: 11111111-1111-1111-1111-111111111111        # [REQUIRED] Azure AD / Entra tenant ID
  bmc:
    endpoints:
      - host: idrac-node-01.contoso.com   # BMC hostname or IP for first node (optional)
        node: azl-node-01.contoso.com
      - host: idrac-node-02.contoso.com
        node: azl-node-02.contoso.com
  switches: []                            # Add network switch targets here (optional)
  firewalls: []                           # Add firewall targets here (optional)

credentials:
  azure:
    method: existing-context              # existing-context | device-code | service-principal | managed-identity | azure-cli
    useAzureCliFallback: true             # Fall back to az cli token if Connect-AzAccount context is missing
  cluster:
    username: 'CONTOSO\ranger-read'       # [REQUIRED] Account with WinRM read access to cluster nodes
    passwordRef: keyvault://kv-ranger/cluster-read  # Vault reference, plain password, or blank to prompt
  domain:
    username: 'CONTOSO\ranger-read'       # Account for AD queries; blank = reuse cluster credential
    passwordRef: keyvault://kv-ranger/domain-read
  bmc:
    username: root                        # iDRAC / iLO credential; only needed when BMC targets are set
    passwordRef: keyvault://kv-ranger/idrac-root

domains:
  include: []                             # Limit collection to these domains (empty = auto-detect)
  exclude: []                             # Skip these domains during collection
  hints:
    fixtures: {}                          # Static override values (rarely needed)
    networkDeviceConfigs: []              # Paths to switch / firewall configuration files for manual evidence import

output:
  mode: current-state                     # current-state | as-built | drift
  formats:                                # Report formats to generate — remove any you don't want
    - html                                # HTML narrative report (executive + management + technical)
    - markdown                            # Markdown narrative report
    - json                                # Raw manifest export
    - json-evidence                       # Raw resource-only inventory JSON (v2.0.0)
    - svg                                 # SVG vector diagrams
    - drawio                              # draw.io XML diagrams (open in diagrams.net)
    - docx                                # Word document (no Office required)
    - xlsx                                # Excel workbook — inventory + findings tabs
    - pdf                                 # PDF (rendered from HTML via headless Edge/Chrome)
    - pptx                                # PowerPoint executive deck (v2.5.0, no Office required)
    - powerbi                             # Power BI CSV star-schema exports under powerbi/
  rootPath: 'C:\AzureLocalRanger'         # Output directory; each run creates a dated sub-folder
  diagramFormat: svg                      # svg | png
  keepRawEvidence: true                   # Keep raw JSON evidence alongside reports

behavior:
  promptForMissingCredentials: true       # Prompt when a credential cannot be resolved
  promptForMissingRequired: true          # Prompt for missing required structural values
  skipUnavailableOptionalDomains: true    # Skip optional collectors (BMC, switches) if unreachable
  failOnSchemaViolation: true             # Abort if config fails schema validation
  logLevel: info                          # debug | info | warning | error
  retryCount: 2                           # WinRM retry attempts per command
  timeoutSeconds: 60                      # WinRM operation timeout in seconds
  continueToRendering: true               # Render reports even when some collectors partially fail

Section-by-section walkthrough¶

`environment` — how the run identifies itself¶

Every run produces a folder named <environment.name>-<mode>-<timestamp> (e.g. prod-azlocal-01-current-state-20260417T203000Z). Reports use clusterName in titles and page headers; description appears in the report metadata block.

`targets.cluster` — what to talk to¶

At least one of fqdn or nodes is required. fqdn is the Cluster Name Object (CNO); nodes is the list of individual node FQDNs. Supply both when you have them — Ranger will use the node list for per-node WinRM calls and the cluster FQDN for cluster-wide queries.

`targets.azure` — where to query in Azure¶

subscriptionId, resourceGroup, and tenantId point Ranger at the Arc-enabled HCI resource. If resourceGroup is omitted, Ranger will try to auto-discover it from Arc (see First Run).

`targets.bmc`, `targets.switches`, `targets.firewalls` — optional hardware¶

BMC endpoints enable the Dell/Redfish hardware collector. Leave the arrays empty to skip these collectors entirely. Manual evidence imports for switches and firewalls use domains.hints.networkDeviceConfigs plus Import-RangerManualEvidence — see the workflow guides for the full flow.

`credentials` — how to authenticate¶

Azure — existing-context reuses Get-AzContext; device-code prompts in-browser; managed-identity is for Azure-hosted runners; service-principal reads from environment variables or a Key Vault; azure-cli falls back to az account get-access-token.
Cluster / Domain / BMC — supply a username + a passwordRef. Supported schemes: keyvault://<vault>/<secret>, env://<VAR>, secret-store://<vault>/<name>. Leave passwordRef blank to be prompted (requires behavior.promptForMissingCredentials: true).

`domains` — scope control¶

Leave include and exclude empty to collect every domain Ranger knows about. Use include to do a focused run ([cluster, storage-networking]), or exclude to skip slow collectors on a broad run. hints.networkDeviceConfigs feeds the manual evidence import flow.

`output` — what to produce¶

mode — current-state for operational snapshots, as-built for formal handoff packages, drift when comparing against a baseline
formats — any of html, markdown, json, json-evidence, svg, drawio, docx, xlsx, pdf, pptx, powerbi
rootPath — parent directory; each run creates its own timestamped sub-folder

`behavior` — engine tuning¶

These are all optional knobs. Leave them at defaults for your first run and revisit them only when you have a specific reason (air-gapped environment, scheduled runner, troubleshooting).

Common variants¶

Minimal — for a smoke test¶

Drop everything except the required fields:

environment:
  name: smoke-test
targets:
  cluster:
    fqdn: azlocal-prod-01.contoso.com
  azure:
    subscriptionId: 00000000-0000-0000-0000-000000000000
    resourceGroup: rg-azlocal-prod-01
    tenantId: 11111111-1111-1111-1111-111111111111
credentials:
  cluster:
    username: 'CONTOSO\ranger-read'

Scheduled / unattended¶

Disable interactive prompts and fail hard on missing credentials:

behavior:
  promptForMissingCredentials: false
  promptForMissingRequired: false
  failOnSchemaViolation: true
credentials:
  azure:
    method: managed-identity
  cluster:
    username: 'CONTOSO\ranger-read'
    passwordRef: keyvault://kv-ranger/cluster-read

Cloud publishing¶

Add the output.remoteStorage block (see Cloud Publishing):

output:
  remoteStorage:
    type: azureBlob
    storageAccount: stircompliance
    container: ranger-runs
    pathTemplate: '{cluster}/{yyyy-MM-dd}/{runId}'
    include: [manifest, evidence, packageIndex, runLog]
    authMethod: default

Configuration Reference — every key with type, default, validation
First Run — step-by-step first-run walkthrough
Command Reference — Invoke-AzureLocalRanger and related commands
Authentication — detailed credential options

Example ranger.yml Configuration¶

Full example¶

Section-by-section walkthrough¶

environment — how the run identifies itself¶

targets.cluster — what to talk to¶

targets.azure — where to query in Azure¶

targets.bmc, targets.switches, targets.firewalls — optional hardware¶

credentials — how to authenticate¶

domains — scope control¶

output — what to produce¶

behavior — engine tuning¶