diff --git a/modules/gitops-argocd-projects.adoc b/modules/gitops-argocd-projects.adoc index 8d7d32fd611d..b5dd81454582 100644 --- a/modules/gitops-argocd-projects.adoc +++ b/modules/gitops-argocd-projects.adoc @@ -7,11 +7,13 @@ = Argo CD projects [role="_abstract"] -Argo CD projects, not to be confused with {OCP} 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). +Argo CD projects, not to be confused with {OCP} projects, provide a way to group applications together. With Argo CD projects, you can specify restrictions on Applications, such as what resources can be deployed and where they can be deployed. -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. +Additionally, you can define Argo CD role-based access control (RBAC) rules at the project level. This approach allows more granular permissions compared to the global settings in the Argo CD custom resource (CR). -If you have a large number of tenants, attempting to manage all tenants with global RBAC might lead to a lot of repetition. +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 much 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. diff --git a/modules/gitops-argocd-rbac.adoc b/modules/gitops-argocd-rbac.adoc index 251533893f6c..dac68585afd9 100644 --- a/modules/gitops-argocd-rbac.adoc +++ b/modules/gitops-argocd-rbac.adoc @@ -9,7 +9,7 @@ [role="_abstract"] Access controls in {gitops-title} are managed at two distinct levels as follows: -* At the Kubernetes level, the {gitops-shortname} Argo CD Application Controller interacts with one or more clusters to deploy various resources by using a single Kubernetes service account per cluster. This service account must have sufficient permissions to deploy resources for all tenants and use cases that this instance of Argo CD is managing. -* At the Argo CD level, the {gitops-shortname} Argo CD Application Controller includes its own RBAC permissions model independent of Kubernetes. To manage the user-level access, you can use this RBAC model independently of the underlying Kubernetes permissions. You can use this capability to provide access to Argo CD applications that a user would not have access to from a purely Kubernetes perspective. +* At the Kubernetes level, the {gitops-shortname} Argo CD Application Controller interacts with one or more clusters to deploy various resources by using a single Kubernetes service account per cluster. This service account must have enough permissions to deploy resources for all tenants and use cases that this instance of Argo CD is managing. +* At the Argo CD level, the {gitops-shortname} Argo CD Application Controller includes its own RBAC permissions model independent of Kubernetes. To manage the user-level access, you can use this RBAC model independently of the underlying Kubernetes permissions. You can use this capability to give access to Argo CD applications that a user would not have access to from a purely Kubernetes perspective. -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. \ No newline at end of file +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. \ No newline at end of file diff --git a/modules/gitops-cluster-scoped-instance.adoc b/modules/gitops-cluster-scoped-instance.adoc index 87f1b1c372e7..de022e7cc74b 100644 --- a/modules/gitops-cluster-scoped-instance.adoc +++ b/modules/gitops-cluster-scoped-instance.adoc @@ -14,7 +14,7 @@ A cluster-scoped instance is intended to deploy and manage resources across a cl If you intend to use the _Applications in any namespace_ feature, choose the mode of the Argo CD instance scope as cluster-scoped instance. ==== -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-shortname} Operator. +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 change the `Subscription` resource of the {gitops-shortname} Operator. [IMPORTANT] ==== @@ -22,7 +22,7 @@ Cluster-scoped instances have access to cluster-level resources and thus are typ * Do not elevate instances that are self-managed by application delivery teams. Elevating such instances would be a severe security risk to the cluster because this action makes users of self-managed instances cluster administrators, and gives them full control over the permissions. ==== -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. +Much care must be taken when setting up multitenancy in Argo CD. For example, if cluster administrators manage a shared Argo CD instance for many application teams, a custom cluster-scoped instance might be appropriate. .How does this method work? @@ -30,4 +30,6 @@ To prevent users from deploying Argo CD instances with `cluster-admin` privilege 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. +When an instance is designated as cluster-scoped, the Operator automatically creates cluster roles and cluster role bindings. These are created for the Argo CD Application Controller and server service accounts in that namespace. + +This default role is not intended to be equal to the standard `cluster-admin` role. It gives a much smaller set of permissions. You can extend these permissions by creating additional cluster roles or cluster role bindings as needed. \ No newline at end of file diff --git a/modules/gitops-configuring-namespace-management-argocd-tenants.adoc b/modules/gitops-configuring-namespace-management-argocd-tenants.adoc index 163894819b4b..8c6c5f110248 100644 --- a/modules/gitops-configuring-namespace-management-argocd-tenants.adoc +++ b/modules/gitops-configuring-namespace-management-argocd-tenants.adoc @@ -52,18 +52,18 @@ apiVersion: argoproj.io/v1alpha1 kind: ArgoCD metadata: name: example-argocd - namespace: # <1> + namespace: # <1> spec: namespaceManagement: - - name: # <2> + - name: # <2> allowManagedBy: true ---- + -- where: -``:: Specifies the `` with the Argo CD instance namespace. -``:: Specifies the `` with the namespace that you want Argo CD to manage. You can also use a glob pattern with wildcards such as `/\*` and `?` for pattern matching. For example, specifying `dev-/\*` matches any namespace with the `dev-` prefix. +``:: Specifies the `` with the Argo CD instance namespace. +``:: Specifies the `` with the namespace that you want Argo CD to manage. You can also use a glob pattern with wildcards such as `/\*` and `?` for pattern matching. For example, specifying `dev-/\*` matches any namespace with the `dev-` prefix. -- . Create a `NamespaceManagement` CR. @@ -76,9 +76,9 @@ apiVersion: argoproj.io/v1beta1 kind: NamespaceManagement metadata: name: ui-team-namespace - namespace: # <1> + namespace: # <1> spec: - managedBy: # <2> + managedBy: # <2> ---- + -- @@ -97,8 +97,8 @@ After you create the `NamespaceManagement` CR, the {gitops-title} Operator autom You can verify the following resources in the tenant namespace: -* *Roles*: `-argocd-server`, `-argocd-application-controller` -* *RoleBindings*: `-argocd-server`, `-argocd-application-controller` -* *Cluster secret*: `-cluster` +* *Roles*: `-argocd-server`, `-argocd-application-controller` +* *RoleBindings*: `-argocd-server`, `-argocd-application-controller` +* *Cluster secret*: `-cluster` -where, is the name of your Argo CD instance. \ No newline at end of file +where, is the name of your Argo CD instance. \ No newline at end of file diff --git a/modules/gitops-enable-tenant-namespace-management-with-namespacemanagement.adoc b/modules/gitops-enable-tenant-namespace-management-with-namespacemanagement.adoc index a82b1fb4e3ec..a208783e44bf 100644 --- a/modules/gitops-enable-tenant-namespace-management-with-namespacemanagement.adoc +++ b/modules/gitops-enable-tenant-namespace-management-with-namespacemanagement.adoc @@ -13,7 +13,7 @@ _NamespaceManagement CR Overview_ The namespace management feature in {gitops-shortname} introduces a new `NamespaceManagement` custom resource (CR) that allows tenants to delegate control of their own namespaces to Argo CD instances without requiring direct cluster administrator action. For security reasons, this feature is disabled by default and must be explicitly enabled by a cluster administrator. -When enabled, Argo CD administrators can configure namespace management using glob patterns to match one or more namespaces, such as `/\*` or `tenant-/\*`. Tenants then create a `NamespaceManagement` custom resource (CR) in their target namespace. The {gitops-title} Operator automatically provisions the required role-based access control (RBAC) resources and updates the Argo CD cluster secret, ensuring that the namespace is managed correctly. +When enabled, Argo CD administrators can configure namespace management by using glob patterns to match one or more namespaces, such as `/\*` or `tenant-/\*`. Tenants then create a `NamespaceManagement` custom resource (CR) in their target namespace. The {gitops-title} Operator automatically provisions the required role-based access control (RBAC) resources and updates the Argo CD cluster secret, ensuring that the namespace is managed correctly. _Effects of `NamespaceManagement` CR_ diff --git a/modules/gitops-namespace-scoped-instance.adoc b/modules/gitops-namespace-scoped-instance.adoc index def7133cedb1..d2a7b5da2eee 100644 --- a/modules/gitops-namespace-scoped-instance.adoc +++ b/modules/gitops-namespace-scoped-instance.adoc @@ -7,7 +7,7 @@ = Namespace-scoped instance (Application delivery instance) [role="_abstract"] -After you create an Argo CD custom resource (CR) in one of your namespaces, the {gitops-shortname} 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. +After you create an Argo CD custom resource (CR) in one of your namespaces, the {gitops-shortname} 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 might need to configure the instance to meet your specific requirements. With the {gitops-shortname} 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. @@ -18,19 +18,19 @@ The roles that the {gitops-shortname} Operator in the namespace creates are name .How does this method work? -The {gitops-shortname} Operator allows OpenShift users to instantiate Argo CD instances in their namespaces, as long as they have permission to create Argo CD resources in the `argoproj.io/v1alpha1` or `argoproj.io/v1beta1` API in their namespace. Currently, a namespace-scoped instance has full administrative permissions for one or many namespaces it manages, similar to allowing all verbs for all resources within that namespace. +The {gitops-shortname} Operator allows OpenShift users to instantiate Argo CD instances in their namespaces, provided that they have permission to create Argo CD resources in the `argoproj.io/v1alpha1` or `argoproj.io/v1beta1` API in their namespace. Currently, a namespace-scoped instance has full administrative permissions for one or many namespaces it manages, similar to allowing all verbs for all resources within that namespace. -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-shortname} 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-shortname} Operator in the namespace-scoped instance mode, it creates a set of roles and role bindings in every namespace that the instance manages. +For the Argo CD Application Controller to deploy resources in other namespaces, you must configure Kubernetes roles and role bindings. These roles and bindings identify the namespaces that a namespace-scoped instance can manage. The {gitops-shortname} Operator supports the argocd.argoproj.io/managed-by label to simplify this setup. Use this label to indicate the namespaces managed by the instance. When you deploy the {gitops-shortname} Operator in namespace-scoped mode, it automatically creates the required roles and role bindings in each labeled namespace. [IMPORTANT] ==== The `argocd.argoproj.io/managed-by` label only works for namespaces in the same cluster as the {gitops-shortname} Operator. For remote clusters, you must define the permissions manually. ==== -By default, when labeling the namespace using the `managed-by` label, the {gitops-shortname} 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. +By default, when labeling the namespace by using the `managed-by` label, the {gitops-shortname} Operator gives the Argo CD Application Controller permissions equal 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 in the Operator's `Subscription` resource. When you give 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. [NOTE] ==== -* When defining your role, Argo CD will attempt to interact with all resources. Therefore, you must either provide permission to `view`, `get`, and `watch` all resources in your custom cluster role, or configure the Argo CD CR to include or exclude specific resources through the `resourceInclusions` or `resourceExclusions` fields defined in the role. +* When defining your role, Argo CD will attempt to interact with all resources. Therefore, you must either give permission to `view`, `get`, and `watch` all resources in your custom cluster role, or configure the Argo CD CR to include or exclude specific resources through the `resourceInclusions` or `resourceExclusions` fields defined in the role. * It is not possible to manage cluster-scoped resources, such as namespaces, custom resource definitions (CRDs), or cluster roles with a namespace-scoped instance. ==== diff --git a/multitenancy/multitenancy-support-in-gitops.adoc b/multitenancy/multitenancy-support-in-gitops.adoc index ea73986c006a..ba6a48fae6f2 100644 --- a/multitenancy/multitenancy-support-in-gitops.adoc +++ b/multitenancy/multitenancy-support-in-gitops.adoc @@ -1,4 +1,4 @@ -:_content-type: ASSEMBLY +:_mod-docs-content-type: ASSEMBLY include::_attributes/common-attributes.adoc[] [id="multitenancy-support-in-gitops"] = Multitenancy support in GitOps @@ -7,16 +7,16 @@ include::_attributes/common-attributes.adoc[] toc::[] [role="_abstract"] -Multitenancy is a software architecture where a single software instance serves multiple distinct user groups, or tenants. Using multitenancy, you can share a single Argo CD instance to deploy resources while maintaining isolation between users. This section helps cluster administrators to understand Argo CD instance scopes and when to choose a particular mode. +Multitenancy is a software architecture where a single software instance serves many distinct user groups, or tenants. Using multitenancy, you can share a single Argo CD instance to deploy resources while maintaining isolation between users. This section helps cluster administrators to understand Argo CD instance scopes and when to choose a particular mode. -With {gitops-title} Operator on {OCP}, as a cluster administrator, you can provide multitenant access to the cluster for application delivery teams (tenants). You can allow tenants to create and manage dedicated Argo CD instances in their user-defined namespaces without having administrative permissions. The tenants have full autonomy and can tailor this instance to their needs and requirements without interfering with other tenants. +With {gitops-title} Operator on {OCP}, as a cluster administrator, you can give multitenant access to the cluster for application delivery teams (tenants). You can allow tenants to create and manage dedicated Argo CD instances in their user-defined namespaces without having administrative permissions. The tenants have full autonomy and can tailor this instance to their needs and requirements without interfering with other tenants. [NOTE] ==== -For a multitenant cluster, the person managing the Argo CD instance may not be the person who manages the cluster and its users. Therefore, you cannot have the Argo CD Application Controller (`argocd-application-controller` component) as a superuser in the cluster. +For a multitenant cluster, the person managing the Argo CD instance might not be the person who manages the cluster and its users. Therefore, you cannot have the Argo CD Application Controller (`argocd-application-controller` component) as a superuser in the cluster. ==== -The Argo CD Application Controller reconciles resources in the managed clusters. Therefore, to use multitenancy in the {gitops-shortname} Operator, depending on your use cases, tenants, and requirements, you must configure, grant, extend, or restrict specific permissions explicitly to Argo CD instances, applications, and on remote clusters to perform certain operations. +The Argo CD Application Controller reconciles resources in managed clusters. To use multitenancy in the {gitops-shortname} Operator, configure permissions based on your use cases and tenant requirements. Explicitly grant, extend, or restrict permissions for Argo CD instances, applications, and remote clusters to control operations. [id="gitops-argocd-instance-scopes_{context}"] == Argo CD instance scopes @@ -47,7 +47,7 @@ include::modules/gitops-default-cluster-scoped-instance.adoc[leveloffset=+2] [id="important-considerations-when-adopting-the-multitenancy-model_{context}"] == Important considerations when adopting the multitenancy model -Granting multitenant cluster administration privileges might allow tenants to bypass any multitenancy efforts and permission restrictions because they might elevate their privileges using permissions granted to the application by Argo CD. To prevent such situations, you must understand the permission model for Argo CD installed through the {gitops-title} Operator and how to leverage it to be successful with OpenShift {gitops-shortname} for application delivery. +Granting multitenant cluster administration privileges might allow tenants to bypass any multitenancy efforts and permission restrictions because they might elevate their privileges by using permissions granted to the application by Argo CD. To prevent such situations, you must understand the permission model for Argo CD installed through the {gitops-title} Operator and how to use it to be successful with OpenShift {gitops-shortname} for application delivery. // Argo CD role-based access control (RBAC) include::modules/gitops-argocd-rbac.adoc[leveloffset=+2]