Initial Commit

content/configuration/_index.md

@@ -0,0 +1,17 @@
+---
+Title: Configuration
+Weight: 30
+---
+
+En tant que solution orientée Infrastructure As Code, Direktil n'est que fait de configuration structurée. Son rôle est de construire des configurations d'hôtes à la volée à partir de ces données.
+
+![Direktil Configuration](configuration.jpg)
+
+{{% notice tip %}}
+Il est conseillé que toute configuration soit gardée dans un dépot git. La fonctionnalité d'[includes]({{< ref "configuration/includes" >}}) permet d'ailleurs l'utilisation du branching git comme stratégie de gestion du code permettant de respecter la méthode "DRY".
+{{% /notice %}}
+
+Pour plus d'informations et d'exemples:
+
+{{% children description="true" %}}
+

content/configuration/clusters.md

@@ -0,0 +1,76 @@
+---
+Title: Clusters
+Description: Un cluster est un groupe d'hosts pouvant être de type différent mais travaillant ensemble dans un même environnement.
+Weight: 20
+---
+
+Les **Clusters** représentent les différents clusters Kubernetes d'une organisation. Ils sont la plupart du temps nommés selon un environnement bien défini, par exemple *prod*, *qual*, *dev*, etc... et permettent la séparation facile des application qui y sont déployées. Il est néanmoins possible de nommer librement ses clusters selon ses objectifs et ses contraintes, comme par exemple selon le nom d'une équipe de développement, d'une large application, etc...
+
+Les information des clusters sont stockés dans le dossier *clusters*, dans des fichiers yaml séparés selon les noms définis ci-dessus. Ces fichiers peuvent présenter un large nombre de variables permettant d'exprimer les différences entre tous les clusters gérés par la configuration globale. Ces variables vont s'appliquer à tous les [Hosts]({{< relref "configuration/hosts" >}}) déclarés comme faisant partie des-dits clusters, et à l'inverse, il n'est évidemment pas possible d'allouer un *host* à plusieurs *clusters* en même temps.
+
+{{< highlight yaml >}}
+domain: cluster.local
+
+subnets:
+  services: 192.168.48.0/20
+  pods: 192.168.64.0/20
+
+addons:
+- essentials
+
+vars:
+  kubernetes_version: v1.26.4
+
+  bootstrap_auths:
+  - name: "my-user"
+    sshKey: "ssh-ed25519 xxx my-user"
+
+  ssh_keys:
+  - "ssh-ed25519 xxx my-user"
+
+  devname_match: /dev/([shv]da|nmve[0-9]+n[0-9]+)
+  # to match a specific partition (here: 3):
+  #devname_match: /dev/([shv]da|nvme[0-9]+n[0-9]+p)3
+
+  vip_interface: main
+  public_vip: 10.42.0.10
+
+  netmask: 24
+  gateway: 10.42.0.254
+  dns:
+  - 10.42.0.1
+
+  dls_base_url: http://10.42.0.254:7606
+
+  etcd:
+    image: quay.io/coreos/etcd
+    version: v3.5.9
+    cluster_state: new # set to existing to secure existing clusters
+
+  keepalived:
+    image: novitnc/keepalived
+    version: 2.0.19
+    garp_master_refresh: 60
+    router_id: 1
+
+  control_plane:
+    api_port: 6443
+    reserve_resources: true
+
+  iface: "(en|eth).*"
+  containerd_size: 50%FREE
+
+  local_storage_class: local
+
+  encrypt_disks: false
+
+  cni_provider: knet-wg
+  ingress_controller: nginx
+  kube_proxy: proxy
+
+  k8s_registry: registry.k8s.io
+
+  kernel_modules: []
+
+{{< / highlight >}}
+

content/configuration/config.md

