Applications in any namespace¶
Current feature state: Beta
Please read this documentation carefully before you enable this feature. Misconfiguration could lead to potential security issues.
As of version 2.5, Argo CD supports managing
Application resources in namespaces other than the control plane's namespace (which is usually
argocd), but this feature has to be explicitly enabled and configured appropriately.
Argo CD administrators can define a certain set of namespaces where
Application resources may be created, updated and reconciled in. However, applications in these additional namespaces will only be allowed to use certain
AppProjects, as configured by the Argo CD administrators. This allows ordinary Argo CD users (e.g. application teams) to use patterns like declarative management of
Application resources, implementing app-of-apps and others without the risk of a privilege escalation through usage of other
AppProjects that would exceed the permissions granted to the application teams.
Some manual steps will need to be performed by the Argo CD administrator in order to enable this feature.
This feature is considered beta as of now. Some of the implementation details may change over the course of time until it is promoted to a stable status. We will be happy if early adopters use this feature and provide us with bug reports and feedback.
Cluster-scoped Argo CD installation¶
This feature can only be enabled and used when your Argo CD is installed as a cluster-wide instance, so it has permissions to list and manipulate resources on a cluster scope. It will not work with an Argo CD installed in namespace-scoped mode.
Switch resource tracking method¶
Also, while technically not necessary, it is strongly suggested that you switch the application tracking method from the default
label setting to either
annotation+label. The reasoning for this is, that application names will be a composite of the namespace's name and the name of the
Application, and this can easily exceed the 63 characters length limit imposed on label values. Annotations have a notably greater length limit.
To enable annotation based resource tracking, refer to the documentation about resource tracking methods
In order for an application to be managed and reconciled outside the Argo CD's control plane namespace, two prerequisites must match:
Application's namespace must be explicitly enabled using the
--application-namespacesparameter for the
argocd-serverworkloads. This parameter controls the list of namespaces that Argo CD will be allowed to source
Applicationresources from globally. Any namespace not configured here cannot be used from any
AppProjectreferenced by the
.spec.projectfield of the
Applicationmust have the namespace listed in its
.spec.sourceNamespacesfield. This setting will determine whether an
Applicationmay use a certain
AppProject. If an
AppProjectthat is not allowed, Argo CD refuses to process this
Application. As stated above, any namespace configured in the
.spec.sourceNamespacesfield must also be enabled globally.
Applications in different namespaces can be created and managed just like any other
Application in the
argocd namespace previously, either declaratively or through the Argo CD API (e.g. using the CLI, the web UI, the REST API, etc).
Reconfigure Argo CD to allow certain namespaces¶
Change workload startup parameters¶
In order to enable this feature, the Argo CD administrator must reconfigure the
argocd-application-controller workloads to add the
--application-namespaces parameter to the container's startup command.
--application-namespaces parameter takes a comma-separated list of namespaces where
Applications are to be allowed in. Each entry of the list supports shell-style wildcards such as
*, so for example the entry
app-team-* would match
app-team-two. To enable all namespaces on the cluster where Argo CD is running on, you can just specify
The startup parameters for both, the
argocd-server and the
argocd-application-controller can also be conveniently set up and kept in sync by specifying the
application.namespaces settings in the
argocd-cmd-params-cm ConfigMap instead of changing the manifests for the respective workloads. For example:
data: application.namespaces: app-team-one, app-team-two
would allow the
app-team-two namespaces for managing
Application resources. After a change to the
argocd-cmd-params-cm namespace, the appropriate workloads need to be restarted:
kubectl rollout restart -n argocd deployment argocd-server kubectl rollout restart -n argocd statefulset argocd-application-controller
Adapt Kubernetes RBAC¶
We decided to not extend the Kubernetes RBAC for the
argocd-server workload by default for the time being. If you want
Applications in other namespaces to be managed by the Argo CD API (i.e. the CLI and UI), you need to extend the Kubernetes permissions for the
We supply a
ClusterRoleBinding suitable for this purpose in the
examples/k8s-rbac/argocd-server-applications directory. For a default Argo CD installation (i.e. installed to the
argocd namespace), you can just apply them as-is:
kubectl apply -f examples/k8s-rbac/argocd-server-applications/
At some later point in time, we may make this cluster role part of the default installation manifests.
Allowing additional namespaces in an AppProject¶
Any user with Kubernetes access to the Argo CD control plane's namespace (
argocd), especially those with permissions to create or update
Applications in a declarative way, is to be considered an Argo CD admin.
This prevented unprivileged Argo CD users from declaratively creating or managing
Applications in the past. Those users were constrained to using the API instead, subject to Argo CD RBAC which ensures only
Applications in allowed
AppProjects were created.
Application to be created outside the
argocd namespace, the
AppProject referred to in the
.spec.project field must include the
Application's namespace in its
For example, consider the two following (incomplete)
kind: AppProject apiVersion: argoproj.io/v1alpha1 metadata: name: project-one namespace: argocd spec: sourceNamespaces: - namespace-one
kind: AppProject apiVersion: argoproj.io/v1alpha1 metadata: name: project-two namespace: argocd spec: sourceNamespaces: - namespace-two
In order for an Application to set
project-one, it would have to be created in either namespace
argocd. Likewise, in order for an Application to set
project-two, it would have to be created in either namespace
If an Application in
namespace-two would set their
project-one or an Application in
namespace-one would set their
project-two, Argo CD would consider this as a permission violation and refuse to reconcile the Application.
Also, the Argo CD API will enforce these constraints, regardless of the Argo CD RBAC permissions.
.spec.sourceNamespaces field of the
AppProject is a list that can contain an arbitrary amount of namespaces, and each entry supports shell-style wildcard, so that you can allow namespaces with patterns like
Do not add user controlled namespaces in the
.spec.sourceNamespaces field of any privileged AppProject like the
default project. Always make sure that the AppProject follows the principle of granting least required privileges. Never grant access to the
argocd namespace within the AppProject.
For backwards compatibility, Applications in the Argo CD control plane's namespace (
argocd) are allowed to set their
.spec.project field to reference any AppProject, regardless of the restrictions placed by the AppProject's
For the CLI and UI, applications are now referred to and displayed as in the format
For backwards compatibility, if the namespace of the Application is the control plane's namespace (i.e.
<namespace> can be omitted from the application name when referring to it. For example, the application names
someapp are semantically the same and refer to the same application in the CLI and the UI.
The RBAC syntax for Application objects has been changed from
<project>/<namespace>/<application> to accommodate the need to restrict access based on the source namespace of the Application to be managed.
For backwards compatibility, Applications in the
argocd namespace can still be refered to as
<project>/<application> in the RBAC policy rules.
Wildcards do not make any distinction between project and application namespaces yet. For example, the following RBAC rule would match any application belonging to project
foo, regardless of the namespace it is created in:
p, somerole, applications, get, foo/*, allow
If you want to restrict access to be granted only to
Applications in project
foo within namespace
bar, the rule would need to be adapted as follows:
p, somerole, applications, get, foo/bar/*, allow
Managing applications in other namespaces¶
For declarative management of Applications, just create the Application from a YAML or JSON manifest in the desired namespace. Make sure that the
.spec.project field refers to an AppProject that allows this namespace. For example, the following (incomplete) Application manifest creates an Application in the namespace
kind: Application apiVersion: argoproj.io/v1alpha1 metadata: name: some-app namespace: some-namespace spec: project: some-project # ...
some-project will then need to specify
some-namespace in the list of allowed source namespaces, e.g.
kind: AppProject apiVersion: argoproj.io/v1alpha1 metadata: name: some-project namespace: argocd spec: sourceNamespaces: - some-namespace
Using the CLI¶
You can use all existing Argo CD CLI commands for managing applications in other namespaces, exactly as you would use the CLI to manage applications in the control plane's namespace.
For example, to retrieve the
foo in the namespace
bar, you can use the following CLI command:
argocd app get foo/bar
Likewise, to manage this application, keep referring to it as
# Create an application argocd app create foo/bar ... # Sync the application argocd app sync foo/bar # Delete the application argocd app delete foo/bar # Retrieve application's manifest argocd app manifests foo/bar
As stated previously, for applications in the Argo CD's control plane namespace, you can omit the namespace from the application name.
Using the UI¶
Similar to the CLI, you can refer to the application in the UI as
For example, to create an application named
bar in the namespace
foo in the web UI, set the application name in the creation dialogue's Application Name field to
foo/bar. If the namespace is omitted, the control plane's namespace will be used.
Using the REST API¶
If you are using the REST API, the namespace for
Application cannot be specified as the application name, and resources need to be specified using the optional
appNamespace query parameter. For example, to work with the
Application resource named
foo in the namespace
bar, the request would look like follows:
For other operations such as
appNamespace parameter must be part of the request's payload.
Application resources in the control plane namespace, this parameter can be omitted.