docs: add user content for managed-by-url annotation

docs/operator-manual/managed-by-url.md

@@ -0,0 +1,200 @@
+# Managed By URL Annotation
+
+## Overview
+
+The `argocd.argoproj.io/managed-by-url` annotation allows an Application resource to specify which Argo CD instance manages it. This is useful when you have multiple Argo CD instances and need application links in the UI to point to the correct managing instance.
+
+## Use Case
+
+When using multiple Argo CD instances with the [app-of-apps pattern](cluster-bootstrapping.md):
+
+1. A primary Argo CD instance creates a parent Application
+2. That parent Application deploys child Applications managed by a secondary Argo CD instance
+3. Without the annotation, clicking on child Applications in the primary instance's UI tries to open them in the primary instance (incorrect)
+4. The child Applications should open in the secondary instance instead
+
+The `managed-by-url` annotation ensures application links redirect to the correct Argo CD instance.
+
+> [!NOTE]
+> This annotation is particularly useful in multi-tenant setups where different teams have their own Argo CD instances, or in hub-and-spoke architectures where a central instance manages multiple edge instances.
+
+## Example
+
+This example demonstrates the [app-of-apps pattern](cluster-bootstrapping.md) where a parent Application deploys child Applications from a Git repository.
+
+### Step 1: Create Parent Application
+
+Create a parent Application in your primary Argo CD instance:
+
+```yaml
+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: true
+```
+
+### Step 2: Create Child Application in Git Repository
+
+In your Git repository at `apps/child-apps/child-app.yaml`, add the `managed-by-url` annotation:
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: child-app
+  namespace: namespace-b
+  annotations:
+    argocd.argoproj.io/managed-by-url: "http://localhost:8081" # replace with actual secondary ArgoCD URL in real setup
+spec:
+  project: default
+  source:
+    repoURL: https://github.com/YOUR-ORG/my-apps-repo.git
+    targetRevision: HEAD
+    path: path-to-child-app
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: namespace-b
+  syncPolicy:
+    automated:
+      selfHeal: true
+      prune: true
+```
+
+### Result
+
+When viewing the parent Application in the primary instance's UI:
+- The parent Application syncs from Git and deploys the child Application
+- Clicking on `child-app` in the resource tree navigates to `https://secondary-argocd.example.com/applications/namespace-b/child-app`
+- The link opens the child Application in the correct Argo CD instance that actually manages it
+
+## Configuration
+
+### Annotation Format
+
+| Field | Value |
+|-------|-------|
+| **Annotation** | `argocd.argoproj.io/managed-by-url` |
+| **Target** | Application |
+| **Value** | Valid HTTP(S) URL |
+| **Required** | No |
+
+### URL Validation
+
+The annotation value **must** be a valid HTTP(S) URL:
+
+- ✅ `https://argocd.example.com`
+- ✅ `https://argocd.example.com:8080`
+- ✅ `http://localhost:8080` (for development)
+- ❌ `argocd.example.com` (missing protocol)
+- ❌ `javascript:alert(1)` (invalid protocol)
+
+Invalid URLs will prevent the Application from being created or updated.
+
+### Behavior
+
+When generating application links, Argo CD:
+- **Without annotation**: Uses the current instance's base URL
+- **With annotation**: Uses the URL from the annotation
+- **Invalid annotation**: Falls back to the current instance's base URL and logs a warning
+
+> [!WARNING]
+> Ensure the URL in the annotation is accessible from users' browsers. For internal deployments, use internal DNS names or configure appropriate network access.
+
+## Testing Locally
+
+To test the annotation with two local Argo CD instances:
+
+```bash
+# Install primary instance
+kubectl create namespace argocd
+kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+
+# Install secondary instance
+kubectl create namespace namespace-b
+kubectl apply -n namespace-b -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+
+# Port forward both instances
+kubectl port-forward -n argocd svc/argocd-server 8080:443 &
+kubectl port-forward -n namespace-b svc/argocd-server 8081:443 &
+
+# Wait for Argo CD to be ready
+kubectl wait --for=condition=available --timeout=300s deployment/argocd-server -n argocd
+
+# Get the admin password for primary instance
+kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d && echo
+
+```
+
+Then:
+1. Open `http://localhost:8080` in your browser
+2. Login with username `admin` and the password from the command above
+3. Navigate to the `parent-app` Application
+4. Click on the `child-app` in the resource tree
+5. It should redirect to `http://localhost:8081/applications/namespace-b/child-app`
+
+You will need to repeat the command to get the password for secondary instance to login and access the child-app
+
+```bash
+# Get the admin password for secondary instance
+kubectl -n namespace-b get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d && echo
+```
+
+## Troubleshooting
+
+### Links Still Point to Wrong Instance
+
+**Check if the annotation is present:**
+
+```bash
+kubectl get application child-app -n instance-b -o jsonpath='{.metadata.annotations.argocd\.argoproj\.io/managed-by-url}'
+```
+
+Expected output: A complete URL like `http://localhost:8081` or the url that has been set 
+i.e `https://secondary-argocd.example.com`
+
+**If the annotation is present but links still don't work:**
+- Verify the URL is accessible from your browser
+- Check browser console for errors
+- Ensure the URL format is correct (includes `http://` or `https://`)
+
+### Application Creation Fails
+
+If Application creation fails with "invalid managed-by URL" error:
+
+- ✅ URL includes protocol (`https://` or `http://`)
+- ✅ URL contains no typos
+- ✅ URL uses only valid characters
+- ✅ URL is not a potentially malicious scheme (e.g., `javascript:`)
+
+### Nested Applications Not Working
+
+For app-of-apps patterns, ensure:
+1. The child Application YAML in Git includes the annotation
+2. The parent Application has synced successfully
+3. The child Application has been created in the cluster
+
+Verify the child Application exists:
+
+```bash
+kubectl get application CHILD-APP-NAME -n NAMESPACE
+```
+
+## See Also
+
+- [Application Annotations](../user-guide/annotations-and-labels.md)
+- [App of Apps Pattern](cluster-bootstrapping.md)
+- [Deep Links](deep_links.md)

docs/user-guide/annotations-and-labels.md

@@ -9,6 +9,7 @@
 | argocd.argoproj.io/hook                    | any                 | [see resource hooks docs](resource_hooks.md)                                                      | Used to configure [resource hooks](resource_hooks.md).                                                                                                                                                       |
 | argocd.argoproj.io/hook-delete-policy      | any                 | [see resource hooks docs](resource_hooks.md#hook-deletion-policies)                               | Used to set a [resource hook's deletion policy](resource_hooks.md#hook-deletion-policies).                                                                                                                   |
 | argocd.argoproj.io/manifest-generate-paths | Application         | [see scaling docs](../operator-manual/high_availability.md#webhook-and-manifest-paths-annotation) | Used to avoid unnecessary Application refreshes, especially in mono-repos.                                                                                                                                   |
+| argocd.argoproj.io/managed-by-url          | Application         | A valid http(s) URL                                                                               | Specifies the URL of the Argo CD instance managing the application. Used to correctly link to applications managed by a different Argo CD instance. See [managed-by-url docs](../operator-manual/managed-by-url.md) for details. |
 | argocd.argoproj.io/refresh                 | Application         | `normal`, `hard`                                                                                  | Indicates that app needs to be refreshed. Removed by application controller after app is refreshed. Value `"hard"` means manifest cache and target cluster state cache should be invalidated before refresh. |
 | argocd.argoproj.io/skip-reconcile          | Application         | `"true"`                                                                                          | Indicates to the Argo CD application controller that the Application should not be reconciled. See the [skip reconcile documentation](skip_reconcile.md) for use cases.                                      |
 | argocd.argoproj.io/sync-options            | any                 | [see sync options docs](sync-options.md)                                                          | Provides a variety of settings to determine how an Application's resources are synced.                                                                                                                       |

mkdocs.yml

@@ -63,6 +63,7 @@ nav:
   - operator-manual/web_based_terminal.md
   - operator-manual/config-management-plugins.md
   - operator-manual/deep_links.md
+  - operator-manual/managed-by-url.md
   - Notifications:
     - Overview: operator-manual/notifications/index.md
     - operator-manual/notifications/triggers.md