###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:
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:
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
.
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
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.
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
Para usar o recurso de autocompletar, pressione a tecla TAB
para exibir os comandos kubectl disponíveis:
- kubectl TAB TAB
Outputannotate 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
Outputdelete describe diff drain
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:
OutputKubernetes 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.
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
OutputapiVersion: 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
OutputNAME
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
Outputdo-nyc1-sammy
Para ver uma lista de todos os contextos configurados, execute get-contexts
:
- kubectl config get-contexts
OutputCURRENT 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
OutputSwitched to context "do-nyc1-sammy"
E você pode excluir um contexto com delete-context
:
- kubectl config delete-context nome_do_contexto
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
OutputNAME 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
Outputnamespace/sammy created
De maneira similar, para excluir um Namespace, use delete namespace
:
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
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, como create
type
é o tipo de recurso do Kubernetes, como deployment
name
é o nome do recurso, como app_frontend
flags
são todas as flags opcionais que você gostaria de incluirPor exemplo, o comando a seguir recupera informações sobre um Deployment chamado app_frontend
:
- kubectl get deployment app_frontend
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
Outputdeployment.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
OutputWaiting 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
OutputNAME 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
Outputdeployment.extensions/nginx-deployment paused
- kubectl rollout resume deployment/nginx-deployment
Outputdeployment.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
:
. . .
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
Outputdeployment.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
Outputdeployment.apps "nginx-deployment" deleted
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
Outputdeployment.apps/nginx-deployment created (dry-run)
Agora podemos criar o objeto:
- kubectl create -f nginx-deployment.yaml
Outputdeployment.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
Outputdeployment.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:
# 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
OutputNAME 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}}'
Outputdeployment.extensions/nginx-deployment patched
Agora podemos inspecionar as alterações:
- kubectl get deployment/nginx-deployment
OutputNAME 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
Outputservice/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
OutputNAME 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.
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
OutputNAME 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
OutputName: 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
Outputnginx-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
Outputroot@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
Outputbin
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
Output10.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
OutputForwarding 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
OutputStarting to serve on 127.0.0.1:8080
Em outro shell, use curl
para explorar a API:
- curl http://localhost:8080/api/
Output{
"kind": "APIVersions",
"versions": [
"v1"
],
"serverAddressByClientCIDRs": [
{
"clientCIDR": "0.0.0.0/0",
"serverAddress": "203.0.113.0:443"
}
]
Feche o proxy pressionando CTRL-C
.
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
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!
Sign up for Infrastructure as a Newsletter.
Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.
Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.