Namespace-scoped Argo CD installations

When a namespace-scoped Argo CD install fits a shared cluster

If your team needs GitOps delivery but cannot get cluster-admin on a shared cluster, a namespace-scoped install is the option to evaluate. The namespace-install.yaml manifest runs Argo CD with namespace-level privileges only, and it deploys to external clusters through credentials you supply. The fit is strongest when the platform team keeps the controller's home namespace and the target clusters separate from the tenant's own workloads, so the tenant can sync applications without holding cluster-wide rights on the host.

The trade-off is capability. The installation guide says this manifest does not include CRDs, so the Application, AppProject and related CRDs must be installed separately from manifests/crds by someone with cluster-level rights. Plan that as a one-time platform task, and confirm with your platform team who owns CRD upgrades, since a later Argo CD version may bring new CRDs. The bigger limit is that applications in any namespace require a cluster-wide installation and do not work in namespace-scoped mode, so every Application must live in the Argo CD namespace.

Before you commit, check three things: whether your tenant needs Applications outside the Argo CD namespace, whether the CRD install step fits your change process, and whether you will register every destination as an external cluster with supplied credentials. Confirm these against the installation guide and the any-namespace documentation for the version you plan to run. If any answer is no, a cluster-wide install scoped by projects is usually the better starting point.

What a namespace install can and cannot do

A namespace install reduces the cluster-wide reach of Argo CD in exchange for a smaller blast radius. Each card marks one boundary that changes who must act: the tenant team, the platform team or both. Read them before you choose between a namespace install and a cluster-wide one.

Namespace-level privileges only

The namespace-install.yaml manifest runs the Argo CD components with privileges limited to one namespace, which suits a tenant on a shared cluster without cluster-admin rights. The install still needs a platform owner to approve it, because the controller and server operate inside that namespace on the tenant's behalf. Confirm that the namespace quota, network policy and Pod Security settings allow every component to start and reach the Git hosts and clusters it needs.

External clusters through supplied credentials

A namespace install deploys only to external clusters, and it reaches them through credentials you supply, such as a cluster secret holding a service account token or cloud-based access. The credential decides what Argo CD can write on the target cluster, so the access boundary sits there and not in the Argo CD namespace. Confirm which role each credential holds on every destination and whether that role stays limited to the tenant's namespaces. Store the secret outside plain Git and review it at each rotation.

CRDs installed separately

The namespace manifest does not include the custom resource definitions, which ship under manifests/crds and must be applied on their own. CRDs are cluster-scoped, so someone with rights beyond the tenant must install them once and keep them at the version the Argo CD release expects. Treat the CRD step as a platform change with its own approval and change record. Confirm who owns the cluster-wide CRD lifecycle before the first upgrade.

Applications in any namespace

Applications in any namespace requires a cluster-wide installation and does not work in namespace-scoped mode. In a namespace install, Application objects must live in the Argo CD namespace, so a team that expects to create Applications in its own project namespaces will not get the behavior it assumes. Confirm that each team can manage its Applications inside the single Argo CD namespace before you choose this model. Check this against your planned namespace layout early.

Your own RBAC boundary

A namespace install removes the need for cluster-admin to run Argo CD, but the person or pipeline that applies the manifests and CRDs still needs sufficient rights. Test the namespace-scoped and cluster-scoped verbs you expect to use before the first apply, for example with kubectl auth can-i. Confirm the identity doing each install step in writing, since a broad apply role quietly reintroduces the privileges the namespace model was meant to avoid.

Choosing between namespace-scoped and cluster-wide installs

This table compares a namespace-scoped Argo CD install with a cluster-wide install across the decisions that usually drive the choice. Read each row as a question to answer with your platform team before you pick a mode. The main takeaway is that namespace scope fits a tenant that deploys only to clusters it is given, while any feature that touches cluster-level resources or other namespaces needs a cluster-wide install.

Decision area	Namespace-scoped install	Cluster-wide install
Cluster privileges	Runs with namespace-level privileges only, suited to a tenant without cluster-admin	Runs with cluster-level privileges, so the platform team must trust it with cluster-wide access
CRD handling	CRDs are not included and must be installed separately from the manifests in manifests/crds	CRDs are installed as part of the standard cluster-wide manifests
Deployment targets	Deploys to external clusters through supplied credentials, not the cluster it runs on	Deploys to the host cluster and to any registered external clusters
Applications in any namespace	Not supported; applications must live in the Argo CD namespace	Supported, so teams can keep Application resources in their own namespaces
Who administers the instance	Typically the tenant team, within the limits its namespace and the platform team allow	Typically the platform team, with tenant teams using projects and RBAC
Upgrade and CRD ownership	Confirm who applies CRD updates during each minor release upgrade	Platform team applies CRD and controller upgrades for all tenants
Blast radius of a misconfiguration	Limited to the tenant namespace and the clusters it is registered to	Can affect every namespace and cluster Argo CD manages
What to confirm with the platform team	Which clusters are registered, who installs CRDs, and whether any feature in your plan needs cluster scope	Which teams share the instance, how projects separate them, and who owns RBAC and upgrades

How to install a namespace-scoped Argo CD

This sequence gives a tenant an Argo CD that runs with namespace-level privileges, deploys only to clusters whose credentials were supplied to it, and is verified to sync only inside its own scope. The platform team handles the one step that needs cluster-level rights.

Confirm the tenant namespace and privileges
The platform team creates or confirms the tenant namespace and agrees with the tenant which clusters, namespaces and Git repositories the instance may touch. Record these in writing before any manifest is applied, since they become the boundaries the install is checked against. Done means the namespace exists, the tenant has no cluster-admin role, and the platform team has a short list of permitted destinations. Ask the platform team to confirm that the cluster policy they operate allows a namespace-scoped controller to run there.
Install the CRDs with cluster-level rights
The namespace-install manifest does not include the Argo CD custom resource definitions, so they must be applied separately from the manifests/crds directory of the Argo CD release. Only a platform engineer with cluster-level rights should run this step, and it should be done once per cluster, not per tenant. Done means the Application, AppProject and ApplicationSet resource types are listed by the cluster API. Confirm the release version you are installing matches the one your tenant manifest uses, as mismatched CRDs are a common cause of failed syncs.
Apply the namespace-install manifest
The tenant applies the namespace-install manifest from the installation guide into its own namespace, which runs the API server, repo server and application controller with namespace-level privileges only. Use the manifest for the same release as the CRDs. Done means the server, repo-server and controller pods reach the Running state and the Argo CD login page or CLI responds from inside the namespace. Check the pod logs for permission errors, which indicate a missing Role or a component that expects cluster scope.
Register external clusters with supplied credentials
Each destination cluster is registered with a credential the owning team supplies, stored as a cluster Secret in the tenant namespace. The instance does not discover clusters on its own, so only the clusters you register are reachable. Done means each registered cluster shows a Successful connection status in the Argo CD settings, and no cluster exists in the list that the team did not intend to add. Confirm with the cluster owner that the credential grants write access only to the namespaces the tenant is permitted to use.
Verify the controller syncs only within scope
Create a test Application in the tenant namespace that targets one permitted namespace on a registered cluster, then sync it. Next, attempt a deployment to a namespace outside the allowed list or a cluster-scoped resource such as a Namespace or ClusterRole, and confirm Argo CD refuses it. Done means the permitted sync succeeds and the out-of-scope attempt fails with a permission error, both recorded for the tenant's evidence. Remove the test Application afterward.
Document the scope and hand over
Write down the registered clusters, the permitted namespaces, the CRD release version and the list of features the instance does not provide, such as cross-namespace Applications. Give this record to the tenant and the platform team so future changes go through the same review. Done means both teams have signed off on the boundaries and know which changes need a cluster-wide install. Confirm the exact steps against the installation guide for your release before you start, since manifest names and paths change between versions.

How the install differs by tenant situation

A single tenant on a shared cluster is the most common reason to choose a namespace-scoped install. The tenant gets its own Argo CD inside one namespace and manages workloads only in that namespace, while the platform team keeps ownership of the cluster itself. The Argo CD instance can then be upgraded and restricted on the tenant's schedule without any cluster-wide permissions being granted.

Namespace and install manifest: Start from the namespace-install manifest, which grants Argo CD namespace-level privileges only.
Cluster access: Confirm what the platform team will provide for the tenant's own namespace, since the tenant cannot create cluster-scoped objects.
CRD ownership: The platform team or tenant must install CRDs separately from the manifests in manifests/crds, and cluster-scoped CRD changes remain a platform team decision.
Feature limits: Applications in any namespace do not work in this mode, so plan for applications living only in the install namespace.
Ownership boundaries: Agree in writing who handles upgrades, backups and access reviews for the tenant instance.

Before go-live, check that the tenant's Argo CD can sync only into its permitted namespaces and that no operation depends on cluster-wide read or write access.

Which features need a cluster-wide install

The most important limit of a namespace-scoped Argo CD is that Applications in any namespace require a cluster-wide installation. In namespace mode, Argo CD only reads and writes Application objects in the namespace where it runs, so an Application created in another namespace is not picked up. Teams that expect to create Applications in their own namespaces on a shared cluster should treat this as a hard constraint, not a configuration option to tune later. The any-namespace feature depends on Argo CD watching namespaces it was not installed into, and a tenant install is not granted that reach.

The practical plan is to keep every Application in the tenant namespace where the namespace-scoped Argo CD runs. Declare the Application, its AppProject and the cluster and repository Secrets in that one namespace, and point the destination at the external cluster or the tenant namespace. Before you commit to this layout, check the Application and AppProject references your tooling generates, since some examples in the wider documentation assume the argocd namespace. Any feature that touches cluster-scoped resources, such as cluster-level CRDs or other watch behavior, should be confirmed against the current Argo CD installation guide for the version you plan to run, because the namespace-scoped mode is documented as a set of trade-offs rather than a full feature parity list.

Confirm the constraint with the any-namespace documentation during design, and write the result into your decision record. If a team later needs Applications spread across namespaces, that is a change to the installation model, so it should go through a cluster-wide design review rather than a quiet edit to the manifests. Ask the platform owner to state explicitly which features are out of reach for the tenant so that application teams do not discover the gap during a release.

Security boundaries of a tenant-scoped instance

A namespace-scoped instance still holds credentials for other clusters, runs repository content through template tools and accepts logins from people who may leave a team. The four controls below limit those exposures, and each one needs a check on the running instance, not only in the manifests.

Limit writes on each managed cluster

A tenant instance deploys to external clusters using credentials you supply, so the permissions on those clusters set the real blast radius. Confirm which service account or identity Argo CD uses on each destination, and whether it can write only to the tenant's namespaces. Pair this with project destination rules so an application cannot target a namespace outside the tenant's allowed set. Review the cluster-scoped resource kinds the project permits, because a cluster-wide write grant undoes namespace limits elsewhere.

Disable the admin user after SSO

The built-in admin account is a shared, password-based login with full control of the instance. The user management documentation recommends using it only for initial setup. Once local users or SSO are configured, set admin.enabled to false and confirm that at least one named administrator can still sign in and recover access. Record who holds that recovery path and how it is audited, since disabling the admin user removes a fallback that many teams rely on.

Vet repositories before the repo-server renders them

The repo-server runs Helm and Kustomize against repository content, so a repository the tenant can add becomes code that executes inside the Argo CD control path. Restrict which repositories each project can use, and treat any new repository as untrusted until its chart dependencies and Kustomize overlays are reviewed. Confirm that manifests cannot reference files outside the repository, since out-of-tree file access is a named risk in the security documentation.

Keep API access on JSON Web Tokens over TLS

Argo CD authenticates API requests only with JSON Web Tokens and encrypts traffic, including traffic between its own components, with TLS. For a tenant instance, check that the ingress in front of the API server presents a valid certificate, that tokens issued for automation are scoped to the tenant's project, and that the tokens used by CI jobs are rotated when a pipeline changes owner. Confirm with your security team how token lifetimes are set, since the documentation does not fix a single value for every deployment.

Questions teams ask before a namespace-scoped install

Can our team install a namespace-scoped Argo CD without cluster-admin?

Yes, for the common case: a team with namespace-level rights can run Argo CD in its own namespace using the namespace install manifest, provided it deploys only to external clusters through credentials it is given. The install needs namespace-level privileges only, but the CRDs are not included and must be installed separately by someone with cluster-level rights. Your platform team usually owns that step, so the question is less about skill and more about who is allowed to apply cluster-scoped objects. Confirm this boundary with your cluster administrators before the install starts, because it decides whether the team can work alone or needs a platform engineer in the loop.

What drives the effort of a namespace-scoped Argo CD install?

The main drivers are cluster policy, CRD ownership, the number of external clusters, and the SSO and RBAC design. Cluster policy decides which namespaces, service accounts and cluster-level objects the team may create. CRD ownership decides who installs and upgrades the CRDs, which becomes a recurring coordination point with every Argo CD upgrade. Each external cluster needs its own supplied credentials, registration and access review, so effort grows with that count. SSO and RBAC design adds work because the team must map identity provider groups to Argo CD roles and projects. Ask any partner to split the quote along these four drivers so you can see which ones your environment makes expensive.

How long does a namespace-scoped install take?

The duration depends mostly on approvals and the environment, not on the Argo CD install itself. Time is spent waiting on access requests for the namespace, CRD installation by the platform team, credential issuance for each external cluster, and change approvals for network paths and identity provider configuration. Teams with a clear request path and an existing identity provider usually move faster than teams that must negotiate new cluster rights. Because the outcome depends on your approval chain, ask for a written schedule that lists each dependency and who owns it. No fixed duration can be given without knowing these factors.

What does the platform team need to provide for this work?

The platform team typically provides four things: the CRDs installed from the separate manifests, the namespace and its quota, the credentials for each external cluster, and a decision on how users sign in. The CRDs must match the Argo CD version the team runs, so the platform team also owns the sequence for future upgrades. Credentials should be scoped to what the team needs to deploy, and the platform team should review them before they are used. Agree on who approves changes to these items in writing, since the tenant team cannot make them alone. Expect the platform team to stay involved in every upgrade, not only the first install.

Can we add applications in any namespace later?

Not inside a namespace-scoped installation. Running applications in any namespace requires a cluster-wide installation, and it does not work in namespace-scoped mode. If your roadmap includes that capability, decide before the install, because moving from a namespace-scoped setup to a cluster-wide one is a change in privileges, CRD ownership and access review. Some teams run a separate cluster-wide instance for platform use and keep tenant instances namespace-scoped, which avoids forcing one model onto every team. Confirm the approach with your architects and the platform team before you commit to a layout.

Which features need a cluster-wide install?

The clearest documented case is applications in any namespace, which needs a cluster-wide installation. Anything that depends on cluster-scoped objects or cluster-level permissions should be checked against the installation guide before you rely on it. Check features such as cluster-level registration, CRD-dependent resources and notification or controller settings against your target version. Treat this as a checklist to verify with the vendor documentation for your release, not as a fixed list. Write the result into the design record so reviewers can see which features are excluded and why.

How do upgrades affect a namespace-scoped installation?

Upgrades remain a recurring cost because the CRDs live outside the namespace install and must be kept in step with the Argo CD version. Argo CD ships minor releases four times a year and supports only the three most recent minor versions with patch releases, so a tenant instance that falls behind will lose patch coverage. Plan a standing upgrade window that includes the platform team's CRD step and a regression check of each tenant's applications. Review the official upgrade notes for each major change before you schedule it, and ask any partner to price upgrades as a recurring item, not a one-time cost.

How DeployOpen scopes a tenant Argo CD engagement

The scope for a tenant Argo CD engagement is agreed in writing before any work starts, and it has to name the boundary the tenant lives inside. Confirm with your platform team whether the Argo CD install will run with the namespace-install.yaml manifest, which gives Argo CD namespace-level privileges only, and whether the tenant needs to deploy only to external clusters through supplied credentials. The written scope should list each cluster Argo CD will manage, the namespace it writes to on each one, who creates the cluster Secrets, and which features are excluded because they need a cluster-wide install. Applications in any namespace, for example, do not work in namespace-scoped mode, so that exclusion belongs in the document, not in a later surprise.

The work then covers three areas. First, the namespace install itself, with RBAC, the admin account disabled once SSO is configured, and TLS on the API. Second, CRD handling: the namespace manifest does not include CRDs, so DeployOpen plans a separate, cluster-level step to install them from the manifests/crds directory, and the person who approves that step should be someone with cluster-admin rights, not the tenant. Third, external cluster registration and verification, where each destination is tested with a sync of a non-production application and the results are recorded. Ask any partner to show the verification steps and the evidence they produce before you sign.

Ongoing support, version upgrades and continuous testing are available as retainers, separate from the fixed-scope build. Ask for the retainer terms in writing, including who applies patch releases, how the tenant is told about upgrades and what happens when a minor release leaves the supported window described in the project's release process. Before you compare quotes, confirm what your own team already owns, such as the cluster, the Git host and the identity provider, because those decisions drive the effort more than the Argo CD install does.

How DeployOpen delivers namespace-scoped Argo CD

DeployOpen plans and builds namespace-scoped Argo CD installations inside infrastructure you control, starting from a written scope that sets which namespaces, clusters and features are in play. The work covers installation, external cluster registration, SSO, project boundaries, testing, documentation and handover, with ongoing support available as a retainer.

How we scope

Confirm which features the tenant needs and whether any require a cluster-wide installation.
Record the namespaces Argo CD may manage, the external clusters it will deploy to, and the credentials each one uses.
Agree the written scope, deliverables and timeline in writing before any build work starts.

How we build

Install from the namespace-install manifests and add the CRDs separately from the manifests/crds directory.
Register external clusters with supplied credentials, limiting each to the namespaces the tenant owns.
Test that applications in other namespaces are refused, and that RBAC, SSO and admin disablement behave as designed.

How we hand over

Document the install method, CRD update steps, namespace list, credential ownership and known feature limits.
Walk your platform and tenant engineers through sync, rollback, upgrade and access review tasks.
Provide a record of test results and configuration so your own reviewers can check the setup against the agreed scope.

How we support

Offer ongoing support, patch and upgrade work, and continuous testing as a retainer after handover.
Plan upgrades around the patch releases the project supports, and confirm the current supported minor versions with the project.
Review the scope when the tenant needs a feature that requires a cluster-wide install, before any change is made.