ANS-CHOCO Architecture movements / 01

Ansible / Chocolatey / Windows

From approved package
to accountable change.

Windows software arrives through different installers and drifts over time. ANS-CHOCO prepares approved packages, aligns host state, and records the result.

Static educational model. No fleet connection, credentials, or execution controls.

Follow the movement

00 / Full system

Separate intent, execution, and evidence.

The catalog defines approved software. Ansible roles prepare packages and align Windows hosts. Per-host and fleet reports make changes, retries, and reboot advisories reviewable.

Explore without connecting to a host. The published page is static and carries no vault, inventory exports, or real deployment reports.

The system, in one frame

Delivered pipeline / configuration, execution, and evidence

The diagram stays at a readable size. Scroll sideways or choose a movement above to focus its part of the system.

Read text equivalent

Readable size / scroll to explore the full diagram.

ANS-CHOCO's current software-alignment architecture A reviewed repository provides catalogs, playbooks, inventory and policy. A Linux controller loads local vault credentials, executes chocoBuild or chocoDeploy, and uses WinRM to reach authorized Windows hosts. Build helpers produce packages for configured sources. Windows PowerShell and Chocolatey reconcile installation state. JSON and HTML evidence return to controller-side fleet reporting. Build iteration reuses deployment logic. The textual architecture below explains each relationship and its implementation boundaries. REVIEWABLE SOURCELINUX CONTROL PLANEWINDOWS / ARTIFACT PLANE load.nupkg WinRMsource iterate install reuses chocoDeploy write evidence 01 / REPOSITORY CONTRACT Reviewed configuration playbooks/ + role task trees requirements.yml collections Manual Azure / Arc samples Deployment-managed checkout PACKAGE INTENT Catalog + version floors internalize / wrapper specs validate_catalog.py checks consistency 03 / TARGET BOUNDARY CSV + AD export + policy csv_to_inventory.py excludes OUs inventory + adjacent group_vars UI / manual inventories bypass this gate CONTROLLER / NOT A WINDOWS AGENT Ansible playbooks + pinned collections chocoBuild / chocoDeploy / patchReady / softwareUsage 02 / BUILD ROLE chocoBuild Community internalization SHA-verified wrappers Lab extract / repack Helpers execute on Windows 04 / DEPLOY ROLE chocoDeploy 5 modes / drift detection Apps + runtime alignment Removal / reboot policy report in always; re-raise fatal PRIVATE / NEVER PUBLISHED Local vault/ vars_files + vault password Encrypted credentials loaded by playbooks 05 / CONTROLLER EVIDENCE Fleet summary JSON input / latest result wins HTML + optional JSON / text ARTIFACT SOURCE / CONFIGURED SEPARATELY Build lab > .nupkg > package source SMB mirror / NuGet repository / public feed Build supply differs from deployment; test before promotion AUTHORIZED WINDOWS TARGETS Host-state reconciliation WinRM > PowerShell helpers > Chocolatey Installed packages + registry / vendor installers Defaults: NTLM / HTTP 5985; chocoDeploy reboot = never TARGET & CONTROLLER OUTPUT Per-run JSON / daily host HTML Readiness + usage are separate playbooks; preserve evidence A SOURCE MODEL, NOT A PRODUCTION TOPOLOGY. COLORS DESCRIBE CONNECTION KIND; THEY DO NOT CLAIM HEALTH OR SUCCESS.
Transport Artifacts / evidence Configuration / credentials Role orchestration Host work

Delivered scope and design decisions

Package preparation and role reuse

Build artifacts separately; reuse deployment logic.

Community-package internalization and checksum-verified wrappers prepare Chocolatey artifacts for configured sources. On-target extract/repack/install iteration keeps the test cycle local. Its install step reuses chocoDeploy, keeping reconciliation and reporting in one operational engine.

Policy-driven operations and evidence

Separate target scope, host work, and review.

CSV and AD evidence apply protected-OU policy during inventory creation. Deployment modes reconcile registry and Chocolatey state against application and runtime floors. Explicit removal/reboot controls and per-host JSON, daily HTML, and fleet summaries support deliberate execution and review.

Portability and future enhancements

Evolution with scale and security requirements

The current execution path is Ansible and WinRM. Catalogs, inventories, adjacent connection variables, package sources, and configuration separate environment choices from reusable roles.

As deployment scale, business scope, and security requirements evolve, enhancement options include Azure Arc execution through official modules and client-based authentication, with the aim of reducing reliance on WinRM.

Textual equivalent + source evidence

Read the architecture as contracts.

01 / Reviewed intent

The shared package catalog describes identity, approved versions, acquisition, and intended mirror versions. Role defaults supply floors and selection/removal policy. The validator checks consistency, not live package availability.

catalogs/chocolatey_packages.yml tools/validate_catalog.py

02 / Prepared artifacts

chocoBuild.yml runs community or wrapper tasks on a Windows build target. PowerShell bundles vendor installers and checks wrapper integrity. Iteration's install action includes chocoDeploy with a single package/local source, reusing install logic rather than duplicating it.

playbooks/chocoBuild.yml chocoBuild / iterate / install-on-target.yml

03 / Target scope

csv_to_inventory.py combines CSV and AD evidence, removes protected-OU targets, and optionally probes reachable hosts. Generated inventories carry adjacent WinRM group variables. Unknown hosts are warned, not excluded. Manual/UI inventories bypass the OU process check.

tools/csv_to_inventory.py policies/target_exclusions.yml

04 / Execute with boundaries

Fleet plays load file-based credentials from ignored vault/. Ansible reaches Windows via WinRM. chocoDeploy reconciles registry/Chocolatey state, routes sources, applies application/runtime policy, records errors and finalizes evidence. Reboots default to never. Conversion can remove a vendor install before replacement succeeds.

playbooks/chocoDeploy.yml chocoDeploy / tasks / main.yml

05 / Account for the result

Deployment writes per-run JSON and daily host HTML. Controller roll-ups combine the final result per software, resolve successful retries, and distinguish reboot advisories. report_only rebuilds existing target evidence, not a new scan. The watcher follows terminal logs; recovery tools collect missing evidence.

chocoDeploy / ops / report.yml chocoDeploy / files / fleet_summary.py

Adjacent roles / separate purposes

patchReady checks reachability/reboot/disk/Chocolatey and archives older logs. softwareUsage reads Security 4688 events and may expose private usernames/command lines. Legacy domain-join helpers are outside this deployment flow. Optional cloud samples require separately provisioned infrastructure.

playbooks/patchReady.yml playbooks/softwareUsage.yml