From 57cca04b725d64761b62f25c61f15aa8464d4f6d Mon Sep 17 00:00:00 2001 From: Mikela Jackson Date: Tue, 25 Nov 2025 18:44:18 -0500 Subject: [PATCH 1/2] https://issues.redhat.com/browse/ACM-24933 part 2 --- gitops/gitops_service_account_argo_cd.adoc | 191 +----------------- secure_clusters/cluster_permission_intro.adoc | 8 +- .../create_cluster_permission.adoc | 95 +++++++++ .../create_cluster_permission_exist.adoc | 76 +++++++ .../create_cluster_permission_ref.adoc | 82 ++++++++ 5 files changed, 258 insertions(+), 194 deletions(-) create mode 100644 secure_clusters/create_cluster_permission.adoc create mode 100644 secure_clusters/create_cluster_permission_exist.adoc create mode 100644 secure_clusters/create_cluster_permission_ref.adoc diff --git a/gitops/gitops_service_account_argo_cd.adoc b/gitops/gitops_service_account_argo_cd.adoc index 61a5c7491c..e03a0d736a 100644 --- a/gitops/gitops_service_account_argo_cd.adoc +++ b/gitops/gitops_service_account_argo_cd.adoc @@ -12,11 +12,6 @@ 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 @@ -24,188 +19,6 @@ The `ManagedServiceAccount` custom resource on the hub provides a convenient way 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 `` service account permission to the sample mortgage application that is deployed to the mortgage namespace on ``, create a YAML with the following content: - -[source,yaml] ----- -apiVersion: rbac.open-cluster-management.io/v1alpha1 -kind: ClusterPermission -metadata: - name: - namespace: -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: - - namespace: mortgage - roleRef: - kind: Role - subject: - apiGroup: authentication.open-cluster-management.io - kind: ManagedServiceAccount - name: - clusterRoleBinding: - subject: - apiGroup: authentication.open-cluster-management.io - kind: ManagedServiceAccount - name: ----- - -. Save the YAML file in a file called, `cluster-permission.yaml`. -. Run `oc apply -f cluster-permission.yaml`. -. The sample `` creates a role called `` in the mortgage namespace. If one does not already exist, create a namespace `mortgage`. -. Review the resources that are created on the ``. - -After you create the sample, ``, the following resources are created in the sample managed cluster: - -* One `Role` called `` in the default namespace. -* One `RoleBinding` called `` in the default namespace for binding the role to the managed service account. -* One `Role` called `` in the mortgage namespace. -* One `RoleBinding` called `` in the mortgage namespace for binding the role to the managed service account. -* One `ClusterRole` called ``. -* One `ClusterRoleBinding` called `` 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,7 +70,7 @@ 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, ``. -. 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 ``. @@ -265,7 +78,7 @@ Deploy an Argo CD application from the Argo CD console by using the pushing mode [#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. diff --git a/secure_clusters/cluster_permission_intro.adoc b/secure_clusters/cluster_permission_intro.adoc index 1868512737..05445cebd2 100644 --- a/secure_clusters/cluster_permission_intro.adoc +++ b/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] diff --git a/secure_clusters/create_cluster_permission.adoc b/secure_clusters/create_cluster_permission.adoc new file mode 100644 index 0000000000..ab1937ae7f --- /dev/null +++ b/secure_clusters/create_cluster_permission.adoc @@ -0,0 +1,95 @@ +[#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 + +- are there any prereqs for this? + +.Procedure + +Complete the following steps to create a `ClusterPermission` resource that grants permissions to a managed service account: + +. To grant the `` service account permission to the sample mortgage application that is deployed to the `mortgage` namespace on ``, create a YAML file with the following content: + ++ +[source,yaml] +---- +apiVersion: rbac.open-cluster-management.io/v1alpha1 +kind: ClusterPermission +metadata: + name: + namespace: +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: + - namespace: mortgage + roleRef: + kind: Role + subject: + apiGroup: authentication.open-cluster-management.io + kind: ManagedServiceAccount + name: + clusterRoleBinding: + subject: + apiGroup: authentication.open-cluster-management.io + kind: ManagedServiceAccount + name: +---- + +. Save the YAML file and name the file, `cluster-permission.yaml`. +//should the name match the name in the previous example? + +. Apply your YAML file by running the following command: + ++ +[source,bash] +---- +oc apply -f cluster-permission.yaml +---- + +. The sample `` creates a role called `` in the `mortgage` namespace. If one does not already exist, create a namespace `mortgage`. +. Review the resources that are created on the `` namespace. + +After you create the sample, ``, the following resources are created in the sample managed cluster: + +* One `Role` called `` in the default namespace. +* One `RoleBinding` called `` in the default namespace for binding the role to the managed service account. +* One `Role` called `` in the mortgage namespace. +* One `RoleBinding` called `` in the mortgage namespace for binding the role to the managed service account. +* One `ClusterRole` called ``. +* One `ClusterRoleBinding` called `` for binding the `ClusterRole` to the managed service account. \ No newline at end of file diff --git a/secure_clusters/create_cluster_permission_exist.adoc b/secure_clusters/create_cluster_permission_exist.adoc new file mode 100644 index 0000000000..eaeba632d1 --- /dev/null +++ b/secure_clusters/create_cluster_permission_exist.adoc @@ -0,0 +1,76 @@ +[#create-cluster-permission-exist] += 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. + +*Required access:* Cluster administrator + +.Prerequisites + +- are there any prereqs for this? + +.Procedure + +. Create a `ClusterPermission` resource that uses an existing role by running the following command: + ++ +[source,bash] +---- +oc create -f .yaml +---- + +. Run the following command to apply your `ClusterPermission` resource that uses an existing `ClusterRole` resource: + ++ +[source,bash] +---- +oc apply -f .yaml +---- + ++ +Your `ClusterPermission` resource might resemble the following example: + ++ +[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. diff --git a/secure_clusters/create_cluster_permission_ref.adoc b/secure_clusters/create_cluster_permission_ref.adoc new file mode 100644 index 0000000000..d2404ee829 --- /dev/null +++ b/secure_clusters/create_cluster_permission_ref.adoc @@ -0,0 +1,82 @@ +[#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. + +*Required access:* Cluster administrator + +.Prerequisites + +- are there any prereqs for this? + +.Procedure + +Complete the following steps to create a `ClusterPermission` resource that references different subjects such as users, groups, and service accounts: + +. Create a `ClusterPermission` resource that references different subjects by running the following command: + ++ +[source,bash] +---- +oc create -f .yaml +---- + +. Run the following command to apply your `ClusterPermission` resource that references different subjects: + ++ +[source,bash] +---- +oc apply -f .yaml +---- + ++ +Your `ClusterPermission` resource might resemble the following YAML file 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 +---- From 6bce1d2254da4dba4d87503765c4aa4aa7128fbd Mon Sep 17 00:00:00 2001 From: Mikela Jackson Date: Mon, 1 Dec 2025 12:32:58 -0500 Subject: [PATCH 2/2] Updates after dev review --- secure_clusters/create_cluster_permission.adoc | 5 ++--- secure_clusters/create_cluster_permission_exist.adoc | 2 +- secure_clusters/create_cluster_permission_ref.adoc | 2 +- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/secure_clusters/create_cluster_permission.adoc b/secure_clusters/create_cluster_permission.adoc index ab1937ae7f..f511bbf6b2 100644 --- a/secure_clusters/create_cluster_permission.adoc +++ b/secure_clusters/create_cluster_permission.adoc @@ -7,7 +7,7 @@ When the service account is created, it does not have any permission associated .Prerequisites -- are there any prereqs for this? +- 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 @@ -71,8 +71,7 @@ spec: name: ---- -. Save the YAML file and name the file, `cluster-permission.yaml`. -//should the name match the name in the previous example? +. Save your YAML file. . Apply your YAML file by running the following command: diff --git a/secure_clusters/create_cluster_permission_exist.adoc b/secure_clusters/create_cluster_permission_exist.adoc index eaeba632d1..ba428a7dc3 100644 --- a/secure_clusters/create_cluster_permission_exist.adoc +++ b/secure_clusters/create_cluster_permission_exist.adoc @@ -7,7 +7,7 @@ When you create a `ClusterPermission` resource, you automatically create new rol .Prerequisites -- are there any prereqs for this? +- 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 diff --git a/secure_clusters/create_cluster_permission_ref.adoc b/secure_clusters/create_cluster_permission_ref.adoc index d2404ee829..9afca572dc 100644 --- a/secure_clusters/create_cluster_permission_ref.adoc +++ b/secure_clusters/create_cluster_permission_ref.adoc @@ -7,7 +7,7 @@ If you create a `ClusterPermission` resource to reference different subjects, yo .Prerequisites -- are there any prereqs for this? +- 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