Posted on March 7, 2024

CNCF projects highlighted in this post

Community post originally published on Medium by Maryam Tavakkoli

This article outlines my hands-on experience with implementing ArgoCD in our project. Drawing from these experiences, I’ve tried to simplify the process of declarative installation and efficient management using the App of Apps approach. I aim to simplify the complexities I have encountered and offer insights that may prove beneficial to others navigating similar challenges. While some of my perspectives are included, they’re not definitive, and I welcome any feedback or insights you may have on the topic.

Concepts and terminologies

GitOps

The definition of GitOps, as outlined by gitops.tech, is as follows:

GitOps is a way of implementing Continuous Deployment for cloud native applications. It focuses on a developer-centric experience when operating infrastructure, by using tools developers are already familiar with, including Git and Continuous Deployment tools.

The core idea of GitOps is having a Git repository that always contains declarative descriptions of the infrastructure currently desired in the production environment and an automated process to make the production environment match the described state in the repository. If you want to deploy a new application or update an existing one, you only need to update the repository – the automated process handles everything else. It’s like having cruise control for managing your applications in production.

GitOps: versioned CI/CD on top of declarative infrastructure. Stop scripting and start shipping.

— Kelsey Hightower

The below quote by Kelsey Hightower highlights the transformative power of GitOps, emphasizing the importance of declarative configuration in managing infrastructure effectively, especially at scale.

Kelsey Hightower posted, "GitOps is the best thing since configuration as code. Git changed how we collaborate, but declarative configuration is the key to dealing with infrastructure at scale, and sets the stage for the next generation of management tools"

ArgoCD

In essence, Argo CD is an open-source, Kubernetes-native continuous delivery tool built around the GitOps methodology.

According to the ArgoCD docs:

Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. Argo CD follows the GitOps pattern of using Git repositories as the source of truth for defining the desired application state. It automates the deployment of the desired application states in the specified target environments.

Kustomize

Kustomize is a tool for customizing Kubernetes object configurations. It allows users to define and manage Kubernetes manifests using a simple and declarative approach, without the need for complex templating or duplication of configurations. With Kustomize, users can efficiently customize Kubernetes resources for different environments, applications, or use cases by applying overlays and patches to base configurations. This enables easier management of Kubernetes deployments and promotes best practices in configuration management.

Helm

Helm is a package manager for Kubernetes that simplifies the process of deploying, managing, and upgrading applications on Kubernetes clusters. It allows users to define and package Kubernetes resources, such as deployments, services, and configurations, into reusable and shareable packages called Helm charts. With Helm, users can easily install and manage complex applications with dependencies, roll back to previous versions, and customize configurations using templating. Helm charts can be distributed and shared through centralized repositories, making it a popular tool for application packaging and deployment in Kubernetes environments.

Installing ArgoCD Declaritively

In this section, we explore various approaches to achieve the goal of declaratively installing ArgoCD. We delve into the pros and cons of each method, empowering you to make an informed decision based on the unique features of each approach.

ArgoCD Autopilot

From ArgoCD Autopilot documentation:

The autopilot bootstrap command will deploy an Argo CD manifest to a target K8s cluster and will commit an Argo CD Application manifest under a specific directory in your GitOps repository. This Application will manage the Argo CD installation itself – so after running this command, you will have an Argo CD deployment that manages itself through GitOps.

Diagram flow of ArgoCD Autopilot — https://argocd-autopilot.readthedocs.io/en/stable/

Installation and usage guidelines

Below is the installation command for macOS, and you can explore other installation methods in the Autopilot documentation.

brew install argocd-autopilot

Then, you need to export your Git access token and your Git repository URL as below:

export GIT_TOKEN=ghp_PcZ...IP0
export GIT_REPO=https://github.com/owner/name

The last step is to execute the bootstrap command on the cluster where you intend to install ArgoCD (cluster context access is required):

argocd-autopilot repo bootstrap

Pros and Cons

Pros

Installation and usage are straightforward and quick.
With this approach, ArgoCD is automatically managed by itself, enabling GitOps to make changes to the ArgoCD installation in the future.

Cons

