DOCSEARCHbyAlgolia
Submit Docs

argocd-agent Documentation

repository·main·Indexed 20 days ago

https://github.com/argoproj-labs/argocd-agent

A distributed GitOps tool that extends Argo CD to manage hundreds or thousands of clusters using a hub-and-spoke pull model. Designed for scale, network resilience, and security in edge, multi-cloud, and air-gapped environments.

Tokens
119.4K
Snippets
258
Records
423
Agent score
67%

What's inside argocd-agent

  2. Use argocd-agentctl to manage components

    main

    argocd-agentctl is a CLI tool used to manage argocd-agent components, including principals and agents. It allows you to inspect configurations, manage JWT signing keys, validate setups, and handle local configuration files to simplify targeting specific Kubernetes contexts and namespaces.

    Available Commands

    • agent: Inspect and manage agent configuration.
    • validate (formerly check-config): Validate principal and agent configurations by running tests.
    • config: Operations related to the local argocd-agentctl configuration file.
    • jwt: Inspect and manage JWT signing keys used by the principal to sign tokens for agents.
    • pki: Inspect and manage the principal's PKI (NOT FOR PRODUCTION USE).

  3. What is the Principal component?

    main

    The Principal is a central component that runs on the Control Plane Cluster (Hub). It acts as the communication bridge between the central management layer and the distributed workload clusters.

    Key Functions:

    • Configuration Distribution: Distributes configuration from the Hub to the agents.
    • Status Aggregation: Receives status information from agents and provides it back to the central system.
    • Agent Management: Handles agent registration and performs authentication once an agent connects.
    • Observability Services: Provides additional services to the Argo CD API server, enabling users to view live resources and container logs directly from workload clusters.

    Privileges: The principal typically requires a limited set of privileges on the control plane cluster.

  4. What is the Agent component?

    main

    The Agent is a component installed on each Workload Cluster (Spoke). It is responsible for local execution and reporting.

    Key Functions:

    • Connectivity: Configured to connect to a specific principal to receive configuration and send status updates.
    • Modes of Operation: Agents can run in either managed or autonomous modes (see agent modes for details).

    Privileges: Depending on the specific features required, an agent may require a limited to an extended set of privileges on the workload cluster.

  5. Overview of argocd-agent TLS and PKI requirements

    main

    argocd-agent uses a Public Key Infrastructure (PKI) to secure communication between the Principal and Agent components. The following certificates and keys are required across the clusters:

    Principal Cluster Requirements

    Certificate/KeyPurposeSecret Name
    CA CertificateRoot CA for signing all other certificatesargocd-agent-ca
    Principal Server CertificateSecures gRPC communication from agentsargocd-agent-principal-tls
    Resource Proxy CertificateSecures HTTP communication between Argo CD and principalargocd-agent-resource-proxy-tls
    JWT Signing KeySigns authentication tokensargocd-agent-jwt

    Agent Cluster Requirements

    Certificate/KeyPurposeSecret Name
    CA CertificateValidates the principal's server certificateargocd-agent-ca
    Client CertificateAuthenticates the agent to the principal (mTLS)argocd-agent-client-tls

  6. How the Live Resource Proxy works

    main

    The resource proxy enables users to view and interact with Kubernetes resources on agent clusters directly from the Argo CD UI (the principal/control plane).

    Workflow:

    1. Intercept: The proxy intercepts Kubernetes API requests from the Argo CD server.
    2. Authenticate: It authenticates requests using client certificates (the agent name is in the certificate subject).
    3. Route: It routes the request to the appropriate connected agent via the event queue.
    4. Forward: The agent executes the request against the local Kubernetes API and forwards the response back through the principal to the server.

    This allows seamless resource inspection without requiring direct network connectivity between the Argo CD server and the workload clusters.

  8. Understand the relationship between the principal and the agent

    main

    The communication between the principal (on the control plane) and the agent (on the workload cluster) is based on a bi-directional message exchange over a single connection.

    • Connection Direction: The connection is established exclusively by the agent connecting to the principal. The control plane cannot initiate connections to the agents.
    • Communication Pattern: Although the connection is unidirectional (agent $\rightarrow$ principal), it uses a bi-directional stream (currently gRPC-based) that allows both the principal and the agent to send and receive messages simultaneously.
    • Data Focus: The exchange focuses on Argo CD configuration (e.g., Applications, AppProjects) rather than raw Kubernetes resource watching.

  9. Understand what data is replicated in HA mode

    main

    When running in a replica configuration, the Replication Client synchronizes the following data from the primary to the replica's local Kubernetes cluster:

    Data TypeReplication Method
    ApplicationsFull snapshot + incremental CloudEvents
    AppProjectsFull snapshot + incremental CloudEvents
    ApplicationSetsFull snapshot
    RepositoriesFull snapshot + incremental CloudEvents
    Cluster secretsFull snapshot (specifically agent-managed secrets where self-registered-cluster=true)
    Agent connection metadataSnapshot (name, mode, connected state)
    Resource keysSnapshot + event-driven
    Queue stateQueue pairs created on snapshot; events flow as queued

  10. Understand the argocd-agent HA state machine

    main

    The HA system uses an active/passive model where transitions are exclusively triggered by an operator. The principal moves through several states based on its configuration and the status of its peer:

    • RECOVERING: Startup phase; determining role. Returns 503 health.
    • SYNCING: Initial catch-up phase where the replica pulls a snapshot from the primary. Returns 503 health.
    • REPLICATING: The replica is in sync and receiving incremental events via the Subscribe stream. Returns 503 health.
    • DISCONNECTED: The replication stream is broken. Returns 503 health.
    • ACTIVE: The principal is serving agents. Returns 200 OK health.

    State Transitions:

    • REPLICATING or DISCONNECTED $\rightarrow$ ha promote $\rightarrow$ ACTIVE
    • ACTIVE $\rightarrow$ ha demote $\rightarrow$ REPLICATING

  11. Configure TLS for the Principal server

    main

    The Principal uses TLS for secure communication. You can configure certificates via Kubernetes Secrets or direct file paths.

    Key Security Modes:

    • Standard TLS: Uses --tls-secret-name (default: argocd-agent-principal-tls) or overrides with --tls-cert and --tls-key file paths.
    • Insecure Plaintext: Use --insecure-plaintext to run the gRPC server without TLS. This is required for service mesh deployments using header authentication.
    • Development Mode: Use --insecure-tls-generate to generate temporary, non-persistent TLS certificates.

    Client Authentication: To enforce identity, use --require-client-certs to mandate client certificates, and optionally use --client-cert-subject-match to ensure the certificate subject matches the agent name.

    # TLS Configuration Reference

