This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

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:

Operação Sintaxe Descrição
alpha kubectl alpha SUBCOMMAND [flags] Lista os comandos disponíveis que correspondem às funcionalidades alfa, que não são habilitadas por padrão nos clusters Kubernetes.
annotate kubectl annotate (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags] Adiciona ou atualiza as anotações de um ou mais recursos.
api-resources kubectl api-resources [flags] Lista os recursos de API que estão disponíveis.
api-versions kubectl api-versions [flags] Lista as versões de API que estão disponíveis.
apply kubectl apply -f FILENAME [flags] Aplica uma alteração de configuração a um recurso de um arquivo ou stdin.
attach kubectl attach POD -c CONTAINER [-i] [-t] [flags] Conecta a um contêiner em execução para visualizar o fluxo de saída ou interagir com o contêiner (stdin).
auth kubectl auth [flags] [options] Inspeciona autorização.
autoscale kubectl autoscale (-f FILENAME | TYPE NAME | TYPE/NAME) [--min=MINPODS] --max=MAXPODS [--cpu-percent=CPU] [flags] Escalona automaticamente o conjunto de pods que são gerenciados por um controlador de replicação.
certificate kubectl certificate SUBCOMMAND [options] Modifica recursos de certificado.
cluster-info kubectl cluster-info [flags] Exibe informações de endpoint sobre o nó principal e serviços no cluster.
completion kubectl completion SHELL [options] Gera código de completar automaticamente para o shell especificado (bash ou zsh).
config kubectl config SUBCOMMAND [flags] Modifica arquivos kubeconfig. Consulte os subcomandos individuais para detalhes.
convert kubectl convert -f FILENAME [options] Converte arquivos de configuração entre diferentes versões de API. Ambos os formatos YAML e JSON são aceitos. Nota - requer que o plugin kubectl-convert esteja instalado.
cordon kubectl cordon NODE [options] Marca o nó como não agendável.
cp kubectl cp <file-spec-src> <file-spec-dest> [options] Copia arquivos e diretórios "de" e "para" contêineres.
create kubectl create -f FILENAME [flags] Cria um ou mais recursos de um arquivo ou stdin.
delete kubectl delete (-f FILENAME | TYPE [NAME | /NAME | -l label | --all]) [flags] Exclui recursos de um arquivo, stdin, ou especificando seletores de rótulo, nomes, seletores de recursos, ou recursos.
describe kubectl describe (-f FILENAME | TYPE [NAME_PREFIX | /NAME | -l label]) [flags] Exibe o estado detalhado de um ou mais recursos.
diff kubectl diff -f FILENAME [flags] Compara arquivo ou stdin contra a configuração ativa.
drain kubectl drain NODE [options] Drena o nó em preparação para manutenção.
edit kubectl edit (-f FILENAME | TYPE NAME | TYPE/NAME) [flags] Edita e atualiza a definição de um ou mais recursos no servidor usando o editor padrão.
events kubectl events Lista eventos
exec kubectl exec POD [-c CONTAINER] [-i] [-t] [flags] [-- COMMAND [args...]] Executa um comando contra um contêiner em um pod.
explain kubectl explain TYPE [--recursive=false] [flags] Obtém documentação de vários recursos. Por exemplo pods, nós, serviços, etc.
expose kubectl expose (-f FILENAME | TYPE NAME | TYPE/NAME) [--port=port] [--protocol=TCP|UDP] [--target-port=number-or-name] [--name=name] [--external-ip=external-ip-of-service] [--type=type] [flags] Expõe um controlador de replicação, service, ou pod como um novo serviço Kubernetes.
get kubectl get (-f FILENAME | TYPE [NAME | /NAME | -l label]) [--watch] [--sort-by=FIELD] [[-o | --output]=OUTPUT_FORMAT] [flags] Lista um ou mais recursos.
kustomize kubectl kustomize <dir> [flags] [options] Lista um conjunto de recursos de API gerados a partir de instruções em um arquivo kustomization.yaml. O argumento deve ser o caminho para o diretório contendo o arquivo, ou uma URL de repositório git com um sufixo de caminho especificando o mesmo em relação à raiz do repositório.
label kubectl label (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags] Adiciona ou atualiza os rótulos de um ou mais recursos.
logs kubectl logs POD [-c CONTAINER] [--follow] [flags] Imprime os logs de um contêiner em um pod.
options kubectl options Lista de opções globais de linha de comando, que se aplicam a todos os comandos.
patch kubectl patch (-f FILENAME | TYPE NAME | TYPE/NAME) --patch PATCH [flags] Atualiza um ou mais campos de um recurso usando o processo de merge estratégico de patch.
plugin kubectl plugin [flags] [options] Fornece utilitários para interagir com plugins.
port-forward kubectl port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N] [flags] Encaminha uma ou mais portas locais para um pod.
proxy kubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix] [flags] Executa um proxy para o servidor de API do Kubernetes.
replace kubectl replace -f FILENAME Substitui um recurso de um arquivo ou stdin.
rollout kubectl rollout SUBCOMMAND [options] Gerencia o rollout de um recurso. Tipos de recursos válidos incluem: deployments, daemonsets e statefulsets.
run kubectl run NAME --image=image [--env="key=value"] [--port=port] [--dry-run=server|client|none] [--overrides=inline-json] [flags] Executa uma imagem especificada no cluster.
scale kubectl scale (-f FILENAME | TYPE NAME | TYPE/NAME) --replicas=COUNT [--resource-version=version] [--current-replicas=count] [flags] Atualiza o tamanho do controlador de replicação especificado.
set kubectl set SUBCOMMAND [options] Configura recursos de aplicação.
taint kubectl taint NODE NAME KEY_1=VAL_1:TAINT_EFFECT_1 ... KEY_N=VAL_N:TAINT_EFFECT_N [options] Atualiza os taints em um ou mais nós.
top kubectl top (POD | NODE) [flags] [options] Exibe o uso de recursos (CPU/Memória/Armazenamento) de pod ou nó.
uncordon kubectl uncordon NODE [options] Marca o nó como agendável.
version kubectl version [--client] [flags] Exibe a versão do Kubernetes em execução no cliente e servidor.
wait kubectl wait ([-f FILENAME] | resource.group/resource.name | resource.group [(-l label | --all)]) [--for=delete|--for condition=available] [options] Experimental: Aguarda uma condição específica em um ou muitos recursos.

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)

