https://issues.redhat.com/browse/ACM-24933 part 2

gitops/gitops_service_account_argo_cd.adoc

@@ -12,200 +12,13 @@ Creating a customzied service account for use with the Argo CD push model includ
 
 After completing all the following procedures, you can grant cluster permissions to your managed service account. Having the cluster permissions, your managed service account has the necessary permissions to deploy your application resources on the managed clusters. Complete the following procedures:
 
-. <<creating-service-account, Creating a managed service account>> 
-. <<using-service-account, Using a managed service account in the _GitOpsCluster_ resource>> 
-. <<creating-argocd-application, Creating an Argo CD application>> 
-. <<using-policy, Using policy to create managed service accounts and cluster permissions>>
-
 [#creating-service-account]
 == Creating a managed service account 
 
 The `ManagedServiceAccount` custom resource on the hub provides a convenient way to create a `ServiceAccount` on the managed clusters. When a `ManagedServiceAccount` custom resource is created in the `<managed-cluster>` namespace on the hub cluster, a `ServiceAccount` is created on the managed cluster.
 
 To create a managed service account, see link:../clusters/cluster_lifecycle/addon_managed_service.adoc#managed-serviceaccount-addon[Enabling ManagedServiceAccount add-ons].
 
-[#creating-cluster-permission]
-== Creating a cluster permission 
-
-When the service account is created, it does not have any permission associated to it. To grant permissions to the new service account, use the `ClusterPermission` resource. The `ClusterPermission` resource is created in the managed cluster namespace on the hub. It provides a convenient way to create roles, cluster roles resources on the managed clusters, and bind them to a service account through a `RoleBinding` or `ClusterRoleBinding` resource.
-
-. To grant the `<managed-sa-sample>` service account permission to the sample mortgage application that is deployed to the mortgage namespace on `<managed-cluster>`, create a YAML with the following content: 
-
-[source,yaml]
-----
-apiVersion: rbac.open-cluster-management.io/v1alpha1
-kind: ClusterPermission
-metadata:
-  name: <clusterpermission-msa-subject-sample>
-  namespace: <managed cluster>
-spec:
-  roles:
-  - namespace: default
-    rules:
-    - apiGroups: ["apps"]
-      resources: ["deployments"]
-      verbs: ["get", "list", "create", "update", "delete", "patch"]
-    - apiGroups: [""]
-      resources: ["configmaps", "secrets", "pods", "podtemplates", "persistentvolumeclaims", "persistentvolumes"]
-      verbs: ["get", "update", "list", "create", "delete", "patch"]
-    - apiGroups: ["storage.k8s.io"]
-      resources: ["*"]
-      verbs: ["list"]
-  - namespace: mortgage
-    rules:
-    - apiGroups: ["apps"]
-      resources: ["deployments"]
-      verbs: ["get", "list", "create", "update", "delete", "patch"]
-    - apiGroups: [""]
-      resources: ["configmaps", "secrets", "pods", "services", "namespace"]
-      verbs: ["get", "update", "list", "create", "delete", "patch"]
-  clusterRole:
-    rules:
-    - apiGroups: ["*"]
-      resources: ["*"]
-      verbs: ["get", "list"]
-  roleBindings:
-  - namespace: default
-    roleRef:
-      kind: Role
-    subject:
-      apiGroup: authentication.open-cluster-management.io
-      kind: ManagedServiceAccount
-      name: <managed-sa-sample>
-  - namespace: mortgage
-    roleRef:
-      kind: Role
-    subject:
-      apiGroup: authentication.open-cluster-management.io
-      kind: ManagedServiceAccount
-      name: <managed-sa-sample>
-  clusterRoleBinding:
-    subject:
-      apiGroup: authentication.open-cluster-management.io
-      kind: ManagedServiceAccount
-      name: <managed-sa-sample>
-----
-
-. Save the YAML file in a file called, `cluster-permission.yaml`.
-. Run `oc apply -f cluster-permission.yaml`. 
-. The sample `<clusterpermission>` creates a role called `<clusterpermission-msa-subject-sample>` in the mortgage namespace. If one does not already exist, create a namespace `mortgage`. 
-. Review the resources that are created on the `<managed-cluster>`. 
-
-After you create the sample, `<clusterpermission>`, the following resources are created in the sample managed cluster:
-
-* One `Role` called `<clusterpermission-msa-subject-sample>` in the default namespace.
-* One `RoleBinding` called `<clusterpermission-msa-subject-sample>` in the default namespace for binding the role to the managed service account. 
-* One `Role` called `<clusterpermission-msa-subject-sample>` in the mortgage namespace.
-* One `RoleBinding` called `<clusterpermission-msa-subject-sample>` in the mortgage namespace for binding the role to the managed service account.
-* One `ClusterRole` called `<clusterpermission-msa-subject-sample>`. 
-* One `ClusterRoleBinding` called `<clusterpermission-msa-subject-sample>` for binding the `ClusterRole` to the managed service account. 
-
-[#creating-cluster-permission-existing-role]
-== Creating a cluster permission by using an existing role 
-
-When you create a `ClusterPermission` resource, you automatically create new roles. You can still use the `ClusterPermission` resource with an existing role. 
-
-For example, when you apply the following YAML sample, you create a `ClusterPermission` resource that uses an existing `ClusterRole`: 
-
-[source,yaml]
-----
-apiVersion: rbac.open-cluster-management.io/v1alpha1
-kind: ClusterPermission
-metadata:
-  name: clusterpermission-existing-role-sample
-spec:
-  roleBindings:
-    - name: default-rb-cluster1 <1>
-      namespace: default
-      roleRef: <2> 
-        apiGroup: rbac.authorization.k8s.io
-        kind: ClusterRole
-        name: argocd-application-controller-1
-      subject:
-        namespace: openshift-gitops
-        kind: ServiceAccount
-        name: sa-sample-existing
-    - name: kubevirt-rb-cluster1
-      namespace: kubevirt
-      roleRef:
-        apiGroup: rbac.authorization.k8s.io
-        kind: Role
-        name: argocd-application-controller-2
-      subject:
-        apiGroup: rbac.authorization.k8s.io
-        kind: User
-        name: user1
-  clusterRoleBinding:
-      name: crb-cluster1-argo-app-con-3 <3>
-      roleRef: <4> 
-        apiGroup: rbac.authorization.k8s.io
-        kind: ClusterRole
-        name: argocd-application-controller-3
-      subject:
-        apiGroup: rbac.authorization.k8s.io
-        kind: Group
-        name: group1 
-----
-<1> An optional name to create the `RoleBinding` field instead of using the default `ClusterPermission` name. 
-<2> Refers to an existing `ClusterRole` on the managed cluster. 
-<3> An optional name to create the `ClusterRoleBinding` field instead of using the default `ClusterPermission` name. 
-<4> Refers to an existing `ClusterRole` on the managed cluster. 
-
-[#creating-cluster-permission-reference]
-== Creating a cluster permission resource to reference subjects 
-
-If you create a `ClusterPermission` resource to reference different subjects, you can work with different subjects at the same time instead of only working on one subject at a time. 
-
-For an example, see the following YAML with the specified `subjects` field: 
-
-[source,yaml]
-----
-apiVersion: rbac.open-cluster-management.io/v1alpha1
-kind: ClusterPermission
-metadata:
-  name: clusterpermission-users-groups
-spec:
-  roleBindings:
-    - namespace: default
-      roleRef:
-        apiGroup: rbac.authorization.k8s.io
-        kind: ClusterRole
-        name: argocd-application-controller-users-1
-      subjects:
-      - namespace: openshift-gitops
-        kind: ServiceAccount
-        name: sa-sample-existing
-      - apiGroup: rbac.authorization.k8s.io
-        kind: User
-        name: argo-users1
-    - name: kubevirt-rb-cluster1-users1
-      namespace: kube-system
-      roleRef:
-        apiGroup: rbac.authorization.k8s.io
-        kind: Role
-        name: argocd-application-controller-users-2
-      subjects:
-      - apiGroup: rbac.authorization.k8s.io
-        kind: User
-        name: users1
-      - apiGroup: rbac.authorization.k8s.io
-        kind: User
-        name: users2
-  clusterRoleBinding:
-      name: crb-cluster1-argo-app-con-groups
-      roleRef:
-        apiGroup: rbac.authorization.k8s.io
-        kind: ClusterRole
-        name: argocd-application-controller-3
-      subjects:
-      - apiGroup: rbac.authorization.k8s.io
-        kind: Group
-        name: groups1
-      - apiGroup: rbac.authorization.k8s.io
-        kind: Group
-        name: groups2
-----
-
 [#using-service-account]
 == Using a managed service account in the _GitOpsCluster_ resource
 
@@ -257,15 +70,15 @@ NAME                                        TYPE     DATA   AGE
 
 Deploy an Argo CD application from the Argo CD console by using the pushing model. The Argo CD application is deployed with the managed service account, `<managed-sa-sample>`. 
 
-. Log into the Argo CD console. 
+. Log in to the Argo CD console. 
 . Click *Create a new application*. 
 . Choose the cluster URL. 
 . Go to your Argo CD application and verify that it has the given permissions, like roles and cluster roles, that you propagated to `<managed cluster>`. 
 
 [#using-policy]
 == Using policy to create managed service accounts and cluster permissions 
 
- When the GitOpsCluster resource is updated with the `ManagedServiceAccountRef`, each managed cluster in the placement of this GitOpsCluster needs to have the service account. If you have several managed clusters, it becomes tedious for you to create the managed service account and cluster permission for each managed cluster. You can simply this process by using a policy to create the managed service account and cluster permission for all your managed clusters
+When the GitOpsCluster resource is updated with the `ManagedServiceAccountRef`, each managed cluster in the placement of this GitOpsCluster needs to have the service account. If you have several managed clusters, it becomes tedious for you to create the managed service account and cluster permission for each managed cluster. You can simply this process by using a policy to create the managed service account and cluster permission for all your managed clusters
 
 When you apply the `ManagedServiceAccount` and `ClusterPermission` resources to the hub cluster, the placement of this policy is bound to the local cluster. Replicate those resources to the managed cluster namespace for all of the managed clusters in the placement of the GitOpsCluster resource.
 

secure_clusters/cluster_permission_intro.adoc

@@ -7,9 +7,7 @@ With the cluster permssions API, `clusterpermissions.rbac.open-cluster-managemen
 
 Learn about how to create and manage cluster permissions in the following topics:
 
-//* xref:../secure_clusters/create_cluster_perm.adoc#creating-cluster-permission[Creating a cluster permission]
-
-//* xref:../secure_clusters/cluster_permissions/create_cluster_perm_exist.adoc#creating-cluster-permission-exist[Creating a cluster permission using an existing role]
-//* xref:../secure_clusters/cluster_permissions/create_cluster_perm_ref.adoc#creating-cluster-permission-reference[Creating a cluster permission resource to reference subjects]
-
+* xref:../secure_clusters/create_cluster_perm.adoc#creating-cluster-permission[Creating a cluster permission]
+* xref:../secure_clusters/cluster_permissions/create_cluster_perm_exist.adoc#creating-cluster-permission-exist[Creating a cluster permission using an existing role]
+* xref:../secure_clusters/cluster_permissions/create_cluster_perm_ref.adoc#creating-cluster-permission-reference[Creating a cluster permission resource to reference subjects]
 * xref:../secure_clusters/cluster_permissions/cluster_permission_validate.adoc#enable-cluster-permission-validate[Enabling validation for cluster permissions]

secure_clusters/create_cluster_permission.adoc

@@ -0,0 +1,94 @@
+[#create-cluster-permission]
+= Creating a cluster permission 
+
+When the service account is created, it does not have any permission associated to it. To grant permissions to the new service account, use the `ClusterPermission` resource. Create the `ClusterPermission` resource in the managed cluster namespace on the hub cluster. Use the `ClusterPermission` resource to create roles, cluster roles resources on the managed clusters, and bind them to a service account through a `RoleBinding` or `ClusterRoleBinding` resource.
+
+*Required access:* Cluster administrator
+
+.Prerequisites
+
+- If you want to bind to the `ManagedServiceAccount` resource, you must have the `ManagedServiceAccount` add-on. For more information about enabling the `ManagedServiceAccount` add-on, see link:../add-ons/configure_klusterlet_addons.adoc[Configuring klusterlet add-ons]. 
+
+.Procedure 
+
+Complete the following steps to create a `ClusterPermission` resource that grants permissions to a managed service account:
+
+. To grant the `<managed-sa-sample>` service account permission to the sample mortgage application that is deployed to the `mortgage` namespace on `<managed-cluster>`, create a YAML file with the following content: 
+
++
+[source,yaml]
+----
+apiVersion: rbac.open-cluster-management.io/v1alpha1
+kind: ClusterPermission
+metadata:
+  name: <clusterpermission-msa-subject-sample>
+  namespace: <managed-cluster>
+spec:
+  roles:
+  - namespace: default
+    rules:
+    - apiGroups: ["apps"]
+      resources: ["deployments"]
+      verbs: ["get", "list", "create", "update", "delete", "patch"]
+    - apiGroups: [""]
+      resources: ["configmaps", "secrets", "pods", "podtemplates", "persistentvolumeclaims", "persistentvolumes"]
+      verbs: ["get", "update", "list", "create", "delete", "patch"]
+    - apiGroups: ["storage.k8s.io"]
+      resources: ["*"]
+      verbs: ["list"]
+  - namespace: mortgage
+    rules:
+    - apiGroups: ["apps"]
+      resources: ["deployments"]
+      verbs: ["get", "list", "create", "update", "delete", "patch"]
+    - apiGroups: [""]
+      resources: ["configmaps", "secrets", "pods", "services", "namespace"]
+      verbs: ["get", "update", "list", "create", "delete", "patch"]
+  clusterRole:
+    rules:
+    - apiGroups: ["*"]
+      resources: ["*"]
+      verbs: ["get", "list"]
+  roleBindings:
+  - namespace: default
+    roleRef:
+      kind: Role
+    subject:
+      apiGroup: authentication.open-cluster-management.io
+      kind: ManagedServiceAccount
+      name: <managed-sa-sample>
+  - namespace: mortgage
+    roleRef:
+      kind: Role
+    subject:
+      apiGroup: authentication.open-cluster-management.io
+      kind: ManagedServiceAccount
+      name: <managed-sa-sample>
+  clusterRoleBinding:
+    subject:
+      apiGroup: authentication.open-cluster-management.io
+      kind: ManagedServiceAccount
+      name: <managed-sa-sample>
+----
+
+. Save your YAML file.
+
+. Apply your YAML file by running the following command:
+
++
+[source,bash]
+----
+oc apply -f cluster-permission.yaml
+----
+
+. The sample `<clusterpermission>` creates a role called `<clusterpermission-msa-subject-sample>` in the `mortgage` namespace. If one does not already exist, create a namespace `mortgage`. 
+. Review the resources that are created on the `<managed-cluster>` namespace. 
+
+After you create the sample, `<clusterpermission>`, the following resources are created in the sample managed cluster:
+
+* One `Role` called `<clusterpermission-msa-subject-sample>` in the default namespace.
+* One `RoleBinding` called `<clusterpermission-msa-subject-sample>` in the default namespace for binding the role to the managed service account. 
+* One `Role` called `<clusterpermission-msa-subject-sample>` in the mortgage namespace.
+* One `RoleBinding` called `<clusterpermission-msa-subject-sample>` in the mortgage namespace for binding the role to the managed service account.
+* One `ClusterRole` called `<clusterpermission-msa-subject-sample>`. 
+* One `ClusterRoleBinding` called `<clusterpermission-msa-subject-sample>` for binding the `ClusterRole` to the managed service account.