Merge pull request 'Update doc operations : déploiement, postgresql, secrets' (#44) from operations_postgresql_secret into main

Reviewed-on: Deuxfleurs/guide.deuxfleurs.fr#44

content/operations/create_database.md

@@ -1,36 +1,100 @@
 ---
-title: "Créer une BDD"
+title: "Créer une BDD psql"
-description: "Création d'une base de données pour une nouvelle application"
+description: "Création d'une base de données PostgreSQL pour une nouvelle application"
-date: 2022-12-22
+date: 2025-02-25
 dateCreated: 2022-12-22
-weight: 11
+weight: 12
 extra:
   parent: 'operations/deployer.md'
 ---
 
-## 1. Create a LDAP user and assign a password for your service
+## Le besoin
 
-Go to guichet.deuxfleurs.fr
+On déploie une application sur l'infra Deuxfleurs, et cette application a besoin de stocker des données dans une base PostgreSQL.
 
-  1. Everything takes place in `ou=services,ou=users,dc=deuxfleurs,dc=fr`
+On utilise pour cela le service PostgreSQL existant de Deuxfleurs, déployé en cluster avec [Stolon](@/operations/stolon.md).
-  2. Create a new user, like `johny`
-  3. Generate a random password with `openssl rand -base64 32`
-  4. Hash it with `slappasswd`
-  5. Add a `userpassword` entry with the hash
 
-This step can also be done using the automated tool `secretmgr.py` in the app folder.
+Pour mettre en place l'accès nécessaire à cette nouvelle application, nous avons besoin de :
 
-## 2. Connect to postgres with the admin users
+- créer un utisateur pour que l'application puisse se connecter à PostgreSQL
+- générer un mot de passe associé
+- créer une ou plusieurs bases de données dans PostgreSQL
+
+Ces trois éléments seront ensuite utilisés dans la configuration de l'application.
+
+## Comment ça marche
+
+- **utilisateur et mot de passe :** PostgreSQL est configuré pour
+  authentifier les connexions via le LDAP de Deuxfleurs, géré par Bottin.
+  Il faut donc créer un nouvel "utilisateur de service" dans le LDAP
+  Deuxfleurs (avec un mot de passe associé).
+
+- **base de données :** On crée une base de données pour chaque
+  application, et seul l'utilisateur associé a le droit d'accéder à cette
+  base.  Cela sépare bien les différentes applications.
+
+- **nom de la base de données :** Cas simple où l'application a besoin
+  d'une seule base de données : on lui donne le nom de l'application.  Cas
+  complexe avec plusieurs bases : on préfixe par le nom de l'application.
+  
+- **configuration de l'application :** On veut passer quatre éléments à
+  l'application : l'adresse/port du service PostgreSQL, le nom
+  d'utilisateur, le mot de passe, et le nom de la base de données.  Les
+  applications se configurent généralement soit via des variables
+  d'environnement, soit via un fichier de configuration.  Chez Deuxfleurs,
+  on stocke les secrets dans Consul, et on utilise des templates pour
+  injecter ces secrets dans la configuration de l'application.  Voir dépôt
+  nixcfg pour des exemples, ou ici un exemple simple :
+  
+```
+DATABASE_URL=postgres://monapplication:{{ key "secrets/monapplication/postgres_pwd" | trimSpace }}@{{ env "meta.site" }}.psql-proxy.service.prod.consul:5432/monapplication
+```
+
+## Etapes de création de l'utilisateur et base de données
+
+### 1. Création de l'utilisateur dans LDAP (méthode automatisée à privilégier)
+
+Voir la page de [secretmgr](@/operations/secretmgr.md)
+
+Gros avantage : le script va également copier les secrets dans Consul, ce qui facilitera la configuration de l'application.
+
+### 1.bis Création de l'utilisateur dans LDAP (méthode manuelle au cas où)
+
+Si la méthode automatique ne convient pas, commencer par générer un mot de passe (sur votre laptop, ou depuis une machine Deuxfleurs, peu importe) :
+
+  1. Générer un mot de passe aléatoire avec la commande `openssl rand -base64 32`
+  2. Hasher ce mot de passe avec la commande `slappasswd`
+
+Puis aller sur https://guichet.deuxfleurs.fr :
+
+  1. Il est nécessaire d'être admin Guichet
+  2. Trouver l'arbre LDAP des utilisateurs de service `ou=services,ou=users,dc=deuxfleurs,dc=fr`
+  3. Créer un nouvel utilisateur dans cet arbre, par exemple `monapplication` (nom de l'application)
+  4. Ajouter un champ `userpassword` avec le hash du mot de passe obtenu précédemment
+
+### 2. Se connecter en admin au PostgreSQL de production
+
+Installer le client postgresql (paquet `postgresql-client` sous Debian).
+
+Se connecter en SSH sur une machine de prod en faisant un tunnel vers
+`psql-proxy.service.prod.consul:5432` (c'est automatique avec [la
+configuration SSH recommandée]
+(https://git.deuxfleurs.fr/Deuxfleurs/nixcfg/src/branch/main/doc/onboarding.md))
+
+On peut alors se connecter au serveur PostgreSQL de production :
 
 ```bash
-# 1. Launch ssh tunnel given in the README 
-# 2. Make sure you have postregsql client installed locally
 psql -h localhost -U postgres -W postgres
 ```
 
-## 3. Create the binded users with LDAP in postgres + the database
+TODO : demande un mot de passe, où est-il stocké ?
+
+
+### 3. Créer l'utilisateur et la base de données dans PostgreSQL
+
+Dans le client `psql`, lancer les commandes SQL suivantes.  Il faut adapter le nom de l'application et le nom de la base de données.
 
 ```sql
-CREATE USER sogo;
+CREATE USER monapplication;
-Create database sogodb with owner sogo encoding 'utf8' LC_COLLATE = 'C' LC_CTYPE = 'C' TEMPLATE template0;
+CREATE DATABASE monapplication WITH OWNER monapplication ENCODING 'utf8' LC_COLLATE = 'C' LC_CTYPE = 'C' TEMPLATE template0;
 ```

content/operations/deployer.md

@@ -1,6 +1,6 @@
 ---
 title: "Déployer du logiciel"
-description: "Déploiement du logiciel"
+description: "Déploiement d'un logiciel"
 sort_by: "weight"
 date: 2022-12-22
 weight: 30
@@ -11,25 +11,33 @@ extra:
 
 # Empaqueter
 
-Packager avec nix un conteneur Docker, le publier
+Packager avec nix un conteneur Docker, le publier.
 
 # Secrets
 
-Créer les secrets avec `secretmgr`
+Créer les secrets avec [secretmgr](@/operations/secretmgr.md)
 
-# Service
+# Base de données SQL
+
+Si besoin, [créer une base de données PostgreSQL](@/operations/create_database.md)
+
+# Service Nomad
 
 Créer un service Nomad
 
-Voir les différentes déclarations :
+Voir les différentes déclarations dans [nixcfg cluster/prod](https://git.deuxfleurs.fr/Deuxfleurs/nixcfg/src/branch/main/cluster/prod/app) :
-  - diplonat
+  - `core/deploy/diplonat.hcl`
-  - tricot
+  - `core/deploy/tricot.hcl`
+  - `guichet/deploy/guichet.hcl`
+
+Voir la [documentation nixcfg](https://git.deuxfleurs.fr/Deuxfleurs/nixcfg/src/branch/main/doc/architecture.md#deploying-stuff-on-nomad) pour utiliser la ligne de commande Nomad.
 
 # Sauvegardes
 
-Voir la section appropriée
+Voir la section appropriée : [Sauvegardes](@/operations/sauvegardes.md)
 
-# Surveillance
+# Supervision
+
+Voir la section appropriée : [Supervision](@/operations/supervision.md)
 
-Voir la section appropriée
 

content/operations/secretmgr.md

@@ -0,0 +1,19 @@
+---
+title: "Gestion des secrets"
+description: "Gestion des secrets pour les applications"
+date: 2025-02-25
+dateCreated: 2025-02-25
+weight: 11
+extra:
+  parent: 'operations/deployer.md'
+---
+
+Cette page documente l'usage du script `secretmgr` dans le dépôt nixcfg.
+
+- écrire un fichier `cluster/prod/app/<monapplication>/secrets.toml` qui décrit les secrets nécessaires à l'application
+- TODO expliquer les différents types de secrets disponibles
+- établir un tunnel SSH et lancer le script `tlsproxy` pour avoir accès à LDAP et Consul (voir `doc/onboarding.md` pour la conf SSH recommandée)
+- utiliser `secretmgr` pour générer les secrets, les copier dans Consul, et créer un utilisateur de service dans LDAP
+- TODO mot de passe admin LDAP
+
+Attention, le script nécessite Nix (sinon, il faut installer les dépendances Python soi-même)

content/operations/stolon.md

@@ -1,13 +1,32 @@
 ---
-title: "Stolon"
+title: "Déployer stolon"
 description: "Comment déployer Stolon"
-date: 2022-12-22
+date: 2025-02-25
 dateCreated: 2022-12-22
-weight: 11
+weight: 15
 extra:
   parent: 'operations/deployer.md'
 ---
 
+## Le besoin
+
+Stolon est utilisé pour gérer un cluster PostgreSQL, afin de stocker une copie des données sur chaque site géographique de Deuxfleurs.
+
+Cette documentation explique comment Stolon a été déployé initialement, et comment mettre à jour sa configuration.
+
+## Comment ça marche
+
+Ca a l'air un peu compliqué...
+
+Stolon va récupérer sa configuration dans Consul.  C'est un fichier JSON.
+
+Le champ `pgHBA` est utilisé par Stolon pour aller configurer le fichier
+`pg_hba.conf` de PostgreSQL.  Ici, on explique donc à PostgreSQL qu'il
+doit utiliser le LDAP de Deuxfleurs pour authentifier les connexions
+postgresql.
+
+## Déploiement initial
+
 Spawn container:
 
 ```bash
@@ -61,7 +80,7 @@ Moreover it would enable the usage of the user namespace that shift the UIDs.
 alias stolonctl='stolonctl --cluster-name chelidoine --store-backend consul --store-endpoints https://consul.service.prod.consul:8501 --store-ca-file /certs/consul-ca.crt --store-cert-file /certs/consul-client.crt --store-key /certs/consul-client.key'
 ```
 
-## Upgrading the cluster
+## Mise à jour du cluster
 
 To retrieve the current stolon config: