The acm-policy-samples repository is a collection of Red Hat Advanced Cluster Management (RHACM) sample policies designed to demonstrate best practices for Kubernetes cluster governance and policy management. Written primarily in Shell, the repository provides a comprehensive framework for managing policies across multiple cluster environments using GitOps principles and kustomize configuration management.
The repository addresses a specific operational challenge: many organizations require that policy changes be deployed sequentially through development, quality assurance, and production environments with the ability to block changes outside maintenance windows. RHACM natively lacks a control process for managing policy changes across managed cluster environments, so this repository showcases recommended approaches for achieving these requirements while maintaining code quality and following GitOps best practices. The core goal is to enable consistent policy deployment across all clusters without requiring multiple copies of the same policy or maintaining a one-to-one ratio between placements and policies.
The repository is organized around a kustomize-based file structure with a policies directory containing policy definitions intended for deployment across all environments. Environment-specific overlays are stored in subdirectories under environments, where namespace names, PolicySet naming conventions, and ClusterSet selections are configured. A local-cluster configuration allows the ACM hub itself to be included in cluster management when deployed to the production environment. The repository recently underwent significant updates in August 2025, including the addition of README files to every policy documenting required ACM versions, dependencies, and other relevant notes. All OLM Operators are now deployed using OperatorPolicy, and kustomization configurations were consolidated into a common folder for reuse as kustomize components.
The repository enforces strict build and validation rules through CI scripts located in the build and .github directories. These scripts validate PolicyGenerator builds, ensure YAML conforms to Custom Resource Definitions, enforce consistent file formatting with empty line endings and no trailing whitespace, and verify all YAML files include the document separator statement. The specific validation requirements are documented in the policy-prerequisites.md file.
The cluster management strategy employs a ClusterSet naming convention matching environment names, such as dev-clusters, qa-clusters, and prod-clusters. Feature-level control is achieved through labels applied to ManagedCluster objects, allowing fine-grained control over which clusters receive specific policy changes. For example, a logging-type label can be used to manage transitions between different logging stacks. Placements are kept minimal and reusable, with standard selectors for all clusters, hub-only, and all-except-hub scenarios. Feature-flag-based placements are generated dynamically using a naming convention of ft-LabelName--LabelValue.
The repository supports two release management approaches: tag-based releases on a main branch for simpler management, and branch-based releases for greater control over which changes appear in each environment. A separate policy-release-management repository manages versioning and releases through ArgoCD Applications and ApplicationSets. The intersection of chosen Placement and ClusterSet membership determines final deployment targets, allowing the same policy to be reused across environments while controlling deployment timing and scope.
GitGenius activity data shows minimal but focused engagement, with a median and mean issue or pull request response latency of 18 hours across tracked items. Primary contributors include brian-jarvis and ch-stark, each with one recorded event. The repository shares overlapping contributors with the perses and keycloak projects, indicating potential cross-project collaboration or shared team involvement.
