refactor: modernize control_groups cookbook

.github/workflows/ci.yml

@@ -23,20 +23,19 @@ jobs:
     strategy:
       matrix:
         os:
-          - "debian-9"
-          - "debian-10"
-          - "ubuntu-1604"
-          - "ubuntu-1804"
-          - "centos-7"
+          - "debian-12"
+          - "ubuntu-2404"
         suite:
           - "default"
+          - "entry"
+          - "rule"
       fail-fast: false
 
     steps:
       - name: Check out code
-        uses: actions/checkout@v5
-      - name: Install Chef
-        uses: actionshub/chef-install@main
+        uses: actions/checkout@v6
+      - name: Install Cinc Workstation
+        uses: sous-chefs/.github/.github/actions/install-workstation@main
       - name: Dokken
         uses: actionshub/test-kitchen@main
         env:

.github/workflows/conventional-commits.yml

@@ -12,3 +12,5 @@ name: conventional-commits
 jobs:
   conventional-commits:
     uses: sous-chefs/.github/.github/workflows/conventional-commits.yml@5.0.8
+    permissions:
+      pull-requests: write

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

@@ -1,5 +1,5 @@
 ---
-name: 'Copilot Setup Steps'
+name: "Copilot Setup Steps"
 
 "on":
   workflow_dispatch:
@@ -17,7 +17,7 @@ jobs:
       contents: read
     steps:
       - name: Check out code
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
       - name: Install Chef
         uses: actionshub/chef-install@main
       - name: Install cookbooks

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

@@ -12,5 +12,7 @@ name: prevent-file-change
 jobs:
   prevent-file-change:
     uses: sous-chefs/.github/.github/workflows/prevent-file-change.yml@5.0.8
+    permissions:
+      pull-requests: write
     secrets:
       token: ${{ secrets.GITHUB_TOKEN }}

Berksfile

@@ -1,3 +1,9 @@
+# frozen_string_literal: true
+
 source 'https://supermarket.chef.io'
 
 metadata
+
+group :integration do
+  cookbook 'test', path: 'test/cookbooks/test'
+end

CHANGELOG.md

@@ -2,14 +2,12 @@
 
 ## [0.2.16](https://github.com/sous-chefs/control_groups/compare/v0.2.15...v0.2.16) (2026-01-06)
 
