Skip to content

Commit 5332a96

Browse files
damacusdamacus
authored
feat!: migrate to custom resources (#196)
* refactor: migrate to custom resources Replace the legacy recipe and attribute model with custom resources for WMF, WinRM, DSC, and LCM management. Align CI and kitchen config with the current Sous-Chefs workflow shape, refresh documentation, and add focused resource/unit and integration coverage for the migrated surface. * test: relax Windows path assertion * ci: fix reusable workflow startup * ci: use cinc in kitchen configs
1 parent 58d5417 commit 5332a96

65 files changed

Lines changed: 1146 additions & 1443 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/copilot-instructions.md‎

Lines changed: 23 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,19 @@
22

33
## Repository Overview
44

5-
**Chef cookbook** for managing software installation and configuration. Part of the Sous Chefs cookbook ecosystem.
5+
**Chef cookbook** for managing legacy Windows Management Framework installation and related
6+
WinRM / DSC configuration through custom resources. Part of the Sous Chefs cookbook ecosystem.
67

7-
**Key Facts:** Ruby-based, Chef >= 16 required, supports various OS platforms (check metadata.rb, kitchen.yml and .github/workflows/ci.yml for which platforms to specifically test)
8+
**Key Facts:** Ruby-based, Chef >= 15.3 required, Windows-focused, with CI centered on
9+
Windows Server 2019 (check `metadata.rb`, `kitchen.yml`, and `.github/workflows/ci.yml`).
810

911
## Project Structure
1012

1113
**Critical Paths:**
12-
- `recipes/` - Chef recipes for cookbook functionality (if this is a recipe-driven cookbook)
13-
- `resources/` - Custom Chef resources with properties and actions (if this is a resource-driven cookbook)
14+
- `resources/` - Custom Chef resources with properties and actions
1415
- `spec/` - ChefSpec unit tests
15-
- `test/integration/` - InSpec integration tests (tests all platforms supported)
16-
- `test/cookbooks/` or `test/fixtures/` - Example cookbooks used during testing that show good examples of custom resource usage
17-
- `attributes/` - Configuration for recipe driven cookbooks (not applicable to resource cookbooks)
16+
- `test/integration/` - InSpec integration tests
17+
- `test/cookbooks/` - Example cookbook used during testing that shows custom resource usage
1818
- `libraries/` - Library helpers to assist with the cookbook. May contain multiple files depending on complexity of the cookbook.
1919
- `templates/` - ERB templates that may be used in the cookbook
2020
- `files/` - files that may be used in the cookbook
@@ -32,25 +32,24 @@ cookstyle # Ruby/Chef linting
3232
yamllint . # YAML linting
3333
markdownlint-cli2 '**/*.md' # Markdown linting
3434
chef exec rspec # Unit tests (ChefSpec)
35-
# Integration tests will be done via the ci.yml action. Do not run these. Only check the action logs for issues after CI is done running.
35+
# Local integration can be exercised with kitchen.yml when a Windows Vagrant environment is available.
3636
```
3737

3838
### Critical Testing Details
39-
- **Kitchen Matrix:** Multiple OS platforms × software versions (check kitchen.yml for specific combinations)
40-
- **Docker Required:** Integration tests use Dokken driver
41-
- **CI Environment:** Set `CHEF_LICENSE=accept-no-persist`
42-
- **Full CI Runtime:** 30+ minutes for complete matrix
39+
- **Kitchen Matrix:** Single Windows Server 2019 suite locally and in CI
40+
- **Local Integration:** `kitchen.yml` uses Vagrant + WinRM for Windows testing
41+
- **CI Environment:** `ci.yml` uses `actionshub/test-kitchen` with `KITCHEN_LOCAL_YAML=kitchen.exec.yml`
42+
- **License:** Set `CHEF_LICENSE=accept-no-persist`
4343

4444
### Common Issues and Solutions
4545
- **Always run `berks install` first** - most failures are dependency-related
46-
- **Docker must be running** for kitchen tests
4746
- **Chef Workstation required** - no workarounds, no alternatives
48-
- **Test data bags needed** (optional for some cookbooks) in `test/integration/data_bags/` for convergence
47+
- **Windows Vagrant provider availability matters** for local kitchen runs
4948

5049
## Development Workflow
5150

5251
### Making Changes
53-
1. Edit recipes/resources/attributes/templates/libraries
52+
1. Edit resources/libraries/templates/files as needed
5453
2. Update corresponding ChefSpec tests in `spec/`
5554
3. Also update any InSpec tests under test/integration
5655
4. Ensure cookstyle and rspec passes at least. You may run `cookstyle -a` to automatically fix issues if needed.
@@ -71,16 +70,16 @@ chef exec rspec # Unit tests (ChefSpec)
7170
- Include comprehensive ChefSpec tests for all actions
7271
- Follow Chef resource DSL patterns
7372

74-
### Recipe Conventions
75-
- Use `include_recipe` for modularity
76-
- Handle platforms with `platform_family?` conditionals
77-
- Use encrypted data bags for secrets (passwords, SSL certs)
78-
- Leverage attributes for configuration with defaults
73+
### Resource Conventions
74+
- Prefer custom resources over recipes for cookbook behavior
75+
- Handle Windows platform/version branching inside the resource actions or helpers
76+
- Keep reusable installer and OS-matrix logic in `libraries/`
77+
- Document each public resource under `documentation/`
7978

8079
### Testing Approach
81-
- **ChefSpec (Unit):** Mock dependencies, test recipe logic in `spec/`
82-
- **InSpec (Integration):** Verify actual system state in `test/integration/inspec/` - InSpec files should contain proper inspec.yml and controls directories so that it could be used by other suites more easily.
83-
- One test file per recipe, use standard Chef testing patterns
80+
- **ChefSpec (Unit):** Mock dependencies and step into custom resources in `spec/unit/`
81+
- **InSpec (Integration):** Verify actual system state in `test/integration/default/`
82+
- Keep the test cookbook focused on exercising the public resources
8483

8584
## Trust These Instructions
8685

@@ -89,7 +88,7 @@ These instructions are validated for Sous Chefs cookbooks. **Do not search for b
8988
**Error Resolution Checklist:**
9089
1. Verify Chef Workstation installation
9190
2. Confirm `berks install` completed successfully
92-
3. Ensure Docker is running for integration tests
91+
3. Ensure the local Windows Vagrant provider can boot and expose WinRM before blaming cookbook code
9392
4. Check for missing test data dependencies
9493

9594
The CI system uses these exact commands - following them matches CI behavior precisely.

‎.github/workflows/ci.yml‎

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -19,30 +19,27 @@ jobs:
1919
statuses: write
2020
issues: write
2121

22-
# This needs to run on vagrant due to the fact these nodes reboot during their
23-
# runs
24-
integration:
22+
integration-windows:
2523
needs: lint-unit
26-
runs-on: macos-latest
24+
runs-on: windows-latest
2725
strategy:
2826
fail-fast: false
2927
matrix:
3028
os:
31-
- "windows-2012r2"
32-
- "windows-2016"
3329
- "windows-2019"
3430
suite:
35-
- "powershell5"
31+
- "default"
3632

3733
steps:
3834
- name: Check out code
3935
uses: actions/checkout@v6
40-
- name: Install Chef
41-
uses: actionshub/chef-install@6.0.0
36+
- name: Install Cinc Workstation
37+
uses: sous-chefs/.github/.github/actions/install-workstation@main
4238
- name: test-kitchen
43-
uses: actionshub/test-kitchen@3.0.0
39+
uses: actionshub/test-kitchen@main
4440
env:
4541
CHEF_LICENSE: accept-no-persist
42+
KITCHEN_LOCAL_YAML: kitchen.exec.yml
4643
with:
4744
suite: ${{ matrix.suite }}
4845
os: ${{ matrix.os }}

‎.github/workflows/conventional-commits.yml‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,13 @@
11
---
2-
name: conventional-commits
2+
name: 'Validate PR'
33

44
"on":
5-
pull_request:
6-
types:
7-
- opened
8-
- reopened
9-
- edited
10-
- synchronize
5+
pull_request_target:
6+
types: [opened, edited, reopened]
117

128
jobs:
139
conventional-commits:
1410
uses: sous-chefs/.github/.github/workflows/conventional-commits.yml@5.0.8
11+
permissions:
12+
pull-requests: read
13+
secrets: inherit

‎.github/workflows/copilot-setup-steps.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ jobs:
1818
steps:
1919
- name: Check out code
2020
uses: actions/checkout@v6
21-
- name: Install Chef
22-
uses: actionshub/chef-install@main
21+
- name: Install Cinc Workstation
22+
uses: sous-chefs/.github/.github/actions/install-workstation@main
2323
- name: Install cookbooks
2424
run: berks install

‎.github/workflows/prevent-file-change.yml‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,14 @@
11
---
2-
name: prevent-file-change
2+
name: 'Prevent file change'
33

44
"on":
5-
pull_request:
6-
types:
7-
- opened
8-
- reopened
9-
- edited
10-
- synchronize
5+
pull_request_target:
6+
branches: [main]
117

128
jobs:
139
prevent-file-change:
1410
uses: sous-chefs/.github/.github/workflows/prevent-file-change.yml@5.0.8
11+
permissions:
12+
pull-requests: write
1513
secrets:
1614
token: ${{ secrets.GITHUB_TOKEN }}

‎Berksfile‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
# frozen_string_literal: true
2+
13
source 'https://supermarket.chef.io'
24

35
metadata
6+
7+
group :integration do
8+
cookbook 'test', path: 'test/cookbooks/test'
9+
end

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ This file is used to list changes made in each version of the powershell cookboo
55
Standardise files with files in sous-chefs/repo-management
66
Standardise files with files in sous-chefs/repo-management
77

8+
## Unreleased
9+
10+
* Migrate the cookbook to custom resources and modernize Windows CI/test coverage
11+
812
## [6.4.21](https://github.com/sous-chefs/powershell/compare/v6.4.20...v6.4.21) (2025-10-16)
913

1014

‎Dangerfile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ def code_changes?
1818
end
1919

2020
def test_changes?
21-
tests = %w(spec test kitchen.yml kitchen.dokken.yml)
21+
tests = %w(spec test kitchen.yml kitchen.exec.yml)
2222
tests.each do |location|
2323
return true unless git.modified_files.grep(/#{location}/).empty?
2424
end

‎LIMITATIONS.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Limitations
2+
3+
## Package Availability
4+
5+
### APT (Debian/Ubuntu)
6+
7+
- Not applicable. This cookbook manages Microsoft Windows Management Framework installers on Windows only.
8+
9+
### DNF/YUM (RHEL family)
10+
11+
- Not applicable. This cookbook manages Microsoft Windows Management Framework installers on Windows only.
12+
13+
### Windows
14+
15+
- Windows PowerShell 2.0 is enabled through built-in Windows features on Windows Server 2008 R2 / Windows 7 and Windows Server 2012 / Windows 8.
16+
- Windows Management Framework 3.0 packages are published for Windows 7 SP1 and Windows Server 2008 R2 SP1 only.
17+
- Windows Management Framework 4.0 packages are published for Windows 7 SP1, Windows Server 2008 R2 SP1, and Windows Server 2012.
18+
- Windows Management Framework 5.1 packages are published for Windows 7 SP1 / Windows Server 2008 R2 SP1, Windows Server 2012, and Windows Server 2012 R2 / Windows 8.1.
19+
- Windows Server 2016 and newer ship with Windows PowerShell 5.1, so the cookbook treats WMF 5.1 as built in on those releases.
20+
21+
## Architecture Limitations
22+
23+
- WMF 3.0 and WMF 4.0 provide both `x86` and `x64` packages for Windows 7 SP1 / Windows Server 2008 R2 SP1.
24+
- WMF 4.0 on Windows Server 2012 is `x64` only.
25+
- WMF 5.1 on Windows Server 2012 is `x64` only.
26+
- WMF 5.1 on Windows 8.1 / Windows Server 2012 R2 is available for `x86` and `x64`.
27+
28+
## Source/Compiled Installation
29+
30+
- Not applicable. Microsoft distributes WMF through signed Windows features, `.msu`, and `.zip` archives.
31+
- WMF 3.0 requires .NET Framework 4.0.
32+
- WMF 4.0 and WMF 5.1 require .NET Framework 4.5 or newer.
33+
34+
## Known Issues
35+
36+
- WMF 2.0, 3.0, and 4.0 are tied to operating systems that are beyond mainstream support; keep them for legacy compatibility only.
37+
- Windows Server 2012 and Windows Server 2012 R2 are past extended support and only available under Microsoft ESU.
38+
- The active test surface in this cookbook is limited to Windows Server 2019 because it has a stable local Vagrant box and a matching CI exec target.

‎README.md‎

Lines changed: 42 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -2,103 +2,68 @@
22

33
[![Cookbook Version](https://img.shields.io/cookbook/v/powershell.svg)](https://supermarket.chef.io/cookbooks/powershell)
44
[![CI State](https://github.com/sous-chefs/powershell/workflows/ci/badge.svg)](https://github.com/sous-chefs/powershell/actions?query=workflow%3Aci)
5-
[![OpenCollective](https://opencollective.com/sous-chefs/backers/badge.svg)](#backers)
6-
[![OpenCollective](https://opencollective.com/sous-chefs/sponsors/badge.svg)](#sponsors)
7-
[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
85

9-
Installs and configures PowerShell 2.0, 3.0, 4.0 or 5.0.
6+
This cookbook provides custom resources for managing legacy Windows Management Framework
7+
(WMF) installers and the supporting WinRM / DSC configuration required by older Windows
8+
platforms.
109

1110
## Maintainers
1211

13-
This cookbook is maintained by the Sous Chefs. The Sous Chefs are a community of Chef cookbook maintainers working together to maintain important cookbooks. If you’d like to know more please visit [sous-chefs.org](https://sous-chefs.org/) or come chat with us on the Chef Community Slack in [#sous-chefs](https://chefcommunity.slack.com/messages/C2V7B88SF).
12+
This cookbook is maintained by the Sous Chefs. The Sous Chefs are a community of Chef
13+
cookbook maintainers working together to maintain important cookbooks. If you would like to
14+
know more, visit [sous-chefs.org](https://sous-chefs.org/).
1415

1516
## Requirements
1617

17-
### Platforms
18-
19-
Not every version of Windows supports every version of Powershell. The following table illustrates Powershell support across the Windows family. **Included** means that the base installation of the operating system includes the indicated version of Powershell.
20-
21-
Windows Version | PowerShell 2.0 | PowerShell 3.0 | PowerShell 4.0 | PowerShell 5.0
22-
----------------------------------- | -------------- | -------------- | -------------- | --------------
23-
Windows Server 2008 R2 | Included | Supported | Supported | Supported
24-
Windows Server 2012 / Windows 8 | Included | Included | Supported | Supported
25-
Windows Server 2012R2 / Windows 8.1 | Included | Not Available | Included | Supported
26-
27-
### Chef
28-
29-
- Chef 13+
30-
31-
### Cookbooks
32-
33-
- windows 3.0+
34-
35-
PowerShell also requires the appropriate version of the Microsoft .NET Framework to be installed, if the operating system does not ship with that version. The following community cookbooks are used to install the correct version of the .NET Framework:
36-
37-
- ms_dotnet
18+
- Chef Infra Client `>= 15.3`
19+
- Windows
20+
- `ms_dotnet` `>= 3.2.1`
3821

3922
## Resources
4023

41-
### `powershell_module`
42-
43-
#### Deprecated
24+
- `powershell_wmf`
25+
- `powershell_winrm`
26+
- `powershell_dsc`
27+
- `powershell_lcm`
4428

45-
The `powershell_module` has been removed from this cookbook as it was non-functional for most needs and has been replaced with built in resources in chef:
46-
47-
- [powershell_package_source](https://docs.chef.io/resource_powershell_package_source.html)
48-
- [powershell_package](https://docs.chef.io/resource_powershell_package.html)
29+
See [`LIMITATIONS.md`](LIMITATIONS.md) for the supported Microsoft download matrix and
30+
lifecycle notes.
4931

5032
## Usage
5133

52-
**Note**: The installation may require a restart of the node being configured before PowerShell can be used.
53-
54-
### default
55-
56-
The default recipe contains no resources and will do nothing if included on a run_list.
57-
58-
### powershell2
59-
60-
Include the `powershell2` recipe in a run list, to ensure PowerShell 2.0 is installed. If the platform is not supported, a warning will be logged.
61-
62-
### powershell3
63-
64-
Include the `powershell3` recipe in a run list, to install PowerShell 3.0 is installed on applicable platforms. If the platform is not supported, a warning will be logged.
65-
66-
### powershell4
67-
68-
Include the `powershell4` recipe in a run list, to install PowerShell 4.0 is installed on applicable platforms. If the platform is not supported, a warning will be logged.
69-
70-
### powershell5
71-
72-
Include the `powershell5` recipe in a run list, to install PowerShell 5.0 is installed on applicable platforms. If the platform is not supported, a warning will be logged.
73-
74-
## References
34+
Install WMF 5.1 when the target platform needs it:
7535

76-
- Installing [Windows Management Framework 2.0](http://support.microsoft.com/kb/968929)
77-
- Installing [Windows Management Framework 3.0](http://www.microsoft.com/en-us/download/details.aspx?id=34595)
78-
- Installing [Windows Management Framework 4.0](http://www.microsoft.com/en-us/download/details.aspx?id=40855)
79-
- Installing [Windows Management Framework 5.0](https://www.microsoft.com/en-us/download/details.aspx?id=50395)
36+
```ruby
37+
powershell_wmf '5.1'
38+
```
8039

81-
## Contributors
40+
Prepare WinRM for DSC with an HTTPS listener:
8241

83-
This project exists thanks to all the people who [contribute.](https://opencollective.com/sous-chefs/contributors.svg?width=890&button=false)
42+
```ruby
43+
powershell_dsc 'default' do
44+
enable_https_transport true
45+
hostname 'node.example.com'
46+
thumbprint 'ABCDEF1234567890'
47+
end
48+
```
8449

85-
### Backers
50+
Enable or disable the Local Configuration Manager:
8651

87-
Thank you to all our backers!
52+
```ruby
53+
powershell_lcm 'default'
8854

89-
![https://opencollective.com/sous-chefs#backers](https://opencollective.com/sous-chefs/backers.svg?width=600&avatarHeight=40)
55+
powershell_lcm 'default' do
56+
action :disable
57+
end
58+
```
9059

91-
### Sponsors
60+
## Testing
9261

93-
Support this project by becoming a sponsor. Your logo will show up here with a link to your website.
62+
Local Vagrant runs use `kitchen.yml`. CI uses the exec driver with `kitchen.exec.yml`.
9463

95-
![https://opencollective.com/sous-chefs/sponsor/0/website](https://opencollective.com/sous-chefs/sponsor/0/avatar.svg?avatarHeight=100)
96-
![https://opencollective.com/sous-chefs/sponsor/1/website](https://opencollective.com/sous-chefs/sponsor/1/avatar.svg?avatarHeight=100)
97-
![https://opencollective.com/sous-chefs/sponsor/2/website](https://opencollective.com/sous-chefs/sponsor/2/avatar.svg?avatarHeight=100)
98-
![https://opencollective.com/sous-chefs/sponsor/3/website](https://opencollective.com/sous-chefs/sponsor/3/avatar.svg?avatarHeight=100)
99-
![https://opencollective.com/sous-chefs/sponsor/4/website](https://opencollective.com/sous-chefs/sponsor/4/avatar.svg?avatarHeight=100)
100-
![https://opencollective.com/sous-chefs/sponsor/5/website](https://opencollective.com/sous-chefs/sponsor/5/avatar.svg?avatarHeight=100)
101-
![https://opencollective.com/sous-chefs/sponsor/6/website](https://opencollective.com/sous-chefs/sponsor/6/avatar.svg?avatarHeight=100)
102-
![https://opencollective.com/sous-chefs/sponsor/7/website](https://opencollective.com/sous-chefs/sponsor/7/avatar.svg?avatarHeight=100)
103-
![https://opencollective.com/sous-chefs/sponsor/8/website](https://opencollective.com/sous-chefs/sponsor/8/avatar.svg?avatarHeight=100)
104-
![https://opencollective.com/sous-chefs/sponsor/9/website](https://opencollective.com/sous-chefs/sponsor/9/avatar.svg?avatarHeight=100)
64+
```shell
65+
berks install
66+
cookstyle
67+
chef exec rspec --format documentation
68+
kitchen test default-windows-2019 --destroy=always
69+
```

0 commit comments

Comments
 (0)
⚡