Guide 03 / 3
Kubernetes configuration · YAML
Understand apiVersion, kind, metadata, spec and the main fields of Deployments, Services, ConfigMaps and PVCs.
Write and review a consistent set of manifests and anticipate its runtime conditions.
01 · Anatomy of a manifest
A manifest describes a Kubernetes object. The fields are nested: their location matters as much as their name.
apiVersion
The version of the API group the resource belongs to. A Deployment uses apps/v1, a Pod or Service uses v1.
Example
apiVersion: apps/v1
This field does not mean “installed Kubernetes version”.
kind
The type of object to create: Deployment, Pod, Service, ConfigMap, Job, etc.
Example
kind: Deployment
metadata.name
The object's unique name within its naming scope.
Example
metadata:
name: web
metadata.namespace
The target namespace when the resource is namespaced.
Example
metadata:
namespace: dev
The namespace must already exist or be declared elsewhere.
metadata.labels
Labels attached to the object, handy for filtering and selection.
Example
metadata:
labels:
app: web
metadata.annotations
Additional metadata readable by tools or controllers.
Example
metadata:
annotations:
exemple.fr/owner: formation
spec
The block describing the desired state. Its structure depends on the object type (kind).
Example
spec:
replicas: 2
A Service and a Deployment do not have the same spec fields.
status
A block filled in by the system describing the observed situation. It is normally read, not supplied by the author.
Example
status.readyReplicas: 2
Do not include status in source manifests.
02 · Describing a Pod's containers
For a durable application, these fields are often placed under spec.template.spec in a Deployment.
spec.containers[].name
The container's distinctive name inside the Pod; kubectl can use it to target logs.
Example
containers:
- name: nginx
spec.containers[].image
The container image to download and run, with a name and a tag or digest.
Example
image: nginx:stable
Do not rely on latest for reproducible deployments.
spec.containers[].ports[].containerPort
An indication of the port on which the application in the container is meant to listen.
Example
ports:
- containerPort: 80
Declaring containerPort does not publish the Pod to the outside.
spec.containers[].command / args
command replaces the image's ENTRYPOINT; args replaces its CMD, depending on the image's configuration.
Example
command: ["sh", "-c"]
args: ["echo bonjour; sleep 3600"]
A badly defined command can cause CrashLoopBackOff.
spec.containers[].env
Declares environment variables supplied to the process.
Example
env:
- name: MODE
value: "demo"
spec.containers[].envFrom
Imports several keys from a ConfigMap or Secret as environment variables.
Example
envFrom:
- configMapRef:
name: web-config
Environment changes are not re-injected into a process that is already running.
spec.containers[].resources.requests
The amount of CPU and memory requested for scheduling; the scheduler uses these values to choose the node.
Example
requests:
cpu: 100m
memory: 64Mi
spec.containers[].resources.limits
The resource ceiling enforced at run time; CPU can be throttled, memory can cause an OOM kill.
Example
limits:
cpu: 500m
memory: 256Mi
spec.containers[].readinessProbe
A periodic test that indicates whether the Pod can receive traffic via Services.
Example
readinessProbe:
httpGet: {path: /, port: 80}
periodSeconds: 5
spec.containers[].livenessProbe
A test indicating whether the container should be restarted because it no longer responds correctly.
Example
livenessProbe:
httpGet: {path: /, port: 80}
initialDelaySeconds: 10
spec.containers[].startupProbe
An optional test that lets a slow application finish starting before the usual probes.
Example
startupProbe:
httpGet: {path: /, port: 80}
failureThreshold: 30
periodSeconds: 2
spec.imagePullSecrets
References a Secret holding the credentials for accessing a private registry, when needed.
Example
imagePullSecrets:
- name: registry-creds
03 · Deployment and other controllers
A Deployment describes not only an image, but also how to run it and update it several times.
Deployment.spec.replicas
The number of Pods wanted for the application, managed indirectly through a ReplicaSet.
Example
spec:
replicas: 3
Deployment.spec.selector.matchLabels
Labels that let the controller recognise which Pods belong to this Deployment.
Example
selector:
matchLabels:
app: web
Must match the template's labels; the selector is immutable in many cases.
Deployment.spec.template
The Pod template Kubernetes uses to create the replicas. Contains the Pod's metadata and spec.
Example
template:
metadata:
labels: {app: web}
spec:
containers: ...
Deployment.spec.strategy
The update strategy. RollingUpdate gradually replaces the Pods, Recreate renews them all together.
Example
strategy:
type: RollingUpdate
Pod.spec.restartPolicy
Indicates when to restart a Pod's containers. For a Deployment's Pod, Always is imposed.
Example
restartPolicy: Always
Job also allows OnFailure or Never.
Job.spec.template / backoffLimit
The Job uses a Pod template and can limit the number of attempts on failure.
Example
backoffLimit: 3
CronJob.spec.schedule
A five-field cron expression used to create Jobs on a calendar.
Example
schedule: "0 2 * * *"
Check the time zone via timeZone if needed.
04 · Services, ports and HTTP entry
The Service chooses Pods using labels and separates the stable address from the ephemeral instances.
Service.spec.type
Defines the Service's exposure: ClusterIP by default, NodePort, LoadBalancer or ExternalName.
Example
type: ClusterIP
Service.spec.selector
Labels of the Pods to route traffic to.
Example
selector:
app: web
Selects no Pod if the labels differ.
Service.spec.ports[].port
The Service port that clients call, for example 80.
Example
ports:
- port: 80
Service.spec.ports[].targetPort
The container port or named port to which the Service redirects traffic.
Example
targetPort: 80
port and targetPort can be different.
Service.spec.ports[].nodePort
A port reachable on the nodes with type NodePort; must be within the configured range.
Example
nodePort: 30080
Does not automatically open the system's firewalls.
Ingress.spec.ingressClassName
The name of the Ingress class used to pick the appropriate controller.
Example
ingressClassName: nginx
An Ingress controller must exist and handle this class.
Ingress.spec.rules
Defines HTTP hosts and paths that route to cluster Services.
Example
rules:
- host: web.exemple.test
Ingress.spec.tls
Associates TLS hosts with a certificate Secret to serve HTTPS.
Example
tls:
- hosts: [web.exemple.test]
secretName: web-tls
05 · Configuration and storage
You must distinguish application configuration, secrets and data that must survive the disappearance of a Pod.
ConfigMap.data
A key-value set for non-sensitive parameters, consumed by Pods.
Example
data:
MODE: "production"
Secret.stringData / data
stringData accepts plain text on input; data carries base64-encoded values.
Example
stringData:
PASSWORD: exemple-fictif
Never commit real secrets. Base64 is not encryption.
spec.volumes
Declares the volumes available in the Pod: emptyDir, Secret, ConfigMap, PVC, etc.
Example
volumes:
- name: cache
emptyDir: {}
volumeMounts
Defines where a declared volume is visible in a container.
Example
volumeMounts:
- name: cache
mountPath: /tmp/cache
persistentVolumeClaim.claimName
Links a Pod volume to an already declared PVC, for persistent storage.
Example
volumes:
- name: donnees
persistentVolumeClaim:
claimName: donnees-pvc
PVC.spec.accessModes
Requests the access modes supported by the storage, for example ReadWriteOnce.
Example
accessModes: [ReadWriteOnce]
RWO does not necessarily mean “a single Pod”; see the volume's semantics.
PVC.spec.resources.requests.storage
The amount of storage requested from the storage system.
Example
resources:
requests:
storage: 2Gi
PVC.spec.storageClassName
The name of the requested storage class; its availability depends on the cluster.
Example
storageClassName: standard
Without a provisioner or compatible PV, a PVC can stay Pending.
06 · Security and placement
These fields influence the process's identity, the workloads' permissions and their placement on nodes.
securityContext.runAsNonRoot
Requires that the process not run with UID 0 in the container.
Example
securityContext:
runAsNonRoot: true
The image must be compatible with a non-root user.
securityContext.allowPrivilegeEscalation
Prevents, where supported, a process from gaining new privileges at run time.
Example
allowPrivilegeEscalation: false
securityContext.readOnlyRootFilesystem
Mounts the container's root file system read-only.
Example
readOnlyRootFilesystem: true
Provide volumes for the paths that must stay writable.
securityContext.capabilities.drop
Lets you remove Linux capabilities the process does not need.
Example
capabilities:
drop: ["ALL"]
spec.serviceAccountName
Associates a Kubernetes workload identity with the Pod, used notably for its requests to the API.
Example
serviceAccountName: lecteur-pods
Do not grant more permissions than necessary.
RBAC Role / RoleBinding
Role describes rules within a namespace; RoleBinding grants that role to a subject.
Example
resources: ["pods"]
verbs: ["get", "list"]
ClusterRole and ClusterRoleBinding concern reusable or cluster-wide permissions.
nodeSelector / affinity
Constrain or steer the choice of a node according to its labels or to relationships between Pods.
Example
nodeSelector:
kubernetes.io/os: linux
tolerations / taints
A taint repels certain Pods; a toleration allows a compatible Pod to be scheduled despite that taint.
Example
tolerations:
- key: dedicated
operator: Equal
value: lab
effect: NoSchedule
A toleration does not force the choice of that node.
NetworkPolicy.spec.podSelector
Determines which Pods in the namespace are subject to a NetworkPolicy.
Example
podSelector:
matchLabels: {app: db}
The application requires a compatible CNI.
07 · Common mix-ups
Some properties look like those of Docker Compose, but Kubernetes's behaviour is different.
containerPort ≠ public exposure
containerPort describes the container's port; a Service, then possibly an Ingress or Gateway, defines the network access wanted.
Example
containerPort: 80 ≠ LoadBalancer
Labels ≠ service names
Selectors link Services, Deployments and Pods by labels; these matches are what determine routing.
Example
Service selector.app = Pod label.app
Readiness ≠ liveness
Readiness avoids sending traffic to a Pod that is not ready; liveness triggers a restart on failure.
Example
/ready → trafic ; /live → redémarrage
Request ≠ limit
Request is used for scheduling; limit caps usage at run time.
Example
100m CPU de request, 500m de limit
Secret ≠ guaranteed encryption
A Secret separates sensitive information, but its base64 data can be readable without encryption at rest or suitable RBAC.
Example
Protéger etcd + accès API + Git
Deployment ≠ StatefulSet
A Deployment suits interchangeable services; a StatefulSet provides stable identities, often useful for workloads with attached storage.
Example
web → Deployment ; base distribuée → StatefulSet
08 · Complete manifests
These complete files match the appendices of the PDF guide and can be copied from the site's sheets.
deployment.yaml
Declares two Nginx replicas with reserved resources and an HTTP availability probe.
Example
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
To apply after creating the dev namespace.
service.yaml
Creates a stable internal access point to the Pods carrying the label app: web.
Example
apiVersion: v1
kind: Service
metadata:
name: web
namespace: dev
spec:
type: ClusterIP
selector:
app: web
ports:
- name: http
port: 80
targetPort: 80
The Service will only work if the selector matches the Pods' labels.
configmap.yaml
Creates two non-confidential application settings in the dev namespace.
Example
apiVersion: v1
kind: ConfigMap
metadata:
name: web-config
namespace: dev
data:
APP_MODE: "demo"
LOG_LEVEL: "info"
pvc.yaml
Requests 2 Gi of persistent storage; provisioning depends on the cluster's configuration.
Example
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: donnees-pvc
namespace: dev
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 2Gi
# La StorageClass disponible dépend du cluster.
Check kubectl get storageclass, then kubectl get pvc -n dev.
job.yaml
Runs a one-off task then finishes; not meant to host an HTTP server.
Example
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"]