Master Argo CD: A Hands‑On Guide to GitOps Continuous Delivery

Argo CD Introduction and Practical Guide

1. Argo CD Overview

1.1 What is Argo CD

Argo CD is a declarative GitOps continuous delivery tool for Kubernetes.

1.2 Why Choose Argo CD

Application definitions, configurations and environments should be declarative and version‑controlled. Deployment and lifecycle management should be automated, auditable and easy to understand.

2. Argo CD Basics

Before using Argo CD effectively, you need to understand the underlying technologies such as Git, Docker, Kubernetes, continuous delivery and GitOps concepts. The following links are useful for deepening this understanding.

2.1 Learning Basics

Read online Docker and Kubernetes tutorials: introductory containers, virtual machines and Docker for beginners.

Depending on how you template your applications: Kustomize, Helm.

If you integrate with CI tools: GitHub Actions documentation, Jenkins user guide.

3. Core Concepts of Argo CD

By now you should be familiar with core Git, Docker, Kubernetes, continuous delivery and GitOps concepts. The following are specific to Argo CD.

Application : a set of Kubernetes resources defined by a manifest (a CRD).

Application source type : the tool used to build the application.

Target state : the desired state of the application, represented by files in the Git repository.

Live state : the current state of the application (which pods are deployed, etc.).

Sync status : whether the live state matches the target state.

Refresh : compares the latest code in Git with the live state to find differences.

Health : whether the application is running normally and can handle requests.

Tool : a tool that creates manifests from a directory, e.g., Kustomize.

Configuration management tool and plugin : custom tools.

4. Architecture

4.1 Architecture Overview

Argo CD is implemented as a Kubernetes controller that continuously monitors running applications and compares the live state with the desired target state defined in a Git repository. When a deviation is detected, it is reported as OutOfSync and can be visualized and automatically or manually synchronized.

4.2.1 API Server

The API server is a gRPC/REST server that exposes the Web UI, CLI and CI/CD APIs. Responsibilities include application management and status reporting, invoking application operations (sync, rollback, custom actions), storing repository and cluster credentials, delegating authentication and authorization, RBAC enforcement, and listening for Git webhook events.

4.2.2 Repository Server

The repository server caches Git repositories that store application manifests and generates Kubernetes manifests from repository URL, revision, application path, and template‑specific settings (parameters, Helm values).

4.2.3 Application Controller

The application controller is a Kubernetes controller that continuously monitors applications, compares the live state with the target state, detects OutOfSync status and optionally takes corrective actions, including invoking lifecycle hooks (PreSync, Sync, PostSync).

4.3 How It Works

Argo CD follows the GitOps model, using a Git repository as the source of truth for the desired application state. Kubernetes manifests can be supplied via custom application deployment, Helm charts, Jsonnet files, plain directories of YAML/JSON, or any custom configuration management tool.

5. Getting Started with Argo CD

5.1 Requirements

kubectl command‑line tool installed.

A kubeconfig file (default location ~/.kube/config).

CoreDNS plugin installed.

5.2 Install Argo CD

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

This creates a new argocd namespace where Argo CD services and resources are stored.

Note: The installation includes a ClusterRoleBinding that references the argocd namespace. If you install Argo CD in a different namespace, update the namespace references accordingly.

The default installation uses a self‑signed certificate, which is not accessible without additional steps. Choose one of the following:

Configure the certificate as described in the documentation.

Configure the client OS to trust the self‑signed certificate.

Use the --insecure flag for all Argo CD CLI commands in this guide.

Note: The default argocd-redis installation uses password authentication. The password is stored in a secret named argocd-initial-admin-secret in the installation namespace.

5.3 Access the Argo CD API Server

By default the API server is not exposed via an external IP. Expose it by one of the following:

Patch the argocd-server service to type LoadBalancer:

kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'

Configure an Ingress (see Argo CD ingress documentation).

Port‑forward the service:

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

Then access the UI at https://localhost:8080.

5.4 CLI Login

The initial admin password is stored in the secret argocd-initial-admin-secret. Retrieve it with: argocd admin initial-password -n argocd Log in with: argocd login <ARGOCD_SERVER> If the CLI cannot reach the API server directly, use port‑forwarding flags or set the ARGOCD_OPTS environment variable.

5.5 Register a Cluster (optional)

Register cluster credentials with Argo CD when deploying to an external cluster:

kubectl config get-contexts -o name
argocd cluster add <CONTEXTNAME>

This installs a service account argocd-manager in the kube-system namespace of the target context and binds it to a cluster‑admin role.

5.6 Create an Application from a Git Repository

Set the current namespace to argocd:

kubectl config set-context --current --namespace=argocd

Create the example guestbook application:

argocd app create guestbook \
  --repo https://github.com/argoproj/argocd-example-apps.git \
  --path guestbook \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

Alternatively, create the application via the UI.

5.7 Sync the Application

Check the application status: argocd app get guestbook The initial status is OutOfSync. Sync (deploy) the application with: argocd app sync guestbook The command applies the manifests to the cluster, creates the service and deployment, and updates the status to Synced and Progressing. Verify the pods:

kubectl get pods -n default