diff --git a/sysadm/deployment/argocd.rst b/sysadm/deployment/argocd.rst new file mode 100644 --- /dev/null +++ b/sysadm/deployment/argocd.rst @@ -0,0 +1,133 @@ +.. _argocd: + +ArgoCD +======= + +.. admonition:: Intended audience + :class: important + + sysadm staff members + +The CD is run by `ArgoCD `_ on argocd.softwareheritage.org. + +The repositories +---------------- + +To manage the kubernetes clusters and ArgoCD, 2 git repositories are used: + +- `k8s-clusters-conf `__ : + Kubernetes yaml files deployed on the clusters, it contains the configurations to apply + directly on the clusters. The ArgoCD configuration is also committed in this repository. +- `k8s-private data `__ : + private repository with the yaml files to configure the secrets per cluster + +**Except during the bootstrap phase, the configuration files are automatically applied on the clusters +by ArgoCD.** + +2 others deployment services related are indirectly related to deployments: + +- `swh-apps `__ : + Image definitions (version and dependencies, docker images definitions) +- `swh-charts `__ + Application definitions, mostly helm charts defining the way to deploy an application. + The public configurations per environment are also in this repository due to an argocd constraints. + The deployment of these applications is done by ArgoCD. + +Bootstrap ArgoCD +---------------- + +Prerequisite: A working kubernetes cluster sized to your needs. At SoftwareHeritage, we chose to +deploy a small cluster of 2 nodes which looks enough for our dozen of applications. + +Install ArgoCD +~~~~~~~~~~~~~~ + +TODO: Detail how it was done in the swh environment + Some working notes are available in a `Readme.md in the k8s-clusters-conf repository `__. + It's based on the official `ArgoCD documentation `__ + +Upgrade ArgoCD +~~~~~~~~~~~~~~ + +Follow the `official ArgoCD document procedure `__ + +Bootstrap the self configuration management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ArgoCD is able to manage its own configuration. + +To do so some manual installation steps are needed: + +- Clone the `k8s-private-data` and `k8s-clusters-conf` repositories locally (or directly the `sysadm-environment repository `__) +- Configure the `k8s-private-data` repository credentials in ArgoCD: + +.. code:: bash + + cd k8s-private-data/argocd/repositories + kubectl apply -f k8s-swh-private-data.yaml + +- Declare the ArgoCD that will import all the ArgoCD configuration + +.. code:: bash + + cd k8s-clusters-conf/argocd/applications + kubectl apply -f argocd-applications.yaml + +After that, ArgoCD will populate itself with all the applications in charge of the clusters configuration +and service deployments. + +Manage a new kubernetes cluster +------------------------------- + +As we saw, ArgoCD can take care of automatically applying and synchronizing the cluster configurations +and secrets based on what is committed in the `k8s-clusters-conf` and `k8s-private-data` repositories. + +A couple of steps are needed to add a new cluster and its associated management applications: + +- Declare the cluster in `k8s-private-data/argocd/clusters` + + - Copy an existing cluster file and adapt to use the new cluster credentials + +- If this cluster has some secrets, create a directory matching the cluster name at the root of the `k8s-private-data` repository too + + - Put the secret configurations in the directory in kubernetes yaml files. + +.. warning:: Only the secrets and private data must be put in this repository + +- In the `k8s-clusters-conf` repository, create a new application in the `argocd/applications/cluster-secrets` + named `.yaml` to manage the new cluster secrets + under `argocd/applications` + Check other applications in this directory and adapt the following properties: + - metadata.name: change to -secrets + - spec.source.path: change to , it must match the directory created in the `k8s-private-data` repository + - spec.destination.server: change to the server url, it must match the `stringData.server` value in the + cluster configuration created in `k8s-private-data/argocd/clusters/.yaml` + +- Create a new directory `k8s-clusters-conf/` and add the yaml for the static + configurations of the cluster (namespace, crd, ...) +- Create a new directory `argocd/` +- Create a new `configuration-application.yaml` to manage the static + configurations + Copy another configuration application and adapt the following properties: + - metadata.name: Change to `-configuration` + - spec.source.path: Change to ``, it must match the directory name created earlier + - spec.destination.server: Change to the url of the server as declared in the cluster configuration + created in `k8s-private-data` + +Commit and push, ArgoCD will apply all the configurations and will keep it in sync + +Deploy a new service +-------------------- + +The deployments of the services with kubernetes are also managed by ArgoCD. + +To create a new application: + - Identify the cluster on which the service will be deployed + - Declare a new ArgoCD application in `k8s-clusters-conf/argocd/application//-application.yaml` + +.. warning:: We are trying when it's possible to always use helm charts to deploy a service. + +You can find some other applications used to deploy helm based services in the repository. + +More information about the application configuration can also be found in the `official ArgoCD documentation `__ + diff --git a/sysadm/deployment/index.rst b/sysadm/deployment/index.rst --- a/sysadm/deployment/index.rst +++ b/sysadm/deployment/index.rst @@ -10,3 +10,4 @@ storage-database-migration howto-debian-packaging jenkins + argocd