GitOps with ArgoCD: A Practical Guide

What Is Argo CD?

Argo CD is a Kubernetes-native continuous deployment tool. It automates the deployment of applications by monitoring Git repositories. As a part of the Argo project, it supports GitOps practices, allowing Kubernetes clusters to be managed using Git as the source of truth. This approach reduces manual configuration, improves consistency, and ensures repeatability. 

Argo CD tracks Git changes and ensures that applications within the clusters reflect these updates. It supports a declarative way to handle application management, enabling multiple configurations. It automatically syncs changes in the Git repository to the cluster, providing a real-time preview of the app’s current state versus its desired state. 

With a focus on security and stability, Argo CD supports safe continuous integration and deployment processes, enabling developers to control configurations thoroughly and securely.

Why Use Argo CD for GitOps? 

Argo CD provides an interface for implementing GitOps workflows. It ensures that changes are tracked and deployed reliably across various clusters through Git integrations. By treating Git as the control plane, Argo CD delivers a method for handling updates, rollbacks, and validation of resource sync status. 

This Git-centric model leads to enhanced traceability and auditability, helping enterprises in maintaining compliance standards. GitOps with Argo CD also delivers benefits regarding collaboration and productivity. Teams can work more effectively with access to a unified history of changes within their applications. 

Developers and operators increase agility, experimentations, and iterative improvements while reducing configuration drift. As a result, organizations achieve faster deployment cycles and higher reliability in continuous delivery pipelines.

Core Concepts of Argo CD 

These core concepts enable Argo CD to deliver a consistent, automated, and secure approach to application deployment in Kubernetes, aligned with GitOps principles:

1. Applications

In Argo CD, an “application” is a defined set of Kubernetes resources representing an instance of a service or application. Applications are created and managed declaratively, with each application’s desired state stored in a Git repository. Argo CD continuously monitors these applications and ensures that their live state on the cluster matches the desired state defined in Git.

2. Repositories

Repositories are the source of truth for Argo CD and contain the declarative configurations for applications. Argo CD supports various repository types, including Git, Helm, Kustomize, and custom configuration management tools. These repositories are regularly scanned to detect changes, which are then applied to ensure synchronization between the repository’s desired state and the live cluster state.

3. Sync

Sync is the process Argo CD uses to apply changes from a Git repository to the Kubernetes cluster. The sync process can be triggered automatically or manually, depending on configuration. If the live state of an application differs from its desired state, Argo CD flags this as “out of sync.” Sync policies allow teams to define how and when updates are deployed, with options for automated sync or manual intervention for production environments.

4. Sync Status and Health Status

Argo CD tracks both the sync status and health status of each application. Sync status indicates whether the application’s live state matches its desired state, while health status reflects the operational health of resources (e.g., “Healthy,” “Degraded,” “Progressing”). Together, these statuses give operators a view of an application’s deployment health and operational readiness.

5. Rollback

Rollback in Argo CD allows for reverting an application to a previous known-good state. This is crucial for error recovery and experimentation, as it provides a safety net if new deployments introduce issues. Rollbacks use the Git history as a reference, making it easy to revert changes while maintaining full version traceability.

6. Access Control and RBAC

Argo CD includes role-based access control (RBAC) to ensure that only authorized users can make changes to applications and clusters. This feature is especially important in multi-team environments, where permissions and access levels can be configured based on team roles, improving security and reducing the risk of unauthorized modifications.

Related content: Read our guide to configuration as code

Tips From the Expert

In my experience, here are tips that can help you better utilize Argo CD for GitOps:

1. Automate Git repository health checks: Set up automated health checks to validate that Git repositories are accessible and up-to-date before each sync. By running these checks, you can identify potential issues—like authentication errors or outdated configurations—before they impact deployments.
2. Use Argo CD ApplicationSets for multi-cluster management: Leverage ApplicationSets to deploy applications across multiple clusters. This feature enables you to define a single source configuration that can be applied across environments, making it simpler to manage and scale across clusters while reducing configuration drift.
3. Integrate CI/CD pipelines with GitOps workflows: Connect CI/CD pipelines with Argo CD by using webhooks to trigger syncs based on pipeline events. This keeps your deployments aligned with testing and build processes, improving reliability by ensuring only validated changes reach production environments.
4. Define custom health checks for application readiness: For custom applications, configure health assessments in Argo CD using custom health checks to ensure deployments meet your unique criteria before marking them as “Healthy.” This is especially helpful for microservices with specific initialization requirements.
5. Set up Slack or email alerts for sync and health events: Configure notifications to send alerts on sync status changes or health degradations via Slack or email. Real-time notifications help teams respond quickly to potential issues, minimizing downtime and enabling fast resolution in production environments.

Ran Cohen

CTO & Co-Founder, Configu

Before co-founding Configu, Ran was a full stack developer at Testim.io and previously served in an elite cybersecurity unit in the Israeli Defense Forces.

Getting Started with Argo CD 

To set up Argo CD and start deploying applications, you need to follow several key steps. Below is a guide to installing Argo CD, configuring access, and deploying a sample application.

1. Prerequisites

To use Argo CD, ensure the following are in place:

• kubectl command-line tool installed

• kubeconfig file configured (default location: ~/.kube/config)

• CoreDNS enabled (for microk8s, run: microk8s enable dns && microk8s stop && microk8s start)

2. Installing Argo CD

To install Argo CD in your Kubernetes cluster, create a namespace named argocd and then apply the Argo CD installation manifest:

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

This creates all necessary Argo CD resources within the argocd namespace, including the core components for managing deployments. If installing in a different namespace, remember to update any namespace references in your configuration.

3. Downloading the Argo CD CLI

Download the Argo CD CLI for managing Argo CD applications from the command line. The CLI is available for multiple operating systems:

# For Mac, Linux, or WSL using Homebrew
brew install argocd

Alternatively, download the latest release directly from Argo CD GitHub releases.

Verify the installation using this command:

argocd version

4. Accessing the Argo CD API Server

The Argo CD API server is not exposed by default. To access it, choose one of the following methods:

1. LoadBalancer: Set the argocd-server service type to LoadBalancer to expose it with an external IP.

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

2. Port Forwarding: Forward a local port to the Argo CD API server port.

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

After setting up access, use https://localhost:8080 to access the Argo CD API server locally using a web browser.

5. Logging in Using the CLI

To log into Argo CD with the CLI:

1. Retrieve the initial password for the admin account from the argocd-initial-admin-secret:

argocd admin initial-password -n argocd

2. With this password, log in to the Argo CD server:

argocd login 

Note: Delete the argocd-initial-admin-secret after changing the password for security purposes.

6. Registering a Cluster (Optional)

Register an external cluster (if deploying outside the current cluster):

1. List available contexts:

kubectl config get-contexts -o name

2. Register a context with Argo CD:

argocd cluster add 

This command creates a service account, argocd-manager, with permissions for deployment management.

7. Creating an Application

To create an application in Argo CD, use a Git repository as the source. For example, to create a “guestbook” application from Argo CD’s example repository:

# Set current namespace to 'argocd'
kubectl config set-context --current --namespace=argocd

# Create an application from the example repository
argocd app create guestbook \
  --repo https://github.com/argoproj/argocd-example-apps.git \
  --path guestbook \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace default

You can also create applications through the Argo CD UI. Log in via the external IP or hostname, click + New App, and specify the Git repository, target cluster, and namespace.

8. Syncing (Deploying) the Application

After creating the application, it starts in an OutOfSync state. To sync the application to the cluster, run:

argocd app sync guestbook

This command retrieves the manifests from the repository and applies them, deploying the guestbook application to the cluster.

Alternatively, use the Argo CD UI to sync by clicking the Sync button on the application’s dashboard.

Best Practices for Using Argo CD for GitOps 

Here are some of the best practices to keep in mind when implementing GitOps with Argo CD.

Use Declarative Configuration