| Setting | CLI Flag | Environment Variable | ConfigMap Entry | Default |
|---|---|---|---|---|
| TLS Secret Name | `--tls-secret-name` | `ARGOCD_PRINCIPAL_TLS_SECRET_NAME` | `principal.tls.secret-name` | `argocd-agent-principal-tls` |
| TLS Cert Path | `--tls-cert` | `ARGOCD_PRINCIPAL_TLS_SERVER_CERT_PATH` | `principal.tls.server.cert-path` | `""` |
| TLS Key Path | `--tls-key` | `ARGOCD_PRINCIPAL_TLS_SERVER_KEY_PATH` | `principal.tls.server.key-path` | `""` |
| Insecure TLS Gen | `--insecure-tls-generate` | `ARGOCD_PRINCIPAL_TLS_SERVER_ALLOW_GENERATE` | `principal.tls.server.allow-generate` | `false` |
| Insecure Plaintext | `--insecure-plaintext` | `ARGOCD_PRINCIPAL_INSECURE_PLAINTEXT` | `principal.tls.insecure-plaintext` | `false` |
| TLS CA Secret | `--tls-ca-secret-name` | `ARGOCD_PRINCIPAL_TLS_SERVER_ROOT_CA_SECRET_NAME` | `principal.tls.server.root-ca-secret-name` | `argocd-agent-ca` |
| Require Client Certs | `--require-client-certs` | `ARGOCD_PRINCIPAL_TLS_CLIENT_CERT_REQUIRE` | `principal.tls.client-cert.require` | `false` |
| Min TLS Version | `--tls-min-version` | `ARGOCD_PRINCIPAL_TLS_MIN_VERSION` | `principal.tls.min-version` | `tls1.3` |

  12. Security and Access Control for Live Resources

    main

    Access to live resources is governed by strict security protocols to ensure isolation and prevent unauthorized cluster access.

    Authentication

    • mTLS Required: All requests must include valid client certificates.
    • Agent Identity: The agent's name is extracted from the certificate subject.
    • Certificate Validation: Certificates are validated against the configured CA.

    Authorization

    • Managed Resources Only: The agent only allows access to resources managed by Argo CD applications. It uses strict filtering (checking for Argo CD annotations/labels) to ensure non-managed resources are inaccessible.
    • Agent Isolation: Each agent is isolated and can only access its own managed resources.
    • Connection Dependency: Requests will fail if the target agent is not currently connected to the principal.