kubectl

Última atualização em 9 de fevereiro de 2026

O kubectl é uma ferramenta de linha de comando para trabalhar com recursos do cluster Kubernetes. Ela permite gerenciar recursos, implantar aplicações, visualizar logs e executar outras tarefas administrativas.

Instalar kubectl no Linux

Existem dois métodos para instalar o kubectl no Linux.

Instalar com curl

Baixe o binário:

curl -LO "https://storage.googleapis.com/kubernetes-release/release/v1.30.2/bin/linux/amd64/kubectl"

Verifique a integridade do arquivo:

echo "$(curl -sL https://dl.k8s.io/release/v1.30.2/bin/linux/amd64/kubectl.sha256) kubectl" | sha256sum --check

Instale o kubectl:

sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

Instalar com apt

Atualize a lista de pacotes:

sudo apt update

Instale os pacotes necessários:

sudo apt install -y apt-transport-https ca-certificates curl gnupg

Adicione a chave do repositório do Kubernetes e defina as permissões corretas:

curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg && sudo chmod 644 /etc/apt/keyrings/kubernetes-apt-keyring.gpg

Adicione o repositório à lista do APT:

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.d/kubernetes.list && sudo chmod 644 /etc/apt/sources.list.d/kubernetes.list

Atualize novamente:

sudo apt update

Instale:

sudo apt install -y kubectl

Instalar no macOS

No macOS, você pode instalar manualmente ou com Homebrew.

Instalar com Homebrew

brew install kubectl@1.30

Ou instalar todo o conjunto de ferramentas CLI do Kubernetes:

brew install kubernetes-cli@1.30

Instalar manualmente

Para Intel

curl -LO "https://dl.k8s.io/release/v1.30.2/bin/darwin/amd64/kubectl"

Verifique a integridade:

echo "$(curl -sL https://dl.k8s.io/release/v1.30.2/bin/darwin/amd64/kubectl.sha256) kubectl" | sha256sum --check

Para Apple Silicon

curl -LO "https://dl.k8s.io/release/v1.30.2/bin/darwin/arm64/kubectl"

Verifique:

echo "$(curl -sL https://dl.k8s.io/release/v1.30.2/bin/darwin/arm64/kubectl.sha256) kubectl" | sha256sum --check

Torne o arquivo executável, ajuste as permissões, mova para /usr/local/bin e defina o proprietário como root:

chmod +x ./kubectl && chmod 644 ./kubectl && sudo mv ./kubectl /usr/local/bin/kubectl && sudo chown root: /usr/local/bin/kubectl

Instalar no Windows

Você pode instalar manualmente ou com Chocolatey.

Instalar com Chocolatey

choco install kubernetes-cli --version=1.30.2

Instalar manualmente

Abra o PowerShell e execute:

mkdir kubectl
cd .\kubectl\
curl.exe -LO "https://dl.k8s.io/release/v1.30.2/bin/windows/amd64/kubectl.exe"

Adicione o caminho do diretório do kubectl ao seu PATH executando o seguinte script no PowerShell:

$destination="$env:USERPROFILE\kubectl"
$currentPath = [System.Environment]::GetEnvironmentVariable("Path", [System.EnvironmentVariableTarget]::User)

if ($currentPath -notlike "*$destination*") {
[System.Environment]::SetEnvironmentVariable("Path", "$currentPath;$destination", [System.EnvironmentVariableTarget]::User)
}

Ou adicione o caminho manualmente:

Clique com o botão direito em This PC
Selecione Properties
Vá para About
Clique em Advanced system settings
Abra a aba Advanced
Clique em Environment Variables
Na seção System variables, encontre a variável Path e adicione o caminho do diretório do kubectl

Reinicie o PowerShell para que as alterações tenham efeito.

Após a instalação, verifique:

kubectl version

Configurar o acesso ao cluster Kubernetes

Para se conectar ao cluster, você precisa do arquivo kubeconfig.

O arquivo config.yaml informa ao kubectl qual cluster usar e quais credenciais aplicar. Ele contém dados sobre clusters, usuários e contextos, permitindo alternar facilmente entre diferentes configurações.

Como esse arquivo contém credenciais sensíveis, armazene-o em um local seguro. Se alguém obtiver acesso, poderá gerenciar o cluster e seus recursos.

Você pode baixar o arquivo de configuração no Dashboard do cluster.

Colocar o kubeconfig no diretório home

Depois de obter o arquivo config.yaml, você precisa colocá-lo no diretório correto para que o kubectl possa usá-lo.

macOS e Linux

Crie o diretório .kube no seu diretório home, caso ainda não exista:

mkdir -p ~/.kube

Copie o arquivo config.yaml para este diretório e renomeie-o para config:

cp ~/Downloads/config.yaml ~/.kube/config

Após esses passos, o kubectl usará automaticamente a configuração do arquivo ~/.kube/config.

Windows

Abra o PowerShell.
Crie o diretório .kube no seu diretório home, caso ainda não exista:

mkdir $env:USERPROFILE\.kube

Copie o arquivo config.yaml para este diretório e renomeie-o para config:

copy <path_to_config.yaml> $env:USERPROFILE\.kube\config

Execute o PowerShell como administrador e rode:

[Environment]::SetEnvironmentVariable("KUBECONFIG", $HOME + "\.kube\config", [EnvironmentVariableTarget]::Machine)

Após esses passos, o kubectl usará automaticamente a configuração do arquivo $env:USERPROFILE\.kube\config.

Usar a variável de ambiente KUBECONFIG

Se você precisar usar múltiplos arquivos de configuração ou colocar o config.yaml em outro local, você pode usar a variável de ambiente KUBECONFIG.

macOS e Linux

Abra o terminal.
Defina a variável de ambiente KUBECONFIG:

export KUBECONFIG=<caminho-para-seu-kubeconfig>

Para que essas configurações persistam após reiniciar o sistema, execute o seguinte comando, substituindo ~/.bashrc por ~/.zshrc (no macOS) ou ~/.profile se necessário:

echo "export KUBECONFIG=<caminho-para-seu-kubeconfig>" >> ~/.bashrc

Windows

Abra o PowerShell.
Defina a variável de ambiente KUBECONFIG:

$env:KUBECONFIG = "<caminho-para-seu-kubeconfig>"

Usar múltiplos arquivos de configuração

Você pode especificar vários arquivos kubeconfig separando os caminhos por dois-pontos (macOS/Linux) ou ponto e vírgula (Windows).

Windows

$env:KUBECONFIG="<caminho-do-primeiro-kubeconfig>;<caminho-do-segundo-kubeconfig>"

macOS e Linux

export KUBECONFIG=<caminho-do-primeiro-kubeconfig>:<caminho-do-segundo-kubeconfig>

Configurar a conexão com o cluster Kubernetes

Depois de configurar o acesso, você precisa garantir que o kubectl consiga se conectar ao cluster. Para isso, execute o comando:

kubectl cluster-info

Este comando exibirá informações sobre seu cluster, incluindo os endereços da API e de outros componentes. Se o comando for bem-sucedido, o kubectl está conectado ao cluster.

Verificar um contexto

Os contextos permitem alternar entre diferentes clusters e credenciais. Cada contexto é uma combinação de cluster, usuário e namespace.

Para listar os contextos disponíveis e ver qual está ativo:

kubectl config get-contexts

Este comando exibirá uma tabela com os contextos disponíveis e indicará qual está ativo.

Para alternar para um contexto diferente:

kubectl config use-context <nome-do-contexto>

Substitua <nome-do-contexto> pelo nome obtido no comando anterior. Depois disso, o kubectl usará o novo contexto para todos os comandos subsequentes.

Configurar a conclusão automática de comandos

A conclusão automática ajuda a digitar comandos mais rápido e reduzir erros, sugerindo opções automaticamente enquanto você digita. É especialmente útil para comandos longos e complexos do kubectl.

Instalar bash-completion

Instale o pacote bash-completion.

Ubuntu/Debian:

sudo apt install bash-completion

CentOS/RHEL:

sudo yum install bash-completion

macOS (Homebrew):

brew install bash-completion

Ativar autocompletar na sessão atual

bash (Linux):

source <(kubectl completion bash)

zsh (macOS e Linux):

source <(kubectl completion zsh)

Para manter o autocompletar sempre habilitado, execute:

bash (Linux):

echo "source <(kubectl completion bash)" >> ~/.bashrc

zsh (macOS e Linux):

echo "source <(kubectl completion zsh)" >> ~/.zshrc

Comandos básicos do kubectl

Obter informações do cluster

Para obter informações gerais sobre seu cluster, incluindo endereços dos componentes:

kubectl cluster-info

Visualizar pods

Para listar todos os pods no namespace atual:

kubectl get pods

Para ver pods em um namespace específico, adicione a opção -n:

kubectl get pods -n <namespace>

Visualizar serviços

Para listar todos os serviços no namespace atual:

kubectl get services

Também é possível especificar um namespace:

kubectl get services -n <namespace>

Visualizar configuração

Para ver a configuração atual e o contexto ativo:

kubectl config view

Descrever recursos

Para obter informações detalhadas sobre qualquer recurso, como um pod ou serviço:

kubectl describe <resource-type> <resource-name>

Exemplo, para ver informações de um pod:

kubectl describe pod <pod-name>

Excluir recursos

Para deletar um recurso, como um pod ou serviço:

kubectl delete <resource-type> <resource-name>

Exemplo, para deletar um pod:

kubectl delete pod <pod-name>

Instalar kubectl no Linux Copiar link

Instalar com curl Copiar link

Instalar com apt Copiar link

Instalar no macOS Copiar link

Instalar com Homebrew Copiar link

Instalar manualmente Copiar link

Para Intel

Para Apple Silicon

Instalar no Windows Copiar link

Instalar com Chocolatey Copiar link

Instalar manualmente Copiar link

Configurar o acesso ao cluster Kubernetes Copiar link

Colocar o kubeconfig no diretório home Copiar link

macOS e Linux

Windows

Usar a variável de ambiente KUBECONFIG Copiar link

macOS e Linux

Windows

Usar múltiplos arquivos de configuração Copiar link

Windows

macOS e Linux

Configurar a conexão com o cluster Kubernetes Copiar link

Verificar um contexto Copiar link

Configurar a conclusão automática de comandos Copiar link

Instalar bash-completion Copiar link

Ativar autocompletar na sessão atual Copiar link

Comandos básicos do kubectl Copiar link

Obter informações do cluster Copiar link

Visualizar pods Copiar link

Visualizar serviços Copiar link

Visualizar configuração Copiar link

Descrever recursos Copiar link

Excluir recursos Copiar link

Instalar kubectl no Linux

Instalar com curl

Instalar com apt

Instalar no macOS

Instalar com Homebrew

Instalar manualmente

Instalar no Windows

Instalar com Chocolatey

Instalar manualmente

Configurar o acesso ao cluster Kubernetes

Colocar o kubeconfig no diretório home

Usar a variável de ambiente KUBECONFIG

Usar múltiplos arquivos de configuração

Configurar a conexão com o cluster Kubernetes

Verificar um contexto

Configurar a conclusão automática de comandos

Instalar bash-completion

Ativar autocompletar na sessão atual

Comandos básicos do kubectl

Obter informações do cluster

Visualizar pods

Visualizar serviços

Visualizar configuração

Descrever recursos

Excluir recursos