NAME SHORTNAMES APIVERSION NAMESPACED KIND
bindings v1 true Binding
componentstatuses cs v1 false ComponentStatus
configmaps cm v1 true ConfigMap
endpoints ep v1 true Endpoints
events ev v1 true Event
limitranges limits v1 true LimitRange
namespaces ns v1 false Namespace
nodes no v1 false Node
persistentvolumeclaims pvc v1 true PersistentVolumeClaim
persistentvolumes pv v1 false PersistentVolume
pods po v1 true Pod
podtemplates v1 true PodTemplate
replicationcontrollers rc v1 true ReplicationController
resourcequotas quota v1 true ResourceQuota
secrets v1 true Secret
serviceaccounts sa v1 true ServiceAccount
services svc v1 true Service
mutatingwebhookconfigurations admissionregistration.k8s.io/v1 false MutatingWebhookConfiguration
validatingwebhookconfigurations admissionregistration.k8s.io/v1 false ValidatingWebhookConfiguration
customresourcedefinitions crd,crds apiextensions.k8s.io/v1 false CustomResourceDefinition
apiservices apiregistration.k8s.io/v1 false APIService
controllerrevisions apps/v1 true ControllerRevision
daemonsets ds apps/v1 true DaemonSet
deployments deploy apps/v1 true Deployment
replicasets rs apps/v1 true ReplicaSet
statefulsets sts apps/v1 true StatefulSet
tokenreviews authentication.k8s.io/v1 false TokenReview
localsubjectaccessreviews authorization.k8s.io/v1 true LocalSubjectAccessReview
selfsubjectaccessreviews authorization.k8s.io/v1 false SelfSubjectAccessReview
selfsubjectrulesreviews authorization.k8s.io/v1 false SelfSubjectRulesReview
subjectaccessreviews authorization.k8s.io/v1 false SubjectAccessReview
horizontalpodautoscalers hpa autoscaling/v2 true HorizontalPodAutoscaler
cronjobs cj batch/v1 true CronJob
jobs batch/v1 true Job
certificatesigningrequests csr certificates.k8s.io/v1 false CertificateSigningRequest
leases coordination.k8s.io/v1 true Lease
endpointslices discovery.k8s.io/v1 true EndpointSlice
events ev events.k8s.io/v1 true Event
flowschemas flowcontrol.apiserver.k8s.io/v1beta2 false FlowSchema
prioritylevelconfigurations flowcontrol.apiserver.k8s.io/v1beta2 false PriorityLevelConfiguration
ingressclasses networking.k8s.io/v1 false IngressClass
ingresses ing networking.k8s.io/v1 true Ingress
networkpolicies netpol networking.k8s.io/v1 true NetworkPolicy
runtimeclasses node.k8s.io/v1 false RuntimeClass
poddisruptionbudgets pdb policy/v1 true PodDisruptionBudget
podsecuritypolicies psp policy/v1beta1 false PodSecurityPolicy
clusterrolebindings rbac.authorization.k8s.io/v1 false ClusterRoleBinding
clusterroles rbac.authorization.k8s.io/v1 false ClusterRole
rolebindings rbac.authorization.k8s.io/v1 true RoleBinding
roles rbac.authorization.k8s.io/v1 true Role
priorityclasses pc scheduling.k8s.io/v1 false PriorityClass
csidrivers storage.k8s.io/v1 false CSIDriver
csinodes storage.k8s.io/v1 false CSINode
csistoragecapacities storage.k8s.io/v1 true CSIStorageCapacity
storageclasses sc storage.k8s.io/v1 false StorageClass
volumeattachments storage.k8s.io/v1 false VolumeAttachment

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:

Formato de saída Descrição
-o custom-columns=<spec> Imprime uma tabela usando uma lista separada por vírgulas de colunas personalizadas.
-o custom-columns-file=<filename> Imprime uma tabela usando o template de colunas personalizadas no arquivo <filename>.
-o json Gera um objeto de API formatado em JSON.
-o jsonpath=<template> Imprime os campos definidos em uma expressão jsonpath.
-o jsonpath-file=<filename> Imprime os campos definidos pela expressão jsonpath no arquivo <filename>.
-o kyaml Gera um objeto de API formatado em KYAML (alfa, requer variável de ambiente KUBECTL_KYAML="true").
-o name Imprime apenas o nome do recurso e nada mais.
-o wide Saída no formato de texto simples com qualquer informação adicional. Para pods, o nome do nó é incluído.
-o yaml Gera um objeto de API formatado em YAML. KYAML é um dialeto experimental específico do Kubernetes do YAML, e pode ser interpretado como YAML.
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

1 - Referência Rápida do kubectl

Esta página contém uma lista de comandos e flags do kubectl comumente utilizados.

Autocompletar do kubectl

BASH

source <(kubectl completion bash) # configura o autocompletar no bash para o shell atual, o pacote bash-completion deve ser instalado primeiro.
echo "source <(kubectl completion bash)" >> ~/.bashrc # adiciona o autocompletar permanentemente ao seu shell bash.

Você também pode usar um alias abreviado para kubectl que também funciona com o completion:

alias k=kubectl
complete -o default -F __start_kubectl k

ZSH

source <(kubectl completion zsh)  # configura o autocompletar no zsh para o shell atual
echo '[[ $commands[kubectl] ]] && source <(kubectl completion zsh)' >> ~/.zshrc # adiciona o autocompletar permanentemente ao seu shell zsh

FISH

echo 'kubectl completion fish | source' > ~/.config/fish/completions/kubectl.fish && source ~/.config/fish/completions/kubectl.fish

Uma observação sobre --all-namespaces

Adicionar --all-namespaces acontece com frequência suficiente para que você deva estar ciente da abreviação para --all-namespaces:

kubectl -A

Contexto e configuração do kubectl

Define com qual cluster Kubernetes o kubectl se comunica e modifica as informações de configuração. Consulte a documentação Autenticando entre Clusters com kubeconfig para informações detalhadas sobre o arquivo de configuração.

kubectl config view # Mostra as configurações mescladas do kubeconfig.

# usa múltiplos arquivos kubeconfig ao mesmo tempo e visualiza a configuração mesclada
KUBECONFIG=~/.kube/config:~/.kube/kubconfig2

kubectl config view

# Mostra as configurações mescladas do kubeconfig e dados brutos de certificado e segredos expostos
kubectl config view --raw 

# obtém a senha para o usuário e2e
kubectl config view -o jsonpath='{.users[?(@.name == "e2e")].user.password}'

# obtém o certificado para o usuário e2e
kubectl config view --raw -o jsonpath='{.users[?(.name == "e2e")].user.client-certificate-data}' | base64 -d

kubectl config view -o jsonpath='{.users[].name}'    # exibe o primeiro usuário
kubectl config view -o jsonpath='{.users[*].name}'   # obtém uma lista de usuários
kubectl config get-contexts                          # exibe a lista de contextos
kubectl config get-contexts -o name                  # obtém todos os nomes de contexto
kubectl config current-context                       # exibe o contexto atual
kubectl config use-context my-cluster-name           # define o contexto padrão como my-cluster-name

kubectl config set-cluster my-cluster-name           # define uma entrada de cluster no kubeconfig

# configura a URL para um servidor proxy a ser usado para requisições feitas por este cliente no kubeconfig
kubectl config set-cluster my-cluster-name --proxy-url=my-proxy-url

# adiciona um novo usuário ao seu kubeconf que suporta autenticação básica
kubectl config set-credentials kubeuser/foo.kubernetes.com --username=kubeuser --password=kubepassword

# salva permanentemente o namespace para todos os comandos kubectl subsequentes naquele contexto.
kubectl config set-context --current --namespace=ggckad-s2

# define um contexto utilizando um nome de usuário e namespace específicos.
kubectl config set-context gce --user=cluster-admin --namespace=foo \
  && kubectl config use-context gce

kubectl config unset users.foo                       # exclui o usuário foo

# alias abreviado para definir/mostrar contexto/namespace (funciona apenas para bash e shells compatíveis com bash, o contexto atual deve ser definido antes de usar kn para definir o namespace)
alias kx='f() { [ "$1" ] && kubectl config use-context $1 || kubectl config current-context ; } ; f'
alias kn='f() { [ "$1" ] && kubectl config set-context --current --namespace $1 || kubectl config view --minify | grep namespace | cut -d" " -f6 ; } ; f'

Kubectl apply

O apply gerencia aplicações por meio de arquivos que definem recursos do Kubernetes. Ele cria e atualiza recursos em um cluster executando kubectl apply. Esta é a forma recomendada de gerenciar aplicações Kubernetes em produção. Consulte Kubectl Book.

Criando objetos

Os manifestos do Kubernetes podem ser definidos em YAML ou JSON. As extensões de arquivo .yaml, .yml e .json podem ser utilizadas.

kubectl apply -f ./my-manifest.yaml                 # cria recurso(s)
kubectl apply -f ./my1.yaml -f ./my2.yaml           # cria a partir de múltiplos arquivos
kubectl apply -f ./dir                              # cria recurso(s) em todos os arquivos de manifesto no diretório
kubectl apply -f https://example.com/manifest.yaml  # cria recurso(s) a partir de url (Nota: este é um domínio de exemplo e não contém um manifesto válido)
kubectl create deployment nginx --image=nginx       # inicia uma única instância do nginx

# cria um Job que imprime "Hello World"
kubectl create job hello --image=busybox:1.28 -- echo "Hello World"

# cria uma CronJob que imprime "Hello World" a cada minuto
kubectl create cronjob hello --image=busybox:1.28   --schedule="*/1 * * * *" -- echo "Hello World"

kubectl explain pods                           # obtém a documentação para manifestos de pod

# Cria múltiplos objetos YAML a partir do stdin
kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: busybox-sleep
spec:
  containers:
  - name: busybox
    image: busybox:1.28
    args:
    - sleep
    - "1000000"
---
apiVersion: v1
kind: Pod
metadata:
  name: busybox-sleep-less
spec:
  containers:
  - name: busybox
    image: busybox:1.28
    args:
    - sleep
    - "1000"
EOF

# Cria um secret com várias chaves
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: mysecret
type: Opaque
data:
  password: $(echo -n "s33msi4" | base64 -w0)
  username: $(echo -n "jane" | base64 -w0)
EOF

Visualizando e encontrando recursos

# Comandos get com saída básica
kubectl get services                          # Lista todos os services no namespace
kubectl get pods --all-namespaces             # Lista todos os pods em todos os namespaces
kubectl get pods -o wide                      # Lista todos os pods no namespace atual, com mais detalhes
kubectl get deployment my-dep                 # Lista um deployment específico
kubectl get pods                              # Lista todos os pods no namespace
kubectl get pod my-pod -o yaml                # Obtém o YAML de um pod

# Comandos describe com saída detalhada
kubectl describe nodes my-node
kubectl describe pods my-pod

# Lista Services ordenados por nome
kubectl get services --sort-by=.metadata.name

# Lista pods ordenados por contagem de reinicializações
kubectl get pods --sort-by='.status.containerStatuses[0].restartCount'

# Lista PersistentVolumes ordenados por capacidade
kubectl get pv --sort-by=.spec.capacity.storage

# Obtém o rótulo da versão de todos os pods com rótulo app=cassandra
kubectl get pods --selector=app=cassandra -o \
  jsonpath='{.items[*].metadata.labels.version}'

# Recupera o valor de uma chave com pontos, ex.: 'ca.crt'
kubectl get configmap myconfig \
  -o jsonpath='{.data.ca\.crt}'

# Recupera um valor codificado em base64 com hífens em vez de sublinhados (underscores).
kubectl get secret my-secret --template='{{index .data "key-name-with-dashes"}}'

# Obtém todos os nós de processamento (usa um seletor para excluir resultados que têm um rótulo
# chamado 'node-role.kubernetes.io/control-plane')
kubectl get node --selector='!node-role.kubernetes.io/control-plane'

# Obtém todos os pods em execução no namespace
kubectl get pods --field-selector=status.phase=Running

# Obtém ExternalIPs de todos os nós
kubectl get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="ExternalIP")].address}'

# Lista nomes de Pods que pertencem a um RC específico
# O comando "jq" é útil para transformações complexas demais para jsonpath, pode ser encontrado em https://jqlang.github.io/jq/
sel=${$(kubectl get rc my-rc --output=json | jq -j '.spec.selector | to_entries | .[] | "\(.key)=\(.value),"')%?}
echo $(kubectl get pods --selector=$sel --output=jsonpath={.items..metadata.name})

# Mostra rótulos para todos os pods (ou qualquer outro objeto Kubernetes que suporte rotulagem)
kubectl get pods --show-labels

# Verifica quais nós estão prontos
JSONPATH='{range .items[*]}{@.metadata.name}:{range @.status.conditions[*]}{@.type}={@.status};{end}{end}' \
 && kubectl get nodes -o jsonpath="$JSONPATH" | grep "Ready=True"

# Verifica quais nós estão prontos com custom-columns
kubectl get node -o custom-columns='NODE_NAME:.metadata.name,STATUS:.status.conditions[?(@.type=="Ready")].status'

# Saída de secrets decodificados sem ferramentas externas
kubectl get secret my-secret -o go-template='{{range $k,$v := .data}}{{"### "}}{{$k}}{{"\n"}}{{$v|base64decode}}{{"\n\n"}}{{end}}'

# Lista todos os Secrets atualmente em uso por um pod
kubectl get pods -o json | jq '.items[].spec.containers[].env[]?.valueFrom.secretKeyRef.name' | grep -v null | sort | uniq

# Lista todos os containerIDs de initContainer de todos os pods
# Útil ao limpar contêineres parados, evitando a remoção de initContainers.
kubectl get pods --all-namespaces -o jsonpath='{range .items[*].status.initContainerStatuses[*]}{.containerID}{"\n"}{end}' | cut -d/ -f3

# Lista eventos ordenados por timestamp
kubectl get events --sort-by=.metadata.creationTimestamp

# Lista todos os eventos de aviso
kubectl events --types=Warning

# Compara o estado atual do cluster com o estado em que o cluster estaria se o manifesto fosse aplicado.
kubectl diff -f ./my-manifest.yaml

# Produz uma árvore delimitada por pontos de todas as chaves retornadas para nós
# Útil ao localizar uma chave dentro de uma estrutura JSON aninhada complexa
kubectl get nodes -o json | jq -c 'paths|join(".")'

# Produz uma árvore delimitada por pontos de todas as chaves retornadas para pods, etc
kubectl get pods -o json | jq -c 'paths|join(".")'

# Produz ENV para todos os pods, assumindo que você tem um contêiner padrão para os pods, namespace padrão e o comando `env` é suportado.
# Útil ao executar qualquer comando suportado em todos os pods, não apenas `env`
for pod in $(kubectl get po --output=jsonpath={.items..metadata.name}); do echo $pod && kubectl exec -it $pod -- env; done

# Obtém o subrecurso status de um deployment
kubectl get deployment nginx-deployment --subresource=status

Atualizando recursos

kubectl set image deployment/frontend www=image:v2                # Atualização gradual dos contêineres "www" do deployment "frontend", atualizando a imagem
kubectl rollout history deployment/frontend                       # Verifica o histórico de deployments incluindo a revisão
kubectl rollout undo deployment/frontend                          # Reverte para o deployment anterior
kubectl rollout undo deployment/frontend --to-revision=2          # Reverte para uma revisão específica
kubectl rollout status -w deployment/frontend                     # Observa o status da atualização gradual do deployment "frontend" até a conclusão
kubectl rollout restart deployment/frontend                       # Reinicialização gradual do deployment "frontend"


