Votre premier cookbook Chef avec Test Kitchen

logo chef

Un cookbook est l'unité de travail de Chef : il décrit l'état voulu d'une machine dans des recettes. Ce guide en génère un, y écrit une recette qui installe un serveur web, puis le fait converger dans un conteneur Docker jetable grâce à Test Kitchen et son driver dokken. L'intérêt : aucune installation sur la cible, tout est piloté depuis votre poste par une seule commande, kitchen converge. Vous verrez surtout la propriété clé de Chef, l'idempotence : jouer le cookbook deux fois ne change rien la seconde fois. Public visé : débutant ayant installé CINC Workstation. Testé avec CINC Client 19.3.14 et kitchen-dokken sur Ubuntu 24.04.

Ce que vous allez apprendre

Générer un cookbook avec cinc generate.
Configurer Test Kitchen avec le driver dokken (Docker).
Converger un conteneur jetable avec kitchen converge, sans rien installer dessus.
Prouver l'idempotence avec un second passage.

Prérequis

CINC Workstation installé sur votre poste.
Docker installé et fonctionnel.

Pourquoi Test Kitchen et dokken

Test Kitchen est l'outil standard pour tester un cookbook : il crée une machine jetable, y applique votre cookbook, puis la détruit. Son driver dokken utilise Docker et, surtout, n'installe rien sur la cible : il monte l'image client officielle cincproject/cinc et votre cookbook dans un conteneur, puis lance la convergence. Résultat : pas d'agent à installer, pas de SSH, pas de serveur. Tout se pilote depuis votre poste, et un cycle complet prend quelques secondes.

C'est aussi le workflow qu'utilisent les équipes Chef au quotidien : l'apprendre, c'est apprendre la vraie pratique du métier.

Générer la structure du cookbook

On ne crée pas un cookbook à la main : le générateur produit une arborescence standard, avec les recettes, les tests et un fichier kitchen.yml déjà présent.

Créer un espace de travail et générer le cookbook :

mkdir -p ~/chef-webserver/cookbooks
cd ~/chef-webserver/cookbooks
cinc generate cookbook webserver
cd webserver

Regarder ce qui a été créé :
Fenêtre de terminal
```
ls
```
```
CHANGELOG.md  kitchen.yml  LICENSE  metadata.rb  Policyfile.rb  README.md  recipes  test  ...
```
Le dossier recipes/ contient les recettes, dont default.rb, la recette jouée par défaut. Le fichier kitchen.yml pilote Test Kitchen. Le reste (metadata, tests) servira plus tard.

Écrire la recette

Ouvrez recipes/default.rb et décrivez l'état voulu : le paquet installé, une page d'accueil, le service démarré.

package "nginx"

file "/var/www/html/index.html" do
  content "Bonjour depuis Chef via CINC\n"
  mode "0644"
end

service "nginx" do
  action [:enable, :start]
end

Chaque bloc est une ressource : un état à atteindre, pas une commande à lancer. package "nginx" signifie « nginx doit être installé », pas « exécute apt install ». C'est cette différence qui rend le cookbook rejouable sans danger.

Configurer Test Kitchen pour Docker

Le générateur a créé un kitchen.yml prévu pour des VM. Remplacez-le par cette configuration dokken, qui cible un conteneur Docker :

---
driver:
  name: dokken
  chef_version: "19.3.14"
  chef_image: cincproject/cinc

provisioner:
  name: dokken
  product_name: cinc

transport:
  name: dokken

verifier:
  name: inspec

platforms:
  - name: ubuntu-24.04
    driver:
      image: dokken/ubuntu-24.04

suites:
  - name: default
    run_list:
      - recipe[webserver::default]

Trois réglages font tout le travail : chef_image: cincproject/cinc fournit l'agent CINC sans l'installer, product_name: cinc indique d'utiliser CINC (et de sauter la licence), et l'image dokken/ubuntu-24.04 est le système cible. La section suites désigne la recette à appliquer.

Converger le conteneur

Une seule commande crée le conteneur, y monte l'agent et le cookbook, puis applique la recette :

kitchen converge

À la première exécution, Chef installe ce qui manque :

-----> Converging <default-ubuntu-2404>...
       Converging 3 resources
       Recipe: webserver::default
         * apt_package[nginx] action install
           - install version 1.24.0-2ubuntu7.13 of package nginx
         * file[/var/www/html/index.html] action create
           - create new file /var/www/html/index.html
         * service[nginx] action enable (up to date)
         * service[nginx] action start
           - start service service[nginx]
       Infra Phase complete, 3/4 resources updated in 03 seconds

Trois ressources sur quatre ont été mises à jour : le paquet installé, la page créée et le service démarré. Rien n'a été installé à la main sur la cible : dokken a monté l'agent depuis l'image cincproject/cinc.

Vérifier le résultat

Lancez une commande dans le conteneur depuis votre poste pour confirmer que la page est servie :

kitchen exec -c "curl -s localhost"

Bonjour depuis Chef via CINC

Prouver l'idempotence

C'est le test qui distingue Chef d'un script shell. Relancez exactement la même commande :

kitchen converge

Infra Phase complete, 0/4 resources updated in 01 seconds

Zéro ressource mise à jour : l'état voulu est déjà atteint, Chef ne refait rien. Un script shell aurait relancé apt install et réécrit le fichier ; Chef, lui, compare l'état courant à l'état voulu et n'agit que si nécessaire. C'est l'idempotence, la garantie qu'on peut converger aussi souvent qu'on veut sans effet de bord.

Quand vous avez terminé, le conteneur se supprime d'une commande, et vous repartez d'une cible propre au prochain essai :

kitchen destroy

Exercice : ajouter une page d'erreur

Étendez le cookbook. Cherchez la solution avant d'ouvrir la réponse.

Énoncé
Réponse

Ajoutez à la recette une seconde page, /var/www/html/404.html, avec le contenu Page introuvable. Sans détruire le conteneur en cours :

convergez une première fois : une ressource doit être mise à jour ;
convergez une seconde fois : zéro ressource mise à jour.

Indice : c'est la même ressource file que pour la page d'accueil. Éditez la recette, puis relancez kitchen converge.

On ajoute une ressource file identique dans la recette :

file "/var/www/html/404.html" do
  content "Page introuvable\n"
  mode "0644"
end

Puis on reconverge le conteneur déjà en place :

kitchen converge

Première convergence après l'ajout :

  * file[/var/www/html/404.html] action create
Infra Phase complete, 1/5 resources updated in 01 seconds

Seconde convergence : 0/5 resources updated. La nouvelle page est créée au premier passage, puis plus rien au second. Chaque ressource ajoutée suit la même logique : Chef n'agit que sur l'écart entre l'état courant et l'état voulu.

À retenir

Un cookbook se génère avec cinc generate cookbook ; il contient déjà un kitchen.yml.
Une recette décrit des ressources (état voulu), pas des commandes.
Le driver dokken converge un conteneur Docker jetable sans rien installer sur la cible : il monte l'agent depuis l'image cincproject/cinc.
kitchen converge applique le cookbook, kitchen exec vérifie, kitchen destroy nettoie. Tout depuis le poste.
L'idempotence se prouve par un second passage à 0 ressource mise à jour : c'est ce qui distingue Chef d'un script.

Prochaines étapes

Installer CINC Workstation Revenir sur l'installation du poste de travail.

La formation Chef avec CINC La suite du parcours (ressources, attributs, templates...) est ici.

CINC Auditor : la conformité Vérifier automatiquement l'état d'une machine.