YAML pentru Kubernetes
Până acum ai creat poduri cu kubectl run și opțiuni în linia de comandă. Pentru aplicații adevărate, cu zeci de setări, Kubernetes folosește fișiere YAML, aceleași ca docker-compose.yml de la cursul de Docker. În această lecție înveți cât YAML îți trebuie, cele patru câmpuri ale oricărui obiect Kubernetes și greșelile care apar cel mai des.
De ce fișiere
O comandă kubectl run cu cinci opțiuni e greu de citit, de recitit peste o lună și imposibil de revizuit de un coleg. Un fișier, în schimb:
- descrie complet obiectul: imaginea, porturile, variabilele, resursele;
- poate fi pus în Git, cu istoric și revizuire, ca orice cod;
- se poate aplica din nou oricând, pe orice cluster, cu același rezultat.
Formatul ales de Kubernetes este YAML (JSON e acceptat și el, dar aproape nimeni nu îl scrie de mână).
Sintaxa YAML cât îți trebuie
| Regulă | Exemplu |
|---|---|
| perechi cheie: valoare (cu spațiu după două puncte) | name: pagina |
| indentarea arată ce aparține cui; doar spații, de obicei 2 pe nivel | metadata: urmat de name: pagina |
| liste: fiecare element începe cu - | - name: pagina |
| șiruri: de obicei fără ghilimele; cu ghilimele când arată ca un număr sau conțin : | versiune: "1", mesaj: "Ora: 10" |
| comentarii cu # | # podul de test |
| mai multe obiecte în același fișier, despărțite de --- | un Namespace, ---, un Pod |
Un exemplu mic, fără legătură cu Kubernetes, ca să vezi toate regulile la un loc:
cat > ~/k8s/exemplu.yaml <<'EOF' # un magazin, descris in YAML magazin: Academia oras: Bucuresti deschis: true produse: - nume: laptop pret: 3500 - nume: mouse pret: 80 cod_postal: "010101" EOF cat ~/k8s/exemplu.yaml | grep -c nume
2
produse este o listă cu două elemente, iar fiecare element are două chei (nume, pret) aliniate sub el. cod_postal are ghilimele, altfel YAML l-ar citi ca număr și ar pierde zeroul din față. grep -c nume numără rândurile cu „nume”: două, unul pentru fiecare produs.
Comanda cat > fișier <<'EOF' … EOF de la cursul de Linux scrie tot textul dintre cele două EOF în fișier. O folosim în exemple ca să vezi fișierul întreg; tu poți scrie același text și în tabul Editor YAML.
Cele patru câmpuri ale oricărui obiect
Orice obiect Kubernetes, fie el Pod, Deployment sau Service, începe cu aceleași patru câmpuri:
| Câmp | Ce conține | Pentru un pod |
|---|---|---|
| apiVersion | versiunea API-ului în care e definit tipul | v1 |
| kind | tipul obiectului | Pod |
| metadata | numele, etichetele, namespace-ul | name: pagina |
| spec | starea dorită: ce vrei să existe | containerele, imaginile, porturile |
Există și un al cincilea, status, pe care nu îl scrii tu: îl completează clusterul cu starea reală (faza, IP-ul, nodul). Starea dorită (spec) și starea reală (status) stau una lângă alta, exact ideea din lecția 1.
Din kubectl api-resources (coloana APIVERSION, lecția 3): podurile sunt v1, Deployment-urile apps/v1, Job-urile batch/v1.
Un pod în YAML
Podul pagina, cu eticheta app: pagina și portul 80, arată așa:
apiVersion: v1
kind: Pod
metadata:
name: pagina
labels:
app: pagina
spec:
containers:
- name: pagina
image: nginx:1.27
ports:
- containerPort: 80- metadata.labels: etichetele podului, perechi cheie-valoare (lecția 9 îți arată la ce folosesc);
- spec.containers: o listă (de aceea - name:), chiar dacă are un singur container;
- name, image și ports sunt la același nivel, sub - , deci aparțin aceluiași container;
- containerPort: 80: portul pe care ascultă nginx, ca --port de la kubectl run.
Dacă îl compari cu kubectl run pagina --image=nginx:1.27 --port=80 -l app=pagina, vezi că fiecare opțiune are locul ei în fișier. Lucrul cu fișierul îl faci în tabul Editor YAML: alegi „Fișier nou”, scrii numele (de exemplu pod.yaml) și conținutul; salvarea e automată, iar fișierele stau în ~/k8s.
Greșeli frecvente și mesajele lor
Fișierul ajunge în cluster cu kubectl apply -f fișier (lecția următoare). Aici îl folosim doar ca să vezi ce răspunde clusterul la un YAML greșit. Prima greșeală: un Tab în loc de spații:
printf 'apiVersion: v1\nkind: Pod\nmetadata:\n\tname: rau\n' > ~/k8s/tab.yaml kubectl apply -f ~/k8s/tab.yaml
error: error parsing /home/elev/k8s/tab.yaml: error converting YAML to JSON: yaml: line 4: found character that cannot start any token
„found character that cannot start any token” la linia 4: caracterul Tab nu e permis pentru indentare. A doua greșeală, mai vicleană: un câmp pus la nivelul greșit. Aici image a ajuns sub metadata:
cat > ~/k8s/nivel.yaml <<'EOF' apiVersion: v1 kind: Pod metadata: name: rau image: nginx:1.27 spec: containers: - name: rau EOF kubectl apply -f ~/k8s/nivel.yaml
Error from server (BadRequest): error when creating "/home/elev/k8s/nivel.yaml": Pod in version "v1" cannot be handled as a Pod: strict decoding error: unknown field "metadata.image"
strict decoding error: unknown field "metadata.image": serverul îți spune exact calea câmpului necunoscut. A treia: image aliniat sub containers, în loc de sub - name:
cat > ~/k8s/lista.yaml <<'EOF' apiVersion: v1 kind: Pod metadata: name: rau spec: containers: - name: rau image: nginx:1.27 EOF kubectl apply -f ~/k8s/lista.yaml
Error from server (BadRequest): error when creating "/home/elev/k8s/lista.yaml": Pod in version "v1" cannot be handled as a Pod: strict decoding error: unknown field "spec.image"
Două spații lipsă și image nu mai aparține containerului, ci lui spec. În toate cele trei cazuri nu s-a creat nimic: clusterul refuză fișierul întreg.
Când primești unknown field, citește calea din mesaj (spec.image) și întreabă-te: sub ce cheie ar fi trebuit să stea? Aproape întotdeauna e o problemă de indentare.
În lumea reală
Echipele țin toate fișierele YAML ale aplicației într-un depozit Git; o schimbare în producție începe cu un pull request.
VS Code cu extensia Kubernetes sau YAML subliniază greșelile de indentare și completează câmpurile înainte să trimiți fișierul.
„Ce câmpuri are orice obiect Kubernetes?” apiVersion, kind, metadata, spec, plus status completat de cluster.
Scrie primul tău manifest: în fișierul ~/k8s/pod.yaml descrie podul pagina, din imaginea nginx:1.27, cu eticheta app: pagina și portul containerului 80. Deocamdată doar fișierul: nu îl aplica în cluster (asta faci în lecția următoare).
- Deschide tabul Editor YAML și fișierul pod.yaml (sau scrie-l cu un here-document în terminal).
- Scrie cele patru câmpuri: apiVersion: v1, kind: Pod, metadata (cu name: pagina și labels → app: pagina) și spec.
- În spec.containers pune un container pagina cu image: nginx:1.27 și ports → - containerPort: 80.
- Verifică fișierul cu cat ~/k8s/pod.yaml.
Soluția exercițiului
cat > ~/k8s/pod.yaml <<'EOF'
apiVersion: v1
kind: Pod
metadata:
name: pagina
labels:
app: pagina
spec:
containers:
- name: pagina
image: nginx:1.27
ports:
- containerPort: 80
EOF
cat ~/k8s/pod.yaml 