kubectl

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.

Observe que a versão minor do kubectl (o segundo número da versão) pode diferir da versão do cluster em ±1. Usar versões mais novas ou mais antigas pode causar problemas de compatibilidade. As instruções abaixo mostram versões específicas como exemplo, mas você pode substituí-las pelas versões de que precisar.

Instalar o 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

As versões disponíveis para instalação via Homebrew podem ser encontradas na página oficial da ferramenta.

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.

O Docker Desktop para Windows adiciona sua própria versão do kubectl ao PATH. Se você tiver o Docker Desktop instalado, talvez seja necessário colocar a entrada do PATH do kubectl antes da adicionada pelo instalador do Docker Desktop ou remover a versão do kubectl instalada pelo Docker Desktop.

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

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

mkdir $env:USERPROFILE\.kube

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

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

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

1. Abra o terminal.
2. 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

1. Abra o PowerShell.
2. 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>