content/en/docs/solution/tools/CNOE/argocd/_index.md

@@ -0,0 +1,141 @@
+---
+title: ArgoCD
+weight: 30
+description: A description of ArgoCD and its role in CNOE
+---
+
+## What is ArgoCD?
+
+ArgoCD is a Continuous Delivery tool for kubernetes based on GitOps principles.
+
+> ELI5: ArgoCD is an application running in kubernetes which monitors Git
+> repositories containing some sort of kubernetes manifests and automatically
+> deploys them to some configured kubernetes clusters.
+
+From ArgoCD's perspective, applications are defined as custom resource
+definitions within the kubernetes clusters that ArgoCD monitors. Such a
+definition describes a source git repository that contains kubernetes
+manifests, in the form of a helm chart, kustomize, jsonnet definitions or plain
+yaml files, as well as a target kubernetes cluster and namespace the manifests
+should be applied to. Thus, ArgoCD is capable of deploying applications to
+various (remote) clusters and namespaces.
+
+ArgoCD monitors both the source and the destination. It applies changes from
+the git repository that acts as the source of truth for the destination as soon
+as they occur, i.e. if a change was pushed to the git repository, the change is
+applied to the kubernetes destination by ArgoCD. Subsequently, it checks
+whether the desired state was established. For example, it verifies that all
+resources were created, enough replicas started, and that all pods are in the
+`running` state and healthy.
+
+## Architecture
+
+### Core Components
+
+An ArgoCD deployment mainly consists of 3 main components:
+
+#### Application Controller
+
+The application controller is a kubernetes operator that synchronizes the live
+state within a kubernetes cluster with the desired state derived from the git
+sources. It monitors the live state, can detect derivations, and perform
+corrective actions. Additionally, it can execute hooks on life cycle stages
+such as pre- and post-sync.
+
+#### Repository Server
+
+The repository server interacts with git repositories and caches their state,
+to reduce the amount of polling necessary. Furthermore, it is responsible for
+generating the kubernetes manifests from the resources within the git
+repositories, i.e. executing helm or jsonnet templates.
+
+#### API Server
+
+The API Server is a REST/gRPC Service that allows the Web UI and CLI, as well
+as other API clients, to interact with the system. It also acts as the callback
+for webhooks particularly from Git repository platforms such as GitHub or
+Gitlab to reduce repository polling.
+
+### Others
+
+The system primarily stores its configuration as kubernetes resources. Thus,
+other external storage is not vital.
+
+Redis
+: A Redis store is optional but recommended to be used as a cache to reduce
+load on ArgoCD components and connected systems, e.g. git repositories.
+
+ApplicationSetController
+: The ApplicationSet Controller is similar to the Application Controller a
+kubernetes operator that can deploy applications based on parameterized
+application templates. This allows the deployment of different versions of an
+application into various environments from a single template.
+
+### Overview
+
+![Conceptual Architecture](./argocd_architecture.webp)
+
+![Core components](./argocd-core-components.webp)
+
+## Role in CNOE
+
+ArgoCD is one of the core components besides gitea/forgejo that is being
+bootstrapped by the idpbuilder. Future project creation, e.g. through
+backstage, relies on the availability of ArgoCD.
+
+After the initial bootstrapping phase, effectively all components in the stack
+that are deployed in kubernetes are managed by ArgoCD. This includes the
+bootstrapped components of gitea and ArgoCD which are onboarded afterward.
+Thus, the idpbuilder is only necessary in the bootstrapping phase of the
+platform and the technical coordination of all components shifts to ArgoCD
+eventually.
+
+In general, the creation of new projects and applications should take place in
+backstop. It is a catalog of software components and best practices that allows
+developers to grasp and to manage their software portfolio. Underneath,
+however, the deployment of applications and platform components is managed by
+ArgoCD. Among others, backstage creates Application CRDs to instruct ArgoCD to
+manage deployments and subsequently report on their current state.
+
+## Glossary
+
+_Initially shamelessly copied from [the docs](https://argo-cd.readthedocs.io/en/stable/core_concepts/)_
+
+Application
+: A group of Kubernetes resources as defined by a manifest. This is a Custom Resource Definition (CRD).
+
+ApplicationSet
+: A CRD that is a template that can create multiple parameterized Applications.
+
+Application source type
+: Which Tool is used to build the application.
+
+Configuration management tool
+: See Tool.
+
+Configuration management plugin
+: A custom tool.
+
+Health
+: The health of the application, is it running correctly? Can it serve requests?
+
+Live state
+: The live state of that application. What pods etc are deployed.
+
+Refresh
+: Compare the latest code in Git with the live state. Figure out what is different.
+
+Sync
+: The process of making an application move to its target state. E.g. by applying changes to a Kubernetes cluster.
+
+Sync status
+: Whether or not the live state matches the target state. Is the deployed application the same as Git says it should be?
+
+Sync operation status
+: Whether or not a sync succeeded.
+
+Target state
+: The desired state of an application, as represented by files in a Git repository.
+
+Tool
+: A tool to create manifests from a directory of files. E.g. Kustomize. See Application Source Type.