Ferramenta de linha de comando (kubectl)

Kubernetes fornece um ferramenta de linha de comando para se comunicar com a camada de gerenciamento de um cluster Kubernetes usando a API do Kubernetes.

Esta ferramenta é chamada kubectl.

Para configuração, kubectl procura por um arquivo chamado config no diretório $HOME/.kube. Você pode especificar outros arquivos kubeconfig definindo a variável de ambiente KUBECONFIG ou configurando a flag --kubeconfig.

Esta visão geral abrange a sintaxe do kubectl, descreve as operações de comando e fornece exemplos comuns. Para detalhes sobre cada comando, incluindo todas as opções e subcomandos suportados, consulte a documentação de referência do kubectl.

Para instruções de instalação, consulte Instalando kubectl; para um guia rápido, consulte a folha de dicas. Se você está acostumado a usar a ferramenta de linha de comando docker, kubectl para Usuários Docker explica alguns comandos equivalentes para Kubernetes.

Sintaxe

Use a seguinte sintaxe para executar comandos kubectl da janela do seu terminal:

kubectl [command] [TYPE] [NAME] [flags]

onde command, TYPE, NAME e flags são:

• command: Especifica a operação que você deseja executar em um ou mais recursos, por exemplo create, get, describe, delete.

• TYPE: Especifica o tipo de recurso. Tipos de recursos não diferenciam maiúsculas de minúsculas e você pode especificar as formas singular, plural ou abreviada. Por exemplo, os seguintes comandos produzem a mesma saída:

  kubectl get pod pod1
  kubectl get pods pod1
  kubectl get po pod1
  

• NAME: Especifica o nome do recurso. Nomes diferenciam maiúsculas de minúsculas. Se o nome for omitido, detalhes para todos os recursos são exibidos, por exemplo kubectl get pods.

  Ao realizar uma operação em vários recursos, você pode especificar cada recurso por tipo e nome ou especificar um ou mais arquivos:

  • Para especificar recursos por tipo e nome:

    • Para agrupar recursos se todos forem do mesmo tipo: TYPE1 name1 name2 name<#>.
      Exemplo: kubectl get pod example-pod1 example-pod2

    • Para especificar vários tipos de recursos individualmente: TYPE1/name1 TYPE1/name2 TYPE2/name3 TYPE<#>/name<#>.
      Exemplo: kubectl get pod/example-pod1 replicationcontroller/example-rc1

  • Para especificar recursos com um ou mais arquivos: -f file1 -f file2 -f file<#>

    • Use YAML em vez de JSON já que YAML tende a ser mais amigável ao usuário, especialmente para arquivos de configuração.
      Exemplo: kubectl get -f ./pod.yaml

• flags: Especifica flags opcionais. Por exemplo, você pode usar as flags -s ou --server para especificar o endereço e porta do servidor de API do Kubernetes.
  

Se você precisar de ajuda, execute kubectl help da janela do terminal.

Autenticação dentro do cluster e sobrescritas de namespace

Por padrão, kubectl primeiro determinará se está sendo executado dentro de um pod, ou seja, em um cluster. Ele começa verificando as variáveis de ambiente KUBERNETES_SERVICE_HOST e KUBERNETES_SERVICE_PORT e a existência de um arquivo de token de conta de serviço em /var/run/secrets/kubernetes.io/serviceaccount/token. Se todos os três forem encontrados, a autenticação dentro do cluster é assumida.

Para manter a retrocompatibilidade, se a variável de ambiente POD_NAMESPACE for definida durante a autenticação dentro do cluster, ela sobrescreverá o namespace padrão do token da conta de serviço. Quaisquer manifestos ou ferramentas que dependam do namespace padrão serão afetados por isso.

Variável de ambiente POD_NAMESPACE

Se a variável de ambiente POD_NAMESPACE for definida, operações de linha de comando em recursos com namespace usarão por padrão o valor da variável. Por exemplo, se a variável for definida como seattle, kubectl get pods retornaria pods no namespace seattle. Isso ocorre porque pods são um recurso com namespace, e nenhum namespace foi fornecido no comando. Revise a saída de kubectl api-resources para determinar se um recurso possui namespace.

O uso explícito de --namespace <value> sobrescreve este comportamento.

Como o kubectl lida com tokens de ServiceAccount

Se:

• há um arquivo de token de conta de serviço do Kubernetes montado em /var/run/secrets/kubernetes.io/serviceaccount/token, e
• a variável de ambiente KUBERNETES_SERVICE_HOST está definida, e
• a variável de ambiente KUBERNETES_SERVICE_PORT está definida, e
• você não especifica explicitamente um namespace na linha de comando do kubectl

então o kubectl assume que está sendo executado no seu cluster. A ferramenta kubectl procura o namespace daquela ServiceAccount (que é o mesmo namespace do Pod) e atua com esse namespace. Isso é diferente do que acontece fora de um cluster; quando o kubectl é executado fora de um cluster e você não especifica um namespace, o comando kubectl atua com o namespace definido para o contexto atual na sua configuração do cliente. Para alterar o namespace padrão para seu kubectl você pode usar o seguinte comando:

kubectl config set-context --current --namespace=<namespace-name>

Operações

A seguinte tabela inclui descrições curtas e a sintaxe geral para todas as operações do kubectl:

Para saber mais sobre operações de comando, consulte a documentação de referência do kubectl.

Tipos de recursos

A seguinte tabela inclui uma lista de todos os tipos de recursos suportados e seus pseudônimos (aliases) abreviados.

(Esta saída pode ser obtida de kubectl api-resources, e estava precisa a partir do Kubernetes 1.25.0)

Opções de saída

Use as seguintes seções para informações sobre como você pode formatar ou classificar a saída de determinados comandos. Para detalhes sobre quais comandos suportam as várias opções de saída, consulte a documentação de referência do kubectl.

Formatando a saída

O formato de saída padrão para todos os comandos kubectl é o formato de texto simples legível por humanos. Para exibir detalhes na janela do seu terminal em um formato específico, você pode adicionar as flags -o ou --output a um comando kubectl suportado.

Sintaxe

kubectl [command] [TYPE] [NAME] -o <output_format>

Dependendo da operação do kubectl, os seguintes formatos de saída são suportados:

Exemplo

Neste exemplo, o seguinte comando gera os detalhes para um único pod como um objeto formatado em YAML:

kubectl get pod web-pod-13je7 -o yaml

Lembre-se: Consulte a documentação de referência do kubectl para detalhes sobre qual formato de saída é suportado por cada comando.

Colunas personalizadas

Para definir colunas personalizadas e gerar apenas os detalhes que você deseja em uma tabela, você pode usar a opção custom-columns. Você pode escolher definir as colunas personalizadas inline ou usar um arquivo de template: -o custom-columns=<spec> ou -o custom-columns-file=<filename>.

Exemplos

Inline:

kubectl get pods <pod-name> -o custom-columns=NAME:.metadata.name,RSRC:.metadata.resourceVersion

Arquivo de template:

kubectl get pods <pod-name> -o custom-columns-file=template.txt

onde o arquivo template.txt contém:

NAME          RSRC
metadata.name metadata.resourceVersion

O resultado da execução de qualquer comando é similar a:

NAME           RSRC
submit-queue   610995

Colunas do lado do servidor

kubectl suporta receber informações específicas de colunas do servidor sobre objetos. Isso significa que para qualquer recurso dado, o servidor retornará colunas e linhas relevantes para esse recurso, para o cliente imprimir. Isso permite uma saída legível por humanos consistente entre clientes usados contra o mesmo cluster, fazendo com que o servidor encapsule os detalhes da impressão.

Esta funcionalidade está habilitada por padrão. Para desabilitá-la, adicione a flag --server-print=false ao comando kubectl get.

Exemplos

Para imprimir informações sobre o status de um pod, use um comando como o seguinte:

kubectl get pods <pod-name> --server-print=false

A saída é similar a:

NAME       AGE
pod-name   1m

Classificando objetos de lista

Para gerar objetos em uma lista classificada na janela do seu terminal, você pode adicionar a flag --sort-by a um comando kubectl suportado. Classifique seus objetos especificando qualquer campo numérico ou string com a flag --sort-by. Para especificar um campo, use uma expressão jsonpath.

Sintaxe

kubectl [command] [TYPE] [NAME] --sort-by=<jsonpath_exp>

Exemplo

Para imprimir uma lista de pods classificados por nome, você executa:

kubectl get pods --sort-by=.metadata.name

Exemplos: Operações comuns

Use o seguinte conjunto de exemplos para ajudar você a se familiarizar com a execução das operações kubectl comumente usadas:

kubectl apply - Aplica ou atualiza um recurso de um arquivo ou stdin.

# Cria um serviço usando a definição em example-service.yaml.
kubectl apply -f example-service.yaml

# Cria um controlador de replicação usando a definição em example-controller.yaml.
kubectl apply -f example-controller.yaml

# Cria os objetos que são definidos em qualquer arquivo .yaml, .yml ou .json dentro do diretório <directory>.
kubectl apply -f <directory>

kubectl get - Lista um ou mais recursos.

# Lista todos os pods em formato de saída de texto simples.
kubectl get pods

# Lista todos os pods em formato de saída de texto simples e inclui informações adicionais (como nome do nó).
kubectl get pods -o wide

# Lista o controlador de replicação com o nome especificado em formato de saída de texto simples. Dica: Você pode encurtar e substituir o tipo de recurso 'replicationcontroller' com o alias 'rc'.
kubectl get replicationcontroller <rc-name>

# Lista todos os controladores de replicação e services juntos em formato de saída de texto simples.
kubectl get rc,services

# Lista todos os daemon sets em formato de saída de texto simples.
kubectl get ds

# Lista todos os pods executando no nó server01
kubectl get pods --field-selector=spec.nodeName=server01

kubectl describe - Exibe o estado detalhado de um ou mais recursos, incluindo os não inicializados por padrão.

# Exibe os detalhes do nó com nome <node-name>.
kubectl describe nodes <node-name>

# Exibe os detalhes do pod com nome <pod-name>.
kubectl describe pods/<pod-name>

