Merge pull request 'Improve operator onboarding docs' (#45) from Armael/guide.deuxfleurs.fr:onboarding into main

Reviewed-on: #45

content/operations/acces.md

@@ -7,4 +7,7 @@ extra:
   parent: 'operations/_index.md'
 ---
 
-Ici l'on traite de comment gagner accès au cluster de Deuxfleurs, quand on a reçu la _terrible responsabilité_ de sysadmin. Vous êtes prêt⋅e ? Alors entrez dans [le dépôt des secrets](@/operations/pass.md).
+Ici l'on traite de comment gagner accès au cluster de Deuxfleurs, quand on a reçu la _terrible responsabilité_ de sysadmin. Vous êtes prêt⋅e ? Les étapes sont les suivantes :
+- [le dépôt des secrets](@/operations/pass.md)
+- [SSH](@/operations/ssh.md)
+- [mot de passe linux](@/operations/user_passwd.md)

content/operations/pass.md

@@ -100,40 +100,22 @@ brew install pass # macOS
 pkg install password-store # FreeBSD
 ```
 
-_Go to  for more information about pass_.
+_Go to [passwordstore.org](https://ww.passwordstore.org) for more information about pass_.
 
 Finally check that everything works:
 
+```bash
+pass deuxfleurs/nix_priv_key
+```
+
+If you see an output of the form `nix.web.deuxfleurs.fr:xxxxxx` then it worked! You are now able to decrypt all the secrets. You can do the following command to list them:
+
 ```bash
 pass show deuxfleurs
 ```
 
-If you see a listing, it worked. Last step is to select a shell password for yourself on the cluster you are now in charge of (`prod` or `staging`, at the time of writing).
+The next step is to [setup SSH](@/operations/ssh.md) to be able to connect to computers of the clusters.
 
-Clone the nixcfg repository:
-
-```
-git clone git@git.deuxfleurs.fr:Deuxfleurs/nixcfg.git
-cd nixcfg
-```
-
-Use the passwd utility to set your shell password:
-
-```
-./passwd
-> Usage: ./passwd <cluster name> <username>
-> The cluster name must be the name of a subdirectory of cluster/
-```
-
-This commited changes to Deuxfleurs' password store, do verify your modifications before pushing them:
-
-```
-cd ~/.password-store/deuxfleurs
-git diff
-git push
-```
-
-You should now be able to `ssh` into our infrastructure with a unified shell password. This is explicated in `nixcfg` repo's [README](https://git.deuxfleurs.fr/Deuxfleurs/nixcfg#how-to-operate-a-node). Be cautious, and enjoy!
 
 > With great power comes great responsibility.
 

content/operations/ssh.md

@@ -6,6 +6,69 @@ extra:
   parent: 'operations/acces.md'
 ---
 
-Voir si on documente comment gérer SSH depuis GPG
+SSH permet de se connecter aux machines du cluster à administrer (`staging` ou `prod`).
 
-# Ajout de la clé au cluster
+# Ajout d'une nouvelle clé SSH au cluster
+
+Dans le dépot [nixcfg](https://git.deuxfleurs.fr/deuxfleurs/nixcfg), éditer le
+fichier `cluster/CLUSTER/cluster.nix`, où `CLUSTER` est à remplacer par `prod`
+ou `staging`.
+
+La variable qui nous intéresse est `deuxfleurs.adminAccounts`. On trouve une
+définition de la forme suivante :
+
+```nix
+  deuxfleurs.adminAccounts = {
+    lx = [
+      "ssh-ed25519 ...."
+    ];
+    quentin = [
+      "ssh-rsa ...."
+      "ssh-rsa ...."
+    ];
+    ...
+  };
+```
+
+Ici, `lx` et `quentin` correspondent à des noms d'utilisateur linux sur les
+machines du cluster, et les `"ssh-ed25519 ..` ou `"ssh-rsa ..."` sont les clefs
+SSH publiques qui permettent de se connecter à ces utilisateurs.
+
+Ajouter un attribut à `deuxfleurs.adminAccounts` avec le nom d'utilisateur et sa
+clef ssh publique choisie. Par exemple, pour ajouter une nouvelle utilisatrice
+`alice` :
+
+```nix
+  deuxfleurs.adminAccounts = {
+    lx = [
+      "ssh-ed25519 ...."
+    ];
+    quentin = [
+      "ssh-rsa ...."
+      "ssh-rsa ...."
+    ];
+    ...
+    alice = [
+      "clef SSH publique d'alice"
+    ];
+```
+
+Commiter et pousser ces modifications (`git commit/push`). 
+
+Un autre administrateur doit ensuite déployer ces modifications sur les machines
+du cluster en utilisant le script `./deploy_nixos` du dépot `nixcfg`.
+
+*TODO*: dire ce qu'il faut mettre dans le `.ssh/config`.
+
+Vous pouvez ensuite tester de vous connecter à une machine du cluster :
+
+```bash
+ssh caribou # staging
+# ou
+ssh pasteque # prod
+```
+
+
+Pour terminer la création d'un nouveau compte utilisateur linux sur le cluster,
+la dernière étape est de lui [assigner un mot de
+passe](@/operations/user_passwd.md).

content/operations/user_passwd.md

@@ -0,0 +1,31 @@
+---
+title: "Mot de passe unix"
+description: "Mot de passe unix"
+weight: 200
+extra:
+  parent: 'operations/acces.md'
+---
+
+The last step of adding an administrator is to select a user password for
+yourself on the cluster you are now in charge of (`prod` or `staging`).
+
+In the [nixcfg](https://git.deuxfleurs.fr/deuxfleurs/nixcfg) repository,
+use the passwd utility to set your shell password:
+
+```
+./passwd
+> Usage: ./passwd <cluster name> <username>
+> The cluster name must be the name of a subdirectory of cluster/
+```
+
+This commited changes to Deuxfleurs' password store, do verify your modifications before pushing them:
+
+```
+cd ~/.password-store/deuxfleurs
+git diff
+git push
+```
+
+These changes must be deployed to the machines to take effect. Ask another
+administrator to deploy them. They will need to use the script
+`./deploy_passwords` from the `nixcfg` repository after pulling your changes.