diff --git a/content/learn/getting-started-multi-cloud-gitops.adoc b/content/learn/getting-started-multi-cloud-gitops.adoc index c678aab72..9089c95e7 100644 --- a/content/learn/getting-started-multi-cloud-gitops.adoc +++ b/content/learn/getting-started-multi-cloud-gitops.adoc @@ -39,7 +39,7 @@ Other patterns build upon these concepts, making this an ideal starting point fo * An OpenShift cluster ** To create an OpenShift cluster, go to the https://console.redhat.com/[Red Hat Hybrid Cloud console]. - ** Select *Services \-> Containers \-> Create cluster*. + ** Select *OpenShift \-> Red Hat OpenShift Container Platform \-> Create cluster*. ** The cluster must have a dynamic `StorageClass` to provision `PersistentVolumes`. Verify that a dynamic `StorageClass` exists before creating one by running the following command: + [source,terminal] @@ -56,6 +56,8 @@ gp2-csi ebs.csi.aws.com gp3-csi ebs.csi.aws.com true ---- ++ +For more information about creating a dynamic `StorageClass`, see the https://docs.openshift.com/container-platform/latest/storage/dynamic-provisioning.html[Dynamic provisioning]. * Optional: A second OpenShift cluster for multicloud demonstration. //Replaced git and podman prereqs with the tooling dependencies page @@ -167,8 +169,8 @@ Choosing a Community Operator warns that Red Hat does not certify Community Oper .. Select a *Version* (if more than one is available). .. Select an *Installation mode*: -*** *All namespaces on the cluster (default)* installs the Operator in the default `openshift-operators` namespace to watch and be made available to all namespaces in the cluster. This option is not always available. -*** *A specific namespace on the cluster* allows you to choose a specific, single namespace in which to install the Operator. The Operator will only watch and be made available for use in this single namespace. ++ +The only supported mode for this Operator is *All namespaces on the cluster (default)*. This installs the Operator in the default `openshift-operators` namespace to watch and be made available to all namespaces in the cluster. This option is not always available. .. Select *Automatic* or *Manual* approval strategy. @@ -217,7 +219,7 @@ A pop-up error with the message "Oh no! Something went wrong." might appear duri The {rh-gitops} Operator displays in list of *Installed Operators*. The {rh-gitops} Operator installs the remaining assets and artifacts for this pattern. To view the installation of these assets and artifacts, such as {rh-rhacm-first}, ensure that you switch to *Project:All Projects*. -When viewing the `config-demo` project through the Hub `ArgoCD` UI from the nines menu, it appears stuck in a Degraded state. This is the expected behavior when installing using the OpenShift Container Platform console. +Wait some time for everything to deploy. You can track the progress through the `Hub ArgoCD` UI from the nines menu. The `config-demo` project appears stuck in a `Degraded` state. This is the expected behavior when installing using the OpenShift Container Platform console. * To resolve this you need to run the following to load the secrets into the vault: + diff --git a/content/patterns/multicloud-gitops/_index.adoc b/content/patterns/multicloud-gitops/_index.adoc index 9a9eded5e..fc2f53ecc 100644 --- a/content/patterns/multicloud-gitops/_index.adoc +++ b/content/patterns/multicloud-gitops/_index.adoc @@ -29,5 +29,5 @@ include::modules/mcg-architecture.adoc[leveloffset=+1] [id="next-steps_mcg-index"] == Next steps -* link:mcg-getting-started[Deploy the management hub] using Helm. +* link:mcg-getting-started[Deploy the management hub]. * Add a managed cluster to link:mcg-managed-cluster[deploy the managed cluster piece using ACM]. diff --git a/content/patterns/multicloud-gitops/mcg-cluster-sizing.adoc b/content/patterns/multicloud-gitops/mcg-cluster-sizing.adoc index 8a8743652..6419e382b 100644 --- a/content/patterns/multicloud-gitops/mcg-cluster-sizing.adoc +++ b/content/patterns/multicloud-gitops/mcg-cluster-sizing.adoc @@ -1,6 +1,6 @@ --- title: Cluster sizing -weight: 30 +weight: 40 aliases: /multicloud-gitops/mcg-cluster-sizing/ --- diff --git a/content/patterns/multicloud-gitops/mcg-demo-script.adoc b/content/patterns/multicloud-gitops/mcg-demo-script.adoc index 292592d42..d79647a5a 100644 --- a/content/patterns/multicloud-gitops/mcg-demo-script.adoc +++ b/content/patterns/multicloud-gitops/mcg-demo-script.adoc @@ -1,6 +1,6 @@ --- -title: Demo Script -weight: 60 +title: Verifying the MultiCloud GitOps pattern +weight: 20 aliases: /multicloud-gitops/demo/ --- @@ -11,111 +11,116 @@ include::modules/comm-attributes.adoc[] [id="demo-intro"] -== Introduction -The multicloud gitops pattern is designed to be an entrypoint into the Validated Patterns framework. For more information on Validated Patterns visit our link:/[documentation site] +== Verifying the MultiCloud GitOps pattern -[id="demo-objectives"] +The MultiCloud GitOps is designed to be an entrypoint into the Validated Patterns framework. The pattern includes two applications that can help you verify the installation. The `hello-world` application is a simple web page that prints "Hello World!" and the `config-demo` application is a simple web page that prints a secret that is loaded into the vault. -== Objectives +Verify the applications are successfully deployed by following this procedure. -In this demo you will complete the following: -* Prepare your local workstation -* Deploy the pattern -* Extend the pattern with a small tweak +.Procedure +. Check the *Red Hat OpenShift GitOps Operator* is installed. -[id="getting-started"] +. Launch the *Hub OpenShift ArgoCD* console from nines menu in the top right of the OpenShift console and verify the applications report the status `Healthy` and `Synched`. -== Getting Started +Verify that the *hello-world* application deployed successfully as follows: -* Make sure you have met all the link:/learn/quickstart/#installation_prerequisites[installation prerequisites] -* Follow the link:../mcg-getting-started[Getting Started Guide] to ensure that you have met all of the prerequisites +. In the OpenShift console go to the *Networking* -> *Routes* menu options. -[NOTE] -==== -This demo begins after `./pattern.sh make install` has been executed -==== - -[id="demo"] - -== Demo - -Now that we have deployed the pattern onto our cluster, with `origin` pointing to your fork and using `my-branch` as the name of the used branch, we can begin to discover what has happened. -You should be able to click on the nine-box and see the following entries: - -image:multicloud-gitops/nine-box.png[] - -If you now click on the "Hub ArgoCD" menu entry you will be taken to the ArgoCD instance with all the applications. - -image:multicloud-gitops/hub-argocd.png[] +. From the *Project:* drop down select the *hello-world* project. +. Click the *Location* URL. This should reveal the following: ++ +[source,terminal] +---- +Hello World! +Hub Cluster domain is 'apps.aws-hub-cluster.openshift.org' +Pod is running on Local Cluster Domain 'apps.aws-hub-cluster.openshift.org' +---- -[id="secrets"] +Verify that the *config-demo* application deployed successfully as follows: -=== Secrets loading +. In the OpenShift console go to the *Networking* -> *Routes* menu options. -By default in the MultiCloud GitOps pattern the secrets get loaded automatically via an out of band process inside the vault running in the OCP cluster. This means that running `./pattern.sh make install` will also call the `load-secrets` makefile target. -This `load-secrets` target will look for a yaml file describing the secrets to be loaded into vault and in case it cannot find one it will use the `values-secret.yaml.template` file in the git repo to try and generate random secrets. +. From the *Project:* drop down select the *config-demo* project. -Let's copy the template to our home folder and reload the secrets: +. Click the *Location* URL. This should reveal the following: ++ [source,terminal] -cp ./values-secret.yaml.template ~/values-secret-multicloud-gitops.yaml -./pattern.sh make load-secrets - +---- +Hub Cluster domain is 'apps.aws-hub-cluster.openshift.org' +Pod is running on Local Cluster Domain 'apps.aws-hub-cluster.openshift.org' +The secret is `secret` +---- -At this point if the `config-demo` application was not green already it should become green in the ArgoCD user interface. +=== Customize the web page +Make a small change to the `hello-world` application to see how the GitOps framework applies the change. -[id="verify"] +.Procedure -=== Verify the test web pages - -If you now click on the `Routes` in the `Networking` menu entry you will see the following network routes: - -image:multicloud-gitops/network-routes.png[] +. Edit `charts/all/hello-world/templates/hello-world-cm.yaml` adding the line `This is a patched version via git`` as shown below: ++ +[source,terminal] +---- + + +

Hello World!

++

This is a patched version via git

+
+

+ Hub Cluster domain is '{{ .Values.global.hubClusterDomain }}'
+---- + +. Add the changes to the staging area by running the following command: ++ +[source,terminal] +---- +$ git add -u +---- -Clicking on the `hello-world` application should show a small demo app that prints "Hello World!": +. Commit this change by running the following command: ++ +[source,terminal] +---- +$ git commit -a -m "test a change" +---- -image:multicloud-gitops/hello-world.png[] +. Push the change to the remote repository by running the following command: ++ +[source,terminal] +---- +$ git push origin my-branch +---- -Once the secrets are loaded correctly inside the vault, clicking on the `config-demo` route should display a small application where said secret is shown: +ArgoCD will apply the change to the `hello-world` application. -image:multicloud-gitops/config-demo.png[] +Verify that the update to the *hello-world* application is successfully applied as follows: -=== Make a small change to the test web pages +. In the OpenShift console go to the *Networking* -> *Routes* menu options. -Now we can try and tweak the hello-world application and add the below line in -the `charts/all/hello-world/templates/hello-world-cm.yaml` file: -[source,patch] -diff --git a/charts/all/hello-world/templates/hello-world-cm.yaml b/charts/all/hello-world/templates/hello-world-cm.yaml -index e59561ca..bd416bc6 100644 ---- a/charts/all/hello-world/templates/hello-world-cm.yaml -+++ b/charts/all/hello-world/templates/hello-world-cm.yaml -@@ -14,6 +14,7 @@ data: - - -

Hello World!

-+

This is a patched version via git

-
-

- Hub Cluster domain is '{{ .Values.global.hubClusterDomain }}'
+. From the *Project:* drop down select the *hello-world* project. +. Click the *Location* URL. This should reveal the following: ++ +[source,terminal] +---- +Hello World! -Once we commit the above change via `git commit -a -m "test a change"` and run -`git push origin my-branch` we will be able to observe argo applying the above -change: +This is a patched version via git -image:multicloud-gitops/config-demo-patched.png[] +Hub Cluster domain is 'apps.aws-hub-cluster.openshift.org' +Pod is running on Local Cluster Domain 'apps.aws-hub-cluster.openshift.org' +---- [id="summary"] == Summary -You did it! You have completed the deployment of the MultiCloud GitOps pattern -and you made a small local change and applied it via GitOps! Hopefully you are -getting ideas of how you can take advantage of our GitOps framework to deploy -and manage your applications. +You did it! You have completed the deployment of the MultiCloud GitOps pattern and you made a small local change and applied it using GitOps. + +Hopefully you are getting ideas of how you can take advantage of our GitOps framework to deploy and manage your applications. -For more information on Validated Patterns visit our -link:https://validatedpatterns.io/[website] +For more information about Validated Patterns visit our +link:https://validatedpatterns.io/[website]. diff --git a/content/patterns/multicloud-gitops/mcg-getting-started.adoc b/content/patterns/multicloud-gitops/mcg-getting-started.adoc index b8fb73ac0..ba2803ed0 100644 --- a/content/patterns/multicloud-gitops/mcg-getting-started.adoc +++ b/content/patterns/multicloud-gitops/mcg-getting-started.adoc @@ -14,7 +14,7 @@ include::modules/mcg-deploying-mcg-pattern.adoc[leveloffset=1] [id="next-steps_mcg-getting-started"] == Next steps -After the management hub is set up and works correctly, attach one or more managed clusters to the architecture. +After the management hub is set up and working correctly, attach one or more managed clusters to the architecture. For instructions on deploying the edge, refer to link:../mcg-managed-cluster/[Attach a managed cluster (edge) to the management hub]. diff --git a/content/patterns/multicloud-gitops/mcg-managed-cluster.adoc b/content/patterns/multicloud-gitops/mcg-managed-cluster.adoc index 4128edce3..910888d6b 100644 --- a/content/patterns/multicloud-gitops/mcg-managed-cluster.adoc +++ b/content/patterns/multicloud-gitops/mcg-managed-cluster.adoc @@ -1,6 +1,6 @@ --- title: Managed cluster sites -weight: 20 +weight: 30 aliases: /multicloud-gitops/mcg-managed-cluster/ --- @@ -13,6 +13,10 @@ include::modules/comm-attributes.adoc[] [id="attach-managed-cluster"] = Attach a managed cluster (edge) to the management hub +The use of this Multicloud GitOps pattern depends on having at least one running Red Hat OpenShift cluster. + +When you install the multi-cloud GitOps pattern, a hub cluster is setup. The hub cluster serves as the central point for managing and deploying applications across multiple clusters. + include::modules/mcg-understanding-rhacm-requirements.adoc[leveloffset=+1] include::modules/mcg-deploying-managed-cluster-using-rhacm.adoc[leveloffset=+1] @@ -26,4 +30,44 @@ include::modules/comm-designate-cluster-as-managed-cluster-site.adoc[leveloffset == Verification -Go to your managed cluster (edge) OpenShift console and check for the `open-cluster-management-agent` pod being launched. It might take a while for the RHACM agent and `agent-addons` to launch. After that, the OpenShift GitOps Operator is installed. On successful installation, launch the OpenShift GitOps (ArgoCD) console from the top right of the OpenShift console. +. Go to your managed cluster (edge) OpenShift console and check for the `open-cluster-management-agent` pod being launched. + +[NOTE] +==== +It might take a while for the RHACM agent and `agent-addons` to launch. +==== + +. Check the *Red Hat OpenShift GitOps Operator* is installed. + +. Launch the *Group-One OpenShift ArgoCD* console from nines menu in the top right of the OpenShift console. Verify the applications report the status `Healthy` and `Synched`. + +Verify that the *hello-world* application deployed successfully as follows: + +. Navigate to the *Networking* -> *Routes* menu options on your managed cluster (edge) OpenShift. + +. From the *Project:* drop down select the *hello-world* project. + +. Click the *Location URL*. This should reveal the following: ++ +[source,terminal] +---- +Hello World! + +Hub Cluster domain is 'apps.aws-hub-cluster.openshift.org' +Pod is running on Local Cluster Domain 'apps.aws-hub-cluster.openshift.org' +---- + +Verify that the *config-demo* application deployed successfully as follows: + +. Navigate to the *Networking* -> *Routes* menu options on your managed cluster (edge) OpenShift. + +. Select the *config-demo* *Project*. + +. Click the *Location URL*. This should reveal the following: ++ +[source,terminal] +---- +Hub Cluster domain is 'apps.aws-hub-cluster.openshift.org' +Pod is running on Local Cluster Domain 'apps.aws-hub-cluster.openshift.org' +The secret is `secret` +---- diff --git a/modules/comm-designate-cluster-as-managed-cluster-site.adoc b/modules/comm-designate-cluster-as-managed-cluster-site.adoc index 6647a408d..e181b62ee 100644 --- a/modules/comm-designate-cluster-as-managed-cluster-site.adoc +++ b/modules/comm-designate-cluster-as-managed-cluster-site.adoc @@ -10,16 +10,38 @@ To tag the cluster as `clusterGroup=`, complete the follo .Procedure -. To find the new cluster, run the following command: +. To list all managed clusters, run the following command: + [source,terminal] ---- -oc get managedcluster.cluster.open-cluster-management.io +$ oc get managedcluster.cluster.open-cluster-management.io +---- ++ +This will display a list of managed clusters registered in ACM, including their names and statuses. + +. Once you identify the target cluster for example `YOURCLUSTER`, label it with the desired key-value pair to associate it with a group or category. To apply the label, run the following command: ++ +[source,terminal] +---- +$ oc label managedcluster.cluster.open-cluster-management.io/YOURCLUSTER site=managed-cluster ---- -. To apply the label, run the following command: +.Verification + +. Confirm that the label was applied by running the following command: + [source,terminal] ---- -oc label managedcluster.cluster.open-cluster-management.io/YOURCLUSTER site=managed-cluster ----- \ No newline at end of file +$ oc get managedcluster.cluster.open-cluster-management.io/YOURCLUSTER --show-labels +---- ++ +This will display the labels associated with the cluster, verifying that the new label has been successfully added.. + +. Optional: If you’re grouping clusters under a clusterGroup for example `factory`, `devel`, or `prod`, add the clusterGroup label also by running the following command: ++ +[source,terminal] +---- +$ oc label managedcluster.cluster.open-cluster-management.io/YOURCLUSTER clusterGroup= +---- ++ +Replace `` with the appropriate value, such as `factory`. \ No newline at end of file diff --git a/modules/mcg-about-customizing-pattern.adoc b/modules/mcg-about-customizing-pattern.adoc index f145e7f54..cc7ee324b 100644 --- a/modules/mcg-about-customizing-pattern.adoc +++ b/modules/mcg-about-customizing-pattern.adoc @@ -9,11 +9,148 @@ One of the major goals of the Validated Patterns development process is to creat You can customize this demo in different ways. [id="split-config-demo"] -== Split the config-demo across hub and regional clusters +== Customizing the config-demo across hub and regional clusters -Currently hub and regional clusters are reusing the exact same helm chart found at `charts/all/config-demo`. The first customization step could be to split the demo app in two separate charts: one in `charts/hub/config-demo` and one in `charts/region/config-demo`. Once `charts/all/config-demo` has been copied to `charts/hub/config-demo` and `charts/region/config-demo`, you need to include them in the respective `values-hub.yaml` and `values-region-one.yaml`, respectively. +Currently hub and regional clusters are reusing the exact same helm chart found at `charts/all/config-demo`. -After completing this configuration, you can start customizing the two apps and make them output a different web page entirely depending if the pod is running on the hub or on the cluster. +Follow this procedure to split the `config-demo` application across the `hub` and `regional` clusters: + +. Ensure you are in your locally created feature branch by running the following command: ++ +[source,terminal] +---- +$ git checkout my-branch main +---- + +. Run the following commands to create the `charts/hub` directory (the region directory already exists): ++ +[source,terminal] +---- +$ mkdir -p charts/hub +---- + +. Copy the `charts/all/config-demo` to `charts/hub/config-demo` by running the following command: ++ +[source,terminal] +---- +$ cp -r charts/all/config-demo charts/hub/config-demo +---- + +. Copy the `charts/all/config-demo` to `charts/region/config-demo` by running the following command: ++ +[source,terminal] +---- +$ cp -r charts/all/config-demo charts/region/config-demo +---- + +. Edit `config-demo-cm.yaml` in `charts/hub/config-demo/templates` add the line `This is the hub cluster patched version via git`: ++ +[source,terminal] +---- + + +

+ This is the hub cluster patched version via git
+ Hub Cluster domain is '{{ .Values.global.hubClusterDomain }}'
+ Pod is running on Local Cluster Domain '{{ .Values.global.localClusterDomain }}'
+

+

+ The secret is secret +---- + +. Edit `config-demo-cm.yaml` in `charts/hub/config-demo/templates` add the line `This is the hub cluster patched version via git`: ++ +[source,terminal] +---- + + +

+ This is the hub cluster patched version via git
+ Hub Cluster domain is '{{ .Values.global.hubClusterDomain }}'
+ Pod is running on Local Cluster Domain '{{ .Values.global.localClusterDomain }}'
+

+

+ The secret is secret +---- + +. In the root directory of your repository, edit the `values-hub.yaml` file and modify the path as follows: ++ +[source,yaml] +---- +config-demo: + name: config-demo + namespace: config-demo + project: config-demo + path: charts/hub/config-demo +---- + +. In the root directory of your repository, edit the `values-group-one.yaml` file and modify the path as follows: ++ +[source,yaml] +---- +config-demo: + name: config-demo + namespace: config-demo + project: config-demo + path: charts/region/config-demo +---- + +. Add the changes to the staging area by running the following command: ++ +[source,terminal] +---- +$ git add . +---- + +. Commit the changes by running the following command: ++ +[source,terminal] +---- +$ git commit -m "test another change" +---- + +. Push the change to the remote repository by running the following command: ++ +[source,terminal] +---- +$ git push origin my-branch +---- + +ArgoCD will apply the change to the `config-demo` application. + +Verify that the update to the *config-demo* application is successfully applied to your hub cluster as follows: + +. In the OpenShift console associated with your hub cluster go to the *Networking* -> *Routes* menu options. + +. From the *Project:* drop down select the *config-demo* project. + +. Click the *Location* URL. This should reveal the following: ++ +[source,terminal] +---- +This is the hub cluster patched version via git +Hub Cluster domain is 'apps.kevstestcluster.aws.validatedpatterns.io' +Pod is running on Local Cluster Domain 'apps.kevstestcluster.aws.validatedpatterns.io' + +The secret is secret +---- + +Verify that the update to the *config-demo* application is successfully applied to your managed cluster as follows: + +. In the OpenShift console associated with your hub cluster go to the *Networking* -> *Routes* menu options. + +. From the *Project:* drop down select the *config-demo* project. + +. Click the *Location* URL. This should reveal the following: ++ +[source,terminal] +---- +This is the managed cluster +Hub Cluster domain is 'apps.kevstestcluster.aws.validatedpatterns.io' +Pod is running on Local Cluster Domain 'apps.ci-ln-cf2475b-76ef8.aws-2.ci.openshift.org' + +The secret is secret +---- == Rest API addition diff --git a/modules/mcg-architecture.adoc b/modules/mcg-architecture.adoc index 1eec6037b..5dcb49871 100644 --- a/modules/mcg-architecture.adoc +++ b/modules/mcg-architecture.adoc @@ -57,15 +57,15 @@ The following figure provides a schematic diagram showing how secrets are handle .Schematic showing the setup and use of external secrets management image::multicloud-gitops/spi-multi-cloud-gitops-sd-security.png[Schematic showing the setup and use of external secrets management] -* During setup, the token to securely access HashiCorp Vault is stored in Ansible Vault. It is encrypted to protect sensitive content. +1. During setup, the token to securely access HashiCorp Vault is stored in Ansible Vault. It is encrypted to protect sensitive content. -* Red Hat Advanced Cluster Management for Kubernetes acquires the token from Ansible Vault during install and distributes it among the clusters. As a result, you have centralized control over the managed clusters through RHACM. +2. Red Hat Advanced Cluster Management for Kubernetes acquires the token from Ansible Vault during install and distributes it among the clusters. As a result, you have centralized control over the managed clusters through RHACM. -* To allow the cluster access to the external vault, you must set up the external secret management with Helm in this study. OpenShift Gitops is used to deploy the external secret object to a managed cluster. +3. To allow the cluster access to the external vault, you must set up the external secret management. OpenShift Gitops is used to deploy the external secret object to a managed cluster. -* External secret management fetches secrets from HashiCorp Vault by using the token that was generated in step 2 and constantly monitors for updates. +4. External secret management fetches secrets from HashiCorp Vault by using the token that was generated in step 2 and constantly monitors for updates. -* Secrets are created in each namespace, where applications can use them. +5. Secrets are created in each namespace, where applications can use them. [role="_additional-resources"] .Additional resources diff --git a/modules/mcg-deploying-managed-cluster-using-rhacm.adoc b/modules/mcg-deploying-managed-cluster-using-rhacm.adoc index e863b6343..225342180 100644 --- a/modules/mcg-deploying-managed-cluster-using-rhacm.adoc +++ b/modules/mcg-deploying-managed-cluster-using-rhacm.adoc @@ -8,19 +8,23 @@ * An OpenShift cluster ** To create an OpenShift cluster, go to the https://console.redhat.com/[Red Hat Hybrid Cloud console]. - ** Select *Services* -> *Containers* -> *Create cluster*. + ** Select *OpenShift \-> Red Hat OpenShift Container Platform \-> Create cluster*. * Red Hat Advanced Cluster Management (RHACM) web console to join the managed cluster to the management hub + [NOTE] ==== -After RHACM is installed, a message regarding a *Web console update is available*" might be displayed. Follow the instructions and click the *Refresh web console* link. +After RHACM is installed, a message regarding a *Web console update is available* might be displayed. Follow the instructions and click the *Refresh web console* link. ==== .Procedure -. In the left navigation panel of web console, click *local-cluster*. Select *All Clusters*. The RHACM web console is displayed with *Cluster** on the left navigation panel. -. On the *Managed clusters* tab, click *Import cluster*. -. On the *Import an existing cluster* page, enter the cluster name and choose *KUBECONFIG* as the "import mode". Add the tag `clusterGroup=region-one`. Click *Import*. - -Now that RHACM is no longer deploying the managed cluster applications everywhere, you must indicate that the new cluster has the managed cluster role. +. In the left navigation panel of the web console associated with your deployed hub cluster, click *local-cluster*. Select *All Clusters*. The RHACM web console is displayed. +. In the *Managing clusters just got easier* window, click *Import an existing cluster*. +.. Enter the cluster name (you can get this from the login token string for example https://api..:6443) +.. You can leave the *Cluster set* blank. +.. In the *Additional labels* dialog box enter the `key=value` as `clusterGroup=group-one`. +.. Choose *KubeConfig* as the "Import mode". +.. In the *KubeConfig* window paste your KubeConfig content. Click *Next*. +. You can skip the *Automation* screen. Click *Next*. +. Review the summary details and click *Import*. diff --git a/modules/mcg-deploying-mcg-pattern.adoc b/modules/mcg-deploying-mcg-pattern.adoc index a49f4914d..316726e12 100644 --- a/modules/mcg-deploying-mcg-pattern.adoc +++ b/modules/mcg-deploying-mcg-pattern.adoc @@ -4,12 +4,48 @@ [id="deploying-mcg-pattern"] = Deploying the Multicloud GitOps pattern +Multicloud GitOps is a foundational pattern that demonstrates GitOps principles for managing applications across multiple clusters. It provides: + +* A GitOps framework using `ArgoCD` +* Infrastructure-as-Code practices +* Multi-cluster management capabilities +* Template for secure secret management + +Red Hat recommend the Multicloud GitOps pattern as your base pattern because: + +. It establishes core GitOps practices +. Provides a minimal but complete implementation +. Serves as a foundation for other patterns +. Demonstrates key validated patterns concepts + +[NOTE] +==== +Other patterns build upon these concepts, making this an ideal starting point for your validated patterns journey. +==== + .Prerequisites * An OpenShift cluster ** To create an OpenShift cluster, go to the https://console.redhat.com/[Red Hat Hybrid Cloud console]. - ** Select *Services \-> Containers \-> Create cluster*. - ** The cluster must have a dynamic `StorageClass` to provision `PersistentVolumes`. See link:../../multicloud-gitops/mcg-cluster-sizing[sizing your cluster]. + ** Select *OpenShift \-> Red Hat OpenShift Container Platform \-> Create cluster*. + ** The cluster must have a dynamic `StorageClass` to provision `PersistentVolumes`. Verify that a dynamic `StorageClass` exists before creating one by running the following command: ++ +[source,terminal] +---- +$ oc get storageclass -o custom-columns=NAME:.metadata.name,PROVISIONER:.provisioner,DEFAULT:.metadata.annotations."storageclass\.kubernetes\.io/is-default-class" +---- ++ +.Example output ++ +[source,terminal] +---- +NAME PROVISIONER DEFAULT +gp2-csi ebs.csi.aws.com +gp3-csi ebs.csi.aws.com true +---- ++ +For more information about creating a dynamic `StorageClass`, see the https://docs.openshift.com/container-platform/latest/storage/dynamic-provisioning.html[Dynamic provisioning] documentation. + * Optional: A second OpenShift cluster for multicloud demonstration. //Replaced git and podman prereqs with the tooling dependencies page * https://validatedpatterns.io/learn/quickstart/[Install the tooling dependencies]. @@ -21,92 +57,223 @@ public or private cloud by using https://console.redhat.com/openshift/create[Red .Procedure -. Fork the https://github.com/validatedpatterns/multicloud-gitops[multicloud-gitops] repository on GitHub. -. Clone the forked copy of this repository. +. From the https://github.com/validatedpatterns/multicloud-gitops[multicloud-gitops] repository on GitHub, click the Fork button. + +. Clone the forked copy of this repository by running the following command. + [source,terminal] ---- -git clone git@github.com:your-username/multicloud-gitops.git +$ git clone git@github.com:/multicloud-gitops.git ---- -. Create a local copy of the secret values file that can safely include credentials. Run the following commands: +. Navigate to your repository: Ensure you are in the root directory of your Git repository by using: + [source,terminal] ---- -cp values-secret.yaml.template ~/values-secret-multicloud-gitops.yaml +$ cd /path/to/your/repository ---- + +. Run the following command to set the upstream repository: + [source,terminal] ---- -vi ~/values-secret-multicloud-gitops.yaml +$ git remote add -f upstream git@github.com/validatedpatterns/multicloud-gitops.git ---- + +. Verify the setup of your remote repositories by running the following command: + -[WARNING] -==== -Do not commit this file. You do not want to push personal credentials to GitHub. If you do not want to customize the secrets, these steps are not needed. The framework generates a random password for the config-demo application. -==== +[source,terminal] +---- +$ git remote -v +---- ++ +.Example output ++ +[source,terminal] +---- +origin git@github.com:/multicloud-gitops.git (fetch) +origin git@github.com:/multicloud-gitops.git (push) +upstream https://github.com/validatedpatterns/multicloud-gitops.git (fetch) +upstream https://github.com/validatedpatterns/multicloud-gitops.git (push) +---- -. Customize the deployment for your cluster. Run the following command: +. Create a local copy of the secret values file that can safely include credentials. Run the following commands: + [source,terminal] ---- -git checkout -b my-branch +$ cp values-secret.yaml.template ~/values-secret-multicloud-gitops.yaml ---- + +[NOTE] +==== +Putting the `values-secret.yaml` in your home directory ensures that it does not get pushed to your git repository. It is based on the `values-secrets.yaml.template` file provided by the pattern in the top level directory. When you create your own patterns you will add your secrets to this file and save. At the moment the focus is on getting started and familiar with this base Multicloud GitOps pattern. +==== + +. Create a new feature branch, for example `my-branch` from the `main` branch for your content: ++ [source,terminal] ---- -vi values-global.yaml +$ git checkout -b my-branch main ---- + +. Create a local branch and push it to origin to gain the flexibility needed to customize the base Multicloud GitOps by running the following command: + [source,terminal] ---- -git add values-global.yaml +$ git push origin my-branch ---- + +You can proceed to install the Multicloud GitOps pattern by using the web console or from command line by using the script `./pattern.sh` script. + +To install the Multicloud GitOps pattern by using the web console you must first install the Validated Patterns Operator. The Validated Patterns Operator installs and manages Validated Patterns. + +//Include Procedure module here +[id="installing-validated-patterns-operator_{context}"] +== Installing the {validated-patterns-op} using the web console + +.Prerequisites +* Access to an {ocp} cluster by using an account with `cluster-admin` permissions. + +.Procedure + +. Navigate in the {hybrid-console-first} to the *Operators* → *OperatorHub* page. + +. Scroll or type a keyword into the *Filter by keyword* box to find the Operator you want. For example, type `validated patterns` to find the {validated-patterns-op}. + +. Select the Operator to display additional information. ++ +[NOTE] +==== +Choosing a Community Operator warns that Red Hat does not certify Community Operators; you must acknowledge the warning before continuing. +==== + +. Read the information about the Operator and click *Install*. + +. On the *Install Operator* page: + +.. Select an *Update channel* (if more than one is available). + +.. Select a *Version* (if more than one is available). + +.. Select an *Installation mode*: ++ +The only supported mode for this Operator is *All namespaces on the cluster (default)*. This installs the Operator in the default `openshift-operators` namespace to watch and be made available to all namespaces in the cluster. This option is not always available. + +.. Select *Automatic* or *Manual* approval strategy. + +. Click *Install* to make the Operator available to the default `openshift-operators` namespace on this {ocp} cluster. + +.Verification +To confirm that the installation is successful: + +. Navigate to the *Operators* → *Installed Operators* page. + +. Check that the Operator is installed in the selected namespace and its status is `Succeeded`. + +//Include Procedure module here +[id="create-pattern-instance_{context}"] +== Creating the Multicloud GitOps instance + +.Prerequisites +The {validated-patterns-op} is successfully installed in the relevant namespace. + +.Procedure + +. Navigate to the *Operators* → *Installed Operators* page. + +. Click the installed *{validated-patterns-op}*. + +. Under the *Details* tab, in the *Provided APIs* section, in the +*Pattern* box, click *Create instance* that displays the *Create Pattern* page. + +. On the *Create Pattern* page, select *Form view* and enter information in the following fields: + +** *Name* - A name for the pattern deployment that is used in the projects that you created. +** *Labels* - Apply any other labels you might need for deploying this pattern. +** *Cluster Group Name* - Select a cluster group name to identify the type of cluster where this pattern is being deployed. For example, if you are deploying the {ie-pattern}, the cluster group name is `datacenter`. If you are deploying the {mcg-pattern}, the cluster group name is `hub`. ++ +To know the cluster group name for the patterns that you want to deploy, check the relevant pattern-specific requirements. +. Expand the *Git Config* section to reveal the options and enter the required information. +. Leave *In Cluster Git Server* unchanged. +.. Change the *Target Repo* URL to your forked repository URL. For example, change `+https://github.com/validatedpatterns/+` to `+https://github.com//+` +.. Optional: You might need to change the *Target Revision* field. The default value is `HEAD`. However, you can also provide a value for a branch, tag, or commit that you want to deploy. For example, `v2.1`, `main`, or a branch that you created, `my-branch`. +. Click *Create*. ++ +[NOTE] +==== +A pop-up error with the message "Oh no! Something went wrong." might appear during the process. This error can be safely disregarded as it does not impact the installation of the Multicloud GitOps pattern. Use the Hub ArgoCD UI, accessible through the nines menu, to check the status of ArgoCD instances, which will display states such as progressing, healthy, and so on, for each managed application. The Cluster ArgoCD provides detailed status on each application, as defined in the clustergroup values file. +==== + +The *{rh-gitops} Operator* displays in list of *Installed Operators*. The *{rh-gitops} Operator* installs the remaining assets and artifacts for this pattern. To view the installation of these assets and artifacts, such as *{rh-rhacm-first}*, ensure that you switch to *Project:All Projects*. + +Wait some time for everything to deploy. You can track the progress through the `Hub ArgoCD` UI from the nines menu. The `config-demo` project appears stuck in a `Degraded` state. This is the expected behavior when installing using the OpenShift Container Platform console. + +* To resolve this you need to run the following to load the secrets into the vault: + [source,terminal] ---- -git commit values-global.yaml +$ ./pattern.sh make load-secrets ---- + +[NOTE] +==== +You must have created a local copy of the secret values file by running the following command: + [source,terminal] ---- -git push origin my-branch +$ cp values-secret.yaml.template ~/values-secret-multicloud-gitops.yaml ---- +==== + +The deployment will not take long but it should deploy successfully. -. Deploy the pattern by running `./pattern.sh make install` or by using the link:/infrastructure/using-validated-pattern-operator/[Validated Patterns Operator]. +Alternatively you can deploy the Multicloud GitOps pattern by using the command line script `pattern.sh`. [id="deploying-cluster-using-patternsh-file"] -== Deploying the cluster by using the pattern.sh file +== Deploying the cluster by using the pattern.sh script -To deploy the cluster by using the `pattern.sh` file, complete the following steps: +To deploy the cluster by using the `pattern.sh` script, complete the following steps: -. Login to your cluster by running the following command: +. Navigate to the root directory of the cloned repository by running the following command: + [source,terminal] ---- - oc login +$ cd /path/to/your/repository ---- + +. Log in to your cluster by running the following this procedure: + +.. Obtain an API token by visiting https://oauth-openshift.apps../oauth/token/request + +.. Log in with this retrieved token by running the following command: + -Optional: Set the `KUBECONFIG` variable for the `kubeconfig` file path: +[source,terminal] +---- +$ oc login --token=sha256~AUv_4DGQoFMVzmdO3cg3v4vnUuaV3lYcy6N2SCwVOz4 --server=https://api..:6443 +---- + +. Alternatively log in by running the following command: + [source,terminal] ---- - export KUBECONFIG=~/ +$ export KUBECONFIG=~/ ---- -. Deploy the pattern to your cluster. Run the following command: +. Deploy the pattern to your cluster by running the following command: + [source,terminal] ---- - ./pattern.sh make install +$ ./pattern.sh make install ---- . Verify that the Operators have been installed. .. To verify, in the OpenShift Container Platform web console, navigate to *Operators → Installed Operators* page. - .. Check that the Operator is installed in the `openshift-operators` namespace and its status is `Succeeded`. -. Verify that all applications are synchronized. Under the project `multicloud-gitops-hub` click the URL for the `hub` gitops `server`. The Vault application is not synched. + .. Check that *{rh-gitops} Operator* is installed in the `openshift-operators` namespace and its status is `Succeeded`. +. Verify that all applications are synchronized. Under *Networking \-> Routes* select the *Location URL* associated with the *hub-gitops-server* . All application are report status as `Synched`. + image::multicloud-gitops/multicloud-gitops-argocd.png[Multicloud GitOps Hub] +As part of installing by using the script `pattern.sh` pattern, HashiCorp Vault is installed. Running `./pattern.sh make install` also calls the `load-secrets` makefile target. This `load-secrets` target looks for a YAML file describing the secrets to be loaded into vault and in case it cannot find one it will use the `values-secret.yaml.template` file in the git repository to try to generate random secrets. + +For more information, see section on https://validatedpatterns.io/secrets/vault/[Vault]. -As part of this pattern, HashiCorp Vault has been installed. Refer to the section on https://validatedpatterns.io/secrets/vault/[Vault]. diff --git a/modules/mcg-understanding-rhacm-requirements.adoc b/modules/mcg-understanding-rhacm-requirements.adoc index 12133d1a1..e4bf788a7 100644 --- a/modules/mcg-understanding-rhacm-requirements.adoc +++ b/modules/mcg-understanding-rhacm-requirements.adoc @@ -4,46 +4,70 @@ [id="understanding-acm-requirements-managed-cluster"] = Understanding Red Hat Advanced Cluster Management requirements -By default, Red Hat Advanced Cluster Management (RHACM) manages the `clusterGroup` applications that are deployed on all clusters. In the `value-hub.yaml` file, add a `managedClusterCgroup` for each cluster or group of clusters that you want to manage as one. +By default, Red Hat Advanced Cluster Management (RHACM) manages the `clusterGroup` applications that are deployed on all clusters. +Add a `managedClusterGroup` for each cluster or group of clusters that you want to manage by following this procedure. + +.Procedure + +. Switch to your locally created feature branch by running the following command: ++ +[source,terminal] +---- +$ git checkout my-branch main +---- + +. In the `value-hub.yaml` file, add a `managedClusterGroup` for each cluster or group of clusters that you want to manage as one. An example `group-one` is provided. ++ [source,yaml] ---- - managedClusterGroups: - - name: region-one +managedClusterGroups: + exampleRegion: + name: group-one + acmlabels: + - name: clusterGroup + value: group-one helmOverrides: - - name: clusterGroup.isHubCluster - value: false - clusterSelector: - matchLabels: - clusterGroup: region-one + - name: clusterGroup.isHubCluster + value: false ---- - -The above YAML file segment deploys the `clusterGroup` applications on managed clusters with the label `clusterGroup=region-one`. Specific subscriptions and Operators, applications and projects for that `clusterGroup` are then managed in a `value-region-one.yaml` file. For example: - ++ +The above YAML file segment deploys the `clusterGroup` applications on managed clusters with the label `clusterGroup=group-one`. Specific subscriptions and Operators, applications and projects for that `clusterGroup` are then managed in a `value-group-one.yaml` file. The following is defined for the `clusterGroup=group-one`. ++ +For example: ++ [source,yaml] ---- +clusterGroup: + name: group-one + isHubCluster: false namespaces: - config-demo - + - hello-world + - golang-external-secrets + # The only subscription on spokes is gitops which gets managed by ACM + # subscriptions: projects: + - eso - config-demo - + - hello-world applications: + golang-external-secrets: + name: golang-external-secrets + namespace: golang-external-secrets + project: eso + chart: golang-external-secrets + chartVersion: 0.1.* config-demo: name: config-demo namespace: config-demo project: config-demo path: charts/all/config-demo - - #Subscriptions can be added too - multicloud-gitops at present does not require subscriptions on its managed clusters - #subscriptions: -. # example-subscription - # name: example-operator - # namespace: example-namespace - # channel: example-channel - # csv: example-operator.v1.0.0 - - subscriptions: + hello-world: + name: hello-world + namespace: hello-world + project: hello-world + path: charts/all/hello-world ---- [IMPORTANT] diff --git a/modules/mcg-using-imperative-actions.adoc b/modules/mcg-using-imperative-actions.adoc index 821f685f5..1f4b9e7ab 100644 --- a/modules/mcg-using-imperative-actions.adoc +++ b/modules/mcg-using-imperative-actions.adoc @@ -4,7 +4,14 @@ [id="mcg-using-kubernetes-cronjob-imperative-actions"] = Using kubernetes cronjobs to apply imperative actions -There is currently no way within Argo CD to apply an imperative action against a cluster. However, you can declaratively apply changes to a cluster using kubernetes cronjob resources. Customers can use their Ansible playbooks to take action against a cluster if necessary. +There is currently no way within Argo CD to apply an imperative action against a cluster. However, you can declaratively apply changes to a cluster using kubernetes cronjob resources. + +Within the Patterns framework we mainly use jobs to: + +* Schedule imperative tasks in the imperative framework such as keeping the Vault unsealed +* Run Ansible playbooks + +Customers can use their Ansible playbooks to take action against a cluster if necessary. [WARNING] ==== @@ -15,7 +22,7 @@ Adding your playbooks to the pattern requires the following: . Move your Ansible configurations to the appropriate directory under Ansible in your forked repository. . Define your job as a list, for example: - ++ [source,yaml] ---- imperative: diff --git a/static/images/multicloud-gitops/config-demo-degarded.png b/static/images/multicloud-gitops/config-demo-degarded.png new file mode 100644 index 000000000..cc918e3a4 Binary files /dev/null and b/static/images/multicloud-gitops/config-demo-degarded.png differ diff --git a/static/images/multicloud-gitops/multicloud-gitops-argocd.png b/static/images/multicloud-gitops/multicloud-gitops-argocd.png index 70a5e386d..c9be5eb93 100644 Binary files a/static/images/multicloud-gitops/multicloud-gitops-argocd.png and b/static/images/multicloud-gitops/multicloud-gitops-argocd.png differ