Este documento pode estar desatualizado

Este documento possui uma data de atualização mais antiga que o documento original. Portanto, este conteúdo pode estar desatualizado. Se você lê inglês, veja a versão em inglês para acessar a versão mais atualizada: Install and Set Up kubectl on macOS

Instalar e configurar o kubectl no macOS

Antes de você começar

Você deve usar uma versão do kubectl que esteja próxima da versão do seu cluster. Por exemplo, um cliente v1.35 pode se comunicar com as versões v1.34, v1.35 e v1.36 da camada de gerenciamento. Usar a versão compatível mais recente do kubectl ajuda a evitar problemas inesperados.

Instalando o kubectl no macOS

Existem os seguintes métodos para instalar o kubectl no macOS:

Instalar o kubectl com o curl no macOS

  1. Baixe a última versão:

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"
   

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"

    Nota:

    Para baixar uma versão específica, substitua a parte $(curl -L -s https://dl.k8s.io/release/stable.txt) do comando com a versão específica da versão.

    Por exemplo, para baixar a versão 1.35.0 no Intel macOS, digite:

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

    E para macOS no Apple Silicon, digite:

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

  2. Valide o binário (opcional).

    Baixe o arquivo de checksum do kubectl:

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl.sha256"
   

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl.sha256"

    Valide o binário do kubectl com o arquivo de checksum:

    echo "$(cat kubectl.sha256)  kubectl" | shasum -a 256 --check

    Se for válido, a saída será:

    kubectl: OK

    Se houver falha na validação, o shasum vai retornar uma saída diferente de zero semelhante a:

    kubectl: FAILED
shasum: WARNING: 1 computed checksum did NOT match

    Nota:

    Baixe a mesma versão do binário e do checksum.

  3. Torne o binário do kubectl executável.

    chmod +x ./kubectl

  4. Mova o binário do kubectl para um diretório que esteja no PATH do seu sistema.

    sudo mv ./kubectl /usr/local/bin/kubectl
sudo chown root: /usr/local/bin/kubectl

    Nota:

    Confira que /usr/local/bin está configurado na sua variável de ambiente PATH.

  5. Teste para validar que a versão instalada está atualizada:

    kubectl version --client

    Ou se preferir, use o seguinte comando para uma visão mais detalhada sobre a versão do Kubernetes:

    kubectl version --client --output=yaml

  6. Depois de instalar e validar o kubectl, delete o arquivo de checksum:

    rm kubectl.sha256

Instalar com Homebrew no macOS

Se você está no macOS e usando o gerenciador de pacote Homebrew, você pode instalar o kubectl usando o Homebrew.

  1. Execute o comando de instalação:

    brew install kubectl

    ou

    brew install kubernetes-cli

  2. Teste para validar se a versão instalada está atualizada:

    kubectl version --client

Instalar com Macports no macOS

Se você está no macOS, usando o gerenciador de pacotes Macports, você pode instalar o kubectl utilizando o Macports.

  1. Execute o comando de instalação:

    sudo port selfupdate
sudo port install kubectl

  2. Teste para validar se a versão instalada está atualizada:

    kubectl version --client

Verificar a configuração do kubectl

Para que o kubectl encontre e acesse um cluster Kubernetes, ele precisa de um arquivo kubeconfig, que é criado automaticamente quando você cria um cluster usando kube-up.sh ou instala com sucesso um cluster Minikube. Por padrão, a configuração kubectl está localizada em ~/.kube/config.

Verifique se o kubectl está configurado corretamente obtendo o estado do cluster:

kubectl cluster-info

Se você receber uma URL de resposta, o kubectl está configurado corretamente para acessar seu cluster.

Se você receber uma mensagem semelhante à seguinte, o kubectl não está configurado corretamente ou não consegue se conectar a um cluster Kubernetes.

The connection to the server <server-name:port> was refused - did you specify the right host or port?

Por exemplo, se você pretende executar um cluster Kubernetes no seu laptop (localmente), precisará que uma ferramenta como o Minikube seja instalada primeiro, para em seguida executar novamente os comandos indicados acima.

Se o comando kubectl cluster-info retornar a URL de resposta, mas você não conseguir acessar seu cluster, use o comando abaixo para verificar se ele está configurado corretamente:

kubectl cluster-info dump

Depurando a mensagem de erro 'No Auth Provider Found'

No Kubernetes 1.26, o kubectl removeu os autenticadores embutidos para as distribuições de Kubernetes dos provedores de nuvem abaixo. Estes provedores lançaram plugins para o kubectl que fornecem autenticação específica para a nuvem. Para instruções, veja as seguintes documentações de cada provedor:

Também podem haver outras razões para que a mesma mensagem de erro ocorra, não relacionadas a esta mudança.

Configurações e plugins opcionais do kubectl

Ative o autocompletar no shell

O kubectl oferece recursos de autocompletar para Bash, Zsh, Fish e PowerShell, o que pode economizar muita digitação.

Abaixo estão os procedimentos para configurar o autocompletar para Bash, Fish e Zsh.

Introdução

O script de autocompletar do kubectl para Bash pode ser gerado com o comando kubectl completion bash. O script permite habilitar o autocompletar do kubectl no seu shell.

No entanto, o script autocompletar depende do bash-completion, o que significa que você precisa instalar este software primeiro.

Aviso:

Existem duas versões do bash-completion, v1 e v2. V1 é para Bash 3.2 (que é padrão no macOS), e v2 é para Bash 4.1+. O script de autocompletar do kubectl não funciona corretamente com o bash-completion v1 e o Bash 3.2. Ele requer bash-completion v2 e Bash 4.1+. Por isso, para executarmos o autocompletar do kubectl no macOS de forma correta, você precisa instalar e usar o Bash 4.1+ (guia). As instruções a seguir, levam em conta que você utilize o Bash 4.1+. (ou seja, a versão 4.1 do Bash ou qualquer outra mais recente).

Atualizando Bash

As instruções abaixo sugerem que você esteja utilizando o Bash 4.1+. Você pode verificar a versão do seu Bash com o comando:

echo $BASH_VERSION

Se a versão do Bash for muito antiga, você pode instalar ou atualizar utilizando o Homebrew:

brew install bash

Recarregue seu shell e verifique se a versão desejada foi instalada e está em uso:

echo $BASH_VERSION $SHELL

O Homebrew normalmente instala os pacotes em /usr/local/bin/bash.

Instalar bash-completar

Nota:

Como mencionado anteriormente, essas instruções assumem que você esteja utilizando o Bash 4.1+. Por isso, você irá instalar o bash-completion v2 (em contraste ao Bash 3.2 e bash-completion v1, caso em que o autocompletar do kubectl não irá funcionar).

Você pode testar se o bash-completion v2 está instalado, utilizando type _init_completion. Se não, você pode instalar utilizando o Homebrew:

brew install bash-completion@2

Como indicado na saída deste comando, adicione a seguinte linha em seu arquivo ~/.bash_profile:

brew_etc="$(brew --prefix)/etc" && [[ -r "${brew_etc}/profile.d/bash_completion.sh" ]] && . "${brew_etc}/profile.d/bash_completion.sh"

Recarregue seu shell e verifique que o bash-completion v2 está instalado corretamente utilizando type _init_completion.

Habilitar autocompletar do kubectl

Agora você precisa garantir que o script de autocompletar do kubectl seja carregado em todas as suas sessões de shell. Existem várias maneiras de fazer isso:

  • Carregue o script de autocompletar no seu arquivo ~/.bash_profile:

    echo 'source <(kubectl completion bash)' >>~/.bash_profile

  • Adicione o script de autocompletar ao diretório /usr/local/etc/bash_completion.d:

    kubectl completion bash >/usr/local/etc/bash_completion.d/kubectl

  • Se você tiver um alias para o kubectl, pode estender o autocompletar do shell para funcionar com esse alias:

    echo 'alias k=kubectl' >>~/.bash_profile
echo 'complete -o default -F __start_kubectl k' >>~/.bash_profile

  • Se você tiver instalado o kubectl com o Homebrew(conforme explicado aqui), então o script de autocompletar do kubectl deverá estar pronto em /usr/local/etc/bash_completion.d/kubectl. Neste caso, você não precisa fazer mais nada.

    Nota:

    A instalação do bash-completion v2 via Homebrew carrega todos os arquivos no diretório BASH_COMPLETION_COMPAT_DIR, é por isso que os dois últimos métodos funcionam.

Em todos os casos, após recarregar seu shell, o autocompletar do kubectl deve estar funcionando.

Nota:

O autocompletar para Fish requer kubectl 1.23 ou posterior.

O script de autocompletar do kubectl para Fish pode ser gerado com o comando kubectl completion fish. O script permite habilitar o autocompletar do kubectl no seu shell.

Para fazer isso em todas as suas sessões do shell, adicione a seguinte linha ao seu arquivo ~/.config/fish/config.fish:

kubectl completion fish | source

Depois de recarregar seu shell, o autocompletar do kubectl deve estar funcionando.

O script de autocompletar do kubectl para Zsh pode ser gerado com o comando kubectl completion zsh. Este script habilita o autocompletar do kubectl no seu shell.

Para fazer isso em todas as suas sessões de shell, adicione a seguinte linha no arquivo ~/.zshrc:

source <(kubectl completion zsh)

Se você tiver um alias para kubectl, o autocompletar funcionará automaticamente com ele.

Depois de recarregar seu shell, o autocompletar do kubectl deve estar funcionando.

Se você ver um erro similar a 2: command not found: compdef, adicione o seguinte bloco ao início do seu arquivo ~/.zshrc:

autoload -Uz compinit
compinit

Instalar kubectl convert plugin

Um plugin para a ferramenta Kubernetes de linha de comando kubectl, que permite converter manifestos entre diferentes versões da API. Isso pode ser particularmente útil para migrar manifestos para uma versão não obsoleta com a versão mais recente da API Kubernetes. Para mais informações, visite Migrar para APIs não obsoletas

  1. Faça download da versão mais recente com o comando:

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl-convert"
   

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl-convert"

  2. Valide o binário (opcional).

    Faça download do arquivo checksum de verificação do kubectl-convert:

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl-convert.sha256"
   

    
   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl-convert.sha256"

    Valide o binário kubectl-convert com o arquivo de verificação:

    echo "$(cat kubectl-convert.sha256)  kubectl-convert" | shasum -a 256 --check

    Se for válido, a saída será:

    kubectl-convert: OK

    Se a verificação falhar, o sha256 exibirá o status diferente de zero e a saída será semelhante a:

    kubectl-convert: FAILED
shasum: WARNING: 1 computed checksum did NOT match

    Nota:

    Baixe a mesma versão do binário e do checksum.

  3. Torne o binário do kubectl-convert um executável.

    chmod +x ./kubectl-convert

  4. Mova o binário do kubectl-convert para o PATH do sistema.

    sudo mv ./kubectl-convert /usr/local/bin/kubectl-convert
sudo chown root: /usr/local/bin/kubectl-convert

    Nota:

    Tenha certeza de que /usr/local/bin está no PATH em suas configurações de variáveis ambiente.

  5. Verifique se o plugin foi instalado com sucesso.

    kubectl convert --help

    Se você não encontrar nenhum erro, isso quer dizer que o plugin foi instalado com sucesso.

  6. Após instalar o plugin, limpe os arquivos de instalação:

    rm kubectl-convert kubectl-convert.sha256

Desinstalar o kubectl no macOS

Dependendo da forma que você instalou o kubectl, use um dos métodos abaixo.

Desinstalar o kubectl usando a linha de comando

  1. Localize o binário do kubectl no seu sistema:

    which kubectl

  2. Remova o binário kubectl:

    sudo rm <path>

    Substitua <path> com o PATH do binário kubectl conforme os passos anteriores. Por exemplo, sudo rm /usr/local/bin/kubectl.

Desinstalar o kubectl usando o homebrew

Se você instalou o kubectl utilizando Homebrew, execute o comando a seguir:

brew remove kubectl

Próximos passos


Última modificação November 18, 2024 at 6:20 PM PST: [pt-br] Update docs/tasks/tools/install-kubectl-macos (e7ac3287d1)