Kubernetes para Iniciantes: Seu Primeiro Deploy Passo a Passo

Iniciar no Kubernetes (também conhecido como K8s) pode parecer intimidador devido à quantidade de novos termos, conceitos e ferramentas. No entanto, a melhor forma de quebrar essa barreira é colocando a mão na massa.

Este guia adota uma abordagem prática e realista: vamos pular a teoria excessiva e configurar um cluster local funcional para rodar sua primeira aplicação, explicando detalhadamente o que acontece por trás de cada comando executado.

O que é Kubernetes e por que ele é necessário?

Quando começamos a trabalhar com containers, o fluxo inicial geralmente envolve criar uma imagem Docker e rodá-la localmente ou em uma máquina virtual simples. Mas o que acontece quando sua aplicação cresce e você precisa de alta disponibilidade, balanceamento de carga entre dezenas de instâncias e atualizações sem tempo de inatividade (zero-downtime)?

Gerenciar múltiplos containers manualmente em diferentes servidores torna-se inviável. É aqui que entra o Kubernetes. O Kubernetes (K8s) é uma plataforma de código aberto projetada para automatizar a implantação, o dimensionamento (escalabilidade) e o gerenciamento de aplicações em containers.

Para quem está começando na área, vale a pena entender o que são containers e orquestração para compreender como o K8s resolve problemas complexos de infraestrutura, como o self-healing (reiniciar automaticamente containers que falham) e a distribuição inteligente de carga de trabalho entre servidores físicos ou virtuais.

A tríade essencial: Pods, Deployments e Services

Antes de abrir o terminal, você precisa entender três conceitos que formam a base de quase qualquer aplicação rodando em Kubernetes. Eles funcionam de forma integrada:

[ Service (Porta de Entrada / IP Estável) ]
                    │
                    ▼
[ Deployment (Gerente / Garante as Replicas) ]
                    │
                    ▼
         [ Pod (Container Nginx) ]

1. Pods

O Pod é a menor unidade de computação que você pode criar e gerenciar no Kubernetes. Um Pod representa um único processo em execução no seu cluster e pode conter um ou mais containers (que compartilham armazenamento e recursos de rede). Na prática, a regra geral é: um container principal por Pod.

2. Deployments

Você raramente criará Pods diretamente em produção. Em vez disso, você criará um Deployment. O Deployment funciona como um “gerente”. Você declara o estado desejado (por exemplo: “quero que 3 réplicas do meu Pod estejam sempre rodando”) e o Deployment se encarrega de criar, atualizar ou destruir os Pods para manter esse estado ativo.

3. Services

Como os Pods são efêmeros (eles podem morrer e ser recriados com novos endereços IP a qualquer momento), você precisa de uma forma estável de acessá-los. O Service é o componente responsável por expor seus Pods para a rede (seja interna ou externa), funcionando como um balanceador de carga com um endereço IP e porta fixos.

Configurando o ambiente local: Minikube e kubectl

Para fins de aprendizado e testes locais, não precisamos contratar um serviço de nuvem complexo. Vamos utilizar o Minikube, que cria um cluster Kubernetes de nó único dentro da sua própria máquina usando virtualização (como Docker, VirtualBox ou Hyper-V).

Pré-requisitos

Antes de começar, certifique-se de ter o Docker instalado e rodando em sua máquina. Você pode utilizar o Docker para facilitar o desenvolvimento local de forma geral, e aqui ele servirá como o driver padrão para o Minikube.

Passo 1: Instalar o kubectl

O kubectl é a ferramenta de linha de comando oficial para interagir com o cluster Kubernetes.

• No macOS (via Homebrew):

  brew install kubectl

• No Windows (via Chocolatey):

  choco install kubernetes-cli

• No Linux (Debian/Ubuntu):

  sudo apt-get update && sudo apt-get install -y apt-transport-https ca-certificates curl
  curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
  echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /' | sudo tee /etc/apt/sources.list.get/kubernetes.list
  sudo apt-get update && sudo apt-get install -y kubectl

Passo 2: Instalar o Minikube

Siga as instruções oficiais de instalação de acordo com o seu sistema operacional na página oficial do Minikube.

• No macOS: brew install minikube
• No Windows: choco install minikube

Passo 3: Iniciar o Cluster

Com o Docker aberto, execute o comando abaixo no seu terminal para iniciar o cluster local:

minikube start --driver=docker

O output esperado será semelhante a este:

😄  minikube v1.32.0 on Darwin 14.1.1
✨  Using the docker driver based on user configuration
👍  Starting control plane node minikube in cluster minikube
🚜  Pulling base image ...
💾  Downloading Kubernetes v1.28.3 ...
🔗  Configuring docker to reach kubernetes...
🔎  Verifying Kubernetes components...
🌟  Enabled addons: storage-provisioner, default-storageclass
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

Para garantir que a comunicação está funcionando, verifique o status do cluster:

kubectl cluster-info

Escrevendo os manifestos YAML: Deployment e Service

No Kubernetes, trabalhamos de forma declarativa. Em vez de dizer como fazer, escrevemos um arquivo de configuração (YAML) descrevendo o que queremos que o cluster mantenha rodando.

Vamos criar um arquivo chamado app-deploy.yaml. Ele conterá a definição do nosso Deployment (usando uma imagem pública simples do Nginx que servirá como nosso servidor web) e do nosso Service.

Salve o código abaixo no arquivo app-deploy.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app-deployment
  labels:
    app: web-app