cat pod.json | kubectl replace -f -                               # Substitui um pod baseado no JSON passado para o stdin

# Substitui forçadamente, exclui e então recria o recurso. Causará uma interrupção do serviço.
kubectl replace --force -f ./pod.json

# Cria um Service para um nginx replicado, que serve na porta 80 e conecta aos contêineres na porta 8000
kubectl expose rc nginx --port=80 --target-port=8000

# Atualiza a versão da imagem (tag) de um pod de contêiner único para v4
kubectl get pod mypod -o yaml | sed 's/\(image: myimage\):.*$/\1:v4/' | kubectl replace -f -

kubectl label pods my-pod new-label=awesome                       # Adiciona um rótulo
kubectl label pods my-pod new-label-                              # Remove um rótulo
kubectl label pods my-pod new-label=new-value --overwrite         # Sobrescreve um valor existente
kubectl annotate pods my-pod icon-url=http://goo.gl/XXBTWq        # Adiciona uma anotação
kubectl annotate pods my-pod icon-url-                            # Remove anotação
kubectl autoscale deployment foo --min=2 --max=10                 # Escalonamento automático de um deployment "foo"

Aplicando patches em recursos

# Atualiza parcialmente um nó
kubectl patch node k8s-node-1 -p '{"spec":{"unschedulable":true}}'

# Atualiza a imagem de um contêiner; spec.containers[*].name é obrigatório porque é uma chave de mesclagem
kubectl patch pod valid-pod -p '{"spec":{"containers":[{"name":"kubernetes-serve-hostname","image":"new image"}]}}'

# Atualiza a imagem de um contêiner usando um json patch com arrays posicionais
kubectl patch pod valid-pod --type='json' -p='[{"op": "replace", "path": "/spec/containers/0/image", "value":"new image"}]'

# Desabilita uma verificação de operacionalidade de deployment usando um json patch com arrays posicionais
kubectl patch deployment valid-deployment --type json -p='[{"op": "remove", "path": "/spec/template/spec/containers/0/livenessProbe"}]'

# Adiciona um novo elemento a um array posicional
kubectl patch sa default --type='json' -p='[{"op": "add", "path": "/secrets/1", "value": {"name": "whatever" } }]'

# Atualiza a contagem de réplicas de um deployment aplicando patch em seu subrecurso de escalonamento
kubectl patch deployment nginx-deployment --subresource='scale' --type='merge' -p '{"spec":{"replicas":2}}'

Editando recursos

Edita qualquer recurso da API no seu editor preferido.

kubectl edit svc/docker-registry                      # Edita o Service chamado docker-registry
KUBE_EDITOR="nano" kubectl edit svc/docker-registry   # Usa um editor alternativo

Escalonando recursos

kubectl scale --replicas=3 rs/foo                                 # Escalona um replicaset chamado 'foo' para 3
kubectl scale --replicas=3 -f foo.yaml                            # Escalona um recurso especificado em "foo.yaml" para 3
kubectl scale --current-replicas=2 --replicas=3 deployment/mysql  # Se o tamanho atual do deployment chamado mysql for 2, escalona mysql para 3
kubectl scale --replicas=5 rc/foo rc/bar rc/baz                   # Escalona múltiplos controladores de replicação

Excluindo recursos

kubectl delete -f ./pod.json                                      # Exclui um pod usando o tipo e nome especificados no pod.json
kubectl delete pod unwanted --now                                 # Exclui um pod sem período de tolerância
kubectl delete pod,service baz foo                                # Exclui pods e services com os mesmos nomes "baz" e "foo"
kubectl delete pods,services -l name=myLabel                      # Exclui pods e services com o rótulo name=myLabel
kubectl -n my-ns delete pod,svc --all                             # Exclui todos os pods e services no namespace my-ns,
# Exclui todos os pods que correspondem ao padrão awk pattern1 ou pattern2
kubectl get pods -n mynamespace --no-headers=true | awk '/pattern1|pattern2/{print $1}' | xargs kubectl delete -n mynamespace pod

Interagindo com Pods em execução

kubectl logs my-pod                                 # despeja logs do pod (stdout)
kubectl logs -l name=myLabel                        # despeja logs do pod, com rótulo name=myLabel (stdout)
kubectl logs my-pod --previous                      # despeja logs do pod (stdout) para uma instanciação anterior de um contêiner
kubectl logs my-pod -c my-container                 # despeja logs do contêiner do pod (stdout, caso multi-contêiner)
kubectl logs -l name=myLabel -c my-container        # despeja logs do contêiner do pod, com rótulo name=myLabel (stdout)
kubectl logs my-pod -c my-container --previous      # despeja logs do contêiner do pod (stdout, caso multi-contêiner) para uma instanciação anterior de um contêiner
kubectl logs -f my-pod                              # transmite logs do pod (stdout)
kubectl logs -f my-pod -c my-container              # transmite logs do contêiner do pod (stdout, caso multi-contêiner)
kubectl logs -f -l name=myLabel --all-containers    # transmite todos os logs dos pods com rótulo name=myLabel (stdout)
kubectl run -i --tty busybox --image=busybox:1.28 -- sh  # Executa pod como shell interativo
kubectl run nginx --image=nginx -n mynamespace      # Inicia uma única instância do pod nginx no namespace mynamespace
kubectl run nginx --image=nginx --dry-run=client -o yaml > pod.yaml
                                                    # Gera especificação para executar o pod nginx e escreve em um arquivo chamado pod.yaml
kubectl attach my-pod -i                            # Anexa ao contêiner em execução
kubectl port-forward my-pod 5000:6000               # Escuta na porta 5000 da máquina local e encaminha para a porta 6000 no my-pod
kubectl exec my-pod -- ls /                         # Executa comando em pod existente (caso de 1 contêiner)
kubectl exec --stdin --tty my-pod -- /bin/sh        # Acesso de shell interativo a um pod em execução (caso de 1 contêiner)
kubectl exec my-pod -c my-container -- ls /         # Executa comando em pod existente (caso multi-contêiner)
kubectl debug my-pod -it --image=busybox:1.28       # Cria uma sessão de depuração interativa dentro do pod existente e anexa imediatamente a ela
kubectl debug node/my-node -it --image=busybox:1.28 # Cria uma sessão de depuração interativa em um nó e anexa imediatamente a ela
kubectl top pod                                     # Mostra métricas para todos os pods no namespace padrão
kubectl top pod POD_NAME --containers               # Mostra métricas para um determinado pod e seus contêineres
kubectl top pod POD_NAME --sort-by=cpu              # Mostra métricas para um determinado pod e ordena por 'cpu' ou 'memory'

Copiando arquivos e diretórios de e para contêineres

kubectl cp /tmp/foo_dir my-pod:/tmp/bar_dir            # Copia o diretório local /tmp/foo_dir para /tmp/bar_dir em um pod remoto no namespace atual
kubectl cp /tmp/foo my-pod:/tmp/bar -c my-container    # Copia o arquivo local /tmp/foo para /tmp/bar em um pod remoto em um contêiner específico
kubectl cp /tmp/foo my-namespace/my-pod:/tmp/bar       # Copia o arquivo local /tmp/foo para /tmp/bar em um pod remoto no namespace my-namespace
kubectl cp my-namespace/my-pod:/tmp/foo /tmp/bar       # Copia /tmp/foo de um pod remoto para /tmp/bar localmente
tar cf - /tmp/foo | kubectl exec -i -n my-namespace my-pod -- tar xf - -C /tmp/bar           # Copia o arquivo local /tmp/foo para /tmp/bar em um pod remoto no namespace my-namespace
kubectl exec -n my-namespace my-pod -- tar cf - /tmp/foo | tar xf - -C /tmp/bar    # Copia /tmp/foo de um pod remoto para /tmp/bar localmente

