Table of Contents
###Introdução
O Kubectl é uma ferramenta de linha de comando projetada para gerenciar objetos e clusters Kubernetes. Ele fornece uma interface de linha de comando para executar operações comuns, como criar e escalar Deployments, alternar contextos e acessar um shell em um container em execução.
Como Usar Este Guia:
- Este guia está no formato de referência rápida com trechos de linha de comando independentes.
- Ele não é uma lista exaustiva de comandos kubectl, mas contém muitas operações e casos de uso comuns. Para uma referência mais completa, consulte a Documentação de referência do Kubectl
- Vá para qualquer seção que seja relevante para a tarefa que você está tentando concluir.
Pré-requisitos
- Para usar o kubectl, você precisará de um cluster Kubernetes disponível para você. Para aprender a criar um cluster Kubernetes do zero, você pode consultar Como Criar um Cluster Kubernetes 1.11 Usando Kubeadm no Ubuntu 18.04. Alternativamente, você pode provisionar um cluster Kubernetes gerenciado em minutos usando o Kubernetes. Para começar a criar um cluster Kubernetes gerenciado na the cloud provider, consulte How to Create Kubernetes Clusters Using the Control Panel.
- Você também precisará de uma máquina remota na qual instalará e executará o kubectl. O kubectl pode ser executado em diversos sistemas operacionais.
Deployment de Exemplo
Para demonstrar algumas das operações e comandos nesta referência rápida, usaremos um exemplo de Deployment que executa duas réplicas do Nginx:
[label nginx-deployment.yaml]
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 2
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx
ports:
- containerPort: 80
Copie e cole esse manifesto em um arquivo chamado nginx-deployment.yaml.
Instalando o kubectl
Nota: Esses comandos foram testados somente em uma máquina Ubuntu 18.04. Para aprender como instalar o kubectl em outros sistemas operacionais, consulte Install and Set Up kubectl da documentação do Kubernetes.
Primeiro, atualize o índice local de pacotes e instale as dependências necessárias:
sudo apt-get update && sudo apt-get install -y apt-transport-https
Em seguida, adicione a chave GPG do Google Cloud ao APT e disponibilize o pacote kubectl no seu sistema:
curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
echo "deb https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee -a /etc/apt/sources.list.d/kubernetes.list
sudo apt-get update
Por fim, instale o kubectl:
sudo apt-get install -y kubectl
Teste se a instalação foi bem-sucedida usando version:
kubectl version
Configurando o Autocompletar no Shell
Nota: Esses comandos foram testados somente em uma máquina Ubuntu 18.04. Para saber como configurar o Autocompletar em outros sistemas operacionais, consulte Install and Set Up kubectl da documentação do Kubernetes.
O kubectl inclui um script de autocompletar no shell que você pode disponibilizar para o software de autocompletar do shell existente no sistema.
Instalando o Autocompletar do kubectl
Primeiro, verifique se você tem o bash-completion instalado:
type _init_completion
Você deve ver alguma saída do script.
Em seguida, faça um source no script de autocompletar do kubectl em seu arquivo ~/.bashrc:
echo 'source <(kubectl completion bash)' >>~/.bashrc
. ~/.bashrc
Alternativamente, você pode adicionar o script de autocompletar ao diretório /etc/bash_completion.d:
kubectl completion bash >/etc/bash_completion.d/kubectl
Uso
Para usar o recurso de autocompletar, pressione a tecla TAB para exibir os comandos kubectl disponíveis:
kubectl TAB TAB
[secondary_label Output]
annotate apply autoscale completion cordon delete drain explain kustomize options port-forward rollout set uncordon
api-resources attach certificate config cp describe
. . .
Você também pode exibir os comandos disponíveis após digitar parcialmente um comando:
kubectl d TAB
[secondary_label Output]
delete describe diff drain
Conectando, Configurando e Usando Contextos
Conectando
Para testar se o kubectl pode se autenticar e acessar seu cluster Kubernetes, use cluster-info:
kubectl cluster-info
Se o kubectl puder se autenticar com sucesso no seu cluster, você deverá ver a seguinte saída:
[secondary_label Output]
Kubernetes master is running at https://<^>kubernetes_master_endpoint<^>
CoreDNS is running at https://<^>coredns_endpoint<^>
To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
O kubectl é configurado usando os arquivos de configuração *kubeconfig*. Por padrão, o kubectl procurará um arquivo chamado config no diretório $HOME/.kube. Para mudar isso, você pode definir a variável de ambiente $KUBECONFIG apontando para um arquivo kubeconfig personalizado ou passar o arquivo personalizado em tempo de execução usando a flag --kubeconfig:
kubectl cluster-info --kubeconfig=<^>caminho_para_seu_arquivo_kubeconfig<^>
Nota: Se você estiver usando um cluster Kubernetes gerenciado, seu provedor de nuvem deverá ter disponibilizado seu arquivo kubeconfig.
Se você não quiser usar a flag --kubeconfig com todos os comandos, e não existe o arquivo ~/.kube/config, crie um diretório chamado ~/.kube no seu diretório home, se ele ainda não existir, e copie o arquivo kubeconfig, renomeando-o para config:
mkdir ~/.kube
cp <^>seu_arquivo_kubeconfig<^> ~/.kube/config
Agora, execute cluster-info novamente para testar sua conexão.
Modificando Sua Configuração do kubectl
Você também pode modificar sua configuração usando o conjunto de comandos kubectl config.
Para visualizar sua configuração do kubectl, use o subcomando view:
kubectl config view
[secondary_label Output]
apiVersion: v1
clusters:
- cluster:
certificate-authority-data: DATA+OMITTED
. . .
Modificando Clusters
Para buscar uma lista de clusters definidos no seu kubeconfig, use get-clusters:
kubectl config get-clusters
[secondary_label Output]
NAME
do-nyc1-sammy
Para adicionar um cluster à sua configuração, use o subcomando set-cluster:
kubectl config set-cluster <^>novo_cluster<^> --server=<^>endereço_do_servidor<^> --certificate-authority=<^>caminho_para_a_autoridade_de_certificação<^>
Para excluir um cluster da sua configuração, use delete-cluster:
Nota: Isso exclui apenas o cluster da sua configuração e não exclui o cluster Kubernetes real.
kubectl config delete-cluster
Modificando Usuários
Você pode executar operações similares para usuários usando set-credentials:
kubectl config set-credentials <^>username<^> --client-certificate=<^>/caminho/para/arquivo/certificado<^> --client-key=<^>/caminho/para/arquivo/chave<^>
Para excluir um usuário da sua configuração, você pode executar unset:
kubectl config unset users.<^>username<^>
Contextos
Um *context* ou contexto no Kubernetes é um objeto que contém um conjunto de parâmetros de acesso para o seu cluster. Ele consiste em uma tripla de cluster, namespace e user. Os contextos permitem alternar rapidamente entre diferentes conjuntos de configurações de cluster.
Para ver seu contexto atual, você pode usar current-context:
kubectl config current-context
[secondary_label Output]
do-nyc1-sammy
Para ver uma lista de todos os contextos configurados, execute get-contexts:
kubectl config get-contexts
[secondary_label Output]
CURRENT NAME CLUSTER AUTHINFO NAMESPACE
* do-nyc1-sammy do-nyc1-sammy do-nyc1-sammy-admin
Para definir um contexto, use set-context:
kubectl config set-context <^>nome_do_contexto<^> --cluster=<^>nome_do_cluster<^> --user=<^>user_name<^> --namespace=<^>namespace<^>
Você pode alternar entre contextos com use-context:
kubectl config use-context <^>nome_do_contexto<^>
[secondary_label Output]
Switched to context "do-nyc1-sammy"
E você pode excluir um contexto com delete-context:
kubectl config delete-context nome_do_contexto
Usando Namespaces
Um Namespace no Kubernetes é uma abstração que lhe permite subdividir seu cluster em vários *clusters virtuais*. Usando Namespaces, você pode dividir os recursos do cluster entre várias equipes e objetos de escopo de maneira apropriada. Por exemplo, você pode ter um Namespace prod para cargas de trabalho de produção e um Namespace dev para cargas de trabalho de desenvolvimento e teste.
Para buscar e imprimir uma lista de todos os Namespaces no cluster, use get namespace:
kubectl get namespace
[secondary_label Output]
NAME STATUS AGE
default Active 2d21h
kube-node-lease Active 2d21h
kube-public Active 2d21h
kube-system Active 2d21h
Para definir um Namespace para o seu contexto atual, use set-context --current:
kubectl config set-context --current --namespace=<^>nome_do_namespace<^>
Para criar um Namespace, use create namespace:
kubectl create namespace <^>namespace_name<^>
[secondary_label Output]
namespace/sammy created
De maneira similar, para excluir um Namespace, use delete namespace:
[warning]
Atenção: A exclusão de um Namespace excluirá tudo no Namespace, incluindo a execução de Deployments, Pods e outras cargas de trabalho. Execute este comando apenas se tiver certeza de que deseja eliminar o que está sendo executado no Namespace ou se estiver excluindo um Namespace vazio.
kubectl delete namespace <^>nome_do_namespace<^>
Para buscar todos os Pods em um determinado Namespace ou para realizar outras operações nos recursos de um determinado Namespace, certifique-se de incluir a flag --namespace:
kubectl get pods --namespace=<^>nome_do_namespace<^>
Gerenciando Recursos do Kubernetes
Sintaxe Geral
A sintaxe geral para a maioria dos comandos de gerenciamento do kubectl é:
kubectl command type name flags
Onde
commandé uma operação que você gostaria de executar, comocreate
typeé o tipo de recurso do Kubernetes, comodeployment
nameé o nome do recurso, comoapp_frontend
flagssão todas as flags opcionais que você gostaria de incluir
Por exemplo, o comando a seguir recupera informações sobre um Deployment chamado app_frontend:
kubectl get deployment app_frontend
Gestão Declarativa e kubectl apply
A abordagem recomendada para gerenciar cargas de trabalho no Kubernetes é confiar no design declarativo do cluster o máximo possível. Isso significa que, em vez de executar uma série de comandos para criar, atualizar, excluir e reiniciar a execução de Pods, você deve definir as cargas de trabalho, serviços e sistemas que deseja executar nos arquivos de manifesto YAML e fornecer esses arquivos ao Kubernetes, que cuidará do resto.
Na prática, isso significa usar o comando kubectl apply, que aplica uma configuração específica a um determinado recurso. Se o recurso de destino não existir, o Kubernetes criará o recurso. Se o recurso já existir, o Kubernetes salvará a revisão atual e atualizará o recurso de acordo com a nova configuração. Essa abordagem *declarativa* existe em contraste com a abordagem *imperativa* de executar o conjunto de comandos kubectl create, kubectl edit e kubectl scale para gerenciar recursos. Para saber mais sobre as diferentes maneiras de gerenciar os recursos do Kubernetes, consulte Gerenciamento de objetos do Kubernetes na documentação do Kubernetes.
Lançando um Deployment
Por exemplo, para fazer o deploy de exemplo do Nginx em seu cluster, use apply e forneça o caminho para o arquivo de manifesto nginx-deployment.yaml:
kubectl apply -f nginx-deployment.yaml
[secondary_label Output]
deployment.apps/nginx-deployment created
A flag -f é usada para especificar um nome de arquivo ou URL contendo uma configuração válida. Se você deseja aplicar todos os manifestos de um diretório, você pode usar a flag -k:
kubectl apply -k <^>diretório_do_manifesto<^>
Você pode acompanhar o status do deployment usando rollout status:
kubectl rollout status deployment/nginx-deployment
[secondary_label Output]
Waiting for deployment "nginx-deployment" rollout to finish: 1 of 2 updated replicas are available...
deployment "nginx-deployment" successfully rolled out
Um alternativa ao rollout status é o comando kubectl get, juntamente com a flag -w (watch):
kubectl get deployment -w
[secondary_label Output]
NAME READY UP-TO-DATE AVAILABLE AGE
nginx-deployment 0/2 2 0 3s
nginx-deployment 1/2 2 1 3s
nginx-deployment 2/2 2 2 3s
Usando rollout pause e rollout resume, você pode pausar e retomar o lançamento ou rollout de um Deployment:
kubectl rollout pause deployment/nginx-deployment
[secondary_label Output]
deployment.extensions/nginx-deployment paused
kubectl rollout resume deployment/nginx-deployment
[secondary_label Output]
deployment.extensions/nginx-deployment resumed
Modificando um Deployment em Execução
Se você quiser modificar um Deployment em execução, poderá fazer alterações no seu arquivo de manifesto e, em seguida, executar o kubectl apply novamente para aplicar a atualização. Por exemplo, vamos modificar o arquivo nginx-deployment.yaml para alterar o número de réplicas de 2 para 3:
[label nginx-deployment.yaml]
. . .
spec:
replicas: <^>3<^>
selector:
matchLabels:
app: nginx
. . .
O comando kubectl diff permite que você veja diferenças entre os recursos em execução no momento e as alterações propostas no arquivo de configuração fornecido:
kubectl diff -f nginx-deployment.yaml
Agora permita que o Kubernetes execute a atualização usando apply:
kubectl apply -f nginx-deployment.yaml
A execução de outro get deployment deve confirmar a adição de uma terceira réplica.
Se você executar apply novamente sem modificar o arquivo de manifesto, o Kubernetes detectará que nenhuma alteração foi feita e não executará nenhuma ação.
Usando o rollout history, você pode ver uma lista das revisões anteriores do Deployment:
kubectl rollout history deployment/nginx-deployment
[secondary_label Output]
deployment.extensions/nginx-deployment
REVISION CHANGE-CAUSE
1 <none>
Com rollout undo, você pode reverter um Deployment para qualquer uma das revisões anteriores:
kubectl rollout undo deployment/nginx-deployment --to-revision=<^>1<^>
Excluindo um Deployment
Para excluir um deployment em execução, use kubectl delete:
kubectl delete -f nginx-deployment.yaml
[secondary_label Output]
deployment.apps "nginx-deployment" deleted
Gerenciamento Imperativo
Você também pode usar um conjunto de comandos imperativos para manipular e gerenciar diretamente os recursos do Kubernetes.
Criando um Deployment
Use create para criar um objeto a partir de um arquivo, URL ou STDIN. Observe que, ao contrário de apply, se um objeto com o mesmo nome já existir, a operação irá falhar. A flag --dry-run lhe permite visualizar o resultado da operação sem realmente executá-la:
kubectl create -f nginx-deployment.yaml --dry-run
[secondary_label Output]
deployment.apps/nginx-deployment created (dry-run)
Agora podemos criar o objeto:
kubectl create -f nginx-deployment.yaml
[secondary_label Output]
deployment.apps/nginx-deployment created
Modificando um Deployment em Execução
Use scale para escalar o número de réplicas para o Deployment de 2 para 4:
kubectl scale --replicas=4 deployment/nginx-deployment
[secondary_label Output]
deployment.extensions/nginx-deployment scaled
Você pode editar qualquer objeto localmente usando o kubectl edit. Isso abrirá o manifesto do objeto no seu editor padrão:
kubectl edit deployment/nginx-deployment
Você deve ver o seguinte arquivo de manifesto em seu editor:
[label nginx-deployment]
# Please edit the object below. Lines beginning with a '#' will be ignored,
# and an empty file will abort the edit. If an error occurs while saving this file will be
# reopened with the relevant failures.
#
apiVersion: extensions/v1beta1
kind: Deployment
. . .
spec:
progressDeadlineSeconds: 600
replicas: 4
revisionHistoryLimit: 10
selector:
matchLabels:
. . .
Altere o valor das replicas de 4 para 2, depois salve e feche o arquivo.
Agora execute um get para inspecionar as alterações:
kubectl get deployment/nginx-deployment
[secondary_label Output]
NAME READY UP-TO-DATE AVAILABLE AGE
nginx-deployment 2/2 2 2 6m40s
Escalamos o Deployment com êxito de volta para duas réplicas on-the-fly (ou seja, durante a operação). Você pode atualizar a maioria dos campos de um objeto do Kubernetes de maneira semelhante.
Outro comando útil para modificar objetos localmente é o kubectl patch. Usando o patch, você pode atualizar os campos de um objeto on-the-fly, sem precisar abrir o seu editor. O patch também permite atualizações mais complexas com várias estratégias de mesclagem e correção. Para saber mais sobre isso, consulte Update API Objects in Place Using kubectl patch.
O comando a seguir irá corrigir o objeto nginx-deployment para atualizar o campo replicas de 2 para 4; deploy é uma abreviação para o objeto deployment.
kubectl patch deploy nginx-deployment -p '{"spec": {"replicas": 4}}'
[secondary_label Output]
deployment.extensions/nginx-deployment patched
Agora podemos inspecionar as alterações:
kubectl get deployment/nginx-deployment
[secondary_label Output]
NAME READY UP-TO-DATE AVAILABLE AGE
nginx-deployment 4/4 4 4 18m
Você também pode criar um Deployment imperativamente usando o comando run. O run criará um Deployment usando uma imagem fornecida como parâmetro:
kubectl run nginx-deployment --image=nginx --port=80 --replicas=2
O comando expose permite expor rapidamente um Deployment em execução como um Serviço Kubernetes, permitindo conexões de fora do seu cluster Kubernetes:
kubectl expose deploy nginx-deployment --type=LoadBalancer --port=80 --name=nginx-svc
[secondary_label Output]
service/nginx-svc exposed
Aqui, expusemos o Deployment nginx-deployment como um serviço LoadBalancer, abrindo a porta 80 para o tráfego externo e direcionando-a para a porta 80 do container. Nomeamos o serviço como nginx-svc. Usando o tipo de Serviço LoadBalancer, um balanceador de carga em nuvem é automaticamente provisionado e configurado pelo Kubernetes. Para obter o endereço IP externo do Serviço, use get:
kubectl get svc nginx-svc
[secondary_label Output]
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
nginx-svc LoadBalancer 10.245.26.242 203.0.113.0 80:30153/TCP 22m
Você pode acessar os containers Nginx em execução indo até o EXTERNAL-IP no seu navegador web.
Inspecionando Cargas de Trabalho e Debugando
Existem vários comandos que você pode usar para obter mais informações sobre cargas de trabalho em execução no seu cluster.
Inspecionando Recursos no Kubernetes
O kubectl get busca um determinado recurso do Kubernetes e exibe algumas informações básicas associadas a ele:
kubectl get deployment -o wide
[secondary_label Output]
NAME READY UP-TO-DATE AVAILABLE AGE CONTAINERS IMAGES SELECTOR
nginx-deployment 4/4 4 4 29m nginx nginx app=nginx
Como não fornecemos um nome de Deployment ou um Namespace, o kubectl busca todos os Deployments no Namespace atual. A flag -o fornece informações adicionais como CONTAINERS e IMAGES.
Além do get, você pode usar o describe para buscar uma descrição detalhada do recurso e dos recursos associados:
kubectl describe deploy nginx-deployment
[secondary_label Output]
Name: nginx-deployment
Namespace: default
CreationTimestamp: Wed, 11 Sep 2019 12:53:42 -0400
Labels: run=nginx-deployment
Annotations: deployment.kubernetes.io/revision: 1
Selector: run=nginx-deployment
. . .
O conjunto de informações apresentadas variará dependendo do tipo de recurso. Você também pode usar este comando sem especificar um nome de recurso; nesse caso, as informações serão fornecidas para todos os recursos desse tipo no Namespace atual.
O explain permite que você puxe rapidamente campos configuráveis para um determinado tipo de recurso:
kubectl explain deployment.spec
Ao acrescentar campos adicionais, você pode mergulhar mais fundo na hierarquia de campos:
kubectl explain deployment.spec.template.spec
Obtendo Acesso ao Shell de um Container
Para obter acesso ao shell de um container em execução, use exec. Primeiro, encontre o Pod que contém o container em execução ao qual você deseja acessar:
kubectl get pod
[secondary_label Output]
nginx-deployment-8859878f8-7gfw9 1/1 Running 0 109m
nginx-deployment-8859878f8-z7f9q 1/1 Running 0 109m
Vamos fazer um exec para o primeiro Pod. Como este Pod possui apenas um container, não precisamos usar a flag -c para especificar em qual container gostaríamos de fazer o exec.
kubectl exec -i -t nginx-deployment-8859878f8-7gfw9 -- /bin/bash
[secondary_label Output]
root@nginx-deployment-8859878f8-7gfw9:/#
Agora você tem acesso ao shell do container Nginx. A flag -i passa o STDIN para o container e -t fornece um TTY interativo. O traço duplo -- atua como um separador para o comando kubectl e o comando que você deseja executar dentro do container. Neste caso, estamos executando o /bin/bash.
Para executar comandos dentro do container sem abrir um shell completo, omita as flags -i e -t e substitua o comando que você deseja executar em vez de /bin/bash:
kubectl exec nginx-deployment-8859878f8-7gfw9 ls
[secondary_label Output]
bin
boot
dev
etc
home
lib
lib64
media
. . .
Buscando Logs
Outro comando útil é o logs, que imprime logs de Pods e containers, incluindo containers finalizados.
Para transmitir logs para a saída do seu terminal, você pode usar a flag -f:
kubectl logs -f nginx-deployment-8859878f8-7gfw9
[secondary_label Output]
10.244.2.1 - - [12/Sep/2019:17:21:33 +0000] "GET / HTTP/1.1" 200 612 "-" "203.0.113.0" "-"
2019/09/16 17:21:34 [error] 6#6: *1 open() "/usr/share/nginx/html/favicon.ico" failed (2: No such file or directory), client: 10.244.2.1, server: localhost, request: "GET /favicon.ico HTTP/1.1", host: "203.0.113.0", referrer: "http://203.0.113.0"
. . .
Este comando continuará sendo executado no seu terminal até ser interrompido com um CTRL+C. Você pode omitir a flag -f se quiser imprimir a saída do log e sair imediatamente.
Você também pode usar a flag -p para buscar logs de um container terminado. Quando esta opção é usada dentro de um Pod que tinha uma instância anterior do container em execução, logs imprimirá a saída do container finalizado:
kubectl logs -p nginx-deployment-8859878f8-7gfw9
A flag -c lhe permite especificar o container do qual você deseja buscar logs, se o Pod tiver vários containers. Você pode usar a flag --all-containers=true para buscar logs de todos os containers no Pod.
Redirecionamento de Porta e Proxying
Para obter acesso de rede a um Pod, você pode usar o port-forward:
sudo kubectl port-forward pod/nginx-deployment-8859878f8-7gfw9 80:80
[secondary_label Output]
Forwarding from 127.0.0.1:80 -> 80
Forwarding from [::1]:80 -> 80
Neste caso, usamos sudo porque a porta 80 local é uma porta protegida. Para a maioria das outras portas, você pode omitir o sudo e executar o comando kubectl como seu usuário do sistema.
Aqui redirecionamos a porta 80 local (que antecede os dois pontos) para a porta 80 do container do Pod (após os dois pontos).
Você também pode usar deploy/nginx-deployment como tipo e nome do recurso para o qual redirecionar. Se você fizer isso, a porta local será redirecionada para o Pod selecionado pelo Deployment.
O comando proxy pode ser usado para acessar o servidor de API do Kubernetes localmente:
kubectl proxy --port=8080
[secondary_label Output]
Starting to serve on 127.0.0.1:8080
Em outro shell, use curl para explorar a API:
curl http://localhost:8080/api/
[secondary_label Output]
{
"kind": "APIVersions",
"versions": [
"v1"
],
"serverAddressByClientCIDRs": [
{
"clientCIDR": "0.0.0.0/0",
"serverAddress": "203.0.113.0:443"
}
]
Feche o proxy pressionando CTRL-C.
Conclusão
Este guia aborda alguns dos comandos mais comuns do kubectl que você pode usar ao gerenciar um cluster Kubernetes e as cargas de trabalho *deployadas* nele.
Você pode aprender mais sobre o kubectl consultando a documentação de referência oficial do Kubernetes.
Existem muitos outros comandos e variações que você pode achar úteis como parte do seu trabalho com o kubectl. Para saber mais sobre todas as suas opções disponíveis, você pode executar:
kubectl --help