spec:
  replicas: 2 # Define que queremos 2 Pods idênticos rodando para garantir redundância
  selector:
    matchLabels:
      app: web-app # Garante que o Deployment gerencie apenas os Pods com esta label
  template:
    metadata:
      labels:
        app: web-app # Label aplicada aos Pods criados a partir deste template
    spec:
      containers:
      - name: nginx-container
        image: nginx:1.25.3-alpine # Imagem leve do servidor web Nginx
        ports:
        - containerPort: 80 # Porta interna que o container escuta
---
apiVersion: v1
kind: Service
metadata:
  name: web-app-service
spec:
  type: NodePort # Expõe o serviço em uma porta estática em cada nó do cluster
  selector:
    app: web-app # Direciona o tráfego para os Pods que possuem esta label
  ports:
    - protocol: TCP
      port: 80 # Porta exposta pelo Service
      targetPort: 80 # Porta de destino no container do Pod

Executando o deploy e acessando a aplicação

Com o manifesto YAML pronto, vamos aplicá-lo ao nosso cluster local.

1. Aplicar as configurações

Execute o comando kubectl apply apontando para o arquivo criado:

kubectl apply -f app-deploy.yaml

Output esperado:

deployment.apps/web-app-deployment created
service/web-app-service created

2. Verificar o status dos recursos

Vamos checar se os Pods foram criados com sucesso e se já estão em execução:

kubectl get pods

Output esperado:

NAME                                  READY   STATUS    RESTARTS   AGE
web-app-deployment-7889b4f94c-abc12   1/1     Running   0          15s
web-app-deployment-7889b4f94c-xyz34   1/1     Running   0          15s

Note que temos exatamente duas réplicas rodando, conforme declaramos no YAML.

Agora, vamos verificar o Service:

kubectl get service web-app-service

Output esperado:

NAME              TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
web-app-service   NodePort   10.104.200.45   <none>        80:31245/TCP   45s

3. Acessar a aplicação no navegador

Como estamos usando o Minikube dentro de um ambiente isolado (Docker driver), o IP do Service não fica diretamente exposto no seu localhost. O Minikube possui um comando utilitário para abrir o túnel de rede e abrir a aplicação diretamente no seu navegador padrão:

minikube service web-app-service

Este comando abrirá automaticamente uma aba no seu navegador exibindo a tela padrão do Nginx (“Welcome to nginx!”), provando que seu deploy local foi concluído com sucesso.

Guia de troubleshooting: Como resolver erros comuns de iniciantes

Nem sempre o deploy funciona de primeira. Se o status do seu Pod não estiver como Running, use os passos abaixo para diagnosticar o problema.

Erro: ImagePullBackOff ou ErrImagePull

• O que significa: O Kubernetes tentou baixar a imagem do container especificada no YAML, mas falhou.
• Causas comuns: Erro de digitação no nome da imagem ou na tag (ex: nginxx:latest), ou a imagem está em um repositório privado sem credenciais configuradas.
• Como diagnosticar: Execute o comando abaixo para ver os eventos detalhados do Pod:

  kubectl describe pod <nome-do-pod>

  Olhe a seção “Events” no final do output para ver o erro exato de download.

Erro: Pod em loop de reinicialização (CrashLoopBackOff)

• O que significa: O container iniciou com sucesso, mas finalizou ou quebrou logo em seguida.
• Causas comuns: Falta de variáveis de ambiente obrigatórias, erro na inicialização do código da aplicação ou ausência de um processo contínuo (o container precisa de um processo em primeiro plano para continuar ativo).
• Como diagnosticar: Verifique os logs internos do container:

  kubectl logs <nome-do-pod>

Problema: Aplicação inacessível no navegador

• Causas comuns: Incompatibilidade de portas no arquivo YAML. Garanta que o targetPort do seu Service seja exatamente igual ao containerPort do seu Deployment.

Próximos passos na sua jornada DevOps

Parabéns! Você configurou um cluster local, entendeu a estrutura declarativa dos manifestos YAML e realizou o deploy de uma aplicação funcional com redundância.

Embora o Kubernetes possua uma curva de aprendizado íngreme à medida que avançamos para tópicos como persistência de dados, segurança de acessos (RBAC) e malhas de serviço (Service Mesh), dominar essa base local é o passo mais importante.

Para continuar evoluindo, o próximo passo natural é automatizar a criação de suas imagens e o deploy no cluster. Você pode aprender a implementar CI/CD com GitHub Actions e Docker para conectar seu fluxo de desenvolvimento diretamente à entrega contínua.

Referências e Fontes

• Documentação Oficial do Kubernetes
• Guia de Início Rápido do Minikube
• Referência de comandos do kubectl

FAQ

Qual a diferença prática entre Docker e Kubernetes?

O Docker é utilizado para empacotar e rodar sua aplicação dentro de um container isolado. O Kubernetes entra em cena para gerenciar, escalar e garantir a alta disponibilidade de múltiplos containers rodando em diferentes servidores.

Posso usar o Kubernetes local para produção?

Não é recomendado. Ferramentas como o Minikube e o Kind foram desenhadas especificamente para testes e desenvolvimento local. Para produção, utilizam-se clusters gerenciados em nuvem (como AWS EKS, Google GKE ou Azure AKS) ou distribuições bare-metal robustas.

O que significa o erro ImagePullBackOff e como resolver?

Esse erro indica que o Kubernetes não conseguiu baixar a imagem do container especificada no YAML. Geralmente ocorre por erros de digitação no nome da imagem, tag inexistente ou falta de autenticação em registros privados (como o Docker Hub).