Interagindo com Deployments e Services

kubectl logs deploy/my-deployment                         # despeja logs do Pod para um Deployment (caso de contêiner único)
kubectl logs deploy/my-deployment -c my-container         # despeja logs do Pod para um Deployment (caso multi-contêiner)

kubectl port-forward svc/my-service 5000                  # escuta na porta local 5000 e encaminha para a porta 5000 no backend do Service
kubectl port-forward svc/my-service 5000:my-service-port  # escuta na porta local 5000 e encaminha para a porta de destino do Service com nome <my-service-port>

kubectl port-forward deploy/my-deployment 5000:6000       # escuta na porta local 5000 e encaminha para a porta 6000 em um Pod criado por <my-deployment>
kubectl exec deploy/my-deployment -- ls                   # executa comando no primeiro Pod e primeiro contêiner no Deployment (casos de contêiner único ou multi-contêiner)

Interagindo com Nós e cluster

kubectl cordon my-node                                                # Marca my-node como não alocável
kubectl drain my-node                                                 # Drena my-node em preparação para manutenção
kubectl uncordon my-node                                              # Marca my-node como alocável
kubectl top node                                                      # Mostra métricas para todos os nós
kubectl top node my-node                                              # Mostra métricas para um determinado nó
kubectl cluster-info                                                  # Exibe endereços do master e services
kubectl cluster-info dump                                             # Despeja o estado atual do cluster para stdout
kubectl cluster-info dump --output-directory=/path/to/cluster-state   # Despeja o estado atual do cluster para /path/to/cluster-state

# Visualiza taints existentes que existem nos nós atuais.
kubectl get nodes -o='custom-columns=NodeName:.metadata.name,TaintKey:.spec.taints[*].key,TaintValue:.spec.taints[*].value,TaintEffect:.spec.taints[*].effect'

# Se um taint com essa chave e efeito já existir, seu valor é substituído conforme especificado.
kubectl taint nodes foo dedicated=special-user:NoSchedule

Tipos de recurso

Lista todos os tipos de recurso suportados junto com seus nomes abreviados, grupo de API, se eles são namespaced, e kind:

kubectl api-resources

Outras operações para explorar recursos da API:

kubectl api-resources --namespaced=true      # Todos os recursos namespaced
kubectl api-resources --namespaced=false     # Todos os recursos não namespaced
kubectl api-resources -o name                # Todos os recursos com saída simples (apenas o nome do recurso)
kubectl api-resources -o wide                # Todos os recursos com saída expandida (também conhecida como "wide")
kubectl api-resources --verbs=list,get       # Todos os recursos que suportam os verbos de requisição "list" e "get"
kubectl api-resources --api-group=extensions # Todos os recursos no grupo de API "extensions"

Formatando saída

Para exibir detalhes na janela do seu terminal em um formato específico, adicione a flag -o (ou --output) a um comando kubectl compatível.

Formato de saída Descrição
-o=custom-columns=<spec> Imprime uma tabela usando uma lista separada por vírgulas de colunas personalizadas
-o=custom-columns-file=<filename> Imprime uma tabela usando o modelo de colunas personalizadas no arquivo <filename>
-o=go-template=<template> Imprime os campos definidos em um template golang
-o=go-template-file=<filename> Imprime os campos definidos pelo template golang no arquivo <filename>
-o=json Exibe um objeto de API formatado em JSON
-o=jsonpath=<template> Imprime os campos definidos em uma expressão jsonpath
-o=jsonpath-file=<filename> Imprime os campos definidos pela expressão jsonpath no arquivo <filename>
-o=kyaml Exibe um objeto de API formatado em KYAML (alfa, requer a variável de ambiente KUBECTL_KYAML="true"). KYAML é um dialeto experimental específico do Kubernetes em YAML, e pode ser interpretado como YAML.
-o=name Imprime apenas o nome do recurso e nada mais
-o=wide Exibe no formato de texto simples com qualquer informação adicional, e para pods, o nome do nó é incluído
-o=yaml Exibe um objeto de API formatado em YAML

Exemplos usando -o=custom-columns:

# Todas as imagens executando em um cluster
kubectl get pods -A -o=custom-columns='DATA:spec.containers[*].image'

# Todas as imagens executando no namespace: default, agrupadas por Pod
kubectl get pods --namespace default --output=custom-columns="NAME:.metadata.name,IMAGE:.spec.containers[*].image"

# Todas as imagens excluindo "registry.k8s.io/coredns:1.6.2"
kubectl get pods -A -o=custom-columns='DATA:spec.containers[?(@.image!="registry.k8s.io/coredns:1.6.2")].image'

# Todos os campos sob metadata independentemente do nome
kubectl get pods -A -o=custom-columns='DATA:metadata.*'

Mais exemplos na documentação de referência do kubectl.

Verbosidade de saída e depuração do kubectl

A verbosidade do kubectl é controlada com as flags -v ou --v seguidas por um inteiro representando o nível de log. As convenções gerais de logging do Kubernetes e os níveis de log associados são descritos aqui.

Verbosidade Descrição
--v=0 Geralmente útil para que isso seja sempre visível para um operador de cluster.
--v=1 Um nível de log padrão razoável se você não quiser verbosidade.
--v=2 Informações úteis de estado estável sobre o service e mensagens de log importantes que podem se correlacionar com mudanças significativas no sistema. Este é o nível de log padrão recomendado para a maioria dos sistemas.
--v=3 Informações estendidas sobre mudanças.
--v=4 Verbosidade de nível de depuração.
--v=5 Verbosidade de nível de rastreamento.
--v=6 Exibe recursos requisitados.
--v=7 Exibe cabeçalhos de requisição HTTP.
--v=8 Exibe conteúdos de requisição HTTP.
--v=9 Exibe conteúdos de requisição HTTP sem truncamento de conteúdos.

Próximos passos

2 - kubectl Cheat Sheet

Esta página contém uma lista de comandos kubectl e flags frequentemente usados.

Kubectl Autocomplete

BASH

source <(kubectl completion bash) # configuração de autocomplete no bash do shell atual, o pacote bash-completion precisa ter sido instalado primeiro.
echo "source <(kubectl completion bash)" >> ~/.bashrc # para adicionar o autocomplete permanentemente no seu shell bash.

Você também pode usar uma abreviação para o atalho para kubectl que também funciona com o auto completar:

alias k=kubectl
complete -o default -F __start_kubectl k

ZSH

source <(kubectl completion zsh)  # configuração para usar autocomplete no terminal zsh no shell atual
echo '[[ $commands[kubectl] ]] && source <(kubectl completion zsh)' >> ~/.zshrc # adicionar auto completar permanentemente para o seu shell zsh

Uma nota sobre --all-namespaces

Acrescentar --all-namespaces acontece com bastante frequência, onde você deve estar ciente da abreviação de --all-namespaces:

kubectl -A

Contexto e Configuração do Kubectl

