Chapter 3. Customizing permissions by creating aggregated cluster roles
The default cluster role for the Argo CD Application Controller has a specific set of hard-coded permissions. The Red Hat OpenShift GitOps Operator manages this cluster role, so you cannot modify it. As a cluster administrator, you can customize the permissions by using any one of the following methods:
3.1. Aggregated cluster roles
By using aggregated cluster roles, you do not have to define permissions by creating new cluster roles from scratch. Instead, you can combine several cluster roles into a single one.
With Red Hat OpenShift GitOps 1.14 and later, as a cluster administrator, you can use aggregated cluster roles and enable users to easily add user-defined permissions for Argo CD Application Controller.
- The aggregated cluster roles functionality is optional and disabled by default. You can create aggregated cluster roles only for the Argo CD Application Controller component of a cluster-scoped Argo CD instance.
-
Deleting the
aggregatedClusterRoles
field from the Argo CD custom resource (CR) does not delete the user-defined cluster role. You must manually delete the user-defined cluster role using the CLI or UI.
3.2. Prerequisites
- You understand aggregated cluster roles.
- You have installed Red Hat OpenShift GitOps on your OpenShift Container Platform cluster.
-
You have installed the OpenShift CLI (
oc
). -
You have installed the Red Hat OpenShift GitOps
argocd
CLI. - You have installed a cluster-scoped Argo CD instance in your defined namespace.
You have validated that the user-defined cluster-scoped instance is configured with the cluster roles and cluster role bindings for the following components:
- Argo CD Application Controller
- Argo CD server
- Argo CD ApplicationSet Controller, if ApplicationSet Controller is created
- You have disabled the creation of the default cluster roles for the cluster-scoped instance.
3.3. Creating aggregated cluster roles
The process of creating aggregated cluster roles consists of the following procedures:
- Enabling the creation of aggregated cluster roles
- Creating user-defined cluster roles and configuring user-defined permissions for Application Controller
3.3.1. Enable the creation of aggregated cluster roles
You can enable the creation of aggregated cluster roles by setting the value of the .spec.aggregatedClusterRoles
field to true
in the Argo CD custom resource (CR). When you enable the creation of aggregated cluster roles, the {gitops} Operator takes the following actions:
-
Creates an
<argocd_name>-<argocd_namespace>-argocd-application-controller
aggregated cluster role with a predefinedaggregationRule
field by default. - Creates a corresponding cluster role binding and manages it.
-
Creates and manages
view
andadmin
cluster roles for Application Controller to add user-defined permissions into the aggregated cluster role.
3.3.2. Create user-defined cluster roles and configure user-defined permissions
To configure user-defined permissions into the <argocd_name>-<argocd_namespace>-argocd-application-controller-admin
cluster role and aggregated cluster role, you must create one or more user-defined cluster roles with the argocd/aggregate-to-admin: 'true'
label and then configure the user-defined permissions for Application Controller.
-
The aggregated cluster role inherits permissions from the
<argocd_name>-<argocd_namespace>-argocd-application-controller-admin
and<argocd_name>-<argocd_namespace>-argocd-application-controller-view
cluster roles. -
The
<argocd_name>-<argocd_namespace>-argocd-application-controller-admin
cluster role inherits permissions from the user-defined cluster role.
3.4. Enabling the creation of aggregated cluster roles
To enable the creation of aggregated cluster roles for the Argo CD Application Controller component of a cluster-scoped Argo CD instance, you must configure the corresponding field by editing the YAML file of the Argo CD custom resource (CR).
Procedure
In the Argo CD CR, set the value of the
.spec.aggregatedClusterRoles
field totrue
:Example Argo CD CR
apiVersion: argoproj.io/v1beta1 kind: ArgoCD metadata: name: example 1 namespace: spring-petclinic 2 # ... spec: aggregatedClusterRoles: true 3 # ...
- 1
- The name of the cluster-scoped instance.
- 2
- The namespace where you want to run the cluster-scoped instance.
- 3
- The value set to
true
enables the creation of aggregated cluster roles. If you do not want to enable the creation of aggregated cluster roles, either do not include this line or set the value tofalse
.
Example output
argocd.argoproj.io/example configured
Verify that the
Status
field of the cluster-scoped Argo CD instance shows asPhase: Available
by running the following command:$ oc describe argocd.argoproj.io/example -n spring-petclinic
Example output
Name: example Namespace: spring-petclinic Labels: <none> Annotations: <none> API Version: argoproj.io/v1beta1 Kind: ArgoCD Metadata: Creation Timestamp: 2024-08-14T08:20:53Z Finalizers: argoproj.io/finalizer Generation: 3 Resource Version: 60437 UID: 57940e54-d60b-4c1a-bc4a-85c81c63ab69 Spec: Aggregated Cluster Roles: true ... Status: Application Controller: Running Application Set Controller: Unknown Phase: Available 1 Redis: Running Repo: Running Server: Running Sso: Unknown Events: <none>
- 1
- The
Available
status indicates that the cluster-scoped Argo CD instance is healthy and available.
NoteThe Red Hat OpenShift GitOps Operator creates the following default cluster roles and manages them:
-
<argocd_name>-<argocd_namespace>-argocd-application-controller
aggregated cluster role -
<argocd_name>-<argocd_namespace>-argocd-application-controller-view
-
<argocd_name>-<argocd_namespace>-argocd-application-controller-admin
Verify that the Operator has created the default cluster roles and cluster role bindings for the Argo CD Application Controller and Argo CD server components by running the following commands:
$ oc get ClusterRoles -l app.kubernetes.io/part-of=argocd
Example output
NAME CREATED AT example-spring-petclinic-argocd-application-controller 2024-08-14T08:20:58Z example-spring-petclinic-argocd-application-controller-admin 2024-08-14T09:08:38Z example-spring-petclinic-argocd-application-controller-view 2024-08-14T09:08:38Z example-spring-petclinic-argocd-server 2024-08-14T08:20:59Z
$ oc get ClusterRoleBindings -l app.kubernetes.io/part-of=argocd
Example output
NAME ROLE AGE example-spring-petclinic-argocd-application-controller ClusterRole/example-spring-petclinic-argocd-application-controller 54m example-spring-petclinic-argocd-server ClusterRole/example-spring-petclinic-argocd-server 54m
The cluster role bindings for the
view
andadmin
cluster roles are not created. This is because theview
andadmin
cluster roles only add permissions to the aggregated cluster role and do not directly configure permissions to the Argo CD Application Controller.TipAlternatively, you can use the OpenShift Container Platform web console to verify from the Administrator perspective. You can go to User Management
Roles and User Management RoleBindings, respectively. You can search for the cluster roles and cluster role bindings that have the app.kubernetes.io/part-of:argocd
label.Verify that the aggregated cluster role is created by checking the permissions of outputs of the roles created by running the following command:
$ oc get ClusterRole/<cluster_role_name> -o yaml 1
- 1
- Replace
<cluster_role_name>
with the name of the role created.
Example output of the aggregated cluster role
apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: annotations: argocds.argoproj.io/name: example argocds.argoproj.io/namespace: spring-petclinic kubectl.kubernetes.io/last-applied-configuration: | {"apiVersion":"argoproj.io/v1beta1","kind":"ArgoCD","metadata":{"annotations":{},"name":"example","namespace":"spring-petclinic"},"spec":{"aggregatedClusterRoles":true}} rbac.authorization.kubernetes.io/autoupdate: "true" creationTimestamp: "2024-08-14T08:20:58Z" labels: app.kubernetes.io/managed-by: spring-petclinic app.kubernetes.io/name: example app.kubernetes.io/part-of: argocd name: example-spring-petclinic-argocd-application-controller 1 resourceVersion: "78640" uid: aeeb2ef5-b531-4fe3-a61a-b5ad8dd8ca6e aggregationRule: 2 clusterRoleSelectors: - matchLabels: app.kubernetes.io/managed-by: spring-petclinic argocd/aggregate-to-controller: "true" rules: [] 3
- 1
- The name of the aggregated cluster role.
- 2
- The predefined list of labels indicates that the aggregated cluster role can inherit permissions from the other user-defined cluster roles.
- 3
- No predefined permissions are set. However, when the Operator immediately creates a
<argocd_name>-<argocd_namespace>-argocd-application-controller-view
cluster role, the corresponding predefinedview
permissions are added into the aggregated cluster role.
Example output of the
view
cluster roleapiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: annotations: argocds.argoproj.io/name: example argocds.argoproj.io/namespace: spring-petclinic kubectl.kubernetes.io/last-applied-configuration: | {"apiVersion":"argoproj.io/v1beta1","kind":"ArgoCD","metadata":{"annotations":{},"name":"example","namespace":"spring-petclinic"},"spec":{"aggregatedClusterRoles":true}} creationTimestamp: "2024-08-14T09:59:14Z" labels: 1 app.kubernetes.io/managed-by: spring-petclinic app.kubernetes.io/name: example app.kubernetes.io/part-of: argocd argocd/aggregate-to-controller: "true" name: example-spring-petclinic-argocd-application-controller-view 2 resourceVersion: "78639" uid: 068b8867-7a0c-4af3-a17a-0560a00eba41 rules: 3 - apiGroups: - '*' resources: - '*' verbs: - get - list - watch - nonResourceURLs: - '*' verbs: - get - list
Example output of the
admin
cluster roleapiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: annotations: argocds.argoproj.io/name: example argocds.argoproj.io/namespace: spring-petclinic kubectl.kubernetes.io/last-applied-configuration: | {"apiVersion":"argoproj.io/v1beta1","kind":"ArgoCD","metadata":{"annotations":{},"name":"example","namespace":"spring-petclinic"},"spec":{"aggregatedClusterRoles":true}} rbac.authorization.kubernetes.io/autoupdate: "true" creationTimestamp: "2024-08-14T09:59:15Z" labels: 1 app.kubernetes.io/managed-by: spring-petclinic app.kubernetes.io/name: example app.kubernetes.io/part-of: argocd argocd/aggregate-to-controller: "true" name: example-spring-petclinic-argocd-application-controller-admin 2 resourceVersion: "78642" uid: e2d35b6f-0832-4993-8b24-915a725454f9 aggregationRule: 3 clusterRoleSelectors: - matchLabels: app.kubernetes.io/managed-by: spring-petclinic argocd/aggregate-to-admin: "true" rules: null 4
- 1
- The labels match the predefined list of an existing aggregated cluster role.
- 2
- The name of the
admin
cluster role. - 3
- The predefined list of labels indicates that the existing
<argocd_name>-<argocd_namespace>-argocd-application-controller-admin
cluster role can inherit permissions from the other user-defined cluster roles. - 4
- Specifies that no permissions are defined yet in one or more user-defined cluster roles.
TipAlternatively, you can use the OpenShift Container Platform web console to verify from the Administrator perspective. You can go to User Management
Roles, use the Filter option, select Cluster-wide Roles, and search for the aggregated cluster role, view
, andadmin
cluster roles. You must open the cluster role to check the details and configurations.As a cluster administrator, you can now create one or more user-defined cluster roles and configure user-defined permissions for Argo CD Application Controller.
Additional resources
3.5. Creating user-defined cluster roles and configuring user-defined permissions for Application Controller
As a cluster administrator, to add user-defined permissions to your aggregated cluster role, you must create one or more user-defined cluster roles and then configure the user-defined permissions for the Argo CD Application Controller component of a cluster-scoped Argo CD instance.
Prerequisites
- You have enabled the creation of aggregated cluster roles for the Argo CD Application Controller component of a cluster-scoped Argo CD instance.
You have the following default cluster roles that are created and managed by the Red Hat OpenShift GitOps Operator:
-
<argocd_name>-<argocd_namespace>-argocd-application-controller
aggregated cluster role with a predefinedaggregationRule
field -
<argocd_name>-<argocd_namespace>-argocd-application-controller-view
with predefinedview
permissions -
<argocd_name>-<argocd_namespace>-argocd-application-controller-admin
with no predefined permissions
-
Procedure
Create a new cluster role with the required labels and permissions by using the following command:
$ oc apply -n <namespace> -f <cluster_role_name>.yaml
where:
<namespace>
- Specifies the name of your defined namespace.
<cluster_role_name>
Specifies the name of your defined cluster role YAML file.
Example user-defined cluster role YAML
apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: user-application-controller 1 labels: 2 app.kubernetes.io/managed-by: spring-petclinic app.kubernetes.io/name: example app.kubernetes.io/part-of: argocd argocd/aggregate-to-admin: 'true' rules: 3 - verbs: - '*' apiGroups: - '' resources: - namespaces - persistentvolumeclaims - persistentvolumes - configmaps - verbs: - '*' apiGroups: - compliance.openshift.io resources: - scansettingbindings
- 1
- The name of the user-defined cluster role.
- 2
- The labels match the predefined list of an existing
<argocd_name>-<argocd_namespace>-argocd-application-controller-admin
cluster role. - 3
- The user-defined permissions that are to be added into the aggregated cluster role through the
<argocd_name>-<argocd_namespace>-argocd-application-controller-admin
cluster role.
TipAlternatively, you can use the web console to create a user-defined cluster role from the Administrator perspective. You can go to User Management
Roles Create Role, use the preceding YAML template to add permissions, and click Create. Example output
clusterrole.rbac.authorization.k8s.io/user-application-controller created
A user-defined cluster role is created.
Verify that the
<argocd_name>-<argocd_namespace>-argocd-application-controller-admin
cluster role inherits permissions from the user-defined cluster role by running the following command:$ oc get ClusterRole/<argocd_name>-<argocd_namespace>-argocd-application-controller-admin -o yaml
where:
<argocd_name>
- Specifies the name of your user-defined cluster-scoped Argo CD instance.
<argocd_namespace>
Specifies the namespace where Argo CD is installed.
Example output
aggregationRule: clusterRoleSelectors: - matchLabels: app.kubernetes.io/managed-by: spring-petclinic argocd/aggregate-to-admin: "true" apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: annotations: argocds.argoproj.io/name: example argocds.argoproj.io/namespace: spring-petclinic kubectl.kubernetes.io/last-applied-configuration: | {"apiVersion":"argoproj.io/v1beta1","kind":"ArgoCD","metadata":{"annotations":{},"name":"example","namespace":"spring-petclinic"},"spec":{"aggregatedClusterRoles":true}} creationTimestamp: "2024-08-14T09:59:15Z" labels: app.kubernetes.io/managed-by: spring-petclinic app.kubernetes.io/name: example app.kubernetes.io/part-of: argocd argocd/aggregate-to-controller: "true" name: example-spring-petclinic-argocd-application-controller-admin resourceVersion: "79202" uid: e2d35b6f-0832-4993-8b24-915a725454f9 rules: - apiGroups: - "" resources: - namespaces - persistentvolumeclaims - persistentvolumes - configmaps verbs: - '*' - apiGroups: - compliance.openshift.io resources: - scansettingbindings verbs: - '*'
TipAlternatively, you can use the OpenShift Container Platform web console to verify from the Administrator perspective. You can go to User Management
Roles, use the Filter option, select Cluster-wide Roles, and search for the <argocd_name>-<argocd_namespace>-argocd-application-controller-admin
cluster role. You must open the cluster role to check the details and configurations.
Verify that the
<argocd_name>-<argocd_namespace>-argocd-application-controller
aggregated cluster role inherits permissions from the<argocd_name>-<argocd_namespace>-argocd-application-controller-admin
and<argocd_name>-<argocd_namespace>-argocd-application-controller-view
cluster roles by running the following command:$ oc get ClusterRole/<argocd_name>-<argocd_namespace>-argocd-application-controller -o yaml
where:
<argocd_name>
- Specifies the name of your user-defined cluster-scoped Argo CD instance.
<argocd_namespace>
Specifies the namespace where Argo CD is installed.
Example output of the aggregated cluster role
aggregationRule: clusterRoleSelectors: - matchLabels: app.kubernetes.io/managed-by: spring-petclinic argocd/aggregate-to-controller: "true" apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: annotations: argocds.argoproj.io/name: example argocds.argoproj.io/namespace: spring-petclinic kubectl.kubernetes.io/last-applied-configuration: | {"apiVersion":"argoproj.io/v1beta1","kind":"ArgoCD","metadata":{"annotations":{},"name":"example","namespace":"spring-petclinic"},"spec":{"aggregatedClusterRoles":true}} rbac.authorization.kubernetes.io/autoupdate: "true" creationTimestamp: "2024-08-14T08:20:58Z" labels: app.kubernetes.io/managed-by: spring-petclinic app.kubernetes.io/name: example app.kubernetes.io/part-of: argocd name: example-spring-petclinic-argocd-application-controller resourceVersion: "79203" uid: aeeb2ef5-b531-4fe3-a61a-b5ad8dd8ca6e rules: - apiGroups: - "" resources: - namespaces - persistentvolumeclaims - persistentvolumes - configmaps verbs: - '*' - apiGroups: - compliance.openshift.io resources: - scansettingbindings verbs: - '*' - apiGroups: - '*' resources: - '*' verbs: - get - list - watch - nonResourceURLs: - '*' verbs: - get - list
TipAlternatively, you can use the OpenShift Container Platform web console to verify from the Administrator perspective. You can go to User Management
Roles, use the Filter option, select Cluster-wide Roles, and search for the aggregated cluster role. You must open the cluster role to check the details and configurations.