> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/continuous-delivery/use-gitops/application/applications-in-any-namespace.md).
# Applications in any namespace
Configure your GitOps agent to deploy Argo CD applications into namespaces other than the agent namespace.
By default, Harness GitOps deploys Argo CD Application resources into the namespace where the GitOps Agent is installed. The **Applications in any namespace** feature lets you deploy Application resources into other namespaces on the same cluster, which enables multi-tenancy and self-service workflows for application teams.
Each participating namespace must be declared in two places:
* The agent's **Application Namespaces** field, which tells the agent's informer which namespaces to watch.
* The AppProject's `sourceNamespaces` field, which enforces the security boundary and controls which namespaces can host Applications that belong to the project.
***
## What you will learn from this topic
* How to [enable Application Namespaces on a new agent](#enable-application-namespaces-on-a-new-agent) during setup
* How to [update Application Namespaces](#update-application-namespaces-after-agent-creation) after agent creation
* How to [configure AppProject source namespaces](#configure-appproject-source-namespaces) to allow multi-namespace deployments
* How to [create an application in a non-default namespace](#create-an-application-in-a-non-default-namespace)
* How Harness [names applications](#how-harness-names-applications) when Source Namespace is used
***
## Before you begin
Review the following requirements before configuring Application Namespaces.
* **Cluster-wide agent required.** The agent must be installed in cluster-wide mode (`isNamespaced=false`). Namespace-scoped agents and Harness Hosted agents do not support this feature.
* **AppProject access.** You need permission to create or edit AppProjects in Harness. Go to [Manage permissions](/continuous-delivery/use-gitops/application/manage-permissions.md) to review the required roles.
* **Existing resources are unaffected.** Enabling Application Namespaces on an agent does not change existing applications. They continue to run without any migration.
***
## Enable Application Namespaces on a new agent
When you create a new agent in Harness, the **Application Namespaces** field is under **Advanced** > **Argo CD Settings** in the agent creation wizard.
1. In your Harness project, go to **GitOps** and select **Settings > GitOps Agents**.
2. Select **New GitOps Agent**.
3. Complete the agent configuration steps.
4. Expand **Advanced** and select **Argo CD Settings**.
5. In the **Application Namespaces** field, enter a comma-separated list of namespaces the agent should watch.
* Enter `*` to allow all namespaces on the cluster.
* Leave the field empty to default to the agent's own namespace only.
6. Finish creating the agent and install the generated manifests on your cluster.
***
## Update Application Namespaces after agent creation
You cannot update the **Application Namespaces** value through the agent API or the Harness UI after the agent is created. The only supported path is the **Generate YAML** workflow.
1. In your Harness project, go to **GitOps** and select **Settings > GitOps Agents**.
2. Select the agent you want to update.
3. Select **Generate YAML**, expand **Advanced**, select **Argo CD Settings**, and update the **Application Namespaces** field.
4. Download or copy the regenerated manifests.
5. Apply the updated manifests on your cluster.
The source of truth for the agent's namespace configuration is the `argocd-cmd-params-cm` ConfigMap on the cluster. If you edit this ConfigMap directly outside of Harness, the Harness UI will show stale configuration until you regenerate and re-apply the manifests through Harness.
***
## Configure AppProject source namespaces
The `sourceNamespaces` field on an AppProject controls which namespaces are permitted to host Application resources that belong to the project. Without this field, only the agent namespace is allowed.
### Create or edit an AppProject with source namespaces
1. In your Harness project, go to **GitOps** and select **Settings > AppProjects**.
2. Create a new AppProject or open an existing one.
3. In the **Source Namespaces** field, enter the namespaces that are permitted to host applications.
* Use a specific name such as `my-team-ns`.
* Use a wildcard pattern such as `team-*` to match all namespaces that start with `team-`.
* Use a regex pattern such as `/^team-[a-z]+$/` for more precise matching.
* Use `*` to allow all namespaces.
4. Save the AppProject.
### Example: AppProject Terraform configuration
```hcl
resource "harness_platform_gitops_app_project" "example" {
agent_id = "my-agent"
org_id = var.org_id
project_id = var.project_id
upsert = true
project {
metadata {
name = "my-app-project"
namespace = "argocd" # namespace where the agent is installed
finalizers = ["resources-finalizer.argocd.argoproj.io"]
}
spec {
destinations {
namespace = "my-team-ns"
server = "https://kubernetes.default.svc"
}
source_namespaces = ["my-team-ns"]
source_repos = ["*"]
orphaned_resources {
warn = "false"
}
}
}
}
```
***
## Create an application in a non-default namespace
When you create a GitOps application in Harness, the **Source Namespace** field in the application metadata controls where the Application resource is deployed.
* If you leave **Source Namespace** empty, the Application resource is deployed in the agent namespace.
* If you set a value in **Source Namespace**, the Application resource is deployed in that namespace. The namespace must be listed in both the agent's Application Namespaces and the AppProject's `sourceNamespaces`.
* The **destination namespace** is separate from **Source Namespace**. It is where the application's workload resources are deployed and can differ from the namespace that hosts the Application CR.
### Example: Application Terraform configuration
```hcl
resource "harness_platform_gitops_applications" "example" {
application {
metadata {
name = "my-app"
namespace = "my-team-ns" # Source Namespace: Application CR location
}
spec {
project = "my-app-project"
source {
repo_url = "https://github.com/my-org/my-repo.git"
path = "apps/my-app"
target_revision = "main"
}
destination {
namespace = "my-app-workloads" # where deployed resources run
server = "https://kubernetes.default.svc"
}
sync_policy {
automated {
self_heal = true
prune = true
}
}
}
}
org_id = var.org_id
project_id = var.project_id
agent_id = "my-agent"
cluster_id = "in-cluster"
repo_id = "my-repo"
name = "my-app"
}
```
The `namespace` in `application.metadata` is the **Source Namespace**. It is set on Create and is **immutable**. An Update request that changes this field returns a `400` error. To move an Application CR to a different namespace, delete and recreate the application.
***
## How Harness names applications
Harness allows multiple applications with the same name in different source namespaces on the same agent. To keep each application unique in Harness, the system prefixes the source namespace to the application name when **Source Namespace** differs from the agent namespace.
* **Prefixed names:** An application named `app1` in source namespace `ns1` is stored in Harness as `ns1/app1`. An application named `app2` in source namespace `ns2` is stored as `ns2/app2`.
* **Same name across namespaces:** Two applications both named `app1` in source namespaces `ns1` and `ns2` are stored as `ns1/app1` and `ns2/app1`.
* **Agent namespace:** If **Source Namespace** matches the agent namespace, Harness stores the application by name only with no namespace prefix.
***
## Resource tracking recommendation
When Application Namespaces is enabled, Argo CD generates tracking labels in the format `namespace/app-name`. Kubernetes labels have a 63-character limit, so application names that result in a combined `namespace/name` string longer than 63 characters cause tracking failures.
Harness recommends switching to **annotation-based tracking** or **annotation+label tracking** when you use Application Namespaces. Annotation values are not subject to the 63-character limit.
Go to [Manage Argo CD configs](/continuous-delivery/use-gitops/connect-and-manage/manage-argo-configs.md) to configure the resource tracking method for your agent.
***
## Known limitations
The following limitations apply to the Application Namespaces feature.
* **ApplicationSets cannot generate applications in a different namespace.** An ApplicationSet must live in the same namespace as the applications it generates. This is an upstream Argo CD limitation tracked in [issue #11104](https://github.com/argoproj/argo-cd/issues/11104).
* **Namespace-scoped agents are not supported.** Only cluster-wide agents (`isNamespaced=false`) support Application Namespaces.
* **Harness Hosted agents are not supported.** Application Namespaces is only available for self-managed agents.
* **Filtering applications by CR namespace in the application list is not yet available.** This is deferred to a future release.
***
## Troubleshooting
GitOps application fails with 'namespace is not permitted' when using a non-default namespace
Here are the key checks and steps to resolve a "namespace is not permitted" error in a Harness GitOps application:
* **Avoid reserved/system namespaces.** Apps deployed to `kube-system` will not appear in GitOps reconciliation or UI. Use a dedicated namespace instead. Go to [GitOps troubleshooting](/continuous-delivery/use-gitops/resources/troubleshooting.md#applications-missing-in-gitops-for-kube-system-namespace) to review this scenario.
* **Check for OPA/Policy violations.** If your account has OPA policies enforcing namespace restrictions (e.g., blocking `kube-system`, `kube-public`, `argocd`, `istio-system`, etc.), your application's destination namespace may be explicitly denied. Review active policies in your project settings. Go to [Block protected namespaces](/continuous-delivery/use-gitops/application/opa-policy-support.md#example-block-protected-namespaces) to review a sample policy.
* **Verify the destination namespace in the Application config.** When creating or editing the GitOps Application, ensure the **Destination > Namespace** field is set to a valid, non-reserved namespace (e.g., `guestbook`, `my-app-ns`). Go to [GitOps applications](/continuous-delivery/troubleshooting-and-resources/tutorials/kubernetes-container-deployments/manifest.md#applications) to review an example configuration.
* **Check for Applications in Any Namespace support.** If you need ArgoCD Application resources in namespaces other than the agent's install namespace, ensure you are using a **cluster-scoped agent** and have configured `applicationNamespaces` accordingly. Namespace-scoped agents do not support this feature. Go to the [GitOps Service 1.61.0 / GitOps Agent 0.121.0 release notes](https://developer.harness.io/release-notes/continuous-delivery/#gitops-service-1610-gitops-agent-01210) to review the minimum version requirements.
* **Review RBAC and role assignments.** Confirm the user has the correct role assignments in Harness and that application labels match any resource group filters. Go to [Manage GitOps application access with labels](/continuous-delivery/use-gitops/application/manage-permissions.md#troubleshooting) to review permission troubleshooting steps.
* **Check ArgoCD project field (Argo CD 2.12+).** If using Argo CD 2.12 or later, the `project` field is now mandatory. Ensure the application's project field matches the project field on the cluster/repo secret, or unset the project field on the secret to allow cross-project access. Go to [GitOps troubleshooting](/continuous-delivery/use-gitops/resources/troubleshooting.md#application-creation-fails-due-to-missing-project-field-argo-cd-212-change-previously-it-was-optional) to review the Argo CD 2.12 project field change.
* **OpenShift clusters only:** If running on OpenShift, the default `restricted` SCC may block agent components. Grant the required SCCs (`nonroot-v2`, `anyuid`) to the relevant service accounts in your GitOps namespace. Go to [OpenShift Security Context Constraints (SCC) for GitOps agent](/continuous-delivery/use-gitops/resources/troubleshooting.md#openshift-security-context-constraints-scc-for-gitops-agent) to review the required SCCs.
GitOps agent informer does not see applications after enabling Application Namespaces
Harness does not publish a dedicated troubleshooting guide for this specific informer behavior. Use the following checks, based on the feature's requirements and known limitations:
* **Verify agent type:** Confirm your agent is cluster-scoped, not namespace-scoped. Namespace-scoped agents do not support Applications in Any Namespace.
* **Check `applicationNamespaces` configuration:** Ensure the `applicationNamespaces` field is correctly specified in your cluster-scoped agent configuration to include the target namespaces.
* **Avoid `kube-system`:** Do not deploy non-system applications to the `kube-system` namespace. Apps in that reserved namespace do not appear in GitOps reconciliation or the UI. Go to [GitOps troubleshooting](/continuous-delivery/use-gitops/resources/troubleshooting.md#applications-missing-in-gitops-for-kube-system-namespace) to review this scenario.
* **Verify agent version:** Ensure you are running GitOps Agent 0.121.0 or later, the minimum version that supports this feature. Go to the [GitOps Service 1.61.0 / GitOps Agent 0.121.0 release notes](https://developer.harness.io/release-notes/continuous-delivery/#gitops-service-1610-gitops-agent-01210) to review the feature announcement.
* **Check agent health:** In the Harness UI, navigate to **GitOps → Settings → GitOps Agents** and confirm the agent shows a **Healthy** status.
* **Review agent logs:** Check the `argocd-application-controller` and `gitops-agent` pod logs for any errors related to namespace watching or RBAC.
If these checks do not resolve the issue, contact [Harness Support](https://support.harness.io/) or consult the Harness community forums.
AppProject sourceNamespaces configuration is rejected when creating a GitOps application via Terraform
Harness does not publish a dedicated troubleshooting guide for this specific Terraform error. Use the following checks:
* **Verify the `sourceNamespaces` field format:** In the `AppProjectSpec`, `sourceNamespaces` is an array of strings. Ensure your Terraform resource passes it as a list, for example:
```hcl
source_namespaces = ["namespace-a", "namespace-b"]
```
Go to the [Harness API documentation](https://apidocs.harness.io/) to review the `AppProjectSpec` model.
* **Include required Argo CD 2.12 fields:** Since Argo CD 2.12, the `project` field is now mandatory for repository access. Ensure your application configuration explicitly includes the `project` field, or the creation fails. Go to [GitOps troubleshooting](/continuous-delivery/use-gitops/resources/troubleshooting.md#application-creation-fails-due-to-missing-project-field-argo-cd-212-change-previously-it-was-optional) to review the Argo CD 2.12 project field change.
* **Check AppProject metadata labels:** When managing an `AppProject` through Git or Terraform, the following labels are required:
* `accountId` (hashed form `b..e`)
* `orgId`
* `projectId`
Missing these labels causes the AppProject to be rejected. Go to [Manage Argo CD configs](/continuous-delivery/use-gitops/connect-and-manage/manage-argo-configs.md#sample-argo-appproject-configuration) to review a sample AppProject configuration.
* **Ensure the AppProject is mapped to the Harness project:** After creating a new AppProject, go to [Bring Your Own Argo CD into Harness GitOps](/continuous-delivery/use-gitops/connect-and-manage/multiple-argo-to-single-harness.md) to add the mapping for the Argo project to the Harness project in the GitOps Agent.
* **Review cluster secret scoping:** If your cluster secret is scoped to a specific project, applications in other projects are denied access. Unset the `project` field on the cluster secret if it needs to be shared across projects. Go to [GitOps troubleshooting](/continuous-delivery/use-gitops/resources/troubleshooting.md#application-creation-fails-due-to-missing-project-field-argo-cd-212-change-previously-it-was-optional) to review this scenario.
* **Check GitOps agent permissions:** Ensure the GitOps agent has the required access permissions to create and update AppProject resources. Go to [GitOps FAQs](/continuous-delivery/use-gitops/resources/gitops-faqs.md#how-can-users-set-up-gitops-correctly-and-avoid-configuration-errors) to review common configuration errors.
For a more targeted diagnosis, check the Harness GitOps agent logs and the exact error message returned when the Terraform apply fails, then contact [Harness Support](https://support.harness.io/) with those details.
Harness GitOps UI shows stale Application Namespaces configuration after editing argocd-cmd-params-cm directly on the cluster
Harness does not publish a dedicated troubleshooting guide for this specific scenario. The following checks, based on related GitOps concepts, may help:
* **Trigger a refresh:** In the Harness GitOps UI, go to **Deployments > GitOps > Applications** and click **Refresh** for the affected application. This pulls the latest commit from Git and updates the sync state, though it does not directly sync live cluster state. Go to [GitOps basics](/continuous-delivery/use-gitops/get-started/harness-git-ops-basics.md#operational-concepts) to review operational concepts.
* **Check agent reconciliation timing:** The GitOps agent reconciles on CRUD events every \~10 seconds and runs a bulk reconciliation every \~100 seconds. If the UI still shows stale data, wait for a full reconciliation cycle to complete. Go to [Install a Harness GitOps agent](/continuous-delivery/use-gitops/gitops-entities/agents/install-a-harness-git-ops-agent.md#considerations) to review reconciliation timing.
* **Restart the GitOps agent:** Direct edits to `argocd-cmd-params-cm` on the cluster require an agent restart to take effect. Run `kubectl rollout restart deployment -n argocd ` to apply the new configuration. Go to [GitOps troubleshooting](/continuous-delivery/use-gitops/resources/troubleshooting.md#issue-agent-degraded-when-installing-a-bring-your-own-argo-cd-byoa-agent-with-a-helm-chart) to review related BYOA agent issues.
* **Manage Argo CD config declaratively through Harness GitOps:** Instead of editing `argocd-cmd-params-cm` directly, manage Argo CD configurations (including `applicationNamespaces`) as Git-backed manifests through a Harness GitOps application. This ensures the UI always reflects the desired state in Git. Go to [Manage Argo CD configs](/continuous-delivery/use-gitops/connect-and-manage/manage-argo-configs.md) to configure this approach.
* **Verify agent version:** Ensure your GitOps agent is on version 0.93 or higher for reliable bulk sync/refresh behavior, and 0.89 or higher to avoid duplicate reconciliation issues in HA setups. Go to [Bulk sync and refresh](/continuous-delivery/use-gitops/application/sync-gitops-applications.md#bulk-sync-and-refresh) and [Install a Harness GitOps agent](/continuous-delivery/use-gitops/gitops-entities/agents/install-a-harness-git-ops-agent.md#considerations) to review the version requirements.
* **Contact Harness Support:** If the UI continues to show stale data after the above steps, contact [Harness Support](mailto:support@harness.io) for further investigation.
***
## Next steps
* [Manage AppProjects](/continuous-delivery/use-gitops/gitops-entities/projects/manage-projects.md): Configure source namespaces and destinations on your AppProjects.
* [Install a Harness GitOps Agent](/continuous-delivery/use-gitops/gitops-entities/agents/install-a-harness-git-ops-agent.md): Review agent installation options and cluster-wide mode requirements.
* [Manage Argo CD configs](/continuous-delivery/use-gitops/connect-and-manage/manage-argo-configs.md): Configure annotation-based resource tracking.
{% @harness-feedback/feedback %}