Define com qual cluster Kubernetes o kubectl se comunica e modifica os detalhes da configuração. Veja a documentação Autenticando entre clusters com o kubeconfig para informações detalhadas do arquivo de configuração.

kubectl config view # Mostra configurações do kubeconfig mergeadas

# use vários arquivos kubeconfig ao mesmo tempo e visualize a configuração mergeada
KUBECONFIG=~/.kube/config:~/.kube/kubconfig2 

kubectl config view

# obtenha a senha para o usuário e2e
kubectl config view -o jsonpath='{.users[?(@.name == "e2e")].user.password}'

kubectl config view -o jsonpath='{.users[].name}'    # exibe o primeiro usuário
kubectl config view -o jsonpath='{.users[*].name}'   # obtém uma lista de usuários
kubectl config get-contexts                          # exibe lista de contextos
kubectl config current-context                       # exibe o contexto atual
kubectl config use-context my-cluster-name           # define o contexto padrão como my-cluster-name

kubectl config set-cluster my-cluster-name           # define uma entrada de cluster no kubeconfig

# configura a URL para um servidor proxy a ser usado para solicitações feitas por este cliente no kubeconfig
kubectl config set-cluster my-cluster-name --proxy-url=my-proxy-url

# adiciona um novo cluster ao seu kubeconfig que suporte autenticação básica
kubectl config set-credentials kubeuser/foo.kubernetes.com --username=kubeuser --password=kubepassword

# salva o namespace permanentemente para todos os comandos subsequentes do kubectl nesse contexto
kubectl config set-context --current --namespace=ggckad-s2

# define um contexto utilizando um nome de usuário e o namespace
kubectl config set-context gce --user=cluster-admin --namespace=foo \
  && kubectl config use-context gce
 
kubectl config unset users.foo                       # exclui usuário foo

# alias curto para definir/mostrar contexto/namespace (funciona apenas para bash e shells compatíveis com bash, contexto atual a ser definido antes de usar kn para definir namespace)
alias kx='f() { [ "$1" ] && kubectl config use-context $1 || kubectl config current-context ; } ; f'
alias kn='f() { [ "$1" ] && kubectl config set-context --current --namespace $1 || kubectl config view --minify | grep namespace | cut -d" " -f6 ; } ; f'

Kubectl apply

apply gerencia aplicações através de arquivos que definem os recursos do Kubernetes. Ele cria e atualiza recursos em um cluster através da execução kubectl apply. Esta é a maneira recomendada para gerenciar aplicações Kubernetes em ambiente de produção. Veja a documentação do Kubectl.

Criando objetos

Manifestos Kubernetes podem ser definidos em YAML ou JSON. As extensões de arquivo .yaml, .yml, e .json podem ser usadas.

kubectl apply -f ./my-manifest.yaml            # cria recurso(s)
kubectl apply -f ./my1.yaml -f ./my2.yaml      # cria a partir de vários arquivos
kubectl apply -f ./dir                         # cria recurso(s) em todos os arquivos de manifesto no diretório
kubectl apply -f https://git.io/vPieo          # cria recurso(s) a partir de URL
kubectl create deployment nginx --image=nginx  # inicia uma única instância do nginx

# cria um Job que exibe "Hello World"
kubectl create job hello --image=busybox:1.28 -- echo "Hello World"

# cria um CronJob que exibe "Hello World" a cada minuto
kubectl create cronjob hello --image=busybox:1.28   --schedule="*/1 * * * *" -- echo "Hello World"

kubectl explain pods                           # obtém a documentação de manifesto do pod

# Cria vários objetos YAML a partir de stdin
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: busybox-sleep
spec:
  containers:
  - name: busybox
    image: busybox
    args:
    - sleep
    - "1000000"
---
apiVersion: v1
kind: Pod
metadata:
  name: busybox-sleep-less
spec:
  containers:
  - name: busybox
    image: busybox
    args:
    - sleep
    - "1000"
EOF

# Cria um segredo com várias chaves
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: mysecret
type: Opaque
data:
  password: $(echo -n "s33msi4" | base64 -w0)
  username: $(echo -n "jane" | base64 -w0)
EOF

Visualizando e localizando recursos

# Comandos get com saída simples
kubectl get services                          # Lista todos os serviços do namespace
kubectl get pods --all-namespaces             # Lista todos os Pods em todos namespaces
kubectl get pods -o wide                      # Lista todos os Pods no namespace atual, com mais detalhes
kubectl get deployment my-dep                 # Lista um deployment específico
kubectl get pods                              # Lista todos os Pods no namespace
kubectl get pod my-pod -o yaml                # Obtém o YAML de um pod

# Comandos describe com saída detalhada
kubectl describe nodes my-node
kubectl describe pods my-pod

# Lista serviços classificados por nome
kubectl get services --sort-by=.metadata.name

# Lista Pods classificados por contagem de reinicializações
kubectl get pods --sort-by='.status.containerStatuses[0].restartCount'

# Lista PersistentVolumes classificados por capacidade
kubectl get pv --sort-by=.spec.capacity.storage

# Obtém a versão da label de todos os Pods com a label app=cassandra
kubectl get pods --selector=app=cassandra -o \
  jsonpath='{.items[*].metadata.labels.version}'

# Recupera o valor de uma chave com pontos, por exemplo 'ca.crt'
kubectl get configmap myconfig \
  -o jsonpath='{.data.ca\.crt}'

# Recupera um valor codificado em base64 com traços em vez de sublinhados
kubectl get secret my-secret --template='{{index .data "key-name-with-dashes"}}'

# Obtém todos os nós workers (use um seletor para excluir resultados que possuem uma label
# nomeado 'node-role.kubernetes.io/control-plane')
kubectl get node --selector='!node-role.kubernetes.io/control-plane'

# Obtém todos os Pods em execução no namespace
kubectl get pods --field-selector=status.phase=Running

# Obtém ExternalIPs de todos os nós
kubectl get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="ExternalIP")].address}'

# Lista nomes de Pods pertencentes a um RC particular
# O comando "jq" é útil para transformações que são muito complexas para jsonpath, pode ser encontrado em https://stedolan.github.io/jq/
sel=${$(kubectl get rc my-rc --output=json | jq -j '.spec.selector | to_entries | .[] | "\(.key)=\(.value),"')%?}
echo $(kubectl get pods --selector=$sel --output=jsonpath={.items..metadata.name})

# Exibe marcadores para todos os Pods (ou qualquer outro objeto Kubernetes que suporte rotulagem)
kubectl get pods --show-labels

# Verifica quais nós estão prontos
JSONPATH='{range .items[*]}{@.metadata.name}:{range @.status.conditions[*]}{@.type}={@.status};{end}{end}' \
 && kubectl get nodes -o jsonpath="$JSONPATH" | grep "Ready=True"

# Exibe o segredo decodificado sem utilizar ferramentas externas
kubectl get secret my-secret -o go-template='{{range $k,$v := .data}}{{"### "}}{{$k}}{{"\n"}}{{$v|base64decode}}{{"\n\n"}}{{end}}'

# Lista todos os segredos atualmente em uso por um pod
kubectl get pods -o json | jq '.items[].spec.containers[].env[]?.valueFrom.secretKeyRef.name' | grep -v null | sort | uniq

