3 min read

Domine YAML, Manifests e a API do Kubernetes: Guia Definitivo para Iniciantes

Domine YAML, Manifests e a API do Kubernetes: Guia Definitivo para Iniciantes

Domine YAML, Manifests e a API do Kubernetes: Guia Definitivo para Iniciantes

Ao trabalhar com Kubernetes – ou com versões mais leves como o K3s – é fundamental dominar YAML, manifests e a própria API. Esses três pilares são a base para definir e controlar recursos dentro de um cluster. Neste guia, vamos analisar a estrutura dos manifests, mostrar como descobrir os campos dos objetos Kubernetes usando comandos práticos e apresentar boas práticas para organizar seus arquivos de forma clara e escalável.

O que são YAML e Manifests no Kubernetes?

YAML (YAML Ain’t Markup Language) é um formato de serialização de dados legível, ideal para descrever recursos no Kubernetes. Um manifest é simplesmente um arquivo YAML que declara o estado desejado de componentes como Pods, Deployments, Services, ConfigMaps etc.

Os manifests são declarativos: você descreve como o recurso deve ser, e o Kubernetes cuida de criá‑lo, atualizá‑lo ou removê‑lo para que o cluster reflita exatamente o que foi especificado.

Estrutura básica de um manifest

apiVersion: v1
kind: Pod
metadata:
  name: meu-pod
  labels:
    app: exemplo
spec:
  containers:
    - name: nginx
      image: nginx:latest
      ports:
        - containerPort: 80

Campos principais

Campo O que descreve
apiVersion Versão da API que contém o recurso (ex.: v1, apps/v1, batch/v1).
kind Tipo do recurso (Pod, Deployment, Service, ConfigMap, etc.).
metadata Dados de identificação – nome, namespace, rótulos, anotações, etc.
spec Especificação do estado desejado – containers, imagens, volumes, réplicas, políticas, etc.

Com esses quatro blocos, você consegue declarar praticamente qualquer objeto do Kubernetes.

Explorando tipos de recursos e seus apiVersion × kind

Recurso apiVersion kind
Podv1Pod
Deploymentapps/v1Deployment
Servicev1Service
ConfigMapv1ConfigMap
Ingressnetworking.k8s.io/v1Ingress

Explorando a API com kubectl explain

O comando kubectl explain permite navegar pelo esquema da API diretamente no terminal, mostrando descrições, tipos esperados e exemplos de uso.

Uso básico

kubectl explain pod

Mostra a descrição geral do objeto Pod.

Aprofundando nos campos

kubectl explain pod.spec
kubectl explain deployment.spec.template.spec.containers

Esses comandos revelam detalhes de subcampos, como nomes, tipos e documentação.

Exemplo prático – obter informações sobre containers em um Pod:

kubectl explain pod.spec.containers

DESCRIPTION:
  List of containers belonging to the pod. Containers cannot currently be
  added or removed.

FIELDS:
  args        <[]string>
  command     <[]string>
  env         <[]Object>
  image       <string>
  name        <string>
  ports       <[]Object>
  resources   <Object>
  ...

Assim você sabe exatamente quais atributos pode usar dentro de containers.

Explorando a API via comandos REST

Além do kubectl explain, é possível explorar a API do Kubernetes via chamadas REST para entender as estruturas dos recursos.

kubectl get --raw /api/v1 | head -n 20

Esse comando retorna a raiz da API v1, mostrando os recursos disponíveis.

Boas práticas para organizar manifests

  1. Prefira arquivos pequenos e focados
    Manifests enxutos são mais fáceis de versionar, revisar e reutilizar.
  2. Comente o que for relevante
    Comentários curtos ajudam a entender a intenção de cada recurso.
  3. Versione diretórios quando houver mudanças significativas
    Ex.: v1/, v2/ dentro de deployments/ para acompanhar evoluções da aplicação.
  4. Use ferramentas de templating
    Helm, Kustomize ou Jsonnet reduzem a repetição e permitem parametrização avançada.

Separe por tipo de recurso

manifests/
├── deployments/
│   ├── backend.yaml
│   └── frontend.yaml
├── services/
│   ├── backend-service.yaml
│   └── frontend-service.yaml
└── configmaps/
    └── app-config.yaml

Facilita a localização e a manutenção.

Quando e por que usar manifests

  • Infraestrutura como código: garante reproduzibilidade e auditoria.
  • Pipelines CI/CD: os manifests são a base para aplicar mudanças automaticamente.
  • Ambientes multi‑cluster: mantêm consistência entre diferentes clusters.
  • Aprendizado: escrever YAML à mão ajuda a internalizar a API e os conceitos do Kubernetes.

Exemplos práticos

Deployment simples

apiVersion: apps/v1
kind: Deployment
metadata:
  name: minha-api
  labels:
    app: minha-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: minha-api
  template:
    metadata:
      labels:
        app: minha-api
    spec:
      containers:
        - name: minha-api-container
          image: minha-api:1.0.0
          ports:
            - containerPort: 8080

Service que expõe o Deployment

apiVersion: v1
kind: Service
metadata:
  name: minha-api-service
spec:
  selector:
    app: minha-api
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
  type: ClusterIP

Aplicação no cluster:

kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

Considerações finais

  • Use kubectl explain sempre que surgir dúvida sobre um campo.
  • YAML depende de indentação correta – preste atenção aos espaços.
  • Mantenha os manifests versionados (Git, por exemplo) e revisados por pares.
  • Avalie ferramentas como Helm ou Kustomize para projetos maiores.
  • Lembre‑se: o manifest descreve o estado desejado; o Kubernetes cuida de reconciliá‑lo.

Com esses conceitos e práticas, você já está pronto para criar manifests claros, seguros e fáceis de manter, explorar a API do Kubernetes de forma confiante e operar seu cluster com eficiência.

Geisler