-
 ### Bug Fixes
 
 * **ci:** Update workflows to use release pipeline ([#78](https://github.com/sous-chefs/control_groups/issues/78)) ([063087d](https://github.com/sous-chefs/control_groups/commit/063087dc2f1ca05a13ad5d7f71580314ee68418c))
 
 ## [0.2.15](https://github.com/sous-chefs/control_groups/compare/0.2.14...v0.2.15) (2025-10-15)
 
-
 ### Bug Fixes
 
 * **ci:** Update workflows to use release pipeline ([#78](https://github.com/sous-chefs/control_groups/issues/78)) ([063087d](https://github.com/sous-chefs/control_groups/commit/063087dc2f1ca05a13ad5d7f71580314ee68418c))

LIMITATIONS.md

@@ -0,0 +1,27 @@
+# Limitations
+
+This cookbook now targets the resource-oriented API only and is validated against a narrow, explicit support matrix.
+
+## Supported platforms
+
+- Debian 12: `packages.debian.org` publishes `cgroup-tools`, `libcgroup2`, and `libpam-cgroup` for Bookworm, and this repository now runs Kitchen coverage for Debian 12.
+- Ubuntu 24.04: `packages.ubuntu.com` lists `libpam-cgroup` in Noble's `admin` section, confirming the libcgroup userspace packages are still published for the current LTS.
+
+## Researched but not supported
+
+- Amazon Linux 2023: AWS documents `libcgroup-tools` on AL2023, but the same documentation states AL2023 uses cgroup v2 and recommends `systemd` resource control instead. This cookbook still renders classic `cgconfig.conf` and `cgrules.conf` files, so AL2023 is documented as a limitation rather than an advertised target.
+- openSUSE Leap: the modern `software.opensuse.org` results for related cgroup packages are either absent or community/experimental, so this cookbook does not claim support.
+- RHEL-family clones: the repository no longer advertises CentOS or clone support without current package and runtime validation.
+- Dokken / cgroup-v2 containers: a direct `kitchen converge` on Debian 12 and Ubuntu 24.04 fails when `cgconfigparser` attempts to mount controller hierarchies from `cgconfig.conf` and receives `Operation not permitted`. The Kitchen suites therefore run with `manage_runtime false`, which verifies package installation, config generation, and systemd unit creation without attempting to start the libcgroup daemons in a cgroup-v2 container.
+
+## Architecture notes
+
+- Debian and Ubuntu publish the libcgroup packages for multiple architectures through their normal package repositories.
+- This cookbook does not attempt source builds or vendor repositories; it relies on distro-packaged libcgroup utilities only.
+
+## Source URLs
+
+- Debian package index: <https://packages.debian.org/bookworm/libpam-cgroup>
+- Ubuntu package index: <https://packages.ubuntu.com/noble/admin/>
+- Amazon Linux 2023 cgroups guidance: <https://docs.aws.amazon.com/linux/al2023/ug/resource-limiting-raw-cgroups.html>
+- Amazon Linux 2023 cgroup v2 note: <https://docs.aws.amazon.com/linux/al2023/ug/cgroupv2.html>

README.md

@@ -8,20 +8,31 @@
 
 Manage control groups (cgroups) via chef!
 
+## Supported platforms
+
+- Debian 12
+- Ubuntu 24.04
+
+See [`LIMITATIONS.md`](LIMITATIONS.md) for the researched support policy and unsupported platforms.
+
+Current unit verification passes on this repository. The Kitchen suites run on Debian 12 and Ubuntu 24.04 with `manage_runtime false` because Dokken/cgroup-v2 containers cannot start the legacy libcgroup mount workflow. See [`LIMITATIONS.md`](LIMITATIONS.md) for the runtime caveat.
+
 ## Maintainers
 
 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).
 
 ## Example usage
 
 ```ruby
+control_groups_install 'default'
+
 control_groups_entry 'lackresources' do
-  memory('memory.limit_in_bytes' => '1M')
-  cpu('cpu.shares' => 1)
+  memory('memory.max' => '1048576')
+  cpu('cpu.max' => '10000 100000')
 end
 
 control_groups_rule 'someuser' do
-  controllers [:cpu, :memory]
+  controllers %w(cpu memory)
   destination 'lackresources'
 end
 ```

documentation/control_groups_entry.md

@@ -0,0 +1,49 @@
+# control_groups_entry
+
+Define or remove a cgroup entry in `/etc/cgconfig.conf`.
+
+## Actions
+
+| Action     | Description                                        |
+| ---------- | -------------------------------------------------- |
+| `:create`  | Adds or updates the named cgroup entry (default)   |
+| `:delete`  | Removes the named cgroup entry                     |
+
+## Properties
+
+- `group`: `String`, defaults to the `name` property. Name of the cgroup entry.
+- `perm_task_uid`: `String`, defaults to `nil`. Task owner UID.
+- `perm_task_gid`: `String`, defaults to `nil`. Task owner GID.
+- `perm_admin_uid`: `String`, defaults to `nil`. Admin owner UID.
+- `perm_admin_gid`: `String`, defaults to `nil`. Admin owner GID.
+- `cpu`: `Hash`, defaults to `nil`. CPU controller settings.
+- `cpuacct`: `Hash`, defaults to `nil`. CPU accounting controller settings.
+- `devices`: `Hash`, defaults to `nil`. Device controller settings.
+- `freezer`: `Hash`, defaults to `nil`. Freezer controller settings.
+- `memory`: `Hash`, defaults to `nil`. Memory controller settings.
+- `extra_config`: `Hash`, defaults to `{}`. Additional key/value pairs rendered inside the group.
+- `mounts`: `Hash`, defaults to `ControlGroups.default_mounts`. Mount map written into `/etc/cgconfig.conf` before the group stanza.
+- `manage_runtime`: `Boolean`, defaults to `true`. When `true`, enables and starts the libcgroup systemd units. Set to `false` in Dokken or other cgroup-v2 test environments.
+
+## Examples
+
+```ruby
+control_groups_entry 'limited' do
+  cpu('cpu.max' => '10000 100000')
+  memory('memory.max' => '1048576')
+end
+```
+
+```ruby
+control_groups_entry 'limited' do
+  perm_task_uid 'root'
+  extra_config('notify_on_release' => '1')
+end
+```
+
+```ruby
+control_groups_entry 'limited' do
+  cpu('cpu.max' => '10000 100000')
+  manage_runtime false
+end
+```

documentation/control_groups_install.md

@@ -0,0 +1,37 @@
+# control_groups_install
+
+Install and remove the libcgroup packages, service units, and generated configuration files used by this cookbook.
+
+## Actions
+
+| Action     | Description                                                                                           |
+| ---------- | ----------------------------------------------------------------------------------------------------- |
+| `:install` | Installs packages, writes the config files, and enables the `cgconfig` and `cgred` services (default) |
+| `:remove`  | Stops the services, deletes the config files, and removes installed packages                          |
+
+## Properties
+
+- `name`: `String`, defaults to `name`. Resource identity.
+- `mounts`: `Hash`, defaults to `ControlGroups.default_mounts`. Mount map written into `/etc/cgconfig.conf`.
+- `manage_runtime`: `Boolean`, defaults to `true`. When `true`, enables and starts the libcgroup systemd units. Set to `false` in cgroup-v2 test environments that cannot mount legacy controller hierarchies.
+
+## Examples
+
+```ruby
+control_groups_install 'default'
+```
+
+```ruby
+control_groups_install 'default' do
+  mounts(
+    cpu: '/sys/fs/cgroup/cpu',
+    memory: '/sys/fs/cgroup/memory'
+  )
+end
+```
+
+```ruby
+control_groups_install 'default' do
+  manage_runtime false
+end
+```

documentation/control_groups_rule.md

@@ -0,0 +1,45 @@
+# control_groups_rule
+
+Define or remove an entry in `/etc/cgrules.conf`.
+
+## Actions
+
+| Action     | Description                                         |
+| ---------- | --------------------------------------------------- |
+| `:create`  | Adds or updates the rule (default)                  |
+| `:delete`  | Removes the rule target from `/etc/cgrules.conf`    |
+
+## Properties
+
+- `user`: `String`, defaults to the `name` property. User segment of the cgrules target.
+- `command`: `String`, defaults to `nil`. Optional command segment of the target.
+- `controllers`: `Array`, required. Controllers bound to the rule.
+- `destination`: `String`, required. Destination group name.
+- `mounts`: `Hash`, defaults to `ControlGroups.default_mounts`. Mount map written into `/etc/cgconfig.conf` before validating destinations.
+- `manage_runtime`: `Boolean`, defaults to `true`. When `true`, enables and starts the libcgroup systemd units. Set to `false` in Dokken or other cgroup-v2 test environments.
+
+## Examples
+
+```ruby
+control_groups_rule 'alice' do
+  controllers %w(cpu memory)
+  destination 'limited'
+end
+```
+
+```ruby
+control_groups_rule 'alice' do
+  command 'stress-ng'
+  controllers ['cpu']
+  destination 'limited'
+end
+```
+
+```ruby
+control_groups_rule 'alice' do
+  command 'stress-ng'
+  controllers %w(cpu memory)
+  destination 'limited'
+  manage_runtime false
+end
+```