Values variants documentation

content/blog/2026-08-04-variants-folder-structure.adoc

@@ -0,0 +1,112 @@
+---
+ date: 2026-08-04
+ title: Introducing the variants folder structure
+ summary: Patterns can now organize per-cluster values files under a variants/ directory, keeping the repository root clean and making multi-variant deployments easier to manage
+ author: Michele Baldessari
+ blog_tags:
+ - patterns
+ - configuration
+ - gitops
+ - clustergroup
+---
+:toc:
+:imagesdir: /images
+
+== Preamble
+
+As validated patterns grow in complexity, the repository root can become cluttered with
+numerous `values-<clusterGroupName>.yaml` files. A pattern that supports a hub, a
+standalone deployment, and several managed cluster groups might have half a dozen values
+files sitting alongside charts, overrides, scripts, and everything else.
+
+Starting with patterns-operator 0.0.78, clustergroup chart v0.9.57, and acm-chart v0.2.10,
+patterns can adopt a new *variant-based directory layout* that groups per-cluster values
+files under a `variants/` directory. This keeps the repository root focused on truly
+global concerns while making it immediately clear which files belong to which deployment
+scenario.
+
+== What changed
+
+A new `main.variant` field in `values-global.yaml` replaces (or supplements)
+`main.clusterGroupName`. The two fields are functionally equivalent, but when
+`main.variant` is set the framework looks for values files inside
+`variants/<variant>/` instead of the repository root.
+
+=== Old flat layout
+
+[source,text]
+----
+.
+├── values-global.yaml
+├── values-hub.yaml
+├── values-group-one.yaml
+├── values-standalone.yaml
+├── charts/
+└── overrides/
+----
+
+=== New variant layout
+
+[source,text]
+----
+.
+├── values-global.yaml
+├── charts/
+├── overrides/
+└── variants/
+    ├── hub/
+    │   ├── values-hub.yaml
+    │   └── values-group-one.yaml
+    └── standalone/
+        └── values-standalone.yaml
+----
+
+The framework detects the variant layout automatically when a top-level `variants/`
+directory is present in the pattern's git repository.
+
+== How to use it
+
+In `values-global.yaml`, set `main.variant` instead of `main.clusterGroupName`:
+
+[source,yaml]
+----
+main:
+  variant: hub
+----
+
+Then move your per-cluster values files into `variants/hub/` (or whichever variant
+name you chose). Running `./pattern.sh make install` deploys the variant specified in
+`main.variant`.
+
+To deploy a different variant, change the `variant` field before installing:
+
+[source,yaml]
+----
+main:
+  variant: standalone
+----
+
+If both `main.variant` and `main.clusterGroupName` are set, `variant` takes precedence.
+
+== Backward compatibility
+
+Existing patterns that use the flat layout with `main.clusterGroupName` continue to work
+without any changes. The variant layout is opt-in: you adopt it by creating a `variants/`
+directory and switching to `main.variant`. There is no migration deadline and no plan to
+remove the flat layout.
+
+Managed cluster groups also work with both layouts. The `values-{name}.yaml` file for a
+managed cluster group can live either at the repository root or under
+`variants/{variant}/`, depending on which layout the pattern uses.
+
+== Documentation updates
+
+The following documentation pages have been updated to cover the new layout:
+
+* link:/learn/values-global-configuration/#main-variant[Global configuration reference] now documents the `main.variant` field and the variant directory structure.
+* link:/learn/vp_openshift_framework/[Validated pattern structure] shows both the flat and variant directory trees side by side.
+* link:/learn/clustergroup-in-values-files/[ClusterGroup in values files] and the managed cluster groups section reference both `main.clusterGroupName` and `main.variant`.
+* link:/values-files/[Exploring values files] mentions the newer layout option.
+
+For full details on all `values-global.yaml` fields, see the
+link:/learn/values-global-configuration/[Global configuration reference].

content/learn/clustergroup-in-values-files.adoc

@@ -19,7 +19,7 @@ ClusterGroup serves as a centralized control mechanism, enabling the grouping of
 
 In the validated patterns framework, the ClusterGroup holds a pivotal role, defined as an individual entity or a collection of clusters, each representing a unique configuration class. This foundational concept uses Helm charts and Kubernetes features to determine its attributes.
 
-Typically, a ClusterGroup represents a singular cluster, serving as the foundation for each validated pattern. However, it can also encompass managed ClusterGroups tailored for replication or scaling efforts. Each pattern requires at least one ClusterGroup, with the primary one often named arbitrarily. This designation is defined in `values-global.yaml` under the key `main.clusterGroupName`, with "Hub" commonly used as a default. Alternatively, other names are acceptable. For example, if `main.clusterGroupName` is "hub," the framework searches for `values-hub.yaml` in the pattern's root directory. It's important to note that the main ClusterGroup is typically a singleton and may incorporate Red Hat Advanced Cluster Management (RHACM) if part of the pattern.
+Typically, a ClusterGroup represents a singular cluster, serving as the foundation for each validated pattern. However, it can also encompass managed ClusterGroups tailored for replication or scaling efforts. Each pattern requires at least one ClusterGroup, with the primary one often named arbitrarily. This designation is defined in `values-global.yaml` under the key `main.clusterGroupName` or `main.variant`, with "hub" commonly used as a default. Alternatively, other names are acceptable. For example, if `main.clusterGroupName` is "hub," the framework searches for `values-hub.yaml` in the pattern's root directory. With the newer `main.variant` layout, the framework searches for the values file inside `variants/hub/` instead. See link:/learn/values-global-configuration/#main-variant[`main.variant`] for details. It's important to note that the main ClusterGroup is typically a singleton and may incorporate Red Hat Advanced Cluster Management (RHACM) if part of the pattern.
 
 Additionally, the main ClusterGroup can define `managedClusterGroups` in its values file, specifying characteristics and policies for spoke clusters, which can be singletons or groups.
 

content/learn/values-global-configuration.adoc

@@ -92,6 +92,7 @@ The `main` section defines settings for the primary cluster that manages the pat
 === `main.clusterGroupName`
 
 Identifies the main ClusterGroup, which acts as the hub or starting point for the pattern. A ClusterGroup represents a set of clusters that share nearly identical configurations and serve a common architectural purpose.
+The new variable `main.variant` is 100% equivalent and is preferred.
 
 [source,yaml]
 ----
@@ -101,8 +102,46 @@ main:
 
 The value must match a corresponding `values-<clusterGroupName>.yaml` file in the repository. For example, `clusterGroupName: hub` requires a `values-hub.yaml` file. Most patterns use `hub` for the primary cluster.
 
+[NOTE]
+====
+`main.clusterGroupName` is equivalent to `main.variant`. New patterns should prefer `main.variant` with the `variants/` directory layout described below. Existing patterns that use `main.clusterGroupName` with values files in the repository root continue to work.
+====
+
 For more information about ClusterGroups, see link:/learn/clustergroup-in-values-files/[ClusterGroup in values files].
 
+[id="main-variant"]
+=== `main.variant`
+
+Starting with patterns-operator 0.0.78, clustergroup chart v0.9.57, and acm-chart v0.2.10, patterns can use `main.variant` instead of `main.clusterGroupName` to select which deployment variant to install. The two fields are functionally equivalent, but `variant` uses a different directory layout that keeps the repository root cleaner.
+When both fields are set, `main.variant` takes precedence.
+
+[source,yaml]
+----
+main:
+  variant: hub
+----
+
+When `main.variant` is set, the framework looks for values files inside a `variants/<variant>/` directory instead of the repository root. For example, `variant: hub` maps to `variants/hub/values-hub.yaml`.
+
+A pattern using this layout organizes its values files as follows:
+
+----
+values-global.yaml          <1>
+variants/
+├── hub/                    <2>
+│   ├── values-hub.yaml
+│   └── values-group-one.yaml
+└── standalone/             <3>
+    └── values-standalone.yaml
+----
+<1> `values-global.yaml` stays at the repository root and defines global settings, including the default `variant`.
+<2> The `hub` variant directory contains all values files for the hub ClusterGroup.
+<3> Additional variant directories hold values files for other deployment scenarios, such as a standalone cluster.
+
+Running `./pattern.sh make install` deploys the variant specified in `main.variant`. To deploy a different variant, change the `variant` field in `values-global.yaml` before installing.
+
+Both `main.variant` and `main.clusterGroupName` are supported. If both are set, `main.variant` takes precedence.
+
 [id="main-multisourceconfig"]
 === `main.multiSourceConfig`
 
@@ -138,7 +177,7 @@ For more information about disconnected environments, see link:/learn/disconnect
 [id="example-values-global"]
 == Example `values-global.yaml`
 
-The following example shows a typical `values-global.yaml` file for the Multicloud GitOps pattern:
+The following example shows a `values-global.yaml` file using the newer `variant` layout:
 
 [source,yaml]
 ----
@@ -153,10 +192,19 @@ global:
     installPlanApproval: Automatic
 
 main:
-  clusterGroupName: hub
+  variant: hub
 
   multiSourceConfig:
     enabled: true
+    clusterGroupChartVersion: "0.9.*"
+----
+
+The equivalent configuration using the older flat layout uses `clusterGroupName` instead:
+
+[source,yaml]
+----
+main:
+  clusterGroupName: hub
 ----
 
 For most patterns, the default values provide a working configuration. Customize specific fields only when your environment requires different behavior, such as pinning operator versions, using a single Argo CD instance, or deploying in a disconnected environment.

content/learn/vp_openshift_framework.adoc

@@ -73,6 +73,42 @@ The Multicloud GitOps approach enables centralized management of multiple cloud
 
 First we notice some subdirectories: charts and common, along with `values-` yaml files.
 
+The directory tree above shows the older flat layout, where all `values-<clusterGroupName>.yaml` files sit at the repository root and `values-global.yaml` uses `main.clusterGroupName` to select the primary cluster group.
+
+Starting with patterns-operator 0.0.78, clustergroup chart v0.9.57, and acm-chart v0.2.10, patterns can use a newer variant-based layout. In this layout, the per-cluster values files move into a `variants/` directory, organized by variant name, and `values-global.yaml` uses `main.variant` instead of `main.clusterGroupName`:
+This new directory layout will automatically be used if the pattern's git repository detects a top-level `variants/` sub-folder.
+
+[source,text]
+----
+.
+├── charts
+│   ├── all
+│   └── region
+├── overrides
+│   ├── values-AWS.yaml
+│   └── values-IBMCloud.yaml
+├── pattern-metadata.yaml
+├── pattern.sh
+├── values-global.yaml
+├── values-secret.yaml.template
+└── variants
+    ├── hub
+    │   ├── values-group-one.yaml
+    │   └── values-hub.yaml
+    └── standalone
+        └── values-standalone.yaml
+----
+
+With this layout, `values-global.yaml` specifies the default variant to deploy:
+
+[source,yaml]
+----
+main:
+  variant: hub
+----
+
+Running `./pattern.sh make install` deploys the variant specified in `main.variant`. Both `main.variant` and `main.clusterGroupName` are supported; if both are set, `variant` takes precedence. For a detailed description of these fields, see link:/learn/values-global-configuration/#main-variant[Global configuration reference].
+
 ===  Industrial edge
 
 [source,text]
@@ -278,4 +314,4 @@ global:
   edge:
     clustername: ipbabble-f1
     domain: blueprints.rhecoeng.com
-----
+----

modules/managed-clustergroups-configuration-in-a-clustergroup.adoc

@@ -6,7 +6,7 @@
 
 Configuring managed cluster groups within a ClusterGroup enhances the organizational structure and simplifies resource management. Through the `managedClusterGroups` parameter, you can define and organize clusters based on specific criteria, promoting efficient management and resource allocation within the ClusterGroup. This functionality streamlines management and coordination tasks across the infrastructure. Managed ClusterGroups mirror the configuration of a single cluster, facilitating the deployment of identical applications or implementing minor configuration adjustments across multiple clusters.
 
-This feature implies the existence of a `values-{name}.yaml` file in the pattern directory root, containing the clusterGroup definition for the managed clusterGroup. It can have its subscriptions, applications, namespaces, and projects, which may or may not reflect those of the hub clusterGroup.
+This feature implies the existence of a `values-{name}.yaml` file containing the clusterGroup definition for the managed clusterGroup — either in the pattern directory root (older flat layout) or under `variants/{variant}/` (newer variant layout). It can have its subscriptions, applications, namespaces, and projects, which may or may not reflect those of the hub clusterGroup.
 
 
 [id="Sub-parameters-managed-clustergroups"]

modules/outline-of-a-basic-values-file.adoc

@@ -21,7 +21,7 @@ Global:: Global values refer to configuration settings shared across multiple ch
 Each pattern includes a `values-global.yaml` file, which contains configurations that are automatically incorporated into the application specification processed by the GitOps operator. For a detailed description of each field in `values-global.yaml`, see link:/learn/values-global-configuration/[Global configuration reference].
 
 
-ClusterGroup:: The ClusterGroup holds a specific significance within validated patterns. It defines clusters that are anticipated to share nearly identical configurations, serving a common architectural purpose. A ClusterGroup may consist of one or many members. Conventionally, there is a main ClusterGroup defined in `main.clusterGroupName` in `values-global.yaml`, acting as the hub or starting point for each pattern. Additional ClusterGroups can be managed by the main ClusterGroup through tools like Red Hat Advanced Cluster Management (RHACM).
+ClusterGroup:: The ClusterGroup holds a specific significance within validated patterns. It defines clusters that are anticipated to share nearly identical configurations, serving a common architectural purpose. A ClusterGroup may consist of one or many members. Conventionally, there is a main ClusterGroup defined in `main.clusterGroupName` (or `main.variant` in the newer layout) in `values-global.yaml`, acting as the hub or starting point for each pattern. Additional ClusterGroups can be managed by the main ClusterGroup through tools like Red Hat Advanced Cluster Management (RHACM).
 
 [NOTE]
 ====