Argo CD Architecture Explained & Hands-On Installation

This note covers the core architectural design of Argo CD, its role as a GitOps controller within a Kubernetes ecosystem, and a step-by-step hands-on guide to installing and configuring Argo CD on a local Kubernetes cluster using Kind and Helm.

1. Revision: GitOps as an Operating Model vs. Tooling

Before diving into Argo CD, it is critical to establish the distinction between GitOps as an operating model and the tools used to implement it. GitOps is not a tool; it is an operating model. Tools like Argo CD and Flux CD are GitOps controllers (or software agents) that help organizations realize this model.

In a GitOps-based architecture, the desired state of both applications and infrastructure is stored in version-controlled repositories. Best practices dictate separating these into:

1. Application Code Repository: Stores the source code and application logic.
2. Application Configuration Repository: Stores the Kubernetes manifests, Helm charts, or Customize configurations.

The Four Core Principles of GitOps

• Declarative: The entire system state must be defined declaratively (using YAML or JSON in the case of Kubernetes). This ensures that configurations are reproducible and readable.
• Immutable: Immutability in GitOps means that once a state is declared and versioned in Git, it cannot be modified on the fly without creating a new record. If something goes wrong, you can roll back to a previous, known-good commit.
• Pulled Automatically: The GitOps controller running inside the cluster continuously pulls the desired state from Git.
• Continuously Reconciled: The controller continuously monitors the cluster's live state and compares it to the desired state in Git. If a drift is detected (e.g., due to manual intervention), the controller automatically reverts the cluster to match the Git repository.

2. What is Argo CD? (The Kubernetes-Native Paradigm)

Argo CD is a Kubernetes-native continuous delivery tool designed to implement the GitOps operating model.

What Does "Kubernetes-Native" Mean?

Kubernetes is designed to be highly modular and extensible. It allows external systems to integrate directly into its control plane using Custom Resource Definitions (CRDs) and Custom Resources (CRs).

Argo CD is built specifically for this ecosystem. It does not run as an external agent pushing commands via SSH or external APIs; instead, it is deployed directly inside the Kubernetes cluster. It registers its own CRDs (such as Application and AppProject) and runs custom controllers to manage them.

Note:

• Custom Resource Definition (CRD): A blueprint or schema that defines a new, custom object type in the Kubernetes API.
• Custom Resource (CR): An instance of a CRD, defined in a YAML file, representing a specific configuration or application managed by the controller.

3. Selective GitOps Adoption in Production

In real-world enterprise environments, GitOps adoption is rarely an "all-or-nothing" migration. It is typically selective and incremental.

A single Kubernetes cluster may host:

• GitOps-Managed Applications: Applications fully onboarded to Argo CD, where Git is the absolute source of truth and manual changes are blocked or automatically reverted.
• Legacy/Traditional Applications: Applications still deployed via traditional push-based CI/CD pipelines (e.g., Jenkins, GitLab CI) or manual kubectl apply commands.

This hybrid model allows teams to migrate workloads incrementally without disrupting existing production services.

4. Core Architecture: The Three Main Components

The Argo CD control plane consists of three primary components that work in unison to fetch, render, and reconcile Kubernetes manifests.

A. The API Server

The API Server is the entry point for all external interactions with Argo CD. It handles requests from the Web UI, the Argo CD CLI, and external CI/CD orchestrators.

• Protocols: It exposes a REST API (typically used by external tools, web browsers, and webhooks) and a gRPC API (used for high-performance, internal service-to-service communication).
• Responsibilities:
  • Authenticates and authorizes user requests.
  • Enforces Role-Based Access Control (RBAC).
  • Coordinates with internal components to fetch and display application status.

B. The Repository Server

The Repository Server is an internal service responsible for maintaining a local cache of Git repositories containing application manifests.

• Responsibilities:
  • Authenticates with private Git repositories using configured credentials (SSH keys or HTTPS tokens).
  • Fetches the desired state from Git.
  • Manifest Rendering: Translates templated configurations (such as Helm charts, Customize overlays, or Jsonnet files) into plain, raw Kubernetes YAML manifests.
• Security Boundary: The Repository Server never communicates directly with the Kubernetes API server. It only interacts with Git and other internal Argo CD components.

C. The Application Controller (The Heart)

The Application Controller is a Kubernetes controller that continuously monitors the live state of the cluster and compares it against the desired state.

• Responsibilities:
  • Watches Application Custom Resources (CRs).
  • Queries the Repository Server to get the target state (rendered raw YAML).
  • Queries the Kubernetes API Server to get the live state of the resources.
  • Detects configuration drift.
  • Executes reconciliation (applying changes to the cluster to match Git).

5. Architectural Workflow: How State Reconciles

The following workflow illustrates how a change in Git propagates through the Argo CD control plane to update a live application in Kubernetes:

Real-Life Analogy: The Virtual Machine vs. Application Access

Conceptually, think of how administrators access software. If you deploy an application (like SonarQube) on a Virtual Machine (VM), end-users and CI systems access the SonarQube web application directly via their browsers or API calls. They do not need SSH access to the underlying VM.

Similarly, DevOps engineers and CI systems interact with the Argo CD API Server to check deployment status or trigger syncs. They do not need direct kubectl access to the underlying Kubernetes cluster. This minimizes security risks by keeping cluster credentials out of external CI systems.

6. Supporting Components for Enterprise Scale

Beyond the three core services, Argo CD includes supporting components that provide caching, scalability, and enterprise-grade authentication.

7. Hands-On Lab: Environment Prerequisites

To follow along with the installation, ensure your local environment has the following tools installed:

1. Docker Desktop / Docker Engine: Required to run the local Kubernetes cluster via Kind.
2. kubectl: The Kubernetes command-line tool.
3. Helm: The package manager for Kubernetes, used to install Argo CD.
4. Kind (Kubernetes in Docker): A tool for running local Kubernetes clusters using Docker container "nodes".
5. IDE (e.g., Visual Studio Code): For editing YAML manifests and configuration files.

8. Step-by-Step Guide: Creating the Local Kubernetes Cluster

We will use Kind to spin up a lightweight, single-node Kubernetes cluster.

Execute the following command to create a cluster named cloud-with-varun:

kind create cluster --name cloud-with-varun

Expected Output:

Creating cluster "cloud-with-varun" ...
 ✓ Ensuring node image (kindest/node:v1.29.2) 🖼
 ✓ Preparing nodes 📦 
 ✓ Writing configuration 📜 
 ✓ Starting control-plane 🕹️ 
 ✓ Installing CNI 🔌 
 ✓ Installing StorageClass 💾 
Set kubectl context to "kind-cloud-with-varun"
Cluster creation complete!

Verify that your kubectl context is pointing to the newly created cluster:

kubectl cluster-info --context kind-cloud-with-varun

9. Step-by-Step Guide: Installing Argo CD via Helm

We will install Argo CD using its official Helm chart. This ensures a predictable, production-ready, and version-controlled installation.

Step 1: Add the Official Argo Helm Repository

Add the repository to your local Helm configuration:

helm repo add argo https://argoproj.github.io/argo-helm

Step 2: Update the Helm Repository Index

Update your local index to ensure you have access to the latest chart versions:

helm repo update

Step 3: Search for Available Chart Versions

Verify the repository was added successfully and search for the argo-cd chart:

helm search repo argo/argo-cd --versions | head -n 10

Step 4: Create a Dedicated Namespace

Create the argo-cd namespace where all control plane components will reside:

kubectl create namespace argo-cd

Step 5: Install Argo CD

Install Argo CD using Helm. We will explicitly lock the chart version to 9.1.9 to ensure environment predictability.

helm install my-argo-cd argo/argo-cd \
  --version 9.1.9 \
  --namespace argo-cd

10. Verifying the Installation & Understanding the Pods

Once the Helm installation completes, verify that all Argo CD components are up and running.

Check Pod Status

List all pods in the argo-cd namespace:

kubectl get pods -n argo-cd

Expected Output:

NAME                                                    READY   STATUS    RESTARTS   AGE
my-argo-cd-argocd-application-controller-0              1/1     Running   0          2m
my-argo-cd-argocd-applicationset-controller-7f8d...     1/1     Running   0          2m
my-argo-cd-argocd-dex-server-5c4d...                    1/1     Running   0          2m
my-argo-cd-argocd-notifications-controller-6d7c...      1/1     Running   0          2m
my-argo-cd-argocd-redis-84b7...                         1/1     Running   0          2m
my-argo-cd-argocd-repo-server-5f6b...                   1/1     Running   0          2m
my-argo-cd-argocd-server-7c8d...                        1/1     Running   0          2m

Check Services

Verify the Kubernetes services created by the Helm chart:

kubectl get svc -n argo-cd

Identify the API server service, which is named my-argo-cd-argocd-server. This service listens on ports 80 and 443 internally.

11. Accessing the Argo CD UI & Post-Install Configuration

Because we are running a local Kind cluster, the Argo CD API Server is not exposed to the public internet or your local host network. We will use kubectl port-forward to access the UI.

Step 1: Retrieve the Auto-Generated Admin Password

Argo CD generates a secure, random password for the default admin user during installation and stores it in a Kubernetes secret. Retrieve and decode this password:

kubectl -n argo-cd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 --decode

Note: Copy the outputted string carefully. Do not copy any trailing system characters (like %).

Step 2: Establish a Port-Forwarding Tunnel

Forward local port 8080 to the Argo CD API Server's secure port (443):

kubectl port-forward svc/my-argo-cd-argocd-server 8080:443 -n argo-cd

Note: This command runs in the foreground and blocks your terminal window. Keep this terminal open to maintain the connection.

Step 3: Log In to the Web UI

1. Open your web browser and navigate to http://localhost:8080.
2. Your browser will display a security warning because Argo CD uses a self-signed SSL certificate by default. Click Proceed or Advanced -> Proceed to localhost (unsafe).
3. On the login screen:
   • Username: admin
   • Password: [The decrypted password retrieved in Step 1]

Step 4: Change the Admin Password

For security and ease of use, change the default password immediately:

1. Click on the User Info icon in the left-hand sidebar.
2. Click Update Password.
3. Paste the temporary password in the Current Password field.
4. Enter and confirm your new secure password.
5. Click Save New Password.

12. Summary and Key Takeaways

• GitOps is an Operating Model: It is a methodology where Git serves as the single source of truth for declarative infrastructure and applications. Argo CD is a specialized controller that implements this model.
• Kubernetes-Native Architecture: Argo CD runs directly inside your cluster, leveraging Custom Resource Definitions (CRDs) to manage application states natively.
• Decoupled Control Plane: The architecture separates concerns cleanly: the API Server handles external access, the Repository Server manages Git connections and manifest rendering, and the Application Controller executes the reconciliation loop.
• Secure Pull-Based Deployments: By running inside the cluster and pulling configurations from Git, Argo CD eliminates the need to store sensitive cluster credentials inside external CI tools like Jenkins or GitHub Actions.
• Selective Adoption: Organizations can adopt GitOps incrementally, managing some namespaces with Argo CD while leaving others under traditional CI/CD pipelines.
• Production-Ready Installation: Installing Argo CD via Helm with explicit version pinning (9.1.9) ensures configuration consistency and reproducibility across environments.