# Lista todos os containerIDs de initContainer de todos os Pods
# Útil ao limpar contêineres parados, evitando a remoção de initContainers.
kubectl get pods --all-namespaces -o jsonpath='{range .items[*].status.initContainerStatuses[*]}{.containerID}{"\n"}{end}' | cut -d/ -f3

# Lista eventos classificados por timestamp
kubectl get events --sort-by=.metadata.creationTimestamp

# Lista todos eventos do tipo Warning
kubectl events --types=Warning

# Compara o estado atual do cluster com o estado em que o cluster estaria se o manifesto fosse aplicado.
kubectl diff -f ./my-manifest.yaml

# Produz uma árvore delimitada por ponto de todas as chaves retornadas para nós
# Útil ao localizar uma chave em uma estrutura JSON aninhada complexa
kubectl get nodes -o json | jq -c 'paths|join(".")'

# Produz uma árvore delimitada por ponto de todas as chaves retornadas para Pods, etc.
kubectl get pods -o json | jq -c 'paths|join(".")'

# Produz ENV para todos os Pods, supondo que você tenha um contêiner padrão para os Pods, namespace padrão e o comando `env` é compatível.
# Útil ao executar qualquer comando suportado em todos os Pods, não apenas `env`
for pod in $(kubectl get po --output=jsonpath={.items..metadata.name}); do echo $pod && kubectl exec -it $pod -- env; done

# Obtém o status de um sub-recurso de uma implantação
kubectl get deployment nginx-deployment --subresource=status

Atualizando recursos

kubectl set image deployment/frontend www=image:v2               # Aplica o rollout nos containers "www" do deployment "frontend", atualizando a imagem
kubectl rollout history deployment/frontend                      # Verifica o histórico do deployment, incluindo a revisão
kubectl rollout undo deployment/frontend                         # Rollback para o deployment anterior
kubectl rollout undo deployment/frontend --to-revision=2         # Rollback para uma revisão específica
kubectl rollout status -w deployment/frontend                    # Acompanha o status de atualização do "frontend" até sua conclusão sem interrupção 
kubectl rollout restart deployment/frontend                      # Reinicia contínuo do deployment "frontend"

cat pod.json | kubectl replace -f -                              # Substitue um pod com base no JSON passado para stdin

# Força a substituição, exclui e recria o recurso. Causará uma interrupção do serviço.
kubectl replace --force -f ./pod.json

# Cria um serviço para um nginx replicado, que serve na porta 80 e se conecta aos contêineres na porta 8000
kubectl expose rc nginx --port=80 --target-port=8000

# Atualiza a versão da imagem (tag) de um pod de contêiner único para a v4
kubectl get pod mypod -o yaml | sed 's/\(image: myimage\):.*$/\1:v4/' | kubectl replace -f -

kubectl label pods my-pod new-label=awesome                      # Adiciona uma label
kubectl label pods my-pod new-label-                             # Remove a label new-label
kubectl annotate pods my-pod icon-url=http://goo.gl/XXBTWq       # Adiciona uma anotação
kubectl autoscale deployment foo --min=2 --max=10                # Escala automaticamente um deployment "foo"

Recursos de correção

# Atualiza parcialmente um nó
kubectl patch node k8s-node-1 -p '{"spec":{"unschedulable":true}}'

# Atualiza a imagem de um contêiner; spec.containers[*].name é obrigatório porque é uma chave de mesclagem
kubectl patch pod valid-pod -p '{"spec":{"containers":[{"name":"kubernetes-serve-hostname","image":"new image"}]}}'

# Atualiza a imagem de um contêiner usando um patch json com matrizes posicionais
kubectl patch pod valid-pod --type='json' -p='[{"op": "replace", "path": "/spec/containers/0/image", "value":"new image"}]'

# Desativa um livenessProbe de deployment usando um patch json com matrizes posicionais
kubectl patch deployment valid-deployment  --type json   -p='[{"op": "remove", "path": "/spec/template/spec/containers/0/livenessProbe"}]'

# Adiciona um novo elemento a uma matriz posicional
kubectl patch sa default --type='json' -p='[{"op": "add", "path": "/secrets/1", "value": {"name": "whatever" } }]'

# Atualiza a contagem de réplicas de uma implantação corrigindo seu sub-recurso de escala
kubectl patch deployment nginx-deployment --subresource='scale' --type='merge' -p '{"spec":{"replicas":2}}'

Editando recursos

Edita qualquer recurso da API no seu editor preferido.

kubectl edit svc/docker-registry                      # Edita o serviço chamado docker-registry
KUBE_EDITOR="nano" kubectl edit svc/docker-registry   # Usa um editor alternativo

Escalando recursos

kubectl scale --replicas=3 rs/foo                                 # Escala um replicaset chamado 'foo' para 3
kubectl scale --replicas=3 -f foo.yaml                            # Escala um recurso especificado em "foo.yaml" para 3
kubectl scale --current-replicas=2 --replicas=3 deployment/mysql  # Se o tamanho atual do deployment chamado mysql for 2, escala para 3
kubectl scale --replicas=5 rc/foo rc/bar rc/baz                   # Escala vários controladores de replicaset

Deletando resources

kubectl delete -f ./pod.json                                              # Exclui um Pod usando o tipo e o nome especificados em pod.json
kubectl delete pod unwanted --now                          ........       # Exclui um Pod imediatamente sem esperar pelo tempo configurado
kubectl delete pod,service baz foo                                        # Exclui Pods e serviços com os mesmos nomes "baz" e "foo"
kubectl delete pods,services -l name=myLabel                              # Exclui Pods e serviços com o nome da label = myLabel
kubectl -n my-ns delete pod,svc --all                                     # Exclui todos os Pods e serviços no namespace my-ns,
# Exclui todos os Pods que correspondem ao awk pattern1 ou pattern2
kubectl get pods  -n mynamespace --no-headers=true | awk '/pattern1|pattern2/{print $1}' | xargs  kubectl delete -n mynamespace pod

Interagindo com Pods em execução

kubectl logs my-pod                                 # despeja logs de pod (stdout)
kubectl logs -l name=myLabel                        # despeja logs de pod, com a label de name=myLabel (stdout)
kubectl logs my-pod --previous                      # despeja logs de pod (stdout) para a instância anterior de um contêiner
kubectl logs my-pod -c my-container                 # despeja logs de um específico contêiner em um pod (stdout, no caso de vários contêineres)
kubectl logs -l name=myLabel -c my-container        # despeja logs de pod, com nome da label = myLabel (stdout)
kubectl logs my-pod -c my-container --previous      # despeja logs de um contêiner específico em um pod (stdout, no caso de vários contêineres) para uma instanciação anterior de um contêiner
kubectl logs -f my-pod                              # Fluxo de logs de pod (stdout)
kubectl logs -f my-pod -c my-container              # Fluxo de logs para um específico contêiner em um pod (stdout, caixa com vários contêineres)
kubectl logs -f -l name=myLabel --all-containers    # transmite todos os logs de Pods com a label name=myLabel (stdout)
kubectl run -i --tty busybox --image=busybox:1.28 -- sh  # Executa pod como shell interativo
kubectl run nginx --image=nginx -n mynamespace      # Inicia uma única instância do pod nginx no namespace de mynamespace
kubectl run nginx --image=nginx --dry-run=client -o yaml > pod.yaml
                                                    # Gera a especificação para executar o pod nginx e grave-a em um arquivo chamado pod.yaml 
