Guia 03 / 3
Configuração Kubernetes · YAML
Compreender apiVersion, kind, metadata, spec e os principais campos de Deployments, Services, ConfigMaps e PVC.
Redigir e rever um conjunto coerente de manifestos e prever as suas condições de execução.
01 · Anatomia de um manifesto
Um manifesto descreve um objeto Kubernetes. Os campos estão imbricados: a sua localização conta tanto quanto o seu nome.
apiVersion
Versão do grupo de API a que o recurso pertence. Um Deployment utiliza apps/v1, um Pod ou Service utiliza v1.
Exemplo
apiVersion: apps/v1
Este campo não significa «versão do Kubernetes instalada».
kind
Tipo de objeto a criar: Deployment, Pod, Service, ConfigMap, Job, etc.
Exemplo
kind: Deployment
metadata.name
Nome único do objeto no seu perímetro de nomenclatura.
Exemplo
metadata:
name: web
metadata.namespace
Namespace alvo quando se trata de um recurso com namespace.
Exemplo
metadata:
namespace: dev
O namespace deve já existir ou ser declarado noutro local.
metadata.labels
Etiquetas associadas ao objeto, práticas para a filtragem e a seleção.
Exemplo
metadata:
labels:
app: web
metadata.annotations
Metadados complementares legíveis por ferramentas ou controladores.
Exemplo
metadata:
annotations:
exemple.fr/owner: formation
spec
Bloco que descreve o estado desejado. A sua estrutura depende do tipo de objeto (kind).
Exemplo
spec:
replicas: 2
Um Service e um Deployment não têm os mesmos campos spec.
status
Bloco preenchido pelo sistema que descreve a situação observada. É normalmente consultado, e não fornecido pelo autor.
Exemplo
status.readyReplicas: 2
Não incluir status nos manifestos de origem.
02 · Descrever os contentores de um Pod
Para uma aplicação duradoura, estes campos colocam-se frequentemente sob spec.template.spec num Deployment.
spec.containers[].name
Nome distintivo do contentor dentro do Pod; o kubectl pode utilizá-lo para visar os registos.
Exemplo
containers:
- name: nginx
spec.containers[].image
Imagem de contentor a descarregar e executar, com nome e tag ou digest.
Exemplo
image: nginx:stable
Não contar com latest para implementações reproduzíveis.
spec.containers[].ports[].containerPort
Indicação da porta em que a aplicação no contentor deve escutar.
Exemplo
ports:
- containerPort: 80
Declarar containerPort não publica o Pod para o exterior.
spec.containers[].command / args
command substitui o ENTRYPOINT da imagem; args substitui o seu CMD, consoante a configuração da imagem.
Exemplo
command: ["sh", "-c"]
args: ["echo bonjour; sleep 3600"]
Um comando mal definido pode provocar CrashLoopBackOff.
spec.containers[].env
Declara variáveis de ambiente fornecidas ao processo.
Exemplo
env:
- name: MODE
value: "demo"
spec.containers[].envFrom
Importa várias chaves de um ConfigMap ou Secret como variáveis de ambiente.
Exemplo
envFrom:
- configMapRef:
name: web-config
As alterações de ambiente não são reinjetadas num processo já lançado.
spec.containers[].resources.requests
Quantidade de CPU e de memória pedida para o planeamento; o scheduler utiliza estes valores para escolher o nó.
Exemplo
requests:
cpu: 100m
memory: 64Mi
spec.containers[].resources.limits
Teto de recursos imposto na execução; a CPU pode ser limitada, a memória pode provocar um OOM kill.
Exemplo
limits:
cpu: 500m
memory: 256Mi
spec.containers[].readinessProbe
Teste periódico que indica se o Pod pode receber tráfego através de Services.
Exemplo
readinessProbe:
httpGet: {path: /, port: 80}
periodSeconds: 5
spec.containers[].livenessProbe
Teste que indica se o contentor deve ser reiniciado por já não responder corretamente.
Exemplo
livenessProbe:
httpGet: {path: /, port: 80}
initialDelaySeconds: 10
spec.containers[].startupProbe
Teste opcional que deixa uma aplicação lenta concluir o arranque antes das probes habituais.
Exemplo
startupProbe:
httpGet: {path: /, port: 80}
failureThreshold: 30
periodSeconds: 2
spec.imagePullSecrets
Referencia um Secret que contém as credenciais de acesso a um registo privado, quando necessário.
Exemplo
imagePullSecrets:
- name: registry-creds
03 · Deployment e outros controladores
Um Deployment descreve não só uma imagem, mas também como a fazer funcionar e atualizar várias vezes.
Deployment.spec.replicas
Número de Pods desejados para a aplicação, geridos indiretamente através de um ReplicaSet.
Exemplo
spec:
replicas: 3
Deployment.spec.selector.matchLabels
Labels que permitem ao controlador reconhecer quais os Pods que pertencem a este Deployment.
Exemplo
selector:
matchLabels:
app: web
Deve corresponder aos labels do modelo; o seletor é imutável em muitos casos.
Deployment.spec.template
Modelo de Pod que o Kubernetes utiliza para criar as réplicas. Contém o metadata e o spec do Pod.
Exemplo
template:
metadata:
labels: {app: web}
spec:
containers: ...
Deployment.spec.strategy
Estratégia de atualização. RollingUpdate substitui progressivamente os Pods, Recreate renova-os todos em conjunto.
Exemplo
strategy:
type: RollingUpdate
Pod.spec.restartPolicy
Indica quando reiniciar os contentores de um Pod. Para um Pod de Deployment, Always é imposto.
Exemplo
restartPolicy: Always
O Job permite também OnFailure ou Never.
Job.spec.template / backoffLimit
O Job utiliza um modelo de Pod e pode limitar o número de tentativas em caso de falha.
Exemplo
backoffLimit: 3
CronJob.spec.schedule
Expressão cron de cinco campos que permite criar Jobs segundo um calendário.
Exemplo
schedule: "0 2 * * *"
Verificar o fuso horário através de timeZone, se necessário.
04 · Services, portas e entrada HTTP
O Service escolhe os Pods graças aos labels e separa o endereço estável das instâncias efémeras.
Service.spec.type
Define a exposição do Service: ClusterIP por omissão, NodePort, LoadBalancer ou ExternalName.
Exemplo
type: ClusterIP
Service.spec.selector
Labels dos Pods para os quais encaminhar o tráfego.
Exemplo
selector:
app: web
Não seleciona nenhum Pod se os labels forem diferentes.
Service.spec.ports[].port
Porta do Service que os clientes chamam, por exemplo 80.
Exemplo
ports:
- port: 80
Service.spec.ports[].targetPort
Porta do contentor, ou porta com nome, para a qual o Service redireciona o tráfego.
Exemplo
targetPort: 80
port e targetPort podem ser diferentes.
Service.spec.ports[].nodePort
Porta acessível nos nós com o tipo NodePort; deve estar no intervalo configurado.
Exemplo
nodePort: 30080
Não abre automaticamente as firewalls do sistema.
Ingress.spec.ingressClassName
Nome da classe de Ingress utilizada para escolher o controlador adequado.
Exemplo
ingressClassName: nginx
Um controlador de Ingress deve existir e gerir esta classe.
Ingress.spec.rules
Define anfitriões e caminhos HTTP que encaminham para Services do cluster.
Exemplo
rules:
- host: web.exemple.test
Ingress.spec.tls
Associa anfitriões TLS a um Secret de certificado para servir em HTTPS.
Exemplo
tls:
- hosts: [web.exemple.test]
secretName: web-tls
05 · Configuração e armazenamento
É preciso distinguir a configuração aplicacional, os segredos e os dados que devem sobreviver ao desaparecimento de um Pod.
ConfigMap.data
Conjunto chave-valor para parâmetros não sensíveis, consumido pelos Pods.
Exemplo
data:
MODE: "production"
Secret.stringData / data
stringData aceita texto simples na entrada; data transporta valores codificados em base64.
Exemplo
stringData:
PASSWORD: exemple-fictif
Nunca fazer commit de segredos reais. Base64 não é cifragem.
spec.volumes
Declara os volumes disponíveis no Pod: emptyDir, Secret, ConfigMap, PVC, etc.
Exemplo
volumes:
- name: cache
emptyDir: {}
volumeMounts
Define onde um volume declarado é visível num contentor.
Exemplo
volumeMounts:
- name: cache
mountPath: /tmp/cache
persistentVolumeClaim.claimName
Liga um volume do Pod a um PVC já declarado, para um armazenamento persistente.
Exemplo
volumes:
- name: donnees
persistentVolumeClaim:
claimName: donnees-pvc
PVC.spec.accessModes
Pede os modos de acesso suportados pelo armazenamento, por exemplo ReadWriteOnce.
Exemplo
accessModes: [ReadWriteOnce]
RWO não significa necessariamente «um único Pod»; ver a semântica do volume.
PVC.spec.resources.requests.storage
Quantidade de armazenamento pedida ao sistema de armazenamento.
Exemplo
resources:
requests:
storage: 2Gi
PVC.spec.storageClassName
Nome da classe de armazenamento pedida; a sua disponibilidade depende do cluster.
Exemplo
storageClassName: standard
Sem aprovisionador nem PV compatível, um PVC pode ficar em Pending.
06 · Segurança e colocação
Estes campos influenciam a identidade do processo, as permissões das cargas de trabalho e a sua colocação nos nós.
securityContext.runAsNonRoot
Exige que o processo não se execute com o UID 0 no contentor.
Exemplo
securityContext:
runAsNonRoot: true
A imagem deve ser compatível com um utilizador não root.
securityContext.allowPrivilegeEscalation
Impede, quando suportado, que um processo obtenha novos privilégios durante a execução.
Exemplo
allowPrivilegeEscalation: false
securityContext.readOnlyRootFilesystem
Monta o sistema de ficheiros raiz do contentor em modo só de leitura.
Exemplo
readOnlyRootFilesystem: true
Prever volumes para os caminhos que devem permanecer modificáveis.
securityContext.capabilities.drop
Permite retirar capacidades Linux desnecessárias ao processo.
Exemplo
capabilities:
drop: ["ALL"]
spec.serviceAccountName
Associa ao Pod uma identidade de workload Kubernetes, utilizada nomeadamente para os seus pedidos à API.
Exemplo
serviceAccountName: lecteur-pods
Não conceder mais permissões do que o necessário.
RBAC Role / RoleBinding
Role descreve regras num namespace; RoleBinding concede esse papel a um sujeito.
Exemplo
resources: ["pods"]
verbs: ["get", "list"]
ClusterRole e ClusterRoleBinding dizem respeito a permissões reutilizáveis ou de âmbito cluster.
nodeSelector / affinity
Restringem ou orientam a seleção de um nó segundo os seus labels ou as relações entre Pods.
Exemplo
nodeSelector:
kubernetes.io/os: linux
tolerations / taints
Um taint permite repelir certos Pods; uma toleration autoriza um Pod compatível a ser planeado apesar desse taint.
Exemplo
tolerations:
- key: dedicated
operator: Equal
value: lab
effect: NoSchedule
A toleration não obriga a escolher esse nó.
NetworkPolicy.spec.podSelector
Determina quais os Pods do namespace sujeitos a uma NetworkPolicy.
Exemplo
podSelector:
matchLabels: {app: db}
A aplicação exige um CNI compatível.
07 · Confusões frequentes
Algumas propriedades parecem-se com as do Docker Compose, mas o comportamento do Kubernetes é diferente.
containerPort ≠ exposição pública
containerPort descreve a porta do contentor; um Service e, eventualmente, um Ingress ou Gateway definem o acesso de rede pretendido.
Exemplo
containerPort: 80 ≠ LoadBalancer
Labels ≠ nomes de serviços
Os seletores ligam Services, Deployments e Pods segundo labels; são essas correspondências que determinam o encaminhamento.
Exemplo
Service selector.app = Pod label.app
Readiness ≠ liveness
Readiness evita enviar tráfego para um Pod que não está pronto; liveness desencadeia um reinício em caso de falha.
Exemplo
/ready → trafic ; /live → redémarrage
Request ≠ limit
Request serve para o planeamento; limit limita a utilização durante a execução.
Exemplo
100m CPU de request, 500m de limit
Secret ≠ cifragem garantida
Um Secret separa as informações sensíveis, mas os seus dados em base64 podem ser legíveis sem cifragem em repouso nem RBAC adequado.
Exemplo
Protéger etcd + accès API + Git
Deployment ≠ StatefulSet
Um Deployment convém a serviços intermutáveis; um StatefulSet fornece identidades estáveis, muitas vezes úteis para cargas com armazenamento associado.
Exemplo
web → Deployment ; base distribuée → StatefulSet
08 · Manifestos completos
Estes ficheiros completos correspondem aos anexos do guia PDF e podem ser copiados das fichas do site.
deployment.yaml
Declara duas réplicas Nginx com recursos reservados e um teste de disponibilidade HTTP.
Exemplo
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
A aplicar depois de criar o namespace dev.
service.yaml
Cria um ponto de acesso interno estável para os Pods que têm o label app: web.
Exemplo
apiVersion: v1
kind: Service
metadata:
name: web
namespace: dev
spec:
type: ClusterIP
selector:
app: web
ports:
- name: http
port: 80
targetPort: 80
O Service só funcionará se o seletor corresponder aos labels dos Pods.
configmap.yaml
Cria dois parâmetros aplicacionais não confidenciais no namespace dev.
Exemplo
apiVersion: v1
kind: ConfigMap
metadata:
name: web-config
namespace: dev
data:
APP_MODE: "demo"
LOG_LEVEL: "info"
pvc.yaml
Pede 2 Gi de armazenamento persistente; o aprovisionamento depende da configuração do cluster.
Exemplo
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: donnees-pvc
namespace: dev
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 2Gi
# La StorageClass disponible dépend du cluster.
Verificar kubectl get storageclass e depois kubectl get pvc -n dev.
job.yaml
Executa uma tarefa pontual e termina; não serve para alojar um servidor HTTP.
Exemplo
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"]