Skip to content

AppLifecycle: Add basic vs advanced pull model documentation #536

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
openshift-merge-bot merged 1 commit into from
Feb 2, 2026
Merged

AppLifecycle: Add basic vs advanced pull model documentation #536

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 140 additions & 12 deletions content/en/docs/getting-started/integration/app-lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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
```