A Practical Guide to Argo CD Part 1: Introduction and Core Concepts

[#1]

Introduction

Modern Kubernetes environments can become difficult to manage as applications, infrastructure, and configuration changes grow in complexity. Teams need a reliable way to deploy changes consistently, track configuration history, and reduce manual operations across clusters and environments.

This is the first of a series of articles covering multiple topics around ArgoCD, one of the most widely adopted CI/CD tools that help site administrators with managing the lifecycle of their (Kubernetes-based) application landscape.

The goal here is to give you a solid feel for how Argo CD works on Kubernetes and how you can put it to use - especially if you’re looking to automate SAS Viya deployments. That said, a lot of what we cover isn’t specific to SAS Viya and applies more broadly.

Here’s what we’ve got lined up for this blog series:

• In this first post, we’ll walk through the basics of Argo CD - what it is, how it’s put together, and the core ideas behind it. We’ll also spend some time on how Argo CD fits into Red Hat OpenShift, since the integration there is especially tight and worth a closer look. If OpenShift isn’t your platform, feel free to skim that part.
• In the next post, we’ll get more hands-on and show how Argo CD can be used to deploy SAS Viya in a granular way, with a clear split between cluster administrator and SAS Viya administrator responsibilities.
• In the final post, we’ll dig into a few details that can make life a lot easier in practice. That includes using kustomize as a custom tool in Argo CD, keeping unwanted objects out of sync, and using the External Secrets Operator to keep sensitive data out of your Git repository.

So, without further ado, let’s get started.

From GitOps to Argo CD is a CI/CD framework that addresses these challenges by using Git as the single source of truth for both application and infrastructure configuration. Instead of applying changes manually to a cluster, cluster administrators and namespace administrators define desired system state in Git repositories. Automated tools continuously monitor those repositories and reconcile the cluster to match the declared configuration.

One of the most widely adopted GitOps tools for Kubernetes is Argo CD. ArgoCD continuously synchronizes Kubernetes manifests from Git into a cluster, providing automated deployments, difference detection, rollback capabilities, and a clear view of application state.

ArgoCD is available across nearly all Kubernetes distributions. The simplest way to install ArgoCD on most Kubernetes distributions is through its official Helm chart, available in the argo-helm repository. Some cloud-based Kubernetes distribution may install ArgoCD as an add-on service. For example, on Amazon EKS clusters, ArgoCD can be deployed as an add-on, as described in the create-argocd-capability guide.

In OpenShift, ArgoCD is integrated directly into the OpenShift platform through the OpenShift GitOps operator. This allows organizations to streamline GitOps workflows in a stable and repeatable way while leveraging native OpenShift capabilities.

OpenShift GitOps Architecture Overview

Red Hat OpenShift GitOps can be installed directly from the OpenShift’s Software Catalog service to a specific namespace as shown in the figure below.

After the operator is installed, several GitOps components are automatically deployed, as shown in the figure below.

At a high level, the GitOps workflow is divided into two layers:

• Operator Layer — Installs and manages ArgoCD itself
• ArgoCD Layer — Manages application deployments using the GitOps model

The operator continuously watches ArgoCD custom resources and ensures a fully functional ArgoCD environment is deployed and maintained.

Together, these two layers consist of the following workflows:

1 - Operator installs and registers ArgoCD CRDs

The OpenShift GitOps Operator is typically installed in the openshift-gitops-operator namespace and starts the openshift-gitops-operator-controller-manager.
It then begins to register custom-resource-definitions (CRDs) specific to ArgoCD, including:

• ArgoCD
• Application
• AppProject
• ApplicationSet

These CRDs define the schema and API for GitOps resources.

2 - Operator creates supporting components

The operator deploys supporting components into the openshift-gitops namespace:

• gitops-cluster: Provides ArgoCD cluster reconciling
• gitops-plugin: Provides GitOps plugin within OpenShift UI Console

These components act as a support mechanism to the OpenShift GitOps operator and are not part of core ArgoCD stack used during CI/CD deployments.

3 - Creation of an ArgoCD Custom Resource Instance

A user creates an ArgoCD CR instance within a target namespace, such as viyagitops. The resource can be created either through the OpenShift console or by applying a YAML manifest with kind: ArgoCD.

4 - Operator Reconciles the ArgoCD Custom Resource Instance

The operator continuously monitors for ArgoCD resources and reconciles them once updates are detected. Once the operator detects a new ArgoCD CR instance has been created in a target namespace, it reconciles, deploys, and maintains all required ArgoCD components in that target namespace.

The components created by the OpenShift GitOps operator are specific to ArgoCD itself. While OpenShift provides a supported packaging and deployment mechanism, these same core components are standard to ArgoCD and will also exist across other Kubernetes distributions where ArgoCD is installed independently of OpenShift.

In OpenShift GitOps, these resources follow a reconciliation loop where the OpenShift GitOps Operator ensures that the actual GitOps cluster state matches the desired state defined by the ArgoCD CR.

The following components are created:

StatefulSet: Application Controller

• Watches Application custom-resources (CRs).
• Compares desired state from a connected Git repo with live cluster state.
• Performs sync operations to update live state to match with desired state.

Deployment: Repo Server

• Pulls manifests from Git repos.

Deployment: ArgoCD server

• Hosts the web UI and REST API endpoints for the ArgoCD instance.
• Acts as a primary interface for users.

Deployment: ApplicationSet Controller

• Dynamically and automatically generates Application resources from a single Kubernetes source.
• Manages multiple ArgoCD applications.

Deployment: Dex Server

• Handles authentication using OIDC.
• Integrates with OpenShift authentication for OpenShift user access into the ArgoCD UI.

Deployment: Redis

• Provides caching for ArgoCD sessions

Service Account: Application Controller

• Provides ArgoCD with the permissions required to deploy and manage Kubernetes resources on behalf of the user based on manifests stored in a Git repository.
• Each ArgoCD instance is assigned a service account used to deploy resources from Git repositories. Cluster administrators can configure an ArgoCD instance with cluster-wide administrative privileges, while developers or namespace administrators can be provided separate ArgoCD instances that operate with namespace-scoped or least-privilege permissions.

5 - ArgoCD UI

Once the ArgoCD components have been installed and an ArgoCD instance is created in a target namespace, an ingress or route object will be created to expose the external ArgoCD console for user access.

The ArgoCD console provides UI access to users for creating ArgoCD applications, connecting a Git Repo, and much more.

Core ArgoCD Components

Once Argo CD resources are installed—whether through GitOps or via the official Helm chart on other Kubernetes distributions—users can begin interacting with ArgoCD and building GitOps workflows to manage Kubernetes manifests directly from Git repositories.

ArgoCD uses several core custom resources to organize and manage deployments:

ArgoCD Instance:

An ArgoCD instance is a user-defined custom resource (CR) created within a specific namespace. It serves as the entry point that triggers the deployment and ongoing management of the core components listed below.

• Application Controller StatefulSet
• ApplicationSet Deployment
• Server Deployment
• Repo Server Deployment
• Redis Deployment
• Dex Server Deployment
• Application Controller Service Account

The ArgoCD instance CR can be created in several ways. It may be provisioned automatically when installing Argo CD via its official Helm chart, created through the OpenShift Console when using OpenShift GitOps, or defined manually using a YAML manifest. Multiple instances can also be deployed across different namespaces to support separation of environments or responsibilities.

A common example of an ArgoCD CR defined in YAML looks like the following:

apiVersion: argoproj.io/v1beta1
kind: ArgoCD
metadata:
  name: my-argo-instance
  namespace: viyagitops
spec:
  ha:
    enabled: false
    resources:
      limits:
        cpu: 500m
        memory: 256Mi
...

The ArgoCD CR is summarized in the figure below:

Application and ApplicationSet

Both Application and ApplicationSet custom resources (CRs) can be created using YAML manifests, while Applications can also be created through the ArgoCD UI. These resources reside within a certain namespace and can be configured to deploy workloads to a specific target namespace using the destination: field in their manifests.

An ArgoCD Application defines a deployment managed through GitOps. It specifies the Git repository, target cluster and namespace, and the manifests to deploy. ArgoCD continuously reconciles the running cluster state with the desired state stored in Git.

An ApplicationSet automatically generates and manages multiple ArgoCD Applications from a template. It is commonly used for multi-cluster or multi-environment deployments where many similar Applications must be managed dynamically.

Application CR

The following YAML example defines an Application CR named viya-dev-app, which resides in the gitops namespace and is configured to deploy resources into the viya-dev namespace. The Application references a Git repository as its source of truth and targets the repo/overlays/dev directory within that repository. This allows ArgoCD to deploy only the Kubernetes manifests defined in that specific directory, such as Deployments, StatefulSets, and other resources to the viya-dev namespace.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: viya-dev-app
  namespace: gitops
spec:
  destination:
    namespace: viya-dev
    server: 'https://kubernetes.default.svc'
  project: default
  source:
    path: repo/overlays/dev
    repoURL: 'https://github.com/example/repo.git'
    targetRevision: HEAD
...

ApplicationSet CR

Instead of creating a separate Application CR for every new environment and namespace, we can define an ApplicationSet CR to be used to manage deployments across multiple consistent environments. The ApplicationSet will dynamically generate and manage individual Applications for each target environment, simplifying large-scale and multi-environment GitOps workflows.

Using the built-in templating and generator capabilities of Argo CD ApplicationSets, we can configure a single ApplicationSet to create separate Applications for each SAS Viya environment (dev, test, and prod) each deployed into its respective namespace.

The Applications generated by the ApplicationSet reside in the gitops namespace but target the corresponding viya-dev, viya-test, and viya-prod namespaces. Each environment maps to its respective Git structure, such as overlays/dev, overlays/test, and overlays/prod within the Git repository.

In the example below, the template variables {{env}} and {{namespace}} are defined in the list generator under spec.generators. Each element in the list provides the values that are substituted into the Application template when the corresponding Application is generated.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: viya-applicationSet
  namespace: gitops
spec:
  generators:
    - list:
        elements:
          - env: dev
            namespace: viya-dev
          - env: test
            namespace: viya-test
          - env: prod
            namespace: viya-prod
 
  template:
    metadata:
      name: 'viya-{{env}}'
    spec:
      project: default
      source:
        repoURL: 'https://github.com/example/repo.git'
        targetRevision: HEAD
        path: overlays/{{env}}
 
      destination:
        server: 'https://kubernetes.default.svc'
        namespace: '{{namespace}}'
...

The below figure illustrates the relationship between ArgoCD Applications and ApplicationSets:

Project

An ArgoCD Project provides organization and access control for Applications. Projects define which repositories, clusters, namespaces, and resources Applications are allowed to use, helping enforce governance and administrative boundaries.

Projects are explicitly referenced in either an Application or ApplicationSet CRs allowing deployments to be scoped to a defined security and governance boundary.

By default, ArgoCD includes a built-in project called default, which can be used for basic deployments or replaced with custom projects for more controlled and secure access patterns.

Conclusion

With that, we’ve covered the foundations: what GitOps is, where Argo CD fits in, and the core building blocks behind it. In Part 2, we’ll build on that and show how to use Argo CD for a granular SAS Viya deployment model with clearly separated responsibilities.

Stay tuned!