OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history bug_report picture_as_pdf
×

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:

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.

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.

Creating aggregated cluster roles

The process of creating aggregated cluster roles consists of the following procedures:

  1. Enabling the creation of aggregated cluster roles

  2. Creating user-defined cluster roles and configuring user-defined permissions for Application Controller

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 predefined aggregationRule field by default.

  • Creates a corresponding cluster role binding and manages it.

  • Creates and manages view and admin cluster roles for Application Controller to add user-defined permissions into the aggregated cluster role.

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.

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

  1. In the Argo CD CR, set the value of the .spec.aggregatedClusterRoles field to true:

    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 to false.
    Example output
    argocd.argoproj.io/example configured

  2. Verify that the Status field of the cluster-scoped Argo CD instance shows as Phase: 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.

    The 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

  3. 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 and admin cluster roles are not created. This is because the view and admin cluster roles only add permissions to the aggregated cluster role and do not directly configure permissions to the Argo CD Application Controller.

    Alternatively, 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.

  4. 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 predefined view permissions are added into the aggregated cluster role.
    Example output of the view 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}}
  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
    1 The labels match the predefined list of an existing aggregated cluster role.
    2 The name of the view cluster role.
    3 The predefined view permissions. These permissions are added into the existing aggregated cluster role.
    Example output of the admin 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-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.

    Alternatively, 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, and admin 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

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 predefined aggregationRule field

    • <argocd_name>-<argocd_namespace>-argocd-application-controller-view with predefined view permissions

    • <argocd_name>-<argocd_namespace>-argocd-application-controller-admin with no predefined permissions

Procedure

  1. 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.

    Alternatively, 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.

  2. 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:
  - '*'

    Alternatively, 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.

  3. 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

    Alternatively, 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.

Additional resources