Argo CD: Up and Running

Chapter 1. Installing Argo CD

A Note for Early Release Readers

With Early Release ebooks, you get books in their earliest form—the author’s raw and unedited content as they write—so you can take advantage of these technologies long before the official release of these titles.

This will be the 2nd chapter of the final book

If you have comments about how we might improve the content and/or examples in this book, or if you notice missing material within this chapter, please reach out to the editor at [e-mail].

Like most cloud native applications, Argo CD features a microservices architecture that comprises multiple components and technologies. Each Argo CD component, working together, helps support a fault tolerant and robust system that helps enable the full set of features and capabilities. Understanding how all of these services work together in concert helps provide a greater awareness of the architecture, their significance, as well as how they are incorporated into the overall system as a whole. This chapter introduces the architecture and design of Argo CD along with detailing the various ways that it can be installed to a Kubernetes environment.

Argo CD Architecture

Since Argo CD is a GitOps based solution designed for Kubernetes, the architecture emphasizes the use of as many Kubernetes primitives as possible. As introduced in Chapter 1, Argo CD sources content stored in repositories and realizes those configurations within a Kubernetes cluster. But, what does that look like and what are the components involved?

Kubernetes Controller Pattern

One of the key benefits of using Argo CD aside from the capability to define Kubernetes resources within source repositories and applying them to a cluster is that Argo CD can be configured to enforce those configurations to stay in place, even if they are modified. This is known as drift management. Argo CD does this by implementing a Kubernetes concept called a Controller which executes a non-terminating control loop for managing and monitoring the desired state of at least one resource. Based on a defined configuration, the controller will ensure that the current state matches the desired state.

For example, Deployments are a common method for registering workloads into Kubernetes and as part of the creation of a Deployment resource, a ReplicaSet is created. One of the built-in Kubernetes controllers, the ReplicaSet controller, monitors all pods that have been created for a given ReplicaSet and ensures that the actual state of the resource(s) in the cluster match the expected and defined state. If the actual state does not match the expected state, the controller will reconcile the difference until the current state matches the defined state.

This controller pattern applies to not only the resources that end users manage, but are foundational for Argo CD itself. The properties that drive the core configurations of Argo CD (everything from how to connect to external entities to the various properties of the Argo CD server) are stored within ConfigMaps and Secrets. However, as one can imagine, there is a limitation of the types of properties that can be stored within the simple key/value constructs provided by not only these Kubernetes resources, but any resources that are part of a standard Kubernetes deployment.

Argo CD is not alone when it comes to solutions for adding new ways of managing resources within a Kubernetes environment. This need led to the creation of Custom Resources which are implemented through CustomResourceDefinitions (CRDs) and enable an end user to register a new resource type within Kubernetes. By defining a new resource type, not only can the properties of this resource be defined (so that consumers can become aware and comply with the acceptable fields and their rules), but a new API endpoint in the Kubernetes API server is registered to facilitate the management of these resources.

A concept similar to a Kubernetes controller, known as an operator, builds upon the primitives of a Kubernetes controller for managing the current and desired state of resources in a Kubernetes cluster and applies them to CRDs. Given that Custom Resources typically have domain specific values and meaning associated with them, an operator is built with this domain level knowledge of how to interpret those values and ensure the state of resources within Kubernetes match those defined values.

Argo CD makes use of several Custom Resources and their properties are the primary vehicle to enable end users to manage their Kubernetes resources using GitOps based principles. The use of Kubernetes Controllers and Custom Resource are fundamental to the overall Argo CD architecture.

Argo CD Architecture Overview

Given that Argo CD implements a microservices based architecture, there is no single Argo CD component, but instead multiple distributed systems that act in a coordinated fashion. Figure 1-1 depicts the overall Argo CD architecture including the relationship between each of the services and resources.

Figure 1-1. Overall Argo CD Architecture

Custom Resources

Argo CD makes use of several Custom Resources to declaratively define business logic and API’s to implement GitOps management capabilities. Three Custom Resources are provided with each installation of Argo CD:

• Applications

• AppProjects

• ApplicationSets

The purpose of each Custom Resource will be described in more detail throughout the course of this book. However, it is important to note that Argo CD interacts with the Kubernetes cluster using these CRDs. This, effectively, makes these CRDs your interface for managing your Kubernetes cluster/clusters.

Application Controller / ApplicationSet Controller

The Application Controller and ApplicationSet Controller are both Kubernetes Operators (and by definition, also controllers) that continuously monitor the state of Application and ApplicationSet resources and compare the live state in the Kubernetes cluster to the desired state from source repositories. In addition to strictly monitoring for Custom Resources, they are also responsible for performing lifecycle events associated with the content that they are reconciling.

Repository Server

The Repository Server maintains a local cache of the remote content source that will be translated into Kubernetes manifests. It is responsible for generating resources based on parameters including:

• Repository type

• Repository source location

• Path within the repository

• Template tool specific parameters

In addition, Custom plugins are also executed within this component as they can influence the generation of the Kubernetes resources.

API Server

The API server is a gRPC/REST based server that exposes services for managing key configurations that are integral to the platform including:

• Application management and status reporting

• Invocation of Application operations including syncing, rollback and additional user defined actions

• Cluster and repository management

• RBAC enforcement

Several other components within the Argo CD ecosystem heavily rely on this asset for their normal operation including the User Interface, CLI, and external CI/CD systems.

In addition to acting as an API server, a web User Interface is also exposed which provides a method for visualizing Application activity as well as supporting the management and configuration of Argo CD.

Redis

Redis is an in-memory database and provides local caching capabilities to reduce the dependency on external systems. While its primary purpose is to cache the contents of remote repositories, it also supports the state of Kubernetes resources as well as connection status of remote repositories and clusters. The content of the cache is not persisted and is always rebuilt at startup.

Command Line Interface (CLI)

Command line based utility for interacting with Argo CD. Support is available to manage the configuration of the platform itself as well as the lifecycle of Applications. Communicates via the Argo CD API and includes a superset of the capabilities that are provided by the Argo CD user interface.

Single Sign On (SSO)

Argo CD provides user management capabilities for interacting with the platform. These users can be defined locally within Argo CD or can be sourced from an external source. When integrating with an external source, OpenID Connect (OIDC) based authentication is supported. For external identity providers that do not provide a direct OIDC integration, an instance of the Dex identity server is provided to act as a bridge between Argo CD and the remote identity provider.

Notifications

Included as part of a standard installation of Argo CD starting in version 2.3. This feature provides a mechanism for monitoring and triggering notifications to external systems based on the lifecycle of Applications through the use of templating capabilities and a catalog of included triggers. Argo CD Notifications can be configured to send information to (but not limited to) Slack, Email, and can also invoke other webhooks. Understanding the current state of systems and environments is key when running production systems and Argo CD notifications will be covered in greater detail within Chapter 13.

Argo CD Key Themes

As may be evident by this point, now that the foundational architecture has been introduced, Argo CD makes use of several key patterns and their significance will become even more apparent as each topic is described.

First, is an emphasis of defining resources in a declarative fashion; whether they be one of the provided Custom Resources, or a core configuration of the Argo CD server itself that is stored in a ConfigMap or Secret. Not only does trait implement one of the most important concepts in GitOps, it also enables the configuration of Argo CD itself to be managed via GitOps and Argo CD.

Building upon the first theme where each resource is managed in a declarative fashion, Argo CD also makes use of a stateless architecture, meaning that configurations are the state of the system that can be rebuilt at any time. This approach to a stateless architecture is achieved by using etcd, the key/value datastore of Kuberntes to act as the persistent store for the aforementioned resources. If there is either a desire or need for state to be tracked against a particular resource, the status field, a standard property and method found on many Kubernetes resources, can be used. In addition, while Redis is included as a caching mechanism within the Argo CD architecture, it is used as a volatile cache without any long term persistence.

Finally, Argo CD enables flexibility. Not only are there multiple repository types which GitOps related content can be sourced from, but there is built in support for templating resources using a number of popular tools including Kustomize, Helm and Jsonnet. Additional user defined tools can also be added to not only integrate with additional external resources, but enhance how assets are rendered.

Now that we’ve covered the basics of the Argo CD architecture including the primary components, let’s shift gears to the methods that are supported for installing Argo CD.

Installing Argo CD

Just as Argo CD supports the use of multiple methods and tools, such as Kustomize and Helm, to generate resources that can be applied to a Kubernetes cluster, many of these same tools and approaches can be used to install Argo CD itself. The determination of the particular approach depends largely on user preference as well as if there are any specific requirements or constraints, such as team or organizational guidance or restrictions. In addition to the tool that is used to facilitate the execution of the installation, Argo CD also supports several installation types which influences the resources that are included in the deployment as well as the configuration of the deployed resources. Some of these topics will be expanded upon in subsequent chapters.

Installation Types

Argo CD as a GitOps tool, similar to many other tools in this space, is utilized by a variety of personas who each have their own set of business domains and goals. Since there are a multitude of use cases and requirements that may be desired, Argo CD supports multiple installation configurations and the determination of a particular configuration depends on the answer to three key decision points:

• Who are the users and consumers of the platform?

• What is the scope Argo CD should manage?

• Is high availability a concern?

These options are illustrated in Figure 1-2:

Figure 1-2. The options and considerations when installing Argo CD

