Red Hat SummitChapter 4. Managing application links with the managed-by-url annotation
Use the argocd.argoproj.io/managed-by-url annotation to specify which Argo CD instance manages an Application resource. This configuration ensures that application links in the user interface resolve to the correct instance in multi-instance environments.
4.1. Overview of the managed-by-url annotation
The argocd.argoproj.io/managed-by-url annotation allows an Application resource to specify which Argo CD instance manages it. This annotation ensures application links in the user interface point to the correct managing instance.
When you use multiple Argo CD instances with the app-of-apps pattern:
- A primary Argo CD instance creates a parent Application.
- The parent Application deploys child Applications that a secondary Argo CD instance manages.
- Without the annotation, clicking on child Applications in the primary instance’s user interface attempts to open them in the primary instance, which is incorrect.
- With the annotation, child Applications correctly open in the secondary instance.
The managed-by-url annotation ensures application links redirect to the correct Argo CD instance.
This annotation is particularly useful in multitenant setups where different teams have their own Argo CD instances, or in hub-and-spoke architectures where a central instance manages multiple edge instances.
4.2. Configuring the managed-by-url annotation
You can configure the argocd.argoproj.io/managed-by-url annotation to direct application links to the correct Argo CD instance in multi-instance environments.
Prerequisites
- You have access to multiple Argo CD instances.
- You are using a GitOps workflow with Application resources.
- You have permissions to create and modify Application manifests.
Procedure
Create a parent Application in the primary Argo CD instance:
apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: parent-app namespace: argocd spec: project: default source: repoURL: https://github.com/YOUR-ORG/my-apps-repo.git targetRevision: main path: path-to-child-app destination: server: https://kubernetes.default.svc namespace: namespace-b syncPolicy: automated: selfHeal: true prune: trueThe parent Application deploys child Applications from the specified repository.
Add the
managed-by-urlannotation to the child Application definition in your Git repository. Replacehttps://secondary-argocd.example.comwith the actual URL of your secondary Argo CD instance:apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: child-app namespace: namespace-b annotations: argocd.argoproj.io/managed-by-url: "https://secondary-argocd.example.com" spec: project: default source: repoURL: https://github.com/YOUR-ORG/my-apps-repo.git targetRevision: main path: path-to-child-app destination: server: https://kubernetes.default.svc namespace: namespace-b syncPolicy: automated: selfHeal: true prune: trueThe annotation defines the Argo CD instance that manages the child Application.
- Apply or sync the parent Application.
Verification
- Log in to the primary Argo CD instance.
-
Navigate to the
parent-appApplication. -
Select the
child-appresource from the resource tree. - Verify that the link opens in the correct Argo CD instance at the URL specified in the annotation.
4.3. Managed-by-url annotation reference
The argocd.argoproj.io/managed-by-url annotation specifies the Argo CD instance URL that manages an Application resource.
| Field | Value |
|---|---|
| Annotation |
|
| Target | Application |
| Value | Valid HTTP(S) URL |
| Required | No |
The annotation value must be a valid HTTP or HTTPS URL.
The following are the examples of valid annotation values:
The following are the examples of invalid annotation values:
-
argocd.example.com- Missing protocol -
javascript:alert(1)- Invalid protocol
Invalid values prevent Argo CD from creating or updating the Application.
Argo CD determines application links as follows:
- Without the annotation, Argo CD uses the current instance URL.
- With the annotation, Argo CD uses the specified URL.
- With an invalid value, Argo CD falls back to the current instance and logs a warning.
Ensure that the specified URL is accessible from user browsers. Configure DNS or network access as required for internal deployments.
4.4. Troubleshooting the managed-by-url annotation
Use the following guidelines to troubleshoot issues with the argocd.argoproj.io/managed-by-url annotation.
If links point to the wrong instance, check if the annotation is present:
$ kubectl get application <child-app-name> -n <namespace> \
-o jsonpath='{.metadata.annotations.argocd\.argoproj\.io/managed-by-url}'where:
<child-app-name>- Specifies the name of the child Argo CD Application whose annotation you want to retrieve.
<namespace>- Specifies the namespace in which the child Application resource exists.
Expected output:
http://localhost:8081
The output displays a complete URL such as http://localhost:8081 or your configured URL such as https://secondary-argocd.example.com.
If the annotation is present but links do not work:
- Verify that the URL is reachable from your browser.
- Check the browser console for errors.
-
Ensure that the URL includes the correct protocol (
http://orhttps://).
If Application creation fails with an "invalid managed-by URL" error, verify the following:
-
Verify that the URL includes a protocol (
https://orhttp://). - Check for typos in the URL.
- Ensure the URL uses only valid characters.
-
Avoid unsupported schemes such as
javascript:.
If nested Applications are not working in app-of-apps patterns, ensure the following:
- The child Application YAML in Git includes the annotation.
- The parent Application synced successfully.
- The child Application exists in the cluster.
Verify that the child Application exists:
$ kubectl get application <child-app-name> -n <namespace>where:
<child-app-name>- Specifies the name of the child Application resource to verify.
<namespace>- Specifies the namespace where the child Application is expected to exist.
If the child Application does not exist, check the parent Application sync status and logs.
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}