Search

Chapter 3. Customizing permissions by creating aggregated cluster roles

download PDF

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.

Important
  • 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:

  1. Enabling the creation of aggregated cluster roles
  2. 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 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.

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.

Note
  • 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

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

    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.

    Tip

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

    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.

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

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

    Tip

    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

    Tip

    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.

3.6. Additional resources

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.