When initially adding applications to be managed by ArgoCD, interaction with Autopilot via the command line (and access to the cluster context) is required, which lacks declarative capabilities. You need to run such command:

argocd-autopilot app create workflows --app "github.com/argoproj/argo-workflows/manifests/cluster-install?ref=v3.0.7" --project prod

As of the time of writing, the Autopilot project is still in version v0.4.17, with a limited number of contributors, potentially impacting its suitability for production use cases.
Autopilot automatically defines the repository structure and installs three different ArgoCD apps initially, which may not align with your project structure preferences.

ArgoCD Helm Chart

The ArgoCD Helm chart, a community-maintained chart, is a pre-configured package that simplifies deploying and managing ArgoCD on Kubernetes using Helm. It includes all the necessary configurations and resources for setting up ArgoCD within a Kubernetes cluster.

Installation and usage guidelines

Here’s the Helm chart installation setup using a Kustomization file. Note that the argocd namespace must be created in advance and referenced in the Kustomization file.

## namespace.yaml
#### ArgoCD Namespace ####
apiVersion: v1
kind: Namespace
metadata:
  name: argocd

## kustomization.yaml
#### ArgoCD Helm Chart####
namespace: argocd
helmCharts:
- name: argo-cd
  repo: <https://argoproj.github.io/argo-helm>
  version: 5.53.5
  releaseName: argocd
  namespace: argocd
  valuesFile: base/values.yaml

resources:
- base/namespace.yaml         # ArgoCD Namespace

Also, note that to install the Helm chart using Kustomize, you’ll need to add the following configuration to your values.yaml file for the chart:

server:
  config:
    kustomize.buildOptions: --enable-helm

To install the chart, execute the following command in the directory containing the kustomization.yaml file:

kubectl kustomize --enable-helm | kubectl apply -f -

Pros and Cons

Pros

Installation is straightforward.
The Helm chart project is currently at version 6.2.3 and boasts a large community of over 500 contributors. This makes it a reliable choice for production-grade deployments, ensuring stability and ongoing support.
Using the concept of an App of Apps, you can utilize ArgoCD Application to manage ArgoCD itself. With Kustomize, you can handle the installation of the ArgoCD Helm chart and manage both ArgoCD and your other applications simultaneously. This architecture requires one-time access to the cluster context and command-line initially. After the setup, you can manage everything declaratively using a GitOps approach.

Cons

Management of ArgoCD with ArgoCD is not included in the helm chart installation process and should be handled as a separate task.

ArgoCD CLI

The ArgoCD Command-Line Interface (CLI) is a powerful tool that enables you to interact with ArgoCD from your terminal. With the ArgoCD CLI, you can perform various tasks such as managing applications, syncing resources, and accessing detailed information about your deployments.

You can easily install it on MacOS using the command below. For more detailed installation instructions, refer to the CLI installation documentation.

brew install argocd

ArgoCD UI

The Initial Login (via CLI)

This part is based on ArgoCD documentation:

The initial password for the admin account is auto-generated and stored as clear text in the field password in a secret named argocd-initial-admin-secret in your Argo CD installation namespace. You can simply retrieve this password using the argocd CLI:

argocd admin initial-password -n argocd

Using the username admin and the password from above, login to Argo CD’s IP or hostname:

argocd login <ARGOCD_SERVER>

One initial login using CLI is required to change the default password. To get the default password, run:

argocd admin initial-password -n argocd

Do a login and change the password

argocd login <ARGOCD_SERVER>
argocd account update-password

ArgoCD UI via Ingress

You can find ArgoCD documentation for Ingress here.

When installing ArgoCD with the Helm chart, simply configure the required ingress settings in the values.yaml file of your chart.

## values.yaml
#### ArgoCD Helm Chart values ####
server:
  ingress:
    enabled: true
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt-production
      ingress.kubernetes.io/force-ssl-redirect: "true"
      nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
    ingressClassName: "nginx" 
    hosts:
      - argocd.somehost.com # To be changed according to the cluster
    paths:
      - /
    pathType: Prefix
    tls:
      - secretName: argocd-tls-certificate
        hosts:
          - argocd.somehost.com # To be changed according to the cluster
  config:
    kustomize.buildOptions: --enable-helm

Once configured, you can access the UI using the admin username and password you set.

Register Github Repository

To grant ArgoCD access to your repository, you must register the repository using a Git access token.

For instance, if you’re using GitHub, generate a Personal Access Token (PAT) in GitHub and add the repository in the Registries section within the ArgoCD UI.

To achieve this declaratively, create a Kubernetes secret as follows, ensuring it has the correct label argocd.argoproj.io/secret-type: repository.

## repository-registration.yaml
#### Repository Registration for ArgoCD ####
 apiVersion: v1
 kind: Secret
 metadata:
   name: private-repo
   namespace: argocd
   labels:
     argocd.argoproj.io/secret-type: repository
 stringData:
   type: git
   url: hhttps://github.com/MaryamTavakkoli/argocd.git
   password: <PASSWORD> # Equivalents to the PAT 
   username: "admin"

If you opt for a secret management solution like the External Secret Operator for a more robust and production-ready approach, you can securely store your access key in an Azure Key Vault, for instance, and access it via ESO as follows:

## repository-registration.yaml
#### Repository Registration for ArgoCD ####
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: argocd-configuration-repo-token
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: cluster-secret-store
  target:
    name: argocd-configuration-repo-token
    creationPolicy: Owner
    template:
      data:
        type: git
        url: <https://github.com/MaryamTavakkoli/argocd.git>
        username: "admin"
        password: "{{ .password }}"
  data:
  - secretKey: password
    remoteRef:
      key: github-personal-access-token # Name of AKV secret for password

Next, include the name of this application manifest in the list of resources within the initial Kustomization file (kustomization.yaml) previously described.

Core ArgoCD Concepts

In this section, we’ll delve into the fundamental concepts of ArgoCD. These concepts are essential to understand for effectively managing and deploying applications in ArgoCD.

Application

An Application in ArgoCD represents a Kubernetes manifest that is managed and deployed by ArgoCD. It defines the desired state of the application, including the source of the application manifests, the destination cluster where it should be deployed, and various synchronization policies.

Source

The Source in ArgoCD specifies the location where the application manifests are stored. This can be a Git repository, a Helm repository, or a directory in the local file system. ArgoCD continuously monitors the source for changes and automatically syncs the application state accordingly.

Destination

The Destination defines the target Kubernetes cluster where the application should be deployed. It includes details such as the cluster’s API server URL, authentication credentials, and namespace where the application should reside.

ApplicationSet

ApplicationSet is a higher-level abstraction in ArgoCD that allows you to define and manage multiple applications based on a template. It enables you to dynamically generate and manage multiple instances of similar applications using a set of parameters.

SyncPolicy

SyncPolicy determines how ArgoCD synchronizes the desired state of the application with its actual state in the target cluster. It includes parameters such as the sync frequency, the strategy for handling conflicts, and hooks to execute before and after synchronization operations.

Managing ArgoCD with ArgoCD (The App of Apps Pattern)

When using the Helm chart to install ArgoCD, there’s no built-in automation for managing ArgoCD with ArgoCD itself. This means that any changes to the ArgoCD installation require updates to the Git repository and manual deployment. However, by adopting a GitOps approach and managing the ArgoCD Helm chart with ArgoCD, we can streamline this process.

To achieve this and minimize manual command-line operations, we can leverage the concept of “App of Apps,” as described in the ArgoCD documentation:

You can create an app that creates other apps, which in turn can create other apps. This allows you to declaratively manage a group of apps that can be deployed and configured in concert.

To this goal, you’ll need an application definition**,** for ArgoCD, outlined in the application-argocd.yaml below:

## application-argocd.yaml
#### Managing Argo with Argo (App of Apps concept) using ArgoCD Application definition ####
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: argo-cd
spec:
  project: default
  sources:
    - repoURL: <https://github.com/MaryamTavakkoli/argocd.git>
      targetRevision: main
      path: environments/env1/argo-cd 
  destination:
    server: <https://kubernetes.default.svc>
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - Prune=false