The first decision point is the type of installation that Argo CD should serve. In most cases, Argo CD will be consumed by multiple individuals that may span across multiple teams within an organization. Additionally, most organizations desire to make use of the full set of features that are provided as part of a standard deployment of Argo CD (we covered these in the previous section). This is known as a multi-tenant type of installation and it is most commonly utilized as it provides the full set of capabilities provided by Argo CD.

Alternatively, an option is available to perform an installation that includes only the minimal set of components to support normal operation. This approach does not include the API server or user interface, SSO or notification features. In addition, each component is also optimized to consume a minimum amount of resources in a non-highly available configuration (more on the topic of high availability later in this chapter). While a core deployment is not intended to appease the masses, this approach is beneficial for individual users that manage Argo CD from both an administrative and end user perspective where there is not a desire to leverage the full featureset of Argo CD, but there is still a desire to take advantage of the primary GitOps capabilities.

The next decision point that must be addressed is the scope that Argo CD should manage. By default, Argo CD has the authority to control resources across an entire Kubernetes cluster. This is the preferred option, especially when Argo CD is being used by Kubernetes cluster administrators. However, another approach, known as “namespaced” mode, that is available is to deploy Argo CD within a specific namespace and to allow Argo CD to only manage resources within specific namespaces. This option is used in multi-tenant environments where individual application teams are given the autonomy to operate their own instance of Argo CD, but are not granted access to manage cluster scoped resources. An in depth look into the use of a namespaced deployment of Argo CD and its use case will be discussed in Chapter 8.

Finally, to support production environments, each of Argo CD’s components can be configured in an optimized manner to ensure greater resiliency and performance needs. This approach is accomplished through a combination of increasing the replica count as well as enabling tunable parameters within each component. However, there are certain considerations that must be followed so that Argo CD can operate in an optimized fashion as merely increasing the replica count of all components uniformly can actually cause a performance degradation. Fortunately, Argo CD provides manifests supporting both clustered and namespace scoped deployments illustrate the types of configurations necessary to enable a highly available deployment.

Now that both an overview of the Argo CD architecture as well as an understanding of the deployment approaches have been addressed, it’s time to see Argo CD in action by working through the first hands-on activity.

Deploying Argo CD

In due course throughout the remainder of this book, most of the installation types and approaches will be realized. However, to get started, let’s start off by performing a basic installation of Argo CD to our kind environment.

We’ve covered multiple approaches for performing an installation of Argo CD. Each of these options are detailed within the installation section (https://argo-cd.readthedocs.io/en/stable/operator-manual/installation) of the Argo CD documentation.

Deploying Argo CD Using YAML Manifests

The simplest and most straightforward option is to use one of the raw YAML formatted manifests that include all of the resources and configurations within a single document, and in particular, a non-highly available, multi-tenant based deployment of Argo CD.

First, ensure that a fresh kind cluster is running.

                kind create cluster
              

Note

By default, the name of the cluster that the kind tool creates is called kind. You are free to change the default behavior by specifying an alternate name using the --name parameter of the kind create cluster command or by setting the environment variable KIND_CLUSTER_NAME with the desired name.

Once the cluster has started, your kubectl context will be automatically updated and ready to utilize the newly created cluster. Execute the following commands using kubectl to create a new namespace called argocd and to deploy Argo CD in the previously described configuration:

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

After a few moments to allow for the associated images to be downloaded to the kind cluster, the pods in the argocd namespace can be queried with a result similar to the following:

kubectl get pods -n argocd
NAME                                                READY   STATUS    RESTARTS   AGE
argocd-application-controller-0                     1/1     Running   0          46s
argocd-applicationset-controller-74575b6959-8dc7l   1/1     Running   0          46s
argocd-dex-server-64897989f8-qg8pm                  1/1     Running   0          46s
argocd-notifications-controller-566bc99494-7vj82    1/1     Running   0          46s
argocd-redis-79c755c747-867nk                       1/1     Running   0          46s
argocd-repo-server-bc9c646dc-6sd86                  1/1     Running   0          46s
argocd-server-757fddb4d7-xgdxh                      1/1     Running   0          46s

The standard deployment of Argo CD depicted here contains each of the primary components that are included with Argo CD, so it is an ideal baseline to work from.

The User Interface is one of the key features that sets Argo CD apart from other GitOps solutions. Before moving on, confirm the successful installation of Argo CD by accessing the User Interface.

By default, the set of resources that were applied to the Kuberntes cluster did not include any configurations or resources to expose access to Argo CD outside the cluster. While there are several approaches that can be used to access Argo CD externally, such as creating a LoadBalancer service type or using an Ingress, to demonstrate baseline functionality, the port forwarding capability of the kubectl CLI can be used to connect to Argo CD without any additional actions.

Next, execute the following command to initiate the forwarding of port 8080 from the local machine to the Argo CD server service which will expose access to the User Interface.

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

The command will establish a tunnel to facilitate the connection and block additional commands from being entered while the tunnel is established. If additional commands need to be executed while ports are forwarded, launch another terminal.

With access to the Argo CD user interface available due to the port-forward tunnel, navigate to https://localhost:8080

By default, Argo CD generates a self signed TLS certificate to enable secure transmission between itself and the browser. Since this certificate is not trusted by the browser, a warning is displayed. Depending on the browser being used, there will be an option to proceed even though the certificate is not trusted and then the Argo CD login page will be displayed.

To login, admin is the username of the Argo CD administrator and the password is a secret with the name argocd-initial-admin-secret. Obtain the password by executing the following command:

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo

Login using admin as the username and the password that was obtained from the prior command. Upon successful login, the Argo CD dashboard is displayed, as shown in Figure 1-3.

Figure 1-3. The Argo CD Application Page

The dashboard contains a list of the current Applications that have been registered to Argo CD and their current status. Since this instance does not have any Applications registered, the dashboard is empty. Feel free to navigate around the user interface as you see fit. However, a more in depth overview of the user interface will be covered in Chapter 3.

High Availability

The standard deployment of Argo CD is ideal for getting started, but is not suitable for production environments due to the fact that there is only a single replica for each component. In case one of the components fails (due to an error or issue with the underlying infrastructure), it will cause a degradation of functionality as one or more of the resources will become unavailable. To mitigate these concerns, an alternate set of YAML definitions are available for both cluster and namespaced modes of operation. The key difference between these sets of resources and those that were deployed previously is that not only have additional tuning options been implemented, but multiple replicas of each service have also been defined. This means that if a failure does occur to one of the services, the remaining replica will be able to take on requests and continue normal operation in a degraded state until the original replica returns to normal operation.

Given that the topic of high availability is just one of the many traits of a production system, this topic will be expounded upon in Chapter 13 as part of a discussion on the considerations for operating Argo CD at scale.

Deploying Argo CD Using Helm

Argo CD can also be installed using a Helm chart. A Helm based installation approach has advantages over YAML manifests as the resources that are installed can be customized using the dynamic templating capabilities provided by Helm. For example, entire components can be enabled or disabled as well as specific properties can be tailored whereas these options would not be possible using the YAML based manifest approach.

To install Argo CD using Helm, first be sure that your kind cluster does not have any previously created resources deployed. If Argo CD is still running from the prior section, the kind cluster can be deleted and recreated or the contents from the prior section can be removed.

To delete and recreate the kind cluster, using the following commands:

kind delete cluster
Kind create cluster

Alternatively, instead of needing to recreate the entire kind cluster, the YAML based manifest installation of Argo CD can be uninstalled by removing the resources from the same manifest and then deleting the argocd namespace:

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

With a fresh kind cluster available, proceed to deploy Argo CD using Helm.

First, add the Argo CD Helm repository:

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

Install the Helm chart using the default configuration and create a new namespace called argocd using the following command:

helm upgrade -i argo-cd argo/argo-cd -n argocd --create-namespace

Note

Either the helm install or helm upgrade command can be used to install the Argo CD chart. When the helm upgrade command is used with the -i parameter, Helm will check if there is an existing release found. If a release is not found, the chart will be installed instead of upgraded. The benefit of using helm upgrade in this situation is that the same command can be issued regardless of installing a chart for the first time, or upgrading an existing release. The helm install command can only be used when installing a chart for the first time.

Another benefit of Helm is that chart creators can include additional information that is displayed whenever a chart is installed or upgraded, known as NOTES. After executing the helm upgrade command previously, the contents of the NOTES document in the chart was displayed which provided a set of next steps, including how to access the Argo CD user interface and how to obtain the password for the Argo CD admin user.

Query the running pods from the argocd namespace and take note that the set of resources are available as they were using the YAML manifest approach (albeit with slightly different names as the Helm chart prefixes each resource with the name of the Helm release).

kubectl get pods -n argocd

If desired, the Argo CD user interface can be accessed in a similar manner as described in the previous section and the exact steps in this instance can be found within the provided Helm NOTES output.

While only a basic deployment of Argo CD was described in this section, the full set of tunable parameters provided by the Argo CD Helm chart can be viewed by listing the available chart Values:

helm show values argo/argo-cd 

The use of Helm values within the Argo CD Helm chart enables a greater level of customization and simplifies the initial configuration when deploying Argo CD.

Summary

This chapter provided an overview of the architecture and components that are included as part of a deployment of Argo CD. In addition, two of the most common approaches for installing Argo CD, YAML manifests and Helm charts were introduced and used to deploy Argo CD to a kind cluster. Finally, the Argo CD was accessed using the user interface to confirm a successful installation. The next chapter expands upon the use of the user interface and describes the various different methods available that can be used to manage and interact with Argo CD.