Kubernetes — O curso

Guia 03 / 3

Configuração Kubernetes · YAML

Compreender apiVersion, kind, metadata, spec e os principais campos de Deployments, Services, ConfigMaps e PVC.

Resultado esperado :

Redigir e rever um conjunto coerente de manifestos e prever as suas condições de execução.

Leitura
0%

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.

apiVersion: apps/v1
A reter :

Este campo não significa «versão do Kubernetes instalada».

kind

Tipo de objeto a criar: Deployment, Pod, Service, ConfigMap, Job, etc.

kind: Deployment

metadata.name

Nome único do objeto no seu perímetro de nomenclatura.

metadata:
  name: web

metadata.namespace

Namespace alvo quando se trata de um recurso com namespace.

metadata:
  namespace: dev
A reter :

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.

metadata:
  labels:
    app: web

metadata.annotations

Metadados complementares legíveis por ferramentas ou controladores.

metadata:
  annotations:
    exemple.fr/owner: formation

spec

Bloco que descreve o estado desejado. A sua estrutura depende do tipo de objeto (kind).

spec:
  replicas: 2
A reter :

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.

status.readyReplicas: 2
A reter :

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.

containers:
  - name: nginx

spec.containers[].image

Imagem de contentor a descarregar e executar, com nome e tag ou digest.

image: nginx:stable
A reter :

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.

ports:
  - containerPort: 80
A reter :

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.

command: ["sh", "-c"]
args: ["echo bonjour; sleep 3600"]
A reter :

Um comando mal definido pode provocar CrashLoopBackOff.

spec.containers[].env

Declara variáveis de ambiente fornecidas ao processo.

env:
  - name: MODE
    value: "demo"

spec.containers[].envFrom

Importa várias chaves de um ConfigMap ou Secret como variáveis de ambiente.

envFrom:
  - configMapRef:
      name: web-config
A reter :

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ó.

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.

limits:
  cpu: 500m
  memory: 256Mi

spec.containers[].readinessProbe

Teste periódico que indica se o Pod pode receber tráfego através de Services.

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.

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.

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.

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.

spec:
  replicas: 3

Deployment.spec.selector.matchLabels

Labels que permitem ao controlador reconhecer quais os Pods que pertencem a este Deployment.

selector:
  matchLabels:
    app: web
A reter :

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.

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.

strategy:
  type: RollingUpdate

maxSurge / maxUnavailable

Com RollingUpdate, maxSurge autoriza Pods suplementares; maxUnavailable limita o número dos que podem faltar durante a atualização.

rollingUpdate:
  maxSurge: 1
  maxUnavailable: 0

Pod.spec.restartPolicy

Indica quando reiniciar os contentores de um Pod. Para um Pod de Deployment, Always é imposto.

restartPolicy: Always
A reter :

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.

backoffLimit: 3

CronJob.spec.schedule

Expressão cron de cinco campos que permite criar Jobs segundo um calendário.

schedule: "0 2 * * *"
A reter :

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.

type: ClusterIP

Service.spec.selector

Labels dos Pods para os quais encaminhar o tráfego.

selector:
  app: web
A reter :

Não seleciona nenhum Pod se os labels forem diferentes.

Service.spec.ports[].port

Porta do Service que os clientes chamam, por exemplo 80.

ports:
  - port: 80

Service.spec.ports[].targetPort

Porta do contentor, ou porta com nome, para a qual o Service redireciona o tráfego.

targetPort: 80
A reter :

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.

nodePort: 30080
A reter :

Não abre automaticamente as firewalls do sistema.

Ingress.spec.ingressClassName

Nome da classe de Ingress utilizada para escolher o controlador adequado.

ingressClassName: nginx
A reter :

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.

rules:
  - host: web.exemple.test

Ingress.spec.tls

Associa anfitriões TLS a um Secret de certificado para servir em HTTPS.

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.

data:
  MODE: "production"

Secret.stringData / data

stringData aceita texto simples na entrada; data transporta valores codificados em base64.

stringData:
  PASSWORD: exemple-fictif
A reter :

Nunca fazer commit de segredos reais. Base64 não é cifragem.

spec.volumes

Declara os volumes disponíveis no Pod: emptyDir, Secret, ConfigMap, PVC, etc.

volumes:
  - name: cache
    emptyDir: {}

volumeMounts

Define onde um volume declarado é visível num contentor.

volumeMounts:
  - name: cache
    mountPath: /tmp/cache

persistentVolumeClaim.claimName

Liga um volume do Pod a um PVC já declarado, para um armazenamento persistente.

volumes:
  - name: donnees
    persistentVolumeClaim:
      claimName: donnees-pvc

PVC.spec.accessModes

Pede os modos de acesso suportados pelo armazenamento, por exemplo ReadWriteOnce.

accessModes: [ReadWriteOnce]
A reter :

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.

resources:
  requests:
    storage: 2Gi

PVC.spec.storageClassName

Nome da classe de armazenamento pedida; a sua disponibilidade depende do cluster.

storageClassName: standard
A reter :

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.

securityContext:
  runAsNonRoot: true
A reter :

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.

allowPrivilegeEscalation: false

securityContext.readOnlyRootFilesystem

Monta o sistema de ficheiros raiz do contentor em modo só de leitura.

readOnlyRootFilesystem: true
A reter :

Prever volumes para os caminhos que devem permanecer modificáveis.

securityContext.capabilities.drop

Permite retirar capacidades Linux desnecessárias ao processo.

capabilities:
  drop: ["ALL"]

spec.serviceAccountName

Associa ao Pod uma identidade de workload Kubernetes, utilizada nomeadamente para os seus pedidos à API.

serviceAccountName: lecteur-pods
A reter :

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.

resources: ["pods"]
verbs: ["get", "list"]
A reter :

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.

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.

tolerations:
  - key: dedicated
    operator: Equal
    value: lab
    effect: NoSchedule
A reter :

A toleration não obriga a escolher esse nó.

NetworkPolicy.spec.podSelector

Determina quais os Pods do namespace sujeitos a uma NetworkPolicy.

podSelector:
  matchLabels: {app: db}
A reter :

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.

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.

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.

/ready → trafic ; /live → redémarrage

Request ≠ limit

Request serve para o planeamento; limit limita a utilização durante a execução.

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.

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.

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.

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 reter :

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.

apiVersion: v1
kind: Service
metadata:
  name: web
  namespace: dev
spec:
  type: ClusterIP
  selector:
    app: web
  ports:
    - name: http
      port: 80
      targetPort: 80
A reter :

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.

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.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: donnees-pvc
  namespace: dev
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 2Gi
# La StorageClass disponible dépend du cluster.
A reter :

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.

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"]