Skip to content

feat: Add system cleanup-state subcommand#41

Open
aaljewarane wants to merge 2 commits into
aws:mainfrom
aaljewarane:system-cleanup-state
Open

feat: Add system cleanup-state subcommand#41
aaljewarane wants to merge 2 commits into
aws:mainfrom
aaljewarane:system-cleanup-state

Conversation

@aaljewarane

Copy link
Copy Markdown

Summary

Adds ec2-macos-utils system cleanup-state, which removes well-known macOS state from the running system that must not be carried into an image (AMI) built from an instance. Initially this removes the macOS cached network interface configuration (/Library/Preferences/SystemConfiguration/NetworkInterfaces.plist), which affects startup health of networking on EC2 Mac instances launched from derived images.

  • New system subcommand group for system provisioning & helper utilities.
  • cleanup-state removes each well-known state entry beneath the system root; absent state is skipped, removal continues through errors and reports them all, and a --dry-run flag reports actions without removing anything. Requires root.
  • The cleanup targets the running system only; the target root is an internal abstraction to permit future targets (e.g. external volumes) and is intentionally not exposed as a flag.
  • Unit tests for the state cleaner (removal, recursion, dry run, error joining, cancellation, and cleaner isolation).
  • Generated command docs.

This supports ec2-macos-init clean delegating OS-level cleanup to ec2-macos-utils by default (companion PR in aws/ec2-macos-init).

Testing

  • Builds darwin/amd64 + arm64; go vet clean; all unit tests pass.
  • Validated end to end on mac1.metal (x86_64, macOS 15.7.7) and mac2.metal (arm64, macOS 26.3.1): removal, idempotence, dry run, plist regeneration on reboot with healthy networking, and integration with ec2-macos-init clean.

… cleanup-state' to remove well-known OS state that must not be carried into an image (AMI) built from an instance. Initially this removes the macOS cached network interface configuration (NetworkInterfaces.plist), which affects startup health of networking for EC2 Mac instances launched from derived images. The cleanup targets the running system only. The target root is an internal abstraction to permit future targets (e.g. external volumes) and is intentionally not exposed as a flag. A --dry-run flag reports actions without removing state. This supports 'ec2-macos-init clean' delegating OS level cleanup to ec2-macos-utils by default.
@aaljewarane
aaljewarane marked this pull request as draft July 20, 2026 22:27
@aaljewarane
aaljewarane marked this pull request as ready for review July 20, 2026 22:44
@jahkeup jahkeup added the enhancement New feature or request label Jul 20, 2026
AhmedMCS

This comment was marked as low quality.

…OS state list out of a hardcoded slice into a TOML config. A default config is embedded in the binary; an external file at /usr/local/aws/ec2-macos-utils/cleanup-state.toml, when present, replaces it entirely, letting the list grow and letting customers configure it without a rebuild. A config that cannot be read or parsed is an error so a broken config never silently skips cleanup.
@aaljewarane

aaljewarane commented Jul 23, 2026

Copy link
Copy Markdown
Author

Validation on EC2 Mac hardware

Validated ec2-macos-utils system cleanup-state (including the new TOML config) on:

Family Arch macOS
mac1.metal x86_64 15.7.7
mac2.metal arm64 26.3.1

Built from this branch's working tree. The real boot-generated NetworkInterfaces.plist
was present beforehand (mac1 6224 B, mac2 5886 B). Results were identical on both families.

External config path tested: /usr/local/aws/ec2-macos-utils/cleanup-state.toml.

# Case Expected Result
1 run without sudo root guard, exit 1 PASS
2 cleanup-state --help exit 0 PASS
3 --dry-run, plist present reports only, does not remove, exit 0 PASS
4 real run removes plist, logs desc + rationale, exit 0 PASS
5 second run "State not present", exit 0 (idempotent) PASS
6 external config present replaces default: custom removed, plist kept PASS
7 malformed external config hard-fail exit 1, no state touched PASS

Sample output, case 4 (mac2):

level=info msg="Removed state (macOS cached interface configuration: affects startup health of networking for EC2 Mac instances)" path=/Library/Preferences/SystemConfiguration/NetworkInterfaces.plist

Sample output, case 7:

level=error msg="Unable to load cleanup-state configuration" error="parse cleanup-state config (...): toml: line 1 ..."
Error: parse cleanup-state config (...)   # exit 1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants