--- title: Ferramenta de linha de comando (kubectl) content_type: reference weight: 110 no_list: true card: name: reference title: Ferramenta de linha de comando kubectl weight: 20 --- {{< glossary_definition prepend="Kubernetes fornece um" term_id="kubectl" length="short" >}} 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](/docs/concepts/configuration/organize-cluster-access-kubeconfig/) definindo a variável de ambiente `KUBECONFIG` ou configurando a flag [`--kubeconfig`](/docs/concepts/configuration/organize-cluster-access-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](/docs/reference/kubectl/generated/kubectl/). Para instruções de instalação, consulte [Instalando kubectl](/docs/tasks/tools/#kubectl); para um guia rápido, consulte a [folha de dicas](/docs/reference/kubectl/quick-reference/). Se você está acostumado a usar a ferramenta de linha de comando `docker`, [`kubectl` para Usuários Docker](/docs/reference/kubectl/docker-cli-to-kubectl/) explica alguns comandos equivalentes para Kubernetes. ## Sintaxe Use a seguinte sintaxe para executar comandos `kubectl` da janela do seu terminal: ```shell 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). 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: ```shell 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](/docs/concepts/configuration/overview/#dicas-gerais-de-configuração) 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.
{{< caution >}} Flags que você especifica da linha de comando sobrescrevem valores padrão e quaisquer variáveis de ambiente correspondentes. {{< /caution >}} 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 ` 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: ```shell kubectl config set-context --current --namespace= ``` ## 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 [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 [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](/docs/reference/kubectl/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](/docs/reference/kubectl/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 ```shell kubectl [command] [TYPE] [NAME] -o ``` Dependendo da operação do `kubectl`, os seguintes formatos de saída são suportados: Formato de saída | Descrição --------------| ----------- `-o custom-columns=` | Imprime uma tabela usando uma lista separada por vírgulas de [colunas personalizadas](#colunas-personalizadas). `-o custom-columns-file=` | Imprime uma tabela usando o template de [colunas personalizadas](#colunas-personalizadas) no arquivo ``. `-o json` | Gera um objeto de API formatado em JSON. `-o jsonpath=