AppLifecycle: Add basic vs advanced pull model documentation (#536)

Document both argocd (basic) and argocd-agent (advanced) pull model options
with comparison table and installation instructions for each.

Signed-off-by: Mike Ng <ming@redhat.com>

Author: mikeshng

content/en/docs/getting-started/integration/app-lifecycle.md

@@ -18,15 +18,19 @@ where resources are deployed from a centralized Argo CD instance to remote or ma
     <img src="https://github.com/open-cluster-management-io/ocm/raw/main/solutions/deploy-argocd-apps-pull/assets/push.png" alt="Argo CD Push Model" style="margin: 0 auto; width: 80%">
 </div>
 
-With the OCM Argo CD add-on, users can leverage a pull based resource delivery model,
-where managed clusters pull and apply application configurations.
+With the OCM Argo CD add-ons, users can leverage a pull based resource delivery model,
+where managed clusters pull and apply application configurations. OCM provides two pull model options:
 
-<div style="text-align: center; padding: 20px;">
-    <img src="https://github.com/open-cluster-management-io/ocm/raw/main/solutions/deploy-argocd-apps-pull/assets/pull.png" alt="Argo CD Pull Model" style="margin: 0 auto; width: 80%">
-</div>
+| Feature | Basic Pull Model (`argocd`) | Advanced Pull Model (`argocd-agent`) |
+|---------|----------------------------|--------------------------------------|
+| **How it works** | Wraps Applications in ManifestWork, distributed via OCM agent | Direct gRPC communication between hub principal and managed agents |
+| **Argo CD on hub** | Full Argo CD instance required | Argo CD + Agent Principal |
+| **Argo CD on managed** | Local Argo CD controller | Argo CD Agent + controller/repo-server |
+| **Status feedback** | Basic status via ManifestWork | Full status sync via gRPC |
+| **Load Balancer** | Not required | Required on hub cluster |
+| **Use Case** | Simpler setup, moderate scale | Large fleets, full Argo CD UI integration |
 
-For more details, visit the
-[Argo CD Pull Integration GitHub page](https://github.com/open-cluster-management-io/argocd-pull-integration).
+For more details, visit the [Argo CD Pull Integration GitHub page](https://github.com/open-cluster-management-io/argocd-pull-integration).
 
 ## Prerequisites
 
@@ -40,9 +44,11 @@ You must meet the following prerequisites to install the application lifecycle m
 
 - Ensure `clusteradm` CLI tool is installed. Download and extract the [clusteradm binary](https://github.com/open-cluster-management-io/clusteradm/releases/latest). For more details see the [clusteradm GitHub page](https://github.com/open-cluster-management-io/clusteradm/blob/main/README.md#quick-start).
 
-## Installation
+## Basic Pull Model Installation
 
-Install Argo CD on the Hub cluster:
+The basic pull model uses the standard Argo CD with a lightweight integration controller.
+
+### Install Argo CD on the Hub cluster
 
 ```shell
 kubectl create namespace argocd
@@ -51,7 +57,7 @@ kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/st
 
 See [Argo CD website](https://argo-cd.readthedocs.io/en/stable/getting_started/) for more details.
 
-Install the OCM Argo CD add-on on the Hub cluster:
+### Install the OCM Argo CD add-on
 
 ```shell
 clusteradm install hub-addon --names argocd
@@ -65,7 +71,7 @@ NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
 argocd-pull-integration   1/1     1            1           55s
 ```
 
-Enable the add-on for your choice of Managed clusters:
+### Enable the add-on for Managed clusters
 
 ```shell
 clusteradm addon enable --names argocd --clusters cluster1,cluster2
@@ -81,6 +87,8 @@ NAME     AVAILABLE   DEGRADED   PROGRESSING
 argocd   True                   False
 ```
 
+### Deploy Applications
+
 On the Hub cluster, apply the example `guestbook-app-set` manifest:
 
 ```shell
@@ -89,7 +97,7 @@ kubectl apply -f https://raw.githubusercontent.com/open-cluster-management-io/oc
 
 **Note:** The Application template inside the ApplicationSet must contain the following content:
 
-```shell
+```yaml
 labels:
   apps.open-cluster-management.io/pull-to-ocm-managed-cluster: 'true'
 annotations:
@@ -142,3 +150,123 @@ NAME                     SYNC STATUS   HEALTH STATUS
 cluster1-guestbook-app   Synced        Healthy
 cluster2-guestbook-app   Synced        Healthy
 ```
+
+## Advanced Pull Model Installation (Argo CD Agent)
+
+The advanced pull model uses [Argo CD Agent](https://github.com/argoproj-labs/argocd-agent/) to offload compute-intensive parts of Argo CD (application controller, repository server) to managed clusters while maintaining centralized control and observability on the hub.
+
+### Prerequisites for Advanced Pull Model
+
+- **The Hub cluster must have a load balancer.** For KinD clusters, you can use MetalLB. See the [OCM solutions guide](https://github.com/open-cluster-management-io/ocm/tree/main/solutions/argocd-agent#additional-resources) for setup instructions.
+
+### Install the OCM Argo CD Agent add-on
+
+```shell
+clusteradm install hub-addon --names argocd-agent --create-namespace
+```
+
+This will install all necessary components including:
+- Argo CD Operator
+- Argo CD Agent principal
+- OCM integration controller
+
+If your hub controller starts successfully, you should see:
+
+```shell
+$ kubectl -n argocd get pods
+NAME                                                  READY   STATUS    RESTARTS   AGE
+argocd-agent-principal-xxx                            1/1     Running   0          2m
+argocd-pull-integration-controller-xxx                1/1     Running   0          2m
+argocd-applicationset-controller-xxx                  1/1     Running   0          2m
+...
+```
+
+### Verify the add-on is enabled on Managed clusters
+
+The Argo CD Agent add-on is automatically enabled for all managed clusters via the GitOpsCluster Placement.
+
+```shell
+$ kubectl get managedclusteraddon --all-namespaces
+NAMESPACE   NAME                 AVAILABLE   DEGRADED   PROGRESSING
+cluster1    argocd-agent-addon   True                   False
+```
+
+On the managed cluster, verify the agent is running:
+
+```shell
+$ kubectl -n argocd get pods
+NAME                                  READY   STATUS    RESTARTS   AGE
+argocd-agent-agent-xxx                1/1     Running   0          2m
+argocd-application-controller-0       1/1     Running   0          2m
+...
+```
+
+### Deploy Applications
+
+Create an AppProject on the hub cluster:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: argoproj.io/v1alpha1
+kind: AppProject
+metadata:
+  name: default
+  namespace: argocd
+spec:
+  clusterResourceWhitelist:
+    - group: '*'
+      kind: '*'
+  destinations:
+    - namespace: '*'
+      server: '*'
+  sourceNamespaces:
+    - '*'
+  sourceRepos:
+    - '*'
+EOF
+```
+
+First, create the target namespace on the managed cluster:
+
+```shell
+# kubectl config use-context <managed-cluster>
+kubectl create namespace guestbook
+```
+
+Then create an Application on the hub cluster:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: guestbook
+  namespace: cluster1  # replace with managed cluster name
+spec:
+  project: default
+  source:
+    repoURL: https://github.com/argoproj/argocd-example-apps
+    targetRevision: HEAD
+    path: guestbook
+  destination:
+    server: https://<principal-external-ip>:443?agentName=cluster1  # Replace with actual IP and cluster name
+    namespace: guestbook
+  syncPolicy:
+    automated:
+      prune: true
+EOF
+```
+
+Note: Replace `<principal-external-ip>` with the external IP of the `argocd-agent-principal` LoadBalancer service:
+
+```shell
+kubectl -n argocd get svc argocd-agent-principal
+```
+
+Verify the application is deployed on the managed cluster:
+
+```shell
+$ kubectl -n argocd get app
+NAME        SYNC STATUS   HEALTH STATUS
+guestbook   Synced        Healthy
+```