diff --git a/sysadm/deployment/argocd.rst b/sysadm/deployment/argocd.rst --- a/sysadm/deployment/argocd.rst +++ b/sysadm/deployment/argocd.rst @@ -15,50 +15,59 @@ 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 +- `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.** +**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 `__ : +- `swh-apps `_: Image definitions (version and dependencies, docker images definitions) -- `swh-charts `__ +- `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. + The public configurations per environment are also in this repository due to 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. +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 `__ + + 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 `__ +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: +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 `__) +- 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 @@ -73,52 +82,57 @@ 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. +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. +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: +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 +- 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`` +- 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, ...) + - 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 +- 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`` + - 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 +Commit and push, ArgoCD will apply all the configurations and will keep it in sync. Deploy a new service -------------------- @@ -127,18 +141,24 @@ 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`` + - 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. +.. warning:: When possible, we try to use helm charts to deploy service. -You can find some other applications used to deploy helm based services in the repository. +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 `__ +More information about the application configuration can also be found in the `official +ArgoCD documentation +`_ Manage users ------------ -This documentation is based on the `official user management documentation `__ (archived link) +This documentation is based on the `official user management documentation +`_ +(archived link) Prerequisite ~~~~~~~~~~~~ @@ -148,8 +168,12 @@ Add a user ~~~~~~~~~~ -- Add the user on the `argo-cm.yaml `__ file -- Add the user role on the `argocd-rbac-cm.yaml `__ file +- Add the user on the `argo-cm.yaml + `_ + file +- Add the user role on the `argocd-rbac-cm.yaml + `_ + file If no role is specified, the user will only have a read-only access .. code:: yaml @@ -176,7 +200,9 @@ Disable a user ~~~~~~~~~~~~~~ -- Add the following line in the `argocd-cm.yaml `__ file +- Add the following line in the `argocd-cm.yaml + `_ + file .. code:: yaml