@@ -0,0 +1,19 @@
+---
+Title: Configs
+Description: Type de configuration très détaillé exploitant toutes les variables présentes dans les autres fichiers de configuration de type Infrastructure As Code (clusters et hosts), pour générer un système Direktil valide
+Weight: 40
+---
+
+La *config* est le type de configuration le plus détaillé. Son rôle est de réunir toutes les variables spécifiées au sein des *clusters* et *hosts*, et de permettre la génération finale de systèmes à utiliser sur des machines virtuelles ou physiques. 
+
+La *config* décrit plus spécifiquement ce qui se passe au démarrage d'un système, par exemple 
+- Definir les *layers* du système (dont les versions sont référencées au niveau des {{< relref "configuration/hosts" >}}).
+- Definir la configuration réseau.
+- Créer les volumes nécessaire, au moins au premier démarrage.
+- Créer les fichiers locaux statique, la plupart dans /etc/ (hosts, resolv.conf, sysctl.conf, services...)
+- Inclure les certificats TLS
+
+Le fichier de configuration utilise le [Go templating langage](https://pkg.go.dev/text/template) pour garantir un code concis et efficace respectant les préceptes du [DRY](https://fr.wikipedia.org/wiki/Ne_vous_répétez_pas). 
+
+
+

content/configuration/configuration-schema.drawio

@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2023-05-07T23:02:24.269Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Safari/537.36 OPR/98.0.0.0" etag="cVpR994JltxWoiEmGIby" version="20.2.8" type="device"><diagram id="YTLo56Nh1-BMgYtjPfZ_" name="Page-1">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</diagram></mxfile>

content/configuration/hosts.md

@@ -0,0 +1,33 @@
+---
+Title: Hosts
+Description: Réunit les variables propres aux rôles des machines prises individuellement.
+Weight: 10
+---
+
+Les fichiers d'**Hosts** décrivent une machine d'un *cluster*, qui peut alors être une machine virtuelle ou physique. Ces fichiers permettent de lier différents types de configurations, en décrivant :
+
+- Le nom du [cluster]({{< ref "configuration/clusters" >}}) de la machine
+- Ses informations réseau, sa version de kernel, de layers systèmes, etc...
+- Toute donnée unique à cette machine propre à son rôle au sein du cluster (par exemple master, compute node, etc...)
+
+Quand le Direktil Local Server génère sa configuration, il utilise ces liens pour génerer une configuration complète pour chaque machine.
+
+## Sample
+
+{{% notice note %}}
+A noter que toutes données déjà présente dans la configuration de cluster sera héritée par cette configuration. Certaines données ci-dessous sont donc dispensables et affichées par commodité.
+{{% /notice %}}
+
+{{< highlight yaml >}}
+ip: 10.42.0.11
+cluster: base
+kernel: 5.15.84
+versions:
+  init:       2.0.1
+  system:     v22.52.0
+  kubernetes: v1.26.4_containerd.1.6.12
+vars:
+  enable_minio: true
+  (...)
+{{< / highlight >}}
+

content/configuration/includes.md

@@ -0,0 +1,53 @@
+---
+Title: Includes
+Description: Compatible avec tous les types de fichiers décrits précédemment, ils représentent le meilleur moyen d'appliquer la méthode "DRY" en faisant référence à un autre fichier de référence.
+Weight: 80
+---
+
+Au sein d'une organisation, les différents [clusters]({{< ref "configuration/clusters" >}}) ont la plupart du temps un vaste nombre de métriques en commun. Dans un souci de code "DRY", l'outil [dir2config]({{< ref "cli/dir2config" >}}) gère l'héritage de configurations par le biais d'un mécanisme intitulé "includes", et qui permet comme son nom l'indique d'inclure des fichiers parents depuis des enfants afin d'éviter d'en répéter la configuration sur ceux-ci.
+
+Les [configurations]({{< ref "configuration" >}}) documentées ici (sauf les [hosts]({{< ref "configuration/hosts" >}}) bien entendu car forcément propres aux clusters) peuvent être définies dans un dossier parent au nom voulu et pouvant être placé n'importe où dans l'arborescence, elles seront alors appliquées par défaut à toutes les configurations. Par convention, il est tout de même conseillé d'utiliser le nom **defaults** pour ce dossier et c'est le nom qui sera utilisé dans la suite de cette documentation. Les différents clusters, hosts et configs du dossier courant pourront alors en hériter automatiquement.
+
+{{% notice note %}}
+Le dossier **defaults** PEUT être présent dans un répo git mais ce n'est pas obligatoire. 
+Egalement, il peut être situé dans un endroit totalement différent de l'arborescence et trouvable par dir2config grâce à l'utilisation d'un lien symbolique.
+{{% /notice %}}
+
+Voici un exemple commun d'arborescence :
+
+```
+./
+├─ defaults/
+│  ├─ addons/
+│  ├─ cert-requests.yaml
+│  ├─ clusters/
+│  ├─ configs/
+│  ├─ hosts/
+│  ├─ static-pods/
+│  ├─ ssl-config.json
+├─ clusters/
+├─ hosts/
+├─ includes.yaml            ## Ce fichier permet l'appel au dossier defaults
+```
+
+Les configurations héritées spécifient alors l'utilisation d'une configuration parente en appelant le dossier **defaults** voulu et la branche git optionnelle, par l'intermédiaire d'un fichier **includes.yaml** : 
+
+```
+- path: defaults
+  branch: v1.25            ## Optionnel
+```
+
+Avec cette configuration, le dossier "defaults" est recherché à la racine du dossier de configuration, ce qui peut être atteignable par un lien symbolique. A la suite de cette spécification, il est possible d'inclure des fichiers grâce à la spécification `#!include` en première ligne de configurations *clusters* et *hosts*. 
+
+Par exemple, le contenu du fichier **clusters/prod.yml** pourrait être :
+```
+#!include clusters/metal
+ ^--------------- mot clé invariable
+             ^-------- nom du dossier à hériter, pouvant être présent localement ou dans le dossier defaults
+                    ^--- nom du fichier à hériter (omettre l'extension .yaml)
+
+(... ajout des variables à écraser depuis le parent spécificé ci-dessus ...)
+```
+
+Ainsi, avec l'exemple précédent, le fichier **defaults/clusters/metal** dans la branche git v1.25 serait utilisé comme parent avec overwrite des variables enfants.
+