# Exibe os detalhes de todos os pods que são gerenciados pelo controlador de replicação chamado <rc-name>.
# Lembre-se: Qualquer pod que seja criado pelo controlador de replicação recebe um prefixo com o nome do controlador de replicação.
kubectl describe pods <rc-name>

# Descreve todos os pods
kubectl describe pods

kubectl delete - Exclui recursos de um arquivo, stdin, ou especificando seletores de rótulo, nomes, seletores de recursos, ou recursos.

# Exclui um pod usando o tipo e nome especificados no arquivo pod.yaml.
kubectl delete -f pod.yaml

# Exclui todos os pods e services que têm o rótulo '<label-key>=<label-value>'.
kubectl delete pods,services -l <label-key>=<label-value>

# Exclui todos os pods, incluindo os não inicializados.
kubectl delete pods --all

kubectl exec - Executa um comando contra um contêiner em um pod.

# Obtém saída da execução de 'date' do pod <pod-name>. Por padrão, a saída é do primeiro contêiner.
kubectl exec <pod-name> -- date

# Obtém saída da execução de 'date' no contêiner <container-name> do pod <pod-name>.
kubectl exec <pod-name> -c <container-name> -- date

# Obtém um TTY interativo e executa /bin/bash do pod <pod-name>. Por padrão, a saída é do primeiro contêiner.
kubectl exec -ti <pod-name> -- /bin/bash

kubectl logs - Imprime os logs de um contêiner em um pod.

# Retorna um snapshot dos logs do pod <pod-name>.
kubectl logs <pod-name>

# Inicia o streaming dos logs do pod <pod-name>. Isso é similar ao comando Linux 'tail -f'.
kubectl logs -f <pod-name>

kubectl diff - Visualiza um diff das atualizações propostas para um cluster.

# Compara recursos incluídos em "pod.json".
kubectl diff -f pod.json

# Compara arquivo lido do stdin.
cat service.yaml | kubectl diff -f -

Exemplos: Criando e usando plugins

Use o seguinte conjunto de exemplos para ajudar você a se familiarizar com a escrita e uso de plugins do kubectl:

# cria um plugin simples em qualquer linguagem e nomeia o arquivo executável resultante
# para que comece com o prefixo "kubectl-"
cat ./kubectl-hello

#!/bin/sh

# este plugin imprime as palavras "hello world"
echo "hello world"

Com um plugin escrito, vamos torná-lo executável:

chmod a+x ./kubectl-hello

# e movê-lo para um local no nosso PATH
sudo mv ./kubectl-hello /usr/local/bin
sudo chown root:root /usr/local/bin

# Você agora criou e "instalou" um plugin kubectl.
# Você pode começar a usar este plugin invocando-o do kubectl como se fosse um comando regular
kubectl hello

hello world

# Você pode "desinstalar" um plugin, removendo-o da pasta no seu
# $PATH onde você o colocou
sudo rm /usr/local/bin/kubectl-hello

Para visualizar todos os plugins que estão disponíveis para kubectl, use o subcomando kubectl plugin list:

kubectl plugin list

A saída é similar a:

The following kubectl-compatible plugins are available:

/usr/local/bin/kubectl-hello
/usr/local/bin/kubectl-foo
/usr/local/bin/kubectl-bar

kubectl plugin list também avisa sobre plugins que não são executáveis, ou que são sombreados por outros plugins; por exemplo:

sudo chmod -x /usr/local/bin/kubectl-foo # remove permissão de execução
kubectl plugin list

The following kubectl-compatible plugins are available:

/usr/local/bin/kubectl-hello
/usr/local/bin/kubectl-foo
  - warning: /usr/local/bin/kubectl-foo identified as a plugin, but it is not executable
/usr/local/bin/kubectl-bar

error: one plugin warning was found

Você pode pensar em plugins como um meio de construir funcionalidades mais complexas sobre os comandos kubectl existentes:

cat ./kubectl-whoami

Os próximos exemplos assumem que você já fez kubectl-whoami ter o seguinte conteúdo:

#!/bin/bash

# este plugin faz uso do comando `kubectl config` para gerar
# informações sobre o usuário atual, baseado no contexto atualmente selecionado
kubectl config view --template='{{ range .contexts }}{{ if eq .name "'$(kubectl config current-context)'" }}Current user: {{ printf "%s\n" .context.user }}{{ end }}{{ end }}'

Executar o comando acima fornece uma saída contendo o usuário para o contexto atual no seu arquivo KUBECONFIG:

# torna o arquivo executável
sudo chmod +x ./kubectl-whoami

# e o move para o seu PATH
sudo mv ./kubectl-whoami /usr/local/bin

kubectl whoami
Current user: plugins-user

Próximos passos

• Leia a documentação de referência do kubectl:
  • a referência de comandos kubectl
  • a referência de argumentos de linha de comando
• Aprenda sobre convenções de uso do kubectl
• Leia sobre suporte ao JSONPath no kubectl
• Leia sobre como estender kubectl com plugins
  • Para descobrir mais sobre plugins, veja plugin CLI de exemplo.