Declarative configuration with Argo CD provides a clear and consistent approach to defining and managing application states within a GitOps workflow. With declarative configuration, the entire setup of an application, including Kubernetes resources, environment variables, and dependencies, is explicitly defined in configuration files (often YAML). 

This approach enables Argo CD to compare the current live state of the application in the Kubernetes cluster with the desired state recorded in the Git repository, automatically identifying and flagging discrepancies. It simplifies troubleshooting and rollback since any changes to the application configuration can be versioned, allowing teams to track changes. 

Structure the Repositories Strategically

A well-organized repository structure promotes clear separation between environments (e.g., development, staging, production) and teams, enabling each group to manage configurations relevant to their needs without overlap. This can be combined with branching strategies within repositories to allow for systematic promotion of changes across environments.

For example, some teams may choose a monorepo setup, which keeps all resources in one repository with distinct folders for each application or environment. This can simplify dependency management and CI/CD pipelines for small projects or tightly coupled applications.

In larger organizations or complex projects, a multi-repo approach may be more effective, allowing distinct repositories per environment or team. For example, separate repositories for each environment prevent accidental deployments from propagating through production, and dedicated application repositories give teams control over their respective configurations.

Leverage Sync Strategies and Hooks

Argo CD’s sync strategies allow teams to automate updates in development environments, which speeds up testing and iteration cycles, while using manual syncs for production ensures that updates are controlled and only applied after thorough review and validation. This helps maintain stability in high-stakes environments while allowing rapid changes in development.

Argo CD sync hooks further increase control by allowing teams to define custom actions before and after sync events. Pre-sync hooks can be used for tasks like database migrations, checking the availability of external dependencies, or putting applications in maintenance mode. Post-sync hooks can handle cleanup actions, validation tests, and health checks. 

Implement Resource Pruning Carefully

Argo CD’s resource pruning feature automatically removes Kubernetes resources that are no longer defined in the Git repository, preventing orphaned resources from cluttering the cluster. While pruning helps maintain a clean and manageable environment, it should be used cautiously, especially in production environments. 

Improper pruning configurations can accidentally delete critical resources, impacting system functionality and stability. In scenarios where pruning is necessary, applying it selectively based on labels or resource types can help avoid unintended deletions. For example, critical resources like databases or network configurations can be excluded from pruning rules.

Adopt Progressive Delivery Strategies

Progressive delivery techniques such as blue-green deployments and canary releases aid in minimizing risk when deploying changes, especially in production. With blue-green deployments, two identical environments are maintained, allowing teams to switch traffic seamlessly from the old version to the new version once the update is confirmed to be stable. 

Canary releases, which gradually direct a portion of traffic to the updated version, allow for incremental testing in a real-world environment, giving teams more control and visibility over potential impacts. These strategies reduce downtime and allow for quick rollback if issues are detected. 

Related content: Read our guide to GitOps tools

Supporting GitOps with Configuration Management

Configu is a configuration management platform that streamlines and automates config management, making it better suited for GitOps processes. You can think of Configu as Git for configurations. It’s comprised of two main components:

Configu Orchestrator

As applications become more dynamic and distributed in microservices architectures, configurations are getting more fragmented. They are saved as raw text that is spread across multiple stores, databases, files, git repositories, and third-party tools (a typical company will have five to ten different stores).

The Configu Orchestrator, which is open-source software, is a powerful standalone tool designed to address this challenge by providing configuration orchestration along with Configuration-as-Code (CaC) approach.

Configu Cloud

Configu Cloud is the most innovative store purpose-built for configurations, including environment variables, secrets, and feature flags. It is built based on the Configu configuration-as-code (CaC) approach and can model configurations and wrap them with unique layers, providing collaboration capabilities, visibility into configuration workflows, and security and compliance standardization.

Unlike legacy tools, which treat configurations as unstructured data or key-value pairs, Configu is leading the way with a Configuration-as-Code approach. By modeling configurations, they are treated as first-class citizens in the developers’ code. This makes our solution more robust and reliable and also enables Configu to provide more capabilities, such as visualization, a testing framework, and security abilities.

Learn more about Configu