Guide 03 / 3
Configuration Kubernetes · YAML
Comprendre apiVersion, kind, metadata, spec et les principaux champs de Deployments, Services, ConfigMaps et PVC.
Rédiger et relire un ensemble cohérent de manifestes et prévoir ses conditions d’exécution.
01 · Anatomie d’un manifeste
Un manifeste décrit un objet Kubernetes. Les champs sont imbriqués : leur emplacement compte autant que leur nom.
apiVersion
Version du groupe d’API auquel appartient la ressource. Un Deployment utilise apps/v1, un Pod ou Service utilise v1.
Exemple
apiVersion: apps/v1
Ce champ ne signifie pas « version Kubernetes installée ».
kind
Type d’objet à créer : Deployment, Pod, Service, ConfigMap, Job, etc.
Exemple
kind: Deployment
metadata.name
Nom unique de l’objet à l’intérieur de son périmètre de nommage.
Exemple
metadata:
name: web
metadata.namespace
Namespace cible lorsqu’il s’agit d’une ressource namespacée.
Exemple
metadata:
namespace: dev
Le namespace doit déjà exister ou être déclaré ailleurs.
metadata.labels
Étiquettes associées à l’objet, pratiques pour le filtrage et la sélection.
Exemple
metadata:
labels:
app: web
metadata.annotations
Métadonnées complémentaires lisibles par des outils ou contrôleurs.
Exemple
metadata:
annotations:
exemple.fr/owner: formation
spec
Bloc décrivant l’état souhaité. Sa structure dépend du type d’objet (kind).
Exemple
spec:
replicas: 2
Un Service et un Deployment n’ont pas les mêmes champs spec.
status
Bloc rempli par le système décrivant la situation observée. Il est normalement consulté, non fourni par l’auteur.
Exemple
status.readyReplicas: 2
Ne pas inclure status dans les manifestes source.
02 · Décrire les conteneurs d’un Pod
Pour une application durable, ces champs se placent souvent sous spec.template.spec dans un Deployment.
spec.containers[].name
Nom distinctif du conteneur à l’intérieur du Pod ; kubectl peut s’en servir pour cibler les logs.
Exemple
containers:
- name: nginx
spec.containers[].image
Image de conteneur à télécharger et exécuter, avec nom et tag ou digest.
Exemple
image: nginx:stable
Ne pas compter sur latest pour des déploiements reproductibles.
spec.containers[].ports[].containerPort
Indication du port sur lequel l’application dans le conteneur est censée écouter.
Exemple
ports:
- containerPort: 80
Déclarer containerPort ne publie pas le Pod vers l’extérieur.
spec.containers[].command / args
command remplace l’ENTRYPOINT de l’image ; args remplace son CMD, selon la configuration de l’image.
Exemple
command: ["sh", "-c"]
args: ["echo bonjour; sleep 3600"]
Une commande mal définie peut provoquer CrashLoopBackOff.
spec.containers[].env
Déclare des variables d’environnement fournies au processus.
Exemple
env:
- name: MODE
value: "demo"
spec.containers[].envFrom
Importe plusieurs clés d’une ConfigMap ou d’un Secret comme variables d’environnement.
Exemple
envFrom:
- configMapRef:
name: web-config
Les changements d’environnement ne sont pas réinjectés dans un processus déjà lancé.
spec.containers[].resources.requests
Quantité de CPU et mémoire demandée pour la planification ; scheduler utilise ces valeurs pour choisir le nœud.
Exemple
requests:
cpu: 100m
memory: 64Mi
spec.containers[].resources.limits
Plafond de ressources imposé à l’exécution ; CPU peut être limité, mémoire peut provoquer un OOM kill.
Exemple
limits:
cpu: 500m
memory: 256Mi
spec.containers[].readinessProbe
Test périodique qui indique si le Pod peut recevoir du trafic via des Services.
Exemple
readinessProbe:
httpGet: {path: /, port: 80}
periodSeconds: 5
spec.containers[].livenessProbe
Test indiquant si le conteneur doit être redémarré car il ne répond plus correctement.
Exemple
livenessProbe:
httpGet: {path: /, port: 80}
initialDelaySeconds: 10
spec.containers[].startupProbe
Test optionnel qui laisse une application lente achever son démarrage avant les probes usuelles.
Exemple
startupProbe:
httpGet: {path: /, port: 80}
failureThreshold: 30
periodSeconds: 2
spec.imagePullSecrets
Référence un Secret contenant les identifiants d’accès à un registre privé, lorsque nécessaire.
Exemple
imagePullSecrets:
- name: registry-creds
03 · Deployment et autres contrôleurs
Deployment décrit non seulement une image, mais aussi comment la faire tourner et mettre à jour plusieurs fois.
Deployment.spec.replicas
Nombre de Pods souhaités pour l’application, gérés indirectement via un ReplicaSet.
Exemple
spec:
replicas: 3
Deployment.spec.selector.matchLabels
Labels permettant au contrôleur de reconnaître quels Pods appartiennent à ce Deployment.
Exemple
selector:
matchLabels:
app: web
Doit correspondre aux labels du template ; sélecteur immuable dans de nombreux cas.
Deployment.spec.template
Modèle de Pod que Kubernetes utilise pour créer les répliques. Contient metadata et spec du Pod.
Exemple
template:
metadata:
labels: {app: web}
spec:
containers: ...
Deployment.spec.strategy
Stratégie de mise à jour. RollingUpdate remplace progressivement les Pods, Recreate les renouvelle ensemble.
Exemple
strategy:
type: RollingUpdate
Pod.spec.restartPolicy
Indique quand redémarrer les conteneurs d’un Pod. Pour un Pod de Deployment, Always est imposé.
Exemple
restartPolicy: Always
Job permet aussi OnFailure ou Never.
Job.spec.template / backoffLimit
Le Job utilise un modèle de Pod et peut limiter le nombre de tentatives en cas d’échec.
Exemple
backoffLimit: 3
CronJob.spec.schedule
Expression cron à cinq champs permettant de créer des Jobs selon un calendrier.
Exemple
schedule: "0 2 * * *"
Vérifier le fuseau horaire via timeZone si nécessaire.
04 · Services, ports et entrée HTTP
Le Service choisit les Pods grâce aux labels et sépare l’adresse stable des instances éphémères.
Service.spec.type
Définit l’exposition du Service : ClusterIP par défaut, NodePort, LoadBalancer ou ExternalName.
Exemple
type: ClusterIP
Service.spec.selector
Labels des Pods vers lesquels router le trafic.
Exemple
selector:
app: web
Ne sélectionne aucun Pod si les labels diffèrent.
Service.spec.ports[].port
Port du Service que les clients appellent, par exemple 80.
Exemple
ports:
- port: 80
Service.spec.ports[].targetPort
Port du conteneur ou port nommé vers lequel le Service redirige le trafic.
Exemple
targetPort: 80
port et targetPort peuvent être différents.
Service.spec.ports[].nodePort
Port accessible sur les nœuds avec type NodePort ; doit être dans la plage configurée.
Exemple
nodePort: 30080
N’ouvre pas automatiquement les pare-feu du système.
Ingress.spec.ingressClassName
Nom de la classe d’Ingress utilisée pour choisir le contrôleur approprié.
Exemple
ingressClassName: nginx
Un contrôleur d’Ingress doit exister et gérer cette classe.
Ingress.spec.rules
Définit des hôtes et chemins HTTP qui envoient vers des Services du cluster.
Exemple
rules:
- host: web.exemple.test
Ingress.spec.tls
Associe des hôtes TLS à un Secret de certificat pour servir HTTPS.
Exemple
tls:
- hosts: [web.exemple.test]
secretName: web-tls
05 · Configuration et stockage
Il faut distinguer configuration applicative, secrets et données qui doivent survivre à la disparition d’un Pod.
ConfigMap.data
Ensemble clé-valeur pour des paramètres non sensibles, consommés par des Pods.
Exemple
data:
MODE: "production"
Secret.stringData / data
stringData accepte du texte brut à l’entrée ; data porte des valeurs encodées en base64.
Exemple
stringData:
PASSWORD: exemple-fictif
Ne jamais committer de vrais secrets. Base64 n’est pas du chiffrement.
spec.volumes
Déclare les volumes disponibles dans le Pod : emptyDir, Secret, ConfigMap, PVC, etc.
Exemple
volumes:
- name: cache
emptyDir: {}
volumeMounts
Définit où un volume déclaré est visible dans un conteneur.
Exemple
volumeMounts:
- name: cache
mountPath: /tmp/cache
persistentVolumeClaim.claimName
Lie un volume du Pod à un PVC déjà déclaré, pour un stockage persistant.
Exemple
volumes:
- name: donnees
persistentVolumeClaim:
claimName: donnees-pvc
PVC.spec.accessModes
Demande les modes d’accès pris en charge par le stockage, par exemple ReadWriteOnce.
Exemple
accessModes: [ReadWriteOnce]
RWO ne signifie pas forcément « un seul Pod » ; voir la sémantique du volume.
PVC.spec.resources.requests.storage
Quantité de stockage demandée au système de stockage.
Exemple
resources:
requests:
storage: 2Gi
PVC.spec.storageClassName
Nom de la classe de stockage demandée ; sa disponibilité dépend du cluster.
Exemple
storageClassName: standard
Sans provisionneur ni PV compatible, un PVC peut rester Pending.
06 · Sécurité et placement
Ces champs influencent l’identité du processus, les permissions des workloads et leur placement sur les nœuds.
securityContext.runAsNonRoot
Demande que le processus ne s’exécute pas avec l’UID 0 dans le conteneur.
Exemple
securityContext:
runAsNonRoot: true
L’image doit être compatible avec un utilisateur non-root.
securityContext.allowPrivilegeEscalation
Empêche, lorsque pris en charge, qu’un processus obtienne de nouveaux privilèges à l’exécution.
Exemple
allowPrivilegeEscalation: false
securityContext.readOnlyRootFilesystem
Monte le système de fichiers racine du conteneur en lecture seule.
Exemple
readOnlyRootFilesystem: true
Prévoir des volumes pour les chemins devant rester modifiables.
securityContext.capabilities.drop
Permet de retirer des capacités Linux non nécessaires au processus.
Exemple
capabilities:
drop: ["ALL"]
spec.serviceAccountName
Associe au Pod une identité de workload Kubernetes, utilisée notamment pour ses demandes à l’API.
Exemple
serviceAccountName: lecteur-pods
Ne pas accorder plus de permissions que nécessaire.
RBAC Role / RoleBinding
Role décrit des règles dans un namespace ; RoleBinding accorde ce rôle à un sujet.
Exemple
resources: ["pods"]
verbs: ["get", "list"]
ClusterRole et ClusterRoleBinding concernent les permissions réutilisables ou à portée cluster.
nodeSelector / affinity
Contraignent ou orientent la sélection d’un nœud selon ses labels ou des relations entre Pods.
Exemple
nodeSelector:
kubernetes.io/os: linux
tolerations / taints
Un taint permet de repousser certains Pods ; une toleration autorise un Pod compatible à être planifié malgré ce taint.
Exemple
tolerations:
- key: dedicated
operator: Equal
value: lab
effect: NoSchedule
La toleration n’oblige pas à choisir ce nœud.
NetworkPolicy.spec.podSelector
Détermine quels Pods du namespace sont soumis à une NetworkPolicy.
Exemple
podSelector:
matchLabels: {app: db}
L’application exige un CNI compatible.
07 · Confusions fréquentes
Certaines propriétés ressemblent à celles de Docker Compose, mais le comportement de Kubernetes est différent.
containerPort ≠ exposition publique
containerPort décrit le port du conteneur ; un Service, puis éventuellement Ingress ou Gateway, définit l’accès réseau voulu.
Exemple
containerPort: 80 ≠ LoadBalancer
Labels ≠ noms de services
Les selectors relient Services, Deployments et Pods selon des labels ; ce sont ces correspondances qui déterminent le routage.
Exemple
Service selector.app = Pod label.app
Readiness ≠ liveness
Readiness évite d’envoyer du trafic à un Pod pas prêt ; liveness déclenche un redémarrage en cas d’échec.
Exemple
/ready → trafic ; /live → redémarrage
Request ≠ limit
Request sert à la planification ; limit plafonne l’utilisation à l’exécution.
Exemple
100m CPU de request, 500m de limit
Secret ≠ chiffrement garanti
Un Secret sépare les informations sensibles, mais ses données base64 peuvent être lisibles sans chiffrement au repos ni RBAC adaptés.
Exemple
Protéger etcd + accès API + Git
Deployment ≠ StatefulSet
Deployment convient à des services interchangeables ; StatefulSet fournit des identités stables, souvent utiles aux charges avec stockage attaché.
Exemple
web → Deployment ; base distribuée → StatefulSet
08 · Manifestes complets
Ces fichiers complets correspondent aux annexes du guide PDF et sont copiables dans les fiches du site.
deployment.yaml
Déclare deux répliques Nginx avec ressources réservées et un test de disponibilité HTTP.
Exemple
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
namespace: dev
spec:
replicas: 2
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: nginx
image: nginx:stable
ports:
- containerPort: 80
resources:
requests:
cpu: 100m
memory: 64Mi
limits:
memory: 256Mi
readinessProbe:
httpGet:
path: /
port: 80
periodSeconds: 5
À appliquer après création du namespace dev.
service.yaml
Crée un point d’accès interne stable vers les Pods portant le label app: web.
Exemple
apiVersion: v1
kind: Service
metadata:
name: web
namespace: dev
spec:
type: ClusterIP
selector:
app: web
ports:
- name: http
port: 80
targetPort: 80
Le Service ne fonctionnera que si le sélecteur correspond aux labels des Pods.
configmap.yaml
Crée deux paramètres applicatifs non confidentiels dans le namespace dev.
Exemple
apiVersion: v1
kind: ConfigMap
metadata:
name: web-config
namespace: dev
data:
APP_MODE: "demo"
LOG_LEVEL: "info"
pvc.yaml
Demande 2 Gi de stockage persistant ; le provisionnement dépend de la configuration du cluster.
Exemple
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: donnees-pvc
namespace: dev
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 2Gi
# La StorageClass disponible dépend du cluster.
Vérifier kubectl get storageclass, puis kubectl get pvc -n dev.
job.yaml
Exécute une tâche ponctuelle puis termine ; ne sert pas à héberger un serveur HTTP.
Exemple
apiVersion: batch/v1
kind: Job
metadata:
name: essai
namespace: dev
spec:
backoffLimit: 2
template:
spec:
restartPolicy: Never
containers:
- name: test
image: busybox:1.36
command: ["sh", "-c", "echo TP Kubernetes"]