kubectl attach my-pod -i                            # Anexa ao contêiner em execução
kubectl port-forward my-pod 5000:6000               # Ouça na porta 5000 na máquina local e encaminhe para a porta 6000 no my-pod
kubectl exec my-pod -- ls /                         # Executa comando no pod existente (1 contêiner)
kubectl exec --stdin --tty my-pod -- /bin/sh        # Acesso de shell interativo a um pod em execução (apenas 1 contêiner)
kubectl exec my-pod -c my-container -- ls /         # Executa comando no pod existente (pod com vários contêineres)
kubectl top pod POD_NAME --containers               # Mostra métricas para um determinado pod e seus contêineres
kubectl top pod POD_NAME --sort-by=cpu              # Mostra métricas para um determinado pod e classificá-lo por 'cpu' ou 'memória'

Copiando arquivos e diretórios de e para contêineres

kubectl cp /tmp/foo_dir my-pod:/tmp/bar_dir            # Copia o diretório local /tmp/foo_dir para /tmp/bar_dir em um pod remoto no namespace atual
kubectl cp /tmp/foo my-pod:/tmp/bar -c my-container    # Copia o arquivo local /tmp/foo para /tmp/bar em um pod remoto em um contêiner específico
kubectl cp /tmp/foo my-namespace/my-pod:/tmp/bar       # Copia o arquivo local /tmp/foo para /tmp/bar em um pod remoto no namespace my-namespace
kubectl cp my-namespace/my-pod:/tmp/foo /tmp/bar       # Copia /tmp/foo de um pod remoto para /tmp/bar localmente
tar cf - /tmp/foo | kubectl exec -i -n my-namespace my-pod -- tar xf - -C /tmp/bar           # Copia o arquivo local /tmp/foo para /tmp/bar em um pod remoto no namespace my-namespace
kubectl exec -n my-namespace my-pod -- tar cf - /tmp/foo | tar xf - -C /tmp/bar    # Copia /tmp/foo de um pod remoto para /tmp/bar localmente

Interagindo com implantações e serviços

kubectl logs deploy/my-deployment                         # despeja logs de pod para uma implantação (caso de contêiner único)
kubectl logs deploy/my-deployment -c my-container         # despeja logs de pod para uma implantação (caso de vários contêineres)

kubectl port-forward svc/my-service 5000                  # escuta na porta local 5000 e encaminhe para a porta 5000 no back-end do serviço
kubectl port-forward svc/my-service 5000:my-service-port  # escuta na porta local 5000 e encaminhe para a porta de destino do serviço com o nome <my-service-port>

kubectl port-forward deploy/my-deployment 5000:6000       # escuta na porta local 5000 e encaminhe para a porta 6000 em um pod criado por <my-deployment>
kubectl exec deploy/my-deployment -- ls                   # executa o comando no primeiro pod e primeiro contêiner na implantação (casos de um ou vários contêineres)

Interagindo com Nós e Cluster

kubectl cordon my-node                                                # Marca o nó my-node como não agendável
kubectl drain my-node                                                 # Drena o nó my-node na preparação para manutenção
kubectl uncordon my-node                                              # Marca nó my-node como agendável
kubectl top node my-node                                              # Mostra métricas para um determinado nó
kubectl cluster-info                                                  # Exibe endereços da master e serviços
kubectl cluster-info dump                                             # Despeja o estado atual do cluster no stdout
kubectl cluster-info dump --output-directory=/path/to/cluster-state   # Despeja o estado atual do cluster em /path/to/cluster-state

# Veja os taints existentes nos nós atuais.
kubectl get nodes -o='custom-columns=NodeName:.metadata.name,TaintKey:.spec.taints[*].key,TaintValue:.spec.taints[*].value,TaintEffect:.spec.taints[*].effect'

# Se uma `taint` com essa chave e efeito já existir, seu valor será substituído conforme especificado.
kubectl taint nodes foo dedicated=special-user:NoSchedule

Tipos de Recursos

Lista todos os tipos de recursos suportados junto com seus nomes abreviados, grupo de API, sejam eles namespaced e Kind:

kubectl api-resources

Outras operações para explorar os recursos da API:

kubectl api-resources --namespaced=true      # Todos os recursos com namespace
kubectl api-resources --namespaced=false     # Todos os recursos sem namespace
kubectl api-resources -o name                # Todos os recursos com saída simples (apenas o nome do recurso)
kubectl api-resources -o wide                # Todos os recursos com saída expandida (também conhecida como "ampla")
kubectl api-resources --verbs=list,get       # Todos os recursos que suportam os verbos de API "list" e "get"
kubectl api-resources --api-group=extensions # Todos os recursos no grupo de API "extensions"

Formatação de saída

Para enviar detalhes para a janela do terminal em um formato específico, adicione a flag -o (ou --output) para um comando kubectl suportado.

Formato de saída Descrição
-o=custom-columns=<spec> Exibe uma tabela usando uma lista separada por vírgula de colunas personalizadas
-o=custom-columns-file=<filename> Exibe uma tabela usando o modelo de colunas personalizadas no arquivo <nome do arquivo>
-o=json Saída de um objeto de API formatado em JSON
-o=jsonpath=<template> Exibe os campos definidos em uma expressão jsonpath
-o=jsonpath-file=<filename> Exibe os campos definidos pela expressão jsonpath no arquivo <nome do arquivo>
-o=name Exibe apenas o nome do recurso e nada mais
-o=wide Saída no formato de texto sem formatação com qualquer informação adicional e, para Pods, o nome do nó está incluído
-o=yaml Saída de um objeto de API formatado em YAML

Exemplos usando -o=custom-columns:

# Todas as imagens em execução em um cluster
kubectl get pods -A -o=custom-columns='DATA:spec.containers[*].image'

# Todas as imagens em execução no namespace: padrão, agrupadas por pod
kubectl get pods --namespace default --output=custom-columns="NAME:.metadata.name,IMAGE:.spec.containers[*].image"

 # Todas as imagens excluindo "registry.k8s.io/coredns:1.6.2"
kubectl get pods -A -o=custom-columns='DATA:spec.containers[?(@.image!="registry.k8s.io/coredns:1.6.2")].image'

# Todos os campos sob metadados, independentemente do nome
kubectl get pods -A -o=custom-columns='DATA:metadata.*'

Mais exemplos na documentação de referência do kubectl.

Verbosidade de saída do Kubectl e depuração

A verbosidade do Kubectl é controlado com as flags -v ou --v seguidos por um número inteiro representando o nível do log. As convenções gerais de log do Kubernetes e os níveis de log associados são descritos aqui.

Verbosidade Descrição
--v=0 Geralmente útil para sempre estar visível para um operador de cluster.
--v=1 Um nível de log padrão razoável se você não deseja verbosidade.
--v=2 Informações úteis sobre o estado estacionário sobre o serviço e mensagens importantes de log que podem se correlacionar com alterações significativas no sistema. Este é o nível de log padrão recomendado para a maioria dos sistemas.
--v=3 Informações estendidas sobre alterações.
--v=4 Detalhamento no nível de debugging.
--v=5 Verbosidade do nível de rastreamento.
--v=6 Exibe os recursos solicitados.
--v=7 Exibe cabeçalhos de solicitação HTTP.
--v=8 Exibe conteúdo da solicitação HTTP.
--v=9 Exibe o conteúdo da solicitação HTTP sem o truncamento do conteúdo.

Próximos passos