Structurer un cookbook Chef propre

Un cookbook n'est pas qu'un fichier de recette : c'est un projet, avec une arborescence à respecter. Tout entasser dans default.rb fonctionne au début, puis devient illisible. Ce guide présente l'anatomie standard d'un cookbook, le rôle de metadata.rb, et comment découper en recettes par responsabilité pour rester maintenable. On déploie le cookbook sur la vraie VM web1 avec knife-zero, comme au guide de déploiement. Public visé : lecteur ayant terminé le Volet 1 des fondamentaux, déploiement sur une VM compris. Testé avec CINC Client 19.3.14 et knife-zero 2.6.0 sur une VM Debian 13.

Ce que vous allez apprendre

• Comprendre le rôle de chaque dossier d'un cookbook.
• Renseigner metadata.rb : nom, version, licence, dépendances.
• Découper un cookbook en recettes par responsabilité.
• Documenter et versionner proprement.

Prérequis

• Le Volet 1 terminé, dont Déployer sur une vraie VM (knife-zero) : vous disposez de la VM web1, du dépôt ~/chef-parc et de son .chef/config.rb.

L'arborescence standard

cinc generate cookbook produit déjà les bons dossiers. Chacun a un rôle précis, et Chef sait où chercher automatiquement.

• Répertoirewebstack/

  • metadata.rb carte d'identité du cookbook
  • README.md documentation
  • Policyfile.rb run list et dépendances verrouillées
  • Répertoireattributes/

    • default.rb les valeurs paramétrables
  • Répertoirerecipes/

    • default.rb point d'entrée
    • install.rb une responsabilité
    • config.rb une autre responsabilité
  • Répertoiretemplates/

    • site.conf.erb modèles ERB
  • Répertoirefiles/ fichiers statiques (cookbook_file)

    • …
  • Répertoireresources/ ressources personnalisées

    • …
  • Répertoiretest/ tests d'intégration

    • …

La règle à retenir : un dossier par type de contenu. On ne met pas un template dans files/, ni une valeur en dur dans une recette quand attributes/ existe. Cette discipline rend n'importe quel cookbook lisible au premier coup d'œil, même écrit par quelqu'un d'autre.

metadata.rb : la carte d'identité

Le fichier metadata.rb décrit le cookbook pour Chef et pour les autres. C'est lui qu'on lit en premier pour savoir ce que fait un cookbook et de quoi il dépend.

name 'webstack'
maintainer 'Equipe plateforme'
license 'Apache-2.0'
description 'Installe et configure un serveur web nginx'
version '1.0.0'
chef_version '>= 18.0'
supports 'debian'

Trois champs méritent l'attention. version suit le versionnage sémantique (MAJEUR.MINEUR.CORRECTIF) : on l'incrémente à chaque changement publié. chef_version annonce la version minimale de Chef requise. supports liste les systèmes testés. Pour dépendre d'un autre cookbook, on ajoute une ligne depends 'nom' ; la résolution des dépendances est gérée par le Policyfile, sujet d'un guide dédié.

Découper en recettes par responsabilité

Une recette fourre-tout mélange installation, configuration et service. On sépare par responsabilité : une recette qui installe, une qui configure, et une recette default qui orchestre en les incluant.

default.rb

include_recipe 'webstack::install'
include_recipe 'webstack::config'

Le point d'entrée ne fait qu'orchestrer : il dit dans quel ordre jouer les recettes spécialisées.

install.rb

apt_update 'mise a jour du cache' do
  action :update
end

package 'nginx'

Une seule responsabilité : installer le nécessaire (avec le rafraîchissement du cache apt avant l'installation).

attributes/default.rb

default['webstack']['racine'] = '/var/www/webstack'
default['webstack']['port']   = 8080

Les valeurs que lisent les recettes, rangées hors du code.

config.rb

directory node['webstack']['racine'] do
  mode '0755'
end

template '/etc/nginx/conf.d/webstack.conf' do
  source 'site.conf.erb'
  variables(port: node['webstack']['port'], racine: node['webstack']['racine'])
  notifies :reload, 'service[nginx]', :delayed
end

file "#{node['webstack']['racine']}/index.html" do
  content "webstack\n"
  mode '0644'
end

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

L'autre responsabilité : configurer et démarrer le service.

On déploie ce cookbook sur la VM web1. On range webstack dans ~/chef-parc/cookbooks/, on pointe le run list du nœud dessus, puis on converge :

knife node run_list set web1 'recipe[webstack::default]' -c .chef/config.rb
knife zero converge 'name:web1' -c .chef/config.rb

La sortie reflète l'organisation : chaque recette apparaît sous son propre bandeau.

Recipe: webstack::install
  * apt_update[mise a jour du cache] action update
  * apt_package[nginx] action install
    - install version 1.26.3-3+deb13u7 of package nginx
Recipe: webstack::config
  * directory[/var/www/webstack] action create
  * template[/etc/nginx/conf.d/webstack.conf] action create
  * file[/var/www/webstack/index.html] action create
  * service[nginx] action enable (up to date)
  * service[nginx] action start
  * service[nginx] action reload
Infra Phase complete, 7/12 resources updated in 04 seconds

Chaque recette reste courte et compréhensible, et la structure se lit dans la sortie. Vérifiez la page servie par la VM (le site écoute sur le port 8080 de l'attribut) :

curl http://192.168.122.167:8080/

webstack

Documenter et versionner

Deux fichiers portent la mémoire du cookbook. Le README.md explique ce que fait le cookbook, ses attributs et un exemple d'usage : c'est la première chose que lira un collègue. Le champ version de metadata.rb se bumpe à chaque changement publié, pour que les consommateurs sachent qu'une nouvelle version existe et laquelle ils utilisent.

Un cookbook, un rôle

Résistez à la tentation du cookbook géant qui installe la base de données, le serveur web et le monitoring. Un cookbook = un rôle (un serveur web, un agent...). C'est plus facile à tester, à versionner et à réutiliser. On compose ensuite plusieurs cookbooks via le run list.

Exercice : ajouter une recette

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

Énoncé

Ajoutez une recette recipes/tuning.rb qui dépose un fichier /etc/sysctl.d/99-webstack.conf (contenu au choix), puis faites-la jouer par le cookbook. À la convergence, un nouveau bandeau Recipe: webstack::tuning doit apparaître.

Indice : la recette default orchestre avec include_recipe.

Réponse

On crée la recette dédiée :

recipes/tuning.rb

file '/etc/sysctl.d/99-webstack.conf' do
  content "net.core.somaxconn = 1024\n"
  mode '0644'
end

Puis on l'inclut dans le point d'entrée :

recipes/default.rb

include_recipe 'webstack::install'
include_recipe 'webstack::config'
include_recipe 'webstack::tuning'

On reconverge avec knife zero converge 'name:web1' -c .chef/config.rb : la sortie affiche le nouveau bandeau Recipe: webstack::tuning avec sa ressource file. La responsabilité « réglages système » vit désormais dans son propre fichier.

À retenir

• Un cookbook a une arborescence standard : un dossier par type de contenu (recipes/, attributes/, templates/, files/, resources/).
• metadata.rb est la carte d'identité : name, version (sémantique), license, chef_version, supports, depends.
• On découpe en recettes par responsabilité ; une recette default orchestre avec include_recipe.
• Un cookbook = un rôle : plus facile à tester, versionner et réutiliser.
• On documente dans README.md et on bumpe la version à chaque changement publié.

×

📖 Voir la documentation →