Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Dec 2, 2025
Merged

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
57cca04
https://issues.redhat.com/browse/ACM-24933 part 2
dockerymick Nov 25, 2025
6bce1d2
Updates after dev review
dockerymick Dec 1, 2025
dfee0f2
Update secure_clusters/cluster_permission_intro.adoc
dockerymick Dec 1, 2025
77e18cf
Apply suggestion from @dockerymick
dockerymick Dec 1, 2025
d5960b7
Breaking up YAML
dockerymick Dec 2, 2025
8dd49f8
Updates
dockerymick Dec 2, 2025
473d834
Updates
dockerymick Dec 2, 2025
dbf3157
Updates
dockerymick Dec 2, 2025
8fd3ec4
Apply suggestion from @dockerymick
dockerymick Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
191 changes: 2 additions & 189 deletions gitops/gitops_service_account_argo_cd.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down
8 changes: 3 additions & 5 deletions secure_clusters/cluster_permission_intro.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
95 changes: 95 additions & 0 deletions secure_clusters/create_cluster_permission.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Contributor

@swopebe swopebe Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should not be using "it" so much. I recommend:

By default, a service account with created without an associated permission.


*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 `<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:

Copy link
Contributor

@swopebe swopebe Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to introduce this YAML better. I would rather not have most of the file a YAML file with no explanation.

We need to introduce the kind, then we should have separate steps about the roles, role bindings, etc... It's not good practice to give a large about of YAML in one step and say Create this YAML.

Copy link
Contributor

@swopebe swopebe Dec 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See here that the bindings were created in a step in 2.14 and pieces of the YAML were defined in a step or the intro: https://github.com/stolostron/rhacm-docs/blob/2.14_stage/secure_clusters/fine_grain_rbac_cli.adoc

We got away from that for some reason here?

Copy link
Contributor Author

@dockerymick dockerymick Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is old content. I just didn't focus on updating all of the content because we were up against time.

Copy link
Contributor Author

@dockerymick dockerymick Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@fxiang1

Copy link

@fxiang1 fxiang1 Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right I agree with @dockerymick , I thought we were just moving this from the ALC Gitops section. This is not something new we've introduced recently.

Copy link
Contributor

@swopebe swopebe Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have gotten away from pushing large YAML samples without directions for them, but now I understand that this is previous content. I suggest we introduce the pieces that make the cluster permission, without reorganizing. Going forward the team agrees that this is not best practice and that important pieces of YAML need to be implemented as part of a larger process for understanding.

Copy link

@fxiang1 fxiang1 Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep understood, going through our docs I see we have many large YAML samples without explanation. Maybe we need to create a separate story/task for each of the component teams to just check and add explanation steps for these?

Copy link
Contributor Author

@dockerymick dockerymick Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@fxiang1 yup that's a great idea. I will improve the examples in this PR and then focus on other areas in the tech debt/refresh doc issue

Copy link
Contributor

@swopebe swopebe Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wow, these changes are more than I even expected here for this PR. I thought we could just add some intro info and be good but you took it even further to improve it. Great job.

Copy link
Contributor

@swopebe swopebe Dec 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@fxiang1 I think for the newer info that is being used a lot, yes, we can improve that YAML presentation. We have as a team mostly been doing that in new content. I don't think we will have time to fix everything, but certainly highly used doc we can improve.

+
[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 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 `<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.
Loading