Chapter 1. Multitenancy support in GitOps

After you create an Argo CD custom resource (CR) in one of your namespaces, the GitOps Operator starts an Argo CD in this namespace, which you can use for application delivery. In its initial state, this instance has permission to deploy resources only in the same namespace in which it is installed. However, you may need to configure the instance to meet your specific requirements.

With the GitOps Operator, you can extend the permissions of the Argo CD instance to enable the Argo CD Application Controller to deploy resources into other namespaces apart from where it is installed.

For the Argo CD Application Controller to deploy resources into any other namespace, you need Kubernetes roles and role bindings to label and indicate these namespaces that you want a namespace-scoped instance to manage. The GitOps Operator supports the use of the argocd.argoproj.io/managed-by label to automatically create these roles and role bindings. Use this label and set the value to indicate the managed namespaces. Then, with the argocd.argoproj.io/managed-by label, when you deploy the GitOps Operator in the namespace-scoped instance mode, it creates a set of roles and role bindings in every namespace that the instance manages.

By default, when labeling the namespace using the managed-by label, the GitOps Operator gives the Argo CD Application Controller permissions equivalent to the Kubernetes default admin cluster role for the labeled namespace. However, you can opt to define an alternate cluster role that is used for the controller and server components by using the CONTROLLER_CLUSTER_ROLE and CONTROLLER_SERVER_ROLE environment variables respectively in the Operator’s Subscription resource. When you provide these variables, the Operator will not create a default role in the namespace but rather only create a role binding in the namespace of the corresponding cluster role. It is up to the administrator to create the cluster role, having full control over the permissions.

A cluster-scoped instance is intended to deploy and manage resources across a cluster.

Cluster-scoped instances have access to cluster-level resources and thus are typically, but not always, used for cluster configuration. You can choose to elevate certain namespace-scoped Argo CD instances to become cluster-scoped. To elevate the instances, you must modify the Subscription resource of the GitOps Operator.

Much care must be taken when setting up multitenancy configuration within Argo CD. For example, in a use case where cluster administrators want to set up an Argo CD instance that is shared among multiple application delivery teams and is managed by the cluster administrators, having a custom cluster-scoped instance might be what you need.

Because non-cluster administrators do not have access to the Subscription resource, they cannot elevate the privileges of their instance and bypass cluster security.

When an instance is designated as cluster-scoped, the Operator automatically creates a set of cluster role and cluster role bindings for the Argo CD Application Controller and server service accounts in that namespace. This default role is not intended to be the equivalent of the standard cluster-admin role. It is given a much smaller set of permissions. These permissions can be extended by creating additional cluster roles or cluster role bindings as needed.

After you install the GitOps Operator, by default, it instantiates a cluster-scoped instance in the openshift-gitops namespace. This instance is set up in a very opinionated way and is intended to allow cluster administrators to manage certain cluster configuration resources.

The default instance does not have full cluster-admin privileges. It has read access to all resources in the cluster, but it can only deploy a limited set of resources.

Access controls in Red Hat OpenShift GitOps are managed at two distinct levels as follows:

Because these two access controls and the interaction between components are distinct and separate, privilege escalation becomes a concern when designing a multitenant solution with Argo CD. Privilege escalation is when a tenant leverages the increased privileges of the application controller’s service account to perform actions they would not typically be permitted to perform. You can mitigate the privilege escalation in an Argo CD instance by using the Argo CD RBAC or separate instances of Argo CD.

Argo CD projects, not to be confused with OpenShift Container Platform projects, provide a way to group applications together. With Argo CD projects, you can specify restrictions on Applications concerning what resources can be deployed and where they can be deployed. Additionally, you can enable Argo CD role-based access control (RBAC) rules and permissions by defining them more granularly at the project level versus the global level in the Argo CD custom resource (CR).

While you can define tenant RBAC globally in the Operator’s Argo CD CR, you should define tenant RBAC along with restrictions in the AppProject CR.

If you have a large number of tenants, attempting to manage all tenants with global RBAC might lead to a lot of repetition.

If you have many instances of tenants, some of the project configurations might be common across tenant projects. To reduce duplication and minimize maintenance, use global projects for common configuration and inherit them in tenant projects.

You can enable non-cluster-admin users to configure namespace management for their Argo CD instances by creating a NamespaceManagement custom resource (CR).

You can verify the following resources in the tenant namespace:

where, <argocd-instance-name> is the name of your Argo CD instance.