Skip to content
Documentation Background

Multi-tenancy and projects

A shared Argo CD instance serves several teams, and each team should deploy only its own applications, from its own repositories, into its own namespaces. Argo CD builds that boundary from two choices: how the instance is installed, and which projects its Applications belong to.


Argo CD installs in one of two scopes, introduced in installation and access.

Cluster-scopedNamespace-scoped
InstancesOne central instance for many teamsOne instance per team, in the team’s namespace
PrivilegesThe service accounts hold cluster-wide permissions, effectively cluster-admin on every managed clusterLimited to its own namespace
Local clusterWorks out of the boxNeeds a service account and RBAC created by hand
Cluster-wide objectsCan manage CRDs, namespaces, and ClusterRolesCannot, a cluster administrator must install them
Operational costOne installation to patch and monitorMany installations to patch and monitor
Blast radiusLarge, a compromise reaches every managed clusterSmall, one namespace

Cluster-scoped is the default and the usual choice for platform teams. It leans on the project and RBAC machinery below for isolation. Namespace-scoped fits teams that need autonomy and strict separation, and accept the maintenance cost. The two can coexist: a central instance for platform components and team instances for application teams.

A cluster-scoped installation can narrow its own privileges by editing the ClusterRole bound to its service accounts, and sync impersonation goes further by running each sync as a limited service account.


An AppProject is the unit of tenancy. Every Application belongs to exactly one project through spec.project, and the project decides what the Application is allowed to do.

A project restricts:

  • Sources - which Git or Helm repositories its Applications may deploy from
  • Destinations - which clusters and namespaces they may deploy into
  • Resource kinds - which cluster-scoped and namespaced kinds they may create
  • Roles - who may do what to the Applications in the project

Projects are enforced by Argo CD, not by Kubernetes. They stop an Application from being created or synced when it breaks a rule, and complement, but do not replace, Argo CD RBAC.

Argo CD creates a project named default. An Application that sets no project joins it. Its settings are the most permissive possible: any repository, any cluster and namespace, any cluster-scoped kind. It cannot be deleted.

spec:
sourceRepos:
- '*'
destinations:
- namespace: '*'
server: '*'
clusterResourceWhitelist:
- group: '*'
kind: '*'

On a shared instance, strip the permissions so that nobody can use it by accident, and require teams to name a real project:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: default
namespace: argocd
spec:
sourceRepos: []
sourceNamespaces: []
destinations: []
namespaceResourceBlacklist:
- group: '*'
kind: '*'

Applications in default are then refused until they move to another project.

spec.sourceRepos lists the repository URLs a project may use. Patterns accept * wildcards. A leading ! denies a match.

spec:
sourceRepos:
- '!ssh://[email protected]:argoproj/test' # never this repository
- '!https://gitlab.com/group/**' # nothing under this group
- '*' # anything else

A repository is allowed when at least one allow rule matches and no deny rule does. The order of the list does not matter. !* is invalid, because denying everything is the same as listing nothing.

spec.destinations pairs a cluster server (or name) with a namespace. Both fields take wildcards and ! denials, and the same allow-and-no-deny logic applies.

spec:
destinations:
- namespace: '!kube-system' # never kube-system, on any cluster
server: '*'
- namespace: '*'
server: '!https://team1-*' # never a cluster whose URL starts with team1-
- namespace: '*' # everything else is fine
server: '*'

Rules like these are a guardrail for projects that need broad access. A tenant project usually lists only the exact servers and namespaces it owns, as in the walkthrough below. Write the cluster as its server URL in destination rules.

Cluster-scoped and namespaced resources are controlled in opposite directions:

FieldBehavior
clusterResourceWhitelistOnly these cluster-scoped kinds are allowed. Empty means none
clusterResourceBlacklistAll cluster-scoped kinds except these
namespaceResourceBlacklistAll namespaced kinds except these. The default, so tenants can create anything namespaced
namespaceResourceWhitelistOnly these namespaced kinds are allowed
spec:
clusterResourceWhitelist: # tenants may create Namespaces, nothing else cluster-wide
- group: ''
kind: Namespace
name: shop-* # and only ones named shop-*
namespaceResourceBlacklist: # tenants may not alter quotas or network policy
- group: ''
kind: ResourceQuota
- group: ''
kind: LimitRange
- group: ''
kind: NetworkPolicy

Blocking ResourceQuota, LimitRange, and NetworkPolicy keeps tenants from lifting the limits the platform team set. Blocking ClusterRole and CustomResourceDefinition (by not whitelisting them) keeps a tenant from granting itself permissions.


A project can define its own roles, which Argo CD turns into RBAC rules scoped to that project. A role’s policies can grant access only inside its own project, and users get the role through the groups list, which holds SSO group names.

spec:
roles:
- name: shop-developer
description: Developers can view and sync, not delete
policies:
- p, proj:shop:shop-developer, applications, get, shop/*, allow
- p, proj:shop:shop-developer, applications, sync, shop/*, allow
groups:
- Developers # an SSO group claim

The policy subject must follow the pattern proj:<project>:<role>, or it has no effect. Anything not granted is denied. This role lets developers see Application status, logs, and trigger syncs, but a delete fails with a permission denied error. That pattern, a safe self-service portal, is what most teams want. For rules that span projects, use the global policies in argocd-rbac-cm.

Roles can also authenticate automation. A role can issue a JWT, and the token carries only that role’s policies:

Terminal window
argocd proj role create shop ci-sync
argocd proj role add-policy shop ci-sync --action sync --permission allow --object '*'
argocd proj role create-token shop ci-sync --expires-in 24h

Argo CD does not store the token, so copy it when it is created. Use it with --auth-token or ARGOCD_AUTH_TOKEN, and revoke it with argocd proj role delete-token. Tokens created without an expiry live until revoked.


A global project holds restrictions that other projects inherit. In argocd-cm, a rule selects projects by label and names the project they inherit from:

data:
globalProjects: |-
- labelSelector:
matchExpressions:
- key: tier
operator: In
values:
- tenant
projectName: tenant-baseline

Matching projects inherit the baseline’s resource lists, syncWindows, sourceRepos, destinations, and destinationServiceAccounts. It is the way to apply a platform-wide denial, such as no ClusterRole, to every tenant project without repeating it.

A repository or cluster Secret with project: shop is usable only by that project’s Applications. This lets a project administrator connect a repository or cluster without involving a platform administrator, as long as RBAC allows the repositories or clusters actions for shop/*:

Terminal window
argocd repo add https://git.example.com/shop/config.git --project shop --username ... --password ...

Setting permitOnlyProjectScopedClusters: true on a project goes further: its Applications may deploy only to clusters scoped to that same project. Without it, a project’s destination rules are the only guard.

By default Application objects live in the Argo CD namespace, which means every tenant who manages Applications declaratively needs write access to a namespace that also holds Argo CD’s configuration. Anyone who can create Applications there is effectively an Argo CD administrator. The apps-in-any-namespace feature lets a tenant keep Applications in their own namespace instead. Two settings must agree, because an Application is processed only when both allow its namespace:

  1. Globally, the namespace is listed in application.namespaces in argocd-cmd-params-cm. Entries accept shell-style wildcards (team-*) or a regular expression wrapped in /. Restart the API server and the application controller after changing it.
  2. In the project, the Application’s spec.project names an AppProject whose sourceNamespaces includes that namespace.
# argocd-cmd-params-cm
data:
application.namespaces: team-shop, team-payments
# AppProject
spec:
sourceNamespaces:
- team-shop

An Application in team-shop can then use the shop project and no other. Argo CD refuses to process one that names a project that does not list its namespace, and the API enforces the same rule regardless of RBAC.

Requirements and consequences:

  • Cluster-scoped install only. The feature does not work with a namespace-scoped Argo CD.
  • Kubernetes RBAC for the API server. To manage these Applications through the CLI and UI, extend the argocd-server service account’s permissions with the ClusterRole and binding in the upstream examples/k8s-rbac/argocd-server-applications directory. The notifications controller has equivalent manifests.
  • Resource tracking. Use annotation tracking, which is the default in 3.x. Label values are limited to 63 characters, and an Application’s tracked name now includes its namespace.
  • Names. The CLI and UI refer to these Applications as <namespace>/<name>, for example argocd app sync team-shop/catalog-api. The namespace can be omitted for the Argo CD namespace.
  • RBAC objects have three segments. The object becomes <project>/<namespace>/<application>, and a rule such as shop/team-shop/* limits access to one namespace. Applications in the Argo CD namespace stay in the two-segment form, so a project must never list the Argo CD namespace in sourceNamespaces. Wildcards such as shop/* match across namespaces.
  • Never list tenant namespaces in a privileged project. The default project in particular must not carry sourceNamespaces for namespaces that tenants control.
  • ApplicationSets can live in other namespaces too. List them in applicationsetcontroller.namespaces in argocd-cmd-params-cm. The list must be covered by application.namespaces, and generated Applications are created in the ApplicationSet’s own namespace. Harden the controller when this is on. applicationsetcontroller.allowed.scm.providers restricts the SCM and pull request generators to listed API URLs, and applicationsetcontroller.enable.tokenref.strict.mode: "true" only accepts token Secrets labeled argocd.argoproj.io/secret-type: scm-creds. Without them a tenant could point a generator at a service they control and capture a token.

The shop team runs a three-tier application: a database, an API, and a frontend. The goal is a project in which developers see and sync but cannot delete.

Declaratively, a file kept in Git:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: shop
namespace: argocd
spec:
description: Shop team project with developer access
sourceRepos:
- https://git.example.com/shop/*
destinations:
- server: https://kubernetes.default.svc
namespace: shop
roles:
- name: shop-developer
description: View and sync only
policies:
- p, proj:shop:shop-developer, applications, get, shop/*, allow
- p, proj:shop:shop-developer, applications, sync, shop/*, allow
groups:
- Developers
Terminal window
kubectl apply -f shop-project.yaml
# or, with an Argo CD session:
argocd proj create --upsert --file shop-project.yaml

The imperative argocd proj create shop --src '...' --dest '...' form exists for quick experiments. It needs administrator rights and leaves no history in Git, so it suits learning, while the manifest suits anything shared.

Each Application states its project:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: shop-api
namespace: argocd
spec:
project: shop
source:
repoURL: https://git.example.com/shop/config.git
targetRevision: main
path: api
destination:
server: https://kubernetes.default.svc
namespace: shop
Terminal window
argocd app create --file shop-db.yaml
argocd app create --file shop-api.yaml
argocd app create --file shop-frontend.yaml
argocd app list --project shop -o name
# Expected output:
# argocd/shop-api
# argocd/shop-db
# argocd/shop-frontend

During first startup the API Pods may restart while the database initializes. They settle once it answers, and readiness probes and waves remove the noise.

Sign in as a user in the Developers group through SSO:

ActionResultReason
Open the Applications viewSees the three shop applicationsThe role grants get on shop/*
Sync all threeSucceedsThe role grants sync
Delete shop-dbpermission denied: applications, delete, shop/shop-dbNo delete policy, so it is denied
Create an Application in the default projectRejecteddefault is locked down
Create an Application deploying to kube-systemRejectedNot in the project’s destinations

The delete refusal protects the stack from an accidental removal of its database.


SymptomLikely causeFix
application repo ... is not permitted in projectThe repository URL matches no sourceRepos allow rule, or a deny ruleAdd the repository, or remove the deny
application destination ... is not permitted in projectThe server and namespace pair is not allowedAdd the destination, matching the server URL
resource ... is not permitted in projectThe kind is blocked by a resource listAllow the kind in the project, if the tenant should manage it
A developer sees no ApplicationsThe SSO group has no project role or global bindingAdd the group to the project role’s groups
The project role has no effectThe policy subject is not proj:<project>:<role>Fix the subject format
Deleting a project failsApplications still reference itMove or delete its Applications first
A project cannot use a repositoryThe repository belongs to a different projectUse an unscoped repository, or add one scoped to this project