Application Synchronization (managed agents)¶

This guide covers how Argo CD Applications are synchronized between the principal (control plane) and managed agents on workload clusters.

For autonomous agents, see Application synchronization (autonomous agents). For how managed and autonomous modes differ at a conceptual level, see Agent modes.

Overview¶

Application synchronization in argocd-agent maps Applications to agents using namespaces, where each namespace on the principal corresponds to a specific agent.

For managed agents, Applications are created on the principal and distributed to agents; agents send status updates back to the principal.

Managed Agent Mode¶

Creating Applications¶

In managed mode, Applications must be created in the agent's corresponding namespace on the principal cluster (control plane). The principal determines which agent should receive an Application based on the namespace where it's created.

Namespace to Agent Mapping¶

Applications are mapped to agents through a simple naming convention:

Namespace name on principal = Agent name
Example: Applications in namespace production-cluster are sent to the agent named production-cluster

Example: Creating an Application for a Managed Agent¶

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: production-cluster  # This determines the target agent
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc  # Will be transformed
    namespace: guestbook
  syncPolicy:
    syncOptions:
    - CreateNamespace=true

When this Application is created in namespace production-cluster on the principal, it will be automatically sent to the managed agent named production-cluster.

Agent-Side Transformation¶

When an Application is sent to a managed agent, it undergoes transformation to make it agent-specific:

Destination Server: Transformed to point to the local cluster:

   destination:
     server: ""
     name: "in-cluster"
     namespace: "guestbook"

Namespace: Changed to the agent's local namespace:

   metadata:
     namespace: argocd  # Agent's local namespace

Source UID Annotation: Added to track the original source for synchronization purposes

Status Synchronization¶

In managed mode, the agent continuously monitors Application status changes and sends updates back to the principal:

Principal → Agent: Spec changes (configuration, source repo, destination, etc.)
Agent → Principal: Status updates (sync status, health, operation results, etc.)

The principal maintains the "source of truth" for the Application specification, while the agent reports back the actual state of the deployment.

Conflict Resolution¶

If an Application is modified directly on the managed agent cluster (outside of the principal), these changes will be automatically reverted to maintain the principal as the single source of truth.

Lifecycle Management¶

Creation: Create Applications on the principal in the agent's namespace
Updates: Modify Applications on the principal; changes are automatically propagated
Deletion: Delete Applications on the principal; they're automatically removed from the agent
Agent Connection: When an agent connects, it receives all Applications in its namespace

Best practices¶

Namespace Organization: Use clear, descriptive namespace names that match your agent names:
```
   production-east
   production-west
   staging-cluster
   development-cluster
```

Application Naming: Use consistent naming conventions within each namespace:

   metadata:
     name: frontend-prod
     namespace: production-east

Monitor Status: Regularly check Application status on the principal to ensure successful deployments
Avoid Direct Changes: Never modify Applications directly on agent clusters; always use the principal

Troubleshooting¶

Application Not Appearing on Agent (Managed Mode)¶

Check Namespace: Verify the Application is created in the correct namespace on the principal
Verify Agent Connection: Ensure the agent is connected and the namespace name matches the agent name
Review Logs: Check principal logs for distribution events and agent logs for reception
Check Source UID: Look for source UID annotations to verify proper synchronization

Status Not Updating¶

Check Agent Health: Verify the agent is running and connected
Review Application Controller: Ensure Argo CD's application-controller is running on the agent
Inspect Annotations: Check for proper source UID annotations
Monitor Network: Verify stable network connectivity between agent and principal

Sync Conflicts¶

Source UID Mismatch:
- Usually resolved automatically by recreating the Application
- Check logs for conflict resolution messages
Cache Issues (Managed Mode):
- Agent may revert unexpected changes
- Review Application cache logs on the agent
Manual Intervention Required:
- Delete and recreate the Application if automatic resolution fails
- Ensure the principal has the desired specification

Monitoring and observability¶

Key Metrics to Monitor¶

Application Creation/Update/Delete Events: Track synchronization activity
Status Update Frequency: Monitor how often agents report status changes
Sync Errors: Watch for failed synchronization attempts
Cache Hit/Miss Rates: Monitor cache effectiveness on managed agents

Log Events to Watch¶

Principal Logs:
- Application distribution events
- Status update processing
- Resync operations
Agent Logs:
- Application creation/update events
- Status reporting activities
- Cache operations (managed mode)
- Conflict resolution actions

Health Checks¶

Principal: Monitor Application informer sync status
Agent: Verify Application backend is running and synced
Network: Ensure stable gRPC connection between principal and agents

Security Considerations¶

Access Control¶

Managed Mode: Principal controls all Application specifications; implement RBAC on the principal
Network Security: Ensure encrypted communication channels between principal and agents.

Isolation¶

Namespace Isolation: Each agent operates in its own namespace on the principal
Agent Authentication: Proper authentication prevents unauthorized agents from connecting
Resource Limits: Consider implementing resource quotas per agent namespace

Audit and Compliance¶

Change Tracking: All Application changes are logged and auditable
Source Tracking: Source UID annotations provide clear provenance
Access Logs: Monitor who creates/modifies Applications on the principal