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.
Choosing an installation model
Section titled “Choosing an installation model”Argo CD installs in one of two scopes, introduced in installation and access.
| Cluster-scoped | Namespace-scoped | |
|---|---|---|
| Instances | One central instance for many teams | One instance per team, in the team’s namespace |
| Privileges | The service accounts hold cluster-wide permissions, effectively cluster-admin on every managed cluster | Limited to its own namespace |
| Local cluster | Works out of the box | Needs a service account and RBAC created by hand |
| Cluster-wide objects | Can manage CRDs, namespaces, and ClusterRoles | Cannot, a cluster administrator must install them |
| Operational cost | One installation to patch and monitor | Many installations to patch and monitor |
| Blast radius | Large, a compromise reaches every managed cluster | Small, 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.
Projects
Section titled “Projects”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.
The default project
Section titled “The default project”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/v1alpha1kind: AppProjectmetadata: name: default namespace: argocdspec: sourceRepos: [] sourceNamespaces: [] destinations: [] namespaceResourceBlacklist: - group: '*' kind: '*'Applications in default are then refused until they move to another project.
Restricting sources
Section titled “Restricting sources”spec.sourceRepos lists the repository URLs a project may use. Patterns accept * wildcards. A leading ! denies a match.
spec: sourceRepos: - '!https://gitlab.com/group/**' # nothing under this group - '*' # anything elseA 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.
Restricting destinations
Section titled “Restricting destinations”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.
Restricting resource kinds
Section titled “Restricting resource kinds”Cluster-scoped and namespaced resources are controlled in opposite directions:
| Field | Behavior |
|---|---|
clusterResourceWhitelist | Only these cluster-scoped kinds are allowed. Empty means none |
clusterResourceBlacklist | All cluster-scoped kinds except these |
namespaceResourceBlacklist | All namespaced kinds except these. The default, so tenants can create anything namespaced |
namespaceResourceWhitelist | Only 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: NetworkPolicyBlocking 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.
Project roles
Section titled “Project roles”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 claimThe 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:
argocd proj role create shop ci-syncargocd proj role add-policy shop ci-sync --action sync --permission allow --object '*'argocd proj role create-token shop ci-sync --expires-in 24hArgo 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.
Sharing rules and resources
Section titled “Sharing rules and resources”Global projects
Section titled “Global projects”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-baselineMatching 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.
Project-scoped repositories and clusters
Section titled “Project-scoped repositories and clusters”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/*:
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.
Applications in other namespaces
Section titled “Applications in other namespaces”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:
- Globally, the namespace is listed in
application.namespacesinargocd-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. - In the project, the Application’s
spec.projectnames an AppProject whosesourceNamespacesincludes that namespace.
# argocd-cmd-params-cmdata: application.namespaces: team-shop, team-payments# AppProjectspec: sourceNamespaces: - team-shopAn 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-serverservice account’s permissions with theClusterRoleand binding in the upstreamexamples/k8s-rbac/argocd-server-applicationsdirectory. 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 exampleargocd 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 asshop/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 insourceNamespaces. Wildcards such asshop/*match across namespaces. - Never list tenant namespaces in a privileged project. The
defaultproject in particular must not carrysourceNamespacesfor namespaces that tenants control. - ApplicationSets can live in other namespaces too. List them in
applicationsetcontroller.namespacesinargocd-cmd-params-cm. The list must be covered byapplication.namespaces, and generated Applications are created in the ApplicationSet’s own namespace. Harden the controller when this is on.applicationsetcontroller.allowed.scm.providersrestricts the SCM and pull request generators to listed API URLs, andapplicationsetcontroller.enable.tokenref.strict.mode: "true"only accepts token Secrets labeledargocd.argoproj.io/secret-type: scm-creds. Without them a tenant could point a generator at a service they control and capture a token.
Walkthrough: a team dashboard
Section titled “Walkthrough: a team dashboard”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.
Create the project
Section titled “Create the project”Declaratively, a file kept in Git:
apiVersion: argoproj.io/v1alpha1kind: AppProjectmetadata: name: shop namespace: argocdspec: 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: - Developerskubectl apply -f shop-project.yaml# or, with an Argo CD session:argocd proj create --upsert --file shop-project.yamlThe 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.
Deploy the applications into it
Section titled “Deploy the applications into it”Each Application states its project:
apiVersion: argoproj.io/v1alpha1kind: Applicationmetadata: name: shop-api namespace: argocdspec: project: shop source: repoURL: https://git.example.com/shop/config.git targetRevision: main path: api destination: server: https://kubernetes.default.svc namespace: shopargocd app create --file shop-db.yamlargocd app create --file shop-api.yamlargocd app create --file shop-frontend.yaml
argocd app list --project shop -o name# Expected output:# argocd/shop-api# argocd/shop-db# argocd/shop-frontendDuring first startup the API Pods may restart while the database initializes. They settle once it answers, and readiness probes and waves remove the noise.
Test the boundaries
Section titled “Test the boundaries”Sign in as a user in the Developers group through SSO:
| Action | Result | Reason |
|---|---|---|
| Open the Applications view | Sees the three shop applications | The role grants get on shop/* |
| Sync all three | Succeeds | The role grants sync |
Delete shop-db | permission denied: applications, delete, shop/shop-db | No delete policy, so it is denied |
Create an Application in the default project | Rejected | default is locked down |
Create an Application deploying to kube-system | Rejected | Not in the project’s destinations |
The delete refusal protects the stack from an accidental removal of its database.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
application repo ... is not permitted in project | The repository URL matches no sourceRepos allow rule, or a deny rule | Add the repository, or remove the deny |
application destination ... is not permitted in project | The server and namespace pair is not allowed | Add the destination, matching the server URL |
resource ... is not permitted in project | The kind is blocked by a resource list | Allow the kind in the project, if the tenant should manage it |
| A developer sees no Applications | The SSO group has no project role or global binding | Add the group to the project role’s groups |
| The project role has no effect | The policy subject is not proj:<project>:<role> | Fix the subject format |
| Deleting a project fails | Applications still reference it | Move or delete its Applications first |
| A project cannot use a repository | The repository belongs to a different project | Use an unscoped repository, or add one scoped to this project |