Ativar Kubernetes no Docker Desktop é como adicionar uma extensão a um apartamento em que você já mora: os fundamentos (a máquina virtual Linux, o motor Docker, a rede para localhost) estão postos, resta marcar uma caixa e deixar a aplicação baixar uma dúzia de imagens, montar o plano de controle e escrever uma linha em seu arquivo ~/.kube/config. Cinco minutos depois, kubectl get nodes responde docker-desktop Ready. Nesta lição, você faz a instalação passo a passo para seu sistema, verifica cada etapa com um comando cuja saída você conhece, e volta com a lista das cinco falhas que bloqueiam nove estudantes em dez no primeiro dia, com a mensagem exata e o remédio.
Docker Desktop faz rodar uma máquina virtual Linux leve: no Windows é uma distribuição WSL 2 chamada docker-desktop, no macOS uma VM Apple Virtualization, no Linux uma VM QEMU. O motor Docker vive dentro, e Kubernetes também: quando você o ativa, Docker Desktop baixa as imagens do plano de controle de Docker Hub (docker/desktop-kubernetes, desktop-kubernetes-etcd, desktop-kubernetes-apiserver…), lança como contêineres privilegiados nesta VM, gera os certificados, depois adiciona em seu ~/.kube/config um contexto docker-desktop que aponta para https://kubernetes.docker.internal:6443. Também instala kubectl (em C:\Program Files\Docker\Docker\resources\bin no Windows, /usr/local/bin/kubectl no macOS): você não tem nada mais a baixar.
Duas formas de provisionar o cluster existem desde Docker Desktop 4.38. Kubeadm cria um único nó, com a versão de Kubernetes escolhida pelo Docker Desktop (v1.34.1 na 4.68); é o modo padrão e do curso. kind (Kubernetes in Docker) cria múltiplos nós, cada um sendo um contêiner, e deixa você escolher a versão; inicia mais rápido mas não compartilha o armazém de imagens Docker classicamente (precisa do modo "containerd image store"). Enquanto você aprende, um nó é suficiente: tudo que o curso faz cabe em docker-desktop.
| Sistema | O que você instala | Onde ajustar memória | Kubernetes integrado? |
|---|---|---|---|
| Windows 10 (21H2+) / 11 | Docker Desktop, motor WSL 2 | arquivo %UserProfile%\.wslconfig, depois wsl --shutdown | sim |
| macOS 13+ (Intel ou Apple Silicon) | Docker Desktop (.dmg de seu chip) | Settings → Resources → Memory, "Apply & restart" | sim |
| Linux (Ubuntu, Debian, Fedora…) | Docker Desktop para Linux (.deb / .rpm) ou Docker Engine apenas | Settings → Resources (Desktop); toda RAM (Engine) | sim com Docker Desktop; não com Engine apenas (use minikube ou kind) |
| Ajuste Kubernetes (Settings → Kubernetes) | O que faz | Nossa escolha |
|---|---|---|
| Enable Kubernetes | Instala e inicia o cluster; desmarcar para e remove os contêineres do cluster e remove kubectl | marcado |
| Cluster provisioning method | Kubeadm (1 nó, versão imposta) ou kind (multi-nós, versão sua escolha) | Kubeadm |
| Show system containers (advanced) | Mostra os contêineres k8s_… do cluster em docker ps | marcado (útil para entender, lição 01 etapa 7) |
| Reset Kubernetes cluster | Deleta tudo o cluster (namespaces, Deployments, volumes) e o recria vazio; único modo de trocar versão Kubernetes | apenas em troubleshooting |
O ajuste é armazenado em arquivo JSON: no Windows %APPDATA%\Docker\settings-store.json, chave KubernetesEnabled (true/false) e KubernetesMode (kubeadm/kind). Conhecer isso ajuda quando a interface recusa abrir.
Windows: instalar WSL 2, depois Docker Desktop. Abra PowerShell como administrador e instale WSL se não estiver já feito (o comando não faz nada se WSL está presente):
wsl --install
wsl --statusReinicie se pedido. Depois baixe "Docker Desktop for Windows" em docs.docker.com/desktop, lance o instalador, deixe marcado Use WSL 2 instead of Hyper-V, depois inicie Docker Desktop e espere que o ícone da baleia na barra de tarefas pare de piscar. O que observar:
wsl --list --verbose NAME STATE VERSION
* docker-desktop Running 2
…A distribuição docker-desktop é a VM na qual Docker e Kubernetes rodarão. Se VERSION mostra 1, converta-a: wsl --set-version docker-desktop 2.
Windows: dar memória para WSL 2. Por padrão WSL usa metade de sua RAM; muitas vezes é suficiente, mas para não depender da sorte, fixe-a. Crie o arquivo %UserProfile%\.wslconfig:
notepad $env:UserProfile\.wslconfigCole, salve, depois reinicie a VM WSL (Docker Desktop reinicia tudo atrás):
[wsl2]
memory=8GB
processors=4wsl --shutdownO que observar, uma vez Docker Desktop voltado: docker info --format '{{.MemTotal}}' retorna um número próximo de 8 000 000 000 (na máquina do curso, sem limite, retorna 33480151040, isto é 31 GB). O curso funciona a partir de 4 GB; 8 GB deixa você confortável até módulo 8.
macOS: instalar e ajustar memória. Baixe o .dmg correspondente a seu chip (Apple Silicon ou Intel), arraste Docker para Applications, inicie-o. Depois Settings (roda dentada) → Resources → Advanced: mova Memory para 8 GB (4 GB mínimo) e CPUs para 4, depois Apply & restart. O que observar: docker info --format '{{.MemTotal}}' reflete seu valor. kubectl será instalado em /usr/local/bin/kubectl na ativação do Kubernetes; se você tinha um via Homebrew e os dois se disputam, delete aquele do Docker ou do Homebrew, não ambos (lição 03).
Linux: Docker Desktop, ou não. Dois caminhos. Docker Desktop para Linux (pacote .deb ou .rpm em docs.docker.com/desktop/setup/install/linux) dá exatamente o mesmo Kubernetes integrado que Windows e macOS; exige KVM (lsmod | grep kvm deve listar o módulo) e uma sessão gráfica. Docker Engine apenas (docker-ce via apt/dnf) não inclui Kubernetes: se você está em um servidor ou prefere Engine, instale kind ou minikube; todos os comandos kubectl do curso ficarão idênticos, apenas o acesso aos Services mudará (lição 04). No Docker Desktop para Linux, kubectl não é fornecido: instale-o de kubernetes.io/docs/tasks/tools em /usr/local/bin/kubectl.
Ativar Kubernetes. Abra Docker Desktop → Settings → Kubernetes → marque Enable Kubernetes. Deixe Cluster provisioning method em Kubeadm (um nó), marque Show system containers (advanced), depois Apply & restart. Em versões 4.51+, você pode também ir pela vista Kubernetes do dashboard (ícone na barra lateral) → Create cluster → mesma escolha Kubeadm / kind → Create. Docker Desktop baixa então as imagens do plano de controle; pode listá-las enquanto trabalha:
docker desktop kubernetes images listSaída real (Docker Desktop 4.68.0):
Mode Repo Name Tag
kind docker desktop-containerd-registry-mirror v0.0.3
kind docker desktop-cloud-provider-kind v0.5.0
kind envoyproxy envoy v1.36.4
kind kindest node
kubeadm docker desktop-kubernetes kubernetes-v1.34.1-cni-v1.7.1-critools-v1.33.0-cri-dockerd-v0.3.20-1-debian
kubeadm docker desktop-storage-provisioner v3.0
kubeadm docker desktop-vpnkit-controller v4.0
kubeadm docker desktop-kubernetes-etcd 3.6.4-0
kubeadm docker desktop-kubernetes-coredns v1.12.1
kubeadm docker desktop-kubernetes-pause 3.10
kubeadm docker desktop-kubernetes-apiserver v1.34.1
kubeadm docker desktop-kubernetes-controller-manager v1.34.1
kubeadm docker desktop-kubernetes-scheduler v1.34.1
kubeadm docker desktop-kubernetes-proxy v1.34.1O que observar: dez imagens para modo kubeadm, todas tagueadas v1.34.1 para componentes do plano de controle. Reconhece etcd, apiserver, controller-manager, scheduler, proxy e coredns da lição 01. O download leva dois a quinze minutos; o ícone Kubernetes no canto inferior esquerdo da janela muda de laranja (starting) para verde.
Observe bem o que vai acontecer: interrogar Docker Desktop propriamente. O comando docker desktop (sub-comandos kubernetes disponíveis desde versão 4.44) fala com a aplicação, não com o daemon. É a verificação mais confiável, antes mesmo de kubectl.
docker desktop status
docker desktop kubernetes statusSaída real:
Name Value
Status running
SessionID 5bc01282-499f-4434-b135-f8ecf0a79886
Field Value
ID: 1758e244
State: running
Mode: kubeadm
Node Count: 1
Version: v1.34.1
Started At: 2026-09-10 21:27:23.469 -0400 EDT
Progress Message: Kubernetes is up and running
Error: NoneO que observar: Status running para a aplicação, depois State: running, Mode: kubeadm, Node Count: 1, Version: v1.34.1, Progress Message: Kubernetes is up and running, Error: None. Durante inicialização, State vale starting e Progress Message descreve a etapa (Pulling images…, Starting control plane…). Se sua versão Docker Desktop é anterior a 4.44, o comando não existe: vá direto próxima etapa.
Verificar o nó com kubectl. Feche e reabra seu terminal (o PATH mudou), depois:
kubectl get nodes -o wideSaída real:
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
docker-desktop Ready control-plane 18d v1.34.1 192.168.65.3 <none> Docker Desktop 6.6.87.2-microsoft-standard-WSL2 docker://29.3.1O que observar: Ready, v1.34.1, IP interna 192.168.65.3 (da VM, não de sua máquina), noyau WSL 2 (no macOS você leria um noyau linuxkit), e runtime docker://29.3.1: Kubernetes lança seus contêineres com o mesmo Docker que você. Na sua máquina AGE conta em segundos ou minutos.
Ver o contexto que Docker Desktop escreveu. Tudo que kubectl sabe de seu cluster cabe em ~/.kube/config (C:\Users\<você>\.kube\config no Windows).
kubectl config get-contexts
kubectl config view --minifySaída real (a máquina do curso mantém um antigo contexto minikube, parado; na sua haverá apenas docker-desktop):
CURRENT NAME CLUSTER AUTHINFO NAMESPACE
* docker-desktop docker-desktop docker-desktop
minikube minikube minikube default
apiVersion: v1
clusters:
- cluster:
certificate-authority-data: DATA+OMITTED
server: https://kubernetes.docker.internal:6443
name: docker-desktop
contexts:
- context:
cluster: docker-desktop
user: docker-desktop
name: docker-desktop
current-context: docker-desktop
kind: Config
users:
- name: docker-desktop
user:
client-certificate-data: DATA+OMITTED
client-key-data: DATA+OMITTEDO que observar: asterisco em docker-desktop, servidor https://kubernetes.docker.internal:6443, e autenticação por certificado de cliente (client-certificate-data) gerado na ativação. Lição 03 volta aos contextos.
Windows: ler o ajuste em seu arquivo. Útil o dia em que a interface recusa abrir, ou para verificar o que um colega fez.
(Get-Content "$env:APPDATA\Docker\settings-store.json" -Raw | ConvertFrom-Json) | Select-Object KubernetesEnabled, KubernetesMode, ShowKubernetesSystemContainers | Format-ListSaída real:
KubernetesEnabled : True
KubernetesMode : kubeadm
ShowKubernetesSystemContainers : TrueO que observar: os três valores marcados na etapa 5. Não modifique este arquivo manualmente enquanto Docker Desktop roda; use a interface. Nada a limpar nesta lição: você nada criou no cluster.
docker desktop kubernetes status mostra State: starting há mais de quinze minutos → as imagens da etapa 5 não baixam. Três causas em ordem: sem acesso a Docker Hub (rede corporativa com proxy: Settings → Resources → Proxies, ou peça ao administrador o ajuste KubernetesImagesRepository), disco cheio (docker system df), ou estado corrompido após atualização. Neste último: Settings → Kubernetes → Reset Kubernetes cluster, depois Apply & restart.Unable to connect to the server: dial tcp 127.0.0.1:6443: connectex: No connection could be made because the target machine actively refused it. (macOS/Linux: connect: connection refused) → ninguém escuta na porta 6443: Docker Desktop está parado, ou Kubernetes não está (mais) ativado. Inicie Docker Desktop, verifique docker desktop kubernetes status → State: running, tente novamente. Se for Error: … em vez de None, leia a mensagem: geralmente memória.docker desktop kubernetes status responde State: running mas kubectl get nodes falha, ou responde para outro cluster → seu kubectl olha em outro lugar (contexto minikube, kind-…, um cluster corporativo). kubectl config current-context deve dizer docker-desktop; senão kubectl config use-context docker-desktop. Detalhes na lição 03.WSL 2 installation is incomplete ou wsl --status falha → Windows Subsystem for Linux não está instalado ou falta noyau WSL 2. wsl --install em PowerShell administrativo, reinício, depois relance Docker Desktop. Se a janela menciona Virtual Machine Platform ou virtualização, ative Virtualization Technology (VT-x / AMD-V) em BIOS/UEFI: sem isso nem WSL 2 nem Docker Desktop iniciam.Error: menciona OOM ou contêineres k8s_… reiniciam em loop → memória insuficiente para VM. Volta à etapa 2 (Windows: .wslconfig, wsl --shutdown) ou 3 (macOS: Resources → Memory), depois Reset Kubernetes cluster se o estado ficar inconsistente.kubectl de Docker Desktop não é encontrado enquanto Kubernetes roda → no Windows, instalação "por usuário" o coloca em %LOCALAPPDATA%\Programs\DockerDesktop\resources\bin\kubectl.exe em vez de C:\Program Files\Docker\Docker\resources\bin; adicione a pasta correta ao PATH (lição 03) e reabra o terminal.docker-desktop sob WSL 2); ativá-lo = Settings → Kubernetes → Enable Kubernetes → Apply & restart, ou vista Kubernetes → Create cluster (4.51+).%UserProfile%\.wslconfig (memory=8GB, processors=4) depois wsl --shutdown.docker desktop kubernetes status deve mostrar State: running, Node Count: 1, Version: v1.34.1, Progress Message: Kubernetes is up and running; kubectl get nodes -o wide deve mostrar docker-desktop Ready control-plane.dial tcp 127.0.0.1:6443 … refused = Docker Desktop parado ou Kubernetes desativado, nunca problema de seu YAML.kubectl, o controle remoto — versões, contextos, anatomia de comando, e seu primeiro namespace primeiros-passos.Docker Desktop não atualiza o cluster Kubernetes quando a aplicação se atualiza: seu nó permanecerá em v1.34.1 até fazer Reset Kubernetes cluster, que recria um cluster vazio com a versão embutida pela novo Docker Desktop. É uma diferença fundamental de um cluster managado (EKS, GKE, AKS), onde migra-se o plano de controle depois os nós sem perder objetos. Página oficial Deploy on Kubernetes with Docker Desktop descreve os dois provisioners, a vista Kubernetes do dashboard e ajuste KubernetesImagesRepository para redes sem acesso a Docker Hub; lado Kubernetes, Install Tools explica como instalar kubectl separadamente se precisar em outra máquina.