Merge pull request #667 from gaurav-nelson/fix-340-info

fix: update instructions for customizing values-global.yaml

Author: mbaldessari

content/learn/values-global-configuration.adoc

@@ -0,0 +1,153 @@
+---
+menu:
+  learn:
+    parent: Validated patterns frameworks
+title: Global configuration reference
+weight: 55
+aliases: /learn/values-global-configuration/
+---
+
+:toc:
+:imagesdir: /images
+:_content-type: ASSEMBLY
+include::modules/comm-attributes.adoc[]
+
+[id="values-global-configuration"]
+= Global configuration reference
+
+Every validated pattern includes a `values-global.yaml` file at the repository root. This file defines configuration settings that apply across all clusters and environments in the pattern.
+
+[id="global-section"]
+== `global` section
+
+The `global` section contains settings that Helm distributes to all sub-charts in the pattern.
+
+[id="global-pattern"]
+=== `global.pattern`
+
+Specifies the name of the validated pattern. The framework uses this value internally to identify the pattern.
+
+[source,yaml]
+----
+global:
+  pattern: multicloud-gitops
+----
+
+Do not change this value unless you are creating a new pattern.
+
+[id="global-options"]
+=== `global.options`
+
+The `options` block sets default behaviors for operator management and ArgoCD synchronization across all clusters.
+
+[source,yaml]
+----
+global:
+  options:
+    useCSV: false
+    syncPolicy: Automatic
+    installPlanApproval: Automatic
+----
+
+.Options fields
+[cols="2,1,5",options="header"]
+|===
+| Field | Default | Description
+
+| `syncPolicy`
+| `Automatic`
+| Sets the default ArgoCD synchronization policy. `Automatic` syncs changes from Git to the cluster without manual intervention. `Manual` requires an administrator to trigger each sync.
+
+| `installPlanApproval`
+| `Automatic`
+| Controls how Operator Lifecycle Manager (OLM) handles operator upgrades. With `Automatic`, operators check for and apply updates periodically. `Manual` requires an administrator to approve each upgrade.
+
+| `useCSV`
+| `false`
+| Determines whether subscriptions use specific `ClusterServiceVersions` (CSV) for operator installation. When set to `false`, the subscription channel determines which version to install. Set to `true` when you need to pin operators to specific versions.
+|===
+
+[id="main-section"]
+== `main` section
+
+The `main` section defines settings for the primary cluster that manages the pattern.
+
+[id="main-clustergroupname"]
+=== `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.
+
+[source,yaml]
+----
+main:
+  clusterGroupName: hub
+----
+
+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.
+
+For more information about ClusterGroups, see link:/learn/clustergroup-in-values-files/[ClusterGroup in values files].
+
+[id="main-multisourceconfig"]
+=== `main.multiSourceConfig`
+
+Controls whether ArgoCD uses multi-source applications, enabling Helm charts to be fetched from external repositories in addition to the local Git repository.
+
+[source,yaml]
+----
+main:
+  multiSourceConfig:
+    enabled: true
+----
+
+.multiSourceConfig fields
+[cols="2,1,5",options="header"]
+|===
+| Field | Default | Description
+
+| `enabled`
+| `true`
+| Enables multi-source ArgoCD applications. This is the recommended setting for most deployments.
+
+| `clusterGroupChartVersion`
+| (optional)
+| Constrains the version of the ClusterGroup Helm chart to fetch. Accepts semver ranges such as `0.9.*`.
+
+| `helmRepoUrl`
+| (optional)
+| Overrides the Helm chart repository URL. Use this for disconnected or air-gapped environments where charts are hosted on an internal registry.
+|===
+
+For more information about disconnected environments, see link:/learn/disconnected-installation/[Disconnected installation].
+
+[id="example-values-global"]
+== Example `values-global.yaml`
+
+The following example shows a typical `values-global.yaml` file for the Multicloud GitOps pattern:
+
+[source,yaml]
+----
+---
+global:
+  pattern: multicloud-gitops
+
+  options:
+    useCSV: false
+    syncPolicy: Automatic
+    installPlanApproval: Automatic
+
+main:
+  clusterGroupName: hub
+
+  multiSourceConfig:
+    enabled: true
+----
+
+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 or deploying in a disconnected environment.
+
+[id="additional-resources"]
+== Additional resources
+
+* link:/values-files/[Exploring values files]
+* link:/learn/clustergroup-in-values-files/[ClusterGroup in values files]
+* link:/learn/disconnected-installation/[Disconnected installation]
+* link:/learn/vp_add_specific_ops_to_pattern/[Adding a specific operator version to a pattern]

content/learn/workflow.adoc

@@ -38,26 +38,16 @@ $ cp values-secret.yaml.template ~/values-secret.yaml
 $ vi ~/values-secret.yaml
 ---- 
 
-. Customize the deployment for your cluster. Customization involves updating the `values-global.yaml` file with configurations specific to your cluster environment.
-.. Edit the `values-global.yaml` file:
+. Optional: Customize the deployment for your cluster. The `values-global.yaml` file contains global settings such as the ArgoCD sync policy, operator install plan approval, and the cluster group name. Review the file and update any values that your environment requires.
 +
-[source,terminal]
+For a description of each field, see link:/learn/values-global-configuration/[Global configuration reference].
 +
-----
-$ vi values-global.yaml
-----
-.. Commit the updated `values-global.yaml` file to the repository:
+If you make changes, commit and push them:
 +
 [source,terminal]
-+
-----
-$ git commit values-global.yaml
-----
-.. Push the committed changes:
-+
-[source,terminal]
-
 ----
+$ git add values-global.yaml
+$ git commit -m "Customize values-global for my cluster"
 $ git push
 ----
 

content/patterns/ansible-edge-gitops-kasten/getting-started.md

@@ -211,13 +211,12 @@ To install a collection that is not currently installed:
     git push origin my-branch
     ```
 
-1. Customize the deployment for your cluster (Optional - the defaults in values-global.yaml are designed to work in AWS):
+1. Optional: Customize the deployment for your cluster. The defaults in `values-global.yaml` are designed to work in AWS. For a description of each field, see [Global configuration reference](/learn/values-global-configuration/). If you make changes, create a branch, commit, and push:
 
    ```sh
    git checkout -b my-branch
-   vi values-global.yaml
    git add values-global.yaml
-   git commit values-global.yaml
+   git commit -m "Customize values-global for my cluster"
    git push origin my-branch
    ```
 

content/patterns/ansible-edge-gitops/getting-started.adoc

@@ -182,25 +182,14 @@ This is the username and password that you use to log in to link:https://catalog
 $ git checkout -b my-branch
 ----
 
-. Edit the `values-global.yaml` file to customize the deployment for your cluster. The defaults in `values-global.yaml` are designed to work in AWS. For example:
+. Optional: Edit the `values-global.yaml` file to customize the deployment for your cluster. The defaults are designed to work in AWS. For a description of each field, see link:/learn/values-global-configuration/[Global configuration reference].
 +
-[source,terminal]
-----
-$ vi values-global.yaml
-----
-
-. Add the changes to the staging area by running the following command:
+If you make changes, stage and commit them:
 +
 [source,terminal]
 ----
 $ git add values-global.yaml
-----
-
-. Commit the changes by running the following command:
-+
-[source,terminal]
-----
-$ git commit -m "any updates"
+$ git commit -m "Customize values-global for my cluster"
 ----
 
 . Push the changes to your forked repository:

content/patterns/devsecops/getting-started.md

@@ -114,12 +114,11 @@ When you create a fine-grained token, you must also configure these settings:
    vi ~/values-secret.yaml
    ```
 
-1. Customize the deployment for your cluster. Change the appropriate values in `values-global.yaml`
+1. Optional: Customize the deployment for your cluster. The `values-global.yaml` file contains global settings for the pattern. For a description of each field, see [Global configuration reference](/learn/values-global-configuration/). If you make changes, commit and push them:
 
    ```sh
-   vi values-global.yaml
    git add values-global.yaml
-   git commit values-global.yaml
+   git commit -m "Customize values-global for my cluster"
    git push origin my-branch
    ```
 

content/patterns/federated-edge-observability/getting-started.adoc

@@ -184,25 +184,14 @@ Certificates for the OpenTelemetry collector infrastructure. `Snakeoil` that is,
 $ git checkout -b my-branch
 ----
 
-. Edit the `values-global.yaml` file to customize the deployment for your cluster. The defaults in `values-global.yaml` are designed to work in AWS. For example:
+. Optional: Edit the `values-global.yaml` file to customize the deployment for your cluster. The defaults are designed to work in AWS. For a description of each field, see link:/learn/values-global-configuration/[Global configuration reference].
 +
-[source,terminal]
-----
-$ vi values-global.yaml
-----
-
-. Add the changes to the staging area by running the following command:
+If you make changes, stage and commit them:
 +
 [source,terminal]
 ----
 $ git add values-global.yaml
-----
-
-. Commit the changes by running the following command:
-+
-[source,terminal]
-----
-$ git commit -m "No updates"
+$ git commit -m "Customize values-global for my cluster"
 ----
 
 . Push the changes to your forked repository:

content/patterns/gaudi-rag-chat-qna/gaudi-rag-chat-qna-getting-started.adoc

@@ -103,23 +103,12 @@ If the cluster is behind proxy remember to change proxy values of fields `gaudil
 git checkout -b my-branch
 ----
 +
-[source,terminal]
-----
-vi values-global.yaml
-----
+For a description of each field in `values-global.yaml`, see link:/learn/values-global-configuration/[Global configuration reference]. Edit the file, then commit and push:
 +
 [source,terminal]
 ----
 git add values-global.yaml
-----
-+
-[source,terminal]
-----
-git commit values-global.yaml
-----
-+
-[source,terminal]
-----
+git commit -m "Customize values-global for my cluster"
 git push origin my-branch
 ----
 

content/patterns/medical-diagnosis-amx/getting-started.adoc

@@ -108,12 +108,11 @@ By default, Vault password policy generates the passwords for you. However, you
 When defining a custom password for the database users, avoid using the `$` special character as it gets interpreted by the shell and will ultimately set the incorrect desired password.
 ====
 
-. To customize the deployment for your cluster, update the `values-global.yaml` file by running the following commands:
+. To customize the deployment for your cluster, update the `values-global.yaml` file. For a description of each field, see link:/learn/values-global-configuration/[Global configuration reference]. Run the following command to create a branch:
 +
 [source,terminal]
 ----
 $ git checkout -b my-branch
-$ vi values-global.yaml
 ----
 +
 Replace 'bucketSource' value. User can set any bucket name without special signs (besides '-') and numbers.

content/patterns/medical-diagnosis/getting-started.adoc

@@ -242,12 +242,7 @@ When defining a custom password for the database users, avoid using the `$` spec
 $ git checkout -b my-branch
 ----
 
-. Edit the `values-global.yaml` updating the S3 and datacenter details. 
-+
-[source,terminal]
-----
-$ vi values-global.yaml
-----
+. Edit the `values-global.yaml` file to update the S3 and datacenter details. For a description of each field, see link:/learn/values-global-configuration/[Global configuration reference].
 +
 .Example edited `values-global.yaml` file
 +

content/patterns/multicloud-gitops-Portworx/getting-started.md

@@ -49,13 +49,12 @@ service](https://console.redhat.com/openshift/create).
     vi ~/values-secret-multicloud-gitops-pxe.yaml
     ```
 
-5. Customize the deployment for your cluster.
+5. Optional: Customize the deployment for your cluster. The `values-global.yaml` file contains global settings for the pattern. For a description of each field, see [Global configuration reference](/learn/values-global-configuration/). If you make changes, create a branch, commit, and push:
 
    ```sh
    git checkout -b my-branch
-   vi values-global.yaml
    git add values-global.yaml
-   git commit values-global.yaml
+   git commit -m "Customize values-global for my cluster"
    git push origin my-branch
    ```