docs: added a getting started section for managing cluster configuration

_topic_maps/_topic_map.yml

@@ -40,6 +40,13 @@ Topics:
 - Name: Gathering diagnostic information for support
   File: gathering-gitops-diagnostic-information-for-support
 ---
+Name: Managing cluster configuration
+Dir: managing_cluster_configuration
+Distros: openshift-gitops
+Topics:
+- Name: Managing OpenShift cluster configuration
+  File: managing-openshift-cluster-configuration
+---
 Name: Installing GitOps
 Dir: installing_gitops
 Distros: openshift-gitops

managing_cluster_configuration/_attributes

@@ -0,0 +1 @@
+../_attributes/

managing_cluster_configuration/images

@@ -0,0 +1 @@
+../images/

managing_cluster_configuration/managing-openshift-cluster-configuration.adoc

@@ -0,0 +1,46 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="managing-openshift-cluster-configuration"]
+include::_attributes/common-attributes.adoc[]
+= Managing {OCP} cluster configuration
+
+:context: managing-openshift-cluster-configuration
+
+toc::[]
+
+With {gitops-title}, you can manage your {OCP} cluster configuration to have the following benefits:
+
+* Version control and auditability: Configuration changes committed to Git provide a complete history of modifications. This facilitates auditing, compliance, and accountability.
+* Single source of truth: Git serves as the definitive source for the desired state of your {OCP} cluster.
+* Optimized performance and disaster recovery: {gitops-shortname} points the Argo CD application to the previous commit or tag with a known-good state in Git, which in turn reduces downtime and helps with disaster recovery.
+* Collaboration and Review: Git's collaborative features enable team members to review and approve infrastructure and application configuration changes before they are applied to your {OCP} cluster.
+* Efficiency and Scalability: {gitops-shortname} streamlines the deployment and operations workflows, enabling efficient management of complex and multi-cluster environments with reduced manual intervention and human error.
+
+Perform the following tasks to manage your {OCP} cluster configuration:
+
+. Installing the {gitops-title} Operator using CLI
+. Analyzing the default Argo CD instance
+. Accessing the default Argo CD instance
+. Configuring the default Argo CD instance
+
+// Installing Red Hat OpenShift GitOps Operator using CLI
+include::modules/installing-gitops-operator-using-cli.adoc[leveloffset=+1]
+
+// Analyzing the default Argo CD instance
+include::modules/analyzing-the-default-instance-details.adoc[leveloffset=+1]
+
+// Accessing the default Argo CD instance
+include::modules/access-the-default-argocd-instance.adoc[leveloffset=+1]
+
+// Configuring the default Argo CD instance
+include::modules/configuring-the-default-argocd-instance.adoc[leveloffset=+1]
+include::modules/configuring-rbac.adoc[leveloffset=+2]
+include::modules/configuring-permissions.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+* xref:../argocd_instance/setting-up-argocd-instance.adoc#gitops-argo-cd-installation_setting-up-argocd-instance[Installing a user-defined Argo CD instance]
+* xref:../installing_gitops/installing-openshift-gitops.adoc#installing-gitops-operator-in-web-console_installing-openshift-gitops[Installing {gitops-shortname} in web console]
+* xref:../declarative_clusterconfig/configuring-an-openshift-cluster-by-deploying-an-application-with-cluster-configurations.adoc#gitops-inbuilt-permissions-for-cluster-config_configuring-an-openshift-cluster-by-deploying-an-application-with-cluster-configurations[Default set of Kubernetes permissions]
+* link:https://argo-cd.readthedocs.io/en/stable/operator-manual/config-management-plugins/#config-management-plugins[Config Management Plugins]
+

managing_cluster_configuration/modules

@@ -0,0 +1 @@
+../modules/

managing_cluster_configuration/snippets

@@ -0,0 +1 @@
+../snippets/

modules/access-the-default-argocd-instance.adoc

@@ -0,0 +1,25 @@
+// Module is included in the following assemblies:
+//
+// * managing_cluster_configuration/managing-openshift-cluster-configuration.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="access-the-default-argocd-instance_{context}"]
+= Access the default Argo CD instance
+
+After analyzing the default Argo CD instance details, you can access it through the Argo CD UI to check whether it is available for use.
+
+.Prerequisite
+
+* You have your login credentials to access the {OCP} cluster with `cluster-admin` privileges.
+
+
+.Procedure
+
+. Click the **Application Launcher** menu in the top right corner of the {OCP} web console.
+. Select **Cluster Argo CD** from the dropdown list. The Argo CD login page opens.
+. Click the **LOG IN VIA OPENSHIFT** button. The {OCP} login page opens.
+. Enter your {OCP} credentials. The **Authorize Access** page opens.
+. Click **Allow selected permissions** to provide requested permission. The Argo CD UI page opens.
+
+At this point, the UI is empty as you have not created any Argo CD applications. You can check the **User Info** page to view the user details. 
+

modules/analyzing-the-default-instance-details.adoc

@@ -0,0 +1,27 @@
+// Module is included in the following assemblies:
+//
+// * managing_cluster_configuration/managing-openshift-cluster-configuration.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="analyzing-the-default-instance-details_{context}"]
+= Analyzing the default Argo CD instance details
+
+By default, the Operator creates an Argo CD instance in the `openshift-gitops` namespace. After installation, you can use the {OCP} web console to view the **Operator details** page and analyze the default instance configuration. This analysis helps you to customize the behavior of this instance later. The instance is intended for the cluster configuration use case and has elevated privileges. 
+
+[NOTE]
+====
+You can create additional Argo CD instances in other namespaces to support your application use cases.  
+====
+
+.Prerequisite
+
+* You have your login credentials to access the {OCP} cluster with `cluster-admin` privileges.
+
+.Procedure
+
+. Perform one of the following steps to open the **Operator details** page:
+** Click the **View Operator** button that is available after the Operator installation completes. 
+** Click **Installed Operators** under the **Operators** menu, and select the **{gitops-title}** Operator.
+. Select the **Argo CD** tab.
+. Click the name of the default instance, `openshift-gitops`, to view its details on a new page.
+. Select the **YAML** tab to analyze how it is configured.

modules/configuring-permissions.adoc

@@ -0,0 +1,65 @@
+// Module is included in the following assemblies:
+//
+// * managing_cluster_configuration/managing-openshift-cluster-configuration.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="configuring-permissions_{context}"]
+= Configuring permissions
+
+Though the default Argo CD instance is automatically configured with a default set of Kubernetes permissions, you need to provide it with additional permissions to deploy all the resources required for cluster configuration. Conversely, if you need to set more restrictive permissions for the default instance to deploy only specific resources, you can do so through additional configurations.
+
+[NOTE]
+====
+For more information about the default set of Kubernetes permissions, see "Additional resources".
+====
+
+When using the default instance for cluster configuration, provide the `cluster-admin` permissions to the Argo CD application controller service account. To do this, you can create a `ClusterRoleBinding` object for the `openshift-gitops-argocd-application-controller` service account as the default instance uses this account for interacting with the Kubernetes API to deploy resources.
+
+.Prerequisite
+
+* You have your login credentials to access the {OCP} cluster with `cluster-admin` privileges.
+* You have installed the link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/cli_tools/openshift-cli-oc[`oc` CLI].
+
+
+.Procedure
+
+* Run the following command:
++
+[source,terminal]
+----
+$ oc adm policy add-cluster-role-to-user --rolebinding-name="openshift-gitops-cluster-admin" cluster-admin -z openshift-gitops-argocd-application-controller -n openshift-gitops
+----
+.Example output
++
+[source,terminal]
+----
+clusterrole.rbac.authorization.k8s.io/cluster-admin added: "openshift-gitops-argocd-application-controller"
+----
+
+
+.Verification
+
+* View the created `ClusterRoleBinding` object:
++
+[source,terminal]
+----
+$ oc get clusterrolebinding openshift-gitops-cluster-admin -o yaml
+----
+.Example output
++
+[source,yaml]
+----
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: openshift-gitops-cluster-admin
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: cluster-admin
+subjects:
+  - kind: ServiceAccount
+    name: openshift-gitops-argocd-application-controller
+    namespace: openshift-gitops
+----
+

modules/configuring-rbac.adoc

@@ -0,0 +1,106 @@
+// Module is included in the following assemblies:
+//
+// * managing_cluster_configuration/managing-openshift-cluster-configuration.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="configuring-rbac_{context}"]
+= Configuring RBAC
+
+You must configure RBAC to provide the sufficient access to the users to work with the default instance.
+
+The `defaultPolicy` of the instance is an empty string, which means no role is assigned automatically. Though users can log into the instance, they have no permissions to view anything or perform any tasks in the Argo CD UI or CLI.
+
+The instance includes the following two groups:
+
+* `system:cluster-admins`: The group only applies to the temporary `kube-admin` credentials and can be ignored.
+* `cluster-admins`: You can add your user to this group to enable them to perform tasks, such as deploying an application, in the Argo CD web console.
+
+[NOTE]
+====
+_Restrict default permissions:_
+
+Ensure that you always use either an empty string or a deny-all type of role for the `defaultPolicy` parameter because permissions granted in it cannot be revoked. Hence, it is not recommended to set the `defaultPolicy` parameter in a way that grants permissions.
+====
+
+.Prerequisite
+
+* You have login credentials to access the {OCP} cluster with `cluster-admin` privileges.
+* You have installed the link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/cli_tools/openshift-cli-oc[`oc` CLI].
+
+.Procedure
+
+. View the Operator-configured RBAC for the default instance:
++
+[source,terminal]
+----
+$ oc get argocd openshift-gitops -n openshift-gitops -o=jsonpath='{.spec.rbac}'
+----
+.Output
++
+[source,json]
+----
+{"defaultPolicy":"","policy":"g, system:cluster-admins, role:admin\ng, cluster-admins, role:admin\n","scopes":"[groups]"}
+----
+
+. Check if the `cluster-admins` group exists:
++
+[source,terminal]
+----
+$ oc get groups
+----
+
+. Perform one of the following steps:
++
+* If the group does not exist, create it and add your user to it:
++
+[source,terminal]
+----
+$ oc adm groups new cluster-admins <user>
+----
++
+where:
+
+<user>:: Denotes the user that you want to add to the group.
++
+.Example output
++
+[source,terminal]
+----
+group.user.openshift.io/cluster-admins created
+----
+
+* If the group exists, check if your user is part of it in the output of the previously run `oc get groups` command. If your user is not in the group, add your user to the group: 
++
+[source,terminal]
+----
+$ oc adm groups add-users cluster-admins <user>
+----
++
+where:
+
+<user>:: Denotes the user that you want to add to the group.
++
+.Example output
++
+[source,terminal]
+----
+group.user.openshift.io/cluster-admins added: "<user>"
+----
+
+
+.Verification
+
+* Validate that the group `cluster-admins` exists and that your user is part of it:
++
+[source,terminal]
+----
+$ oc get groups cluster-admins
+----
++
+The output shows the `cluster-admins` group with your user assigned to it.
+
+
+[IMPORTANT]
+====
+After creating or editing the `cluster-admins` group, ensure you log out of the Argo CD web console and then log back in again so that the group becomes associated with your user. Check the **User Info** page to validate that your user is part of the `cluster-admins` group within Argo CD.
+====

modules/configuring-the-default-argocd-instance.adoc

@@ -0,0 +1,12 @@
+// Module included in the following assemblies:
+//
+// * managing_cluster_configuration/managing-openshift-cluster-configuration.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="configuring-the-default-argocd-instance_{context}"]
+= Configuring the default Argo CD instance
+
+Though the Operator creates a default Argo CD instance in the `openshift-gitops` namespace, you must configure it to make it useful for deploying applications and setting cluster configuration:
+
+* Configure Role Based Access Control (RBAC): Argo CD uses its own RBAC configuration. The default permissions configured by the Operator might not be sufficient, depending on the {OCP} cluster groups your user has been assigned to.
+* Configure permissions: The Operator configures the default instance with a default set of Kubernetes permissions. However, these permissions are insufficient when deploying applications in the real-time environment. Therefore, ensure to provide additional permissions to this default instance.

modules/installing-gitops-operator-using-cli.adoc

@@ -1,6 +1,7 @@
 // Module is included in the following assemblies:
 //
 // * installing_gitops/installing-openshift-gitops.adoc
+// * managing_cluster_configuration/managing-openshift-cluster-configuration.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="installing-gitops-operator-using-cli_{context}"]
@@ -13,6 +14,11 @@ You can install {gitops-title} Operator from the OperatorHub by using the CLI.
 For the {gitops-shortname} version 1.10 and later, the default namespace changed from `openshift-operators` to `openshift-gitops operator`.
 ====
 
+.Prerequisite
+
+* You have login credentials to access the {OCP} cluster with `cluster-admin` privileges.
+* You have installed the link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/cli_tools/openshift-cli-oc[`oc` CLI].
+
 .Procedure
 
 . Create a `openshift-gitops-operator` namespace:
@@ -117,13 +123,14 @@ $ oc get pods -n openshift-gitops
 [source,terminal]
 ----
 NAME                                                      	  READY   STATUS    RESTARTS   AGE
-cluster-b5798d6f9-zr576                                   	  1/1 	  Running   0          65m
-openshift-gitops-application-controller-0                 	  1/1 	  Running   0          53m
-openshift-gitops-applicationset-controller-6447b8dfdd-5ckgh       1/1 	  Running   0          65m
-openshift-gitops-dex-server-569b498bd9-vf6mr                      1/1     Running   0          65m
-openshift-gitops-redis-74bd8d7d96-49bjf                   	  1/1 	  Running   0          65m
-openshift-gitops-repo-server-c999f75d5-l4rsg              	  1/1 	  Running   0          65m
-openshift-gitops-server-5785f7668b-wj57t                  	  1/1 	  Running   0          53m
+cluster-785cfc5f75-669wq                                      1/1     Running   0          76s
+gitops-plugin-6664c749dd-dx64s                                1/1     Running   0          76s
+openshift-gitops-application-controller-0                     1/1     Running   0          74s
+openshift-gitops-applicationset-controller-549d7f6686-wzckt   1/1     Running   0          74s
+openshift-gitops-dex-server-5d4ffdb9b9-lb7b7                  1/1     Running   0          74s
+openshift-gitops-redis-6d65c94d4b-k9l8k                       1/1     Running   0          75s
+openshift-gitops-repo-server-79db854c58-279jr                 1/1     Running   0          75s
+openshift-gitops-server-f488b848-xntbc                        1/1     Running   0          75s
 ----
 
 . Verify that the pods in the `openshift-gitops-operator` namespace are running:
@@ -137,6 +144,6 @@ $ oc get pods -n openshift-gitops-operator
 [source,terminal]
 ----
 NAME                                                            READY   STATUS    RESTARTS   AGE
-openshift-gitops-operator-controller-manager-664966d547-vr4vb   2/2     Running   0          65m
+openshift-gitops-operator-controller-manager-6fdc5cd9dc-jr9mn   2/2     Running   0          41s
 ----