Autenticação no Kubernetes - Kubeconfig

Como dito no post anterior, executar kubectl apply -f manifest.yaml é um processo que envolve autenticação, autorização e admissão. Dando continuidade à série de artigos que culminará na persistência do recurso no etcd, neste capítulo falaremos sobre o processo de autenticação no Kubernetes — o primeiro passo da cadeia de segurança.

A autenticação é responsável por responder à pergunta: “Quem está fazendo essa requisição?”

Somente após essa etapa o Kubernetes prossegue para verificar o que essa entidade pode fazer (autorização) e se a requisição é válida (admissão).

---

Entendendo a Requisição

Vamos continuar com o mesmo exemplo, agora executando um comando com o kubectl e habilitando o nível de verbosidade 7:

Observando a sequência de eventos na imagem acima, temos que:

1. Ao executar o comando kubectl get pods,

2. uma das primeiras operações feitas é a leitura do arquivo disponível em ~/.kube/config,

3. logo em seguida, é feita uma requisição usando o método HTTP GET para a URI disponível em https://127.0.0.1:53806/api/v1/namespaces/kube-system/pods,

4. e, finalmente, a lista de pods disponível no namespace kube-system é apresentada.

Ao observar a execução do comando, notamos que a leitura do arquivo ~/.kube/config é uma das primeiras operações. As informações disponíveis nele servirão como insumo para efetuar a requisição ao kube-apiserver e retornar a lista de pods no namespace kube-system.

---

O Papel do Arquivo kubeconfig

O arquivo kubeconfig guarda as informações de clusters, usuários, namespaces e mecanismos de segurança utilizados para autenticar-se nos clusters. Na prática, todos os comandos executados com o kubectl leem esse arquivo para determinar como se conectar e como autenticar ao servidor da API do Kubernetes.

Continuando com o exemplo anterior, vamos tentar fazer a mesma requisição que o kubectl está fazendo, mas usando um cliente HTTP. (Estou usando o httpie para uma resposta melhor apresentada, mas o mesmo pode ser feito usando curl -s -X GET -k https://127.0.0.1:53806/api/v1/namespaces/kube-system/pods):

Como pode ser observado, todas as requisições ao kube-apiserver precisam ser associadas a um usuário comum ou a um ServiceAccount. Neste caso, como não estamos passando nenhuma informação que nos identifique na requisição, o usuário é tratado como anônimo (system:anonymous).

É possível desabilitar completamente o usuário anônimo, passando a flag --anonymous-auth=false no kube-apiserver. Dessa maneira, todas as requisições que não têm um usuário conhecido associado serão completamente ignoradas.

Para os próximos comandos, usarei informações disponíveis no kubeconfig a fim de replicar o mesmo comportamento retornado pelo kubectl, ou seja, vamos usar as mesmas credenciais. Não se preocupe se não entender o que são essas informações; no decorrer deste artigo, essas lacunas serão preenchidas.

Primeiro, com o yq, vamos extrair as informações dos certificados utilizados para autenticar no kube-apiserver. As informações que precisamos são o certificado da autoridade certificadora, o certificado do cliente e a chave do cliente. Com posse dos certificados e chaves, vamos passá-los como parâmetros no comando curl.

Com os arquivos salvos, executamos a requisição com o curl:

Como podemos observar na imagem acima, passando as mesmas informações utilizadas pelo kubectl, conseguimos o mesmo resultado, autenticando a requisição com sucesso.

---

Localização do kubeconfig

Por padrão, o arquivo de configuração (kubeconfig) é armazenado em:

No entanto, é possível definir um caminho alternativo por meio da variável de ambiente KUBECONFIG.

Por exemplo, usando o kind, podemos criar dois clusters e especificar onde o arquivo de configuração será salvo:

Definindo o Arquivo de Configuração a Ser Utilizado

Há três formas principais de indicar qual arquivo de configuração o kubectl deve usar.

1. Utilizando a variável KUBECONFIG diretamente

Você pode definir o caminho do arquivo para uma única execução:

Para evitar repetir a variável em todos os comandos, podemos exportá-la para o ambiente atual:

2. Usando múltiplos arquivos kubeconfig

A variável KUBECONFIG também pode conter uma lista de arquivos, separados por : (em sistemas Unix/Linux/macOS) ou ; (no Windows). O kubectl mesclará automaticamente esses arquivos em uma única visualização:

Essa funcionalidade é extremamente útil em cenários com múltiplos clusters — como ambientes de desenvolvimento, homologação e produção — permitindo unificar credenciais e contextos em um único arquivo consolidado.

3. Utilizando a flag --kubeconfig

Outra opção é especificar o arquivo diretamente na linha de comando, usando a flag --kubeconfig:

Essa abordagem é especialmente prática em scripts ou pipelines de automação, onde o caminho do arquivo precisa ser definido de forma explícita.

---

Estrutura do Arquivo kubeconfig

O kubeconfig é um arquivo YAML que segue um schema que define quatro seções principais:

• clusters – informações sobre o endereço da API do cluster e o certificado utilizado na comunicação.

• users – credenciais e mecanismos de autenticação.

• contexts – combinações entre cluster, usuário e namespace.

• current-context – o contexto ativo, utilizado por padrão pelo kubectl.

Um exemplo básico de um arquivo kubeconfig:

apiVersion: v1
kind: Config
current-context: kind-cluster-1
clusters:
- cluster:
    certificate-authority-data: "..." # CA do cluster em Base64
    server: [https://127.0.0.1:56815](https://127.0.0.1:56815)
  name: kind-cluster-1
users:
- name: kind-cluster-1
  user:
    client-certificate-data: "..." # Certificado do cliente em Base64
    client-key-data: "..."         # Chave privada do cliente em Base64
contexts:
- context:
    cluster: kind-cluster-1
    namespace: kube-system
    user: kind-cluster-1
  name: kind-cluster-1

Seção clusters

A lista clusters define todos os clusters Kubernetes conhecidos pelo kubectl.

Cada entrada contém:

• name: nome único do cluster dentro do arquivo (referenciado pelos contexts).

• cluster.server: URL do servidor da API Kubernetes (endpoint do apiserver).

• cluster.certificate-authority-data: certificado da autoridade certificadora (CA) codificado em Base64, usado para validar a identidade do servidor.

  • Alternativamente, pode-se usar certificate-authority: /caminho/para/ca.crt.

Exemplos com kubectl config:

Descrição	Comando kubectl
Recupera a lista de clusters disponíveis	kubectl config get-clusters
Salva um novo cluster (com caminho de CA)	kubectl config set-cluster kind-cluster-3 --server https://127.0.0.1:56815 --certificate-authority certificate.cer
Salva um novo cluster (com CA embutida)	kubectl config set-cluster kind-cluster-3 --server https://127.0.0.1:56815 --certificate-authority certificate.cer --embed-certs
Remove um cluster	kubectl config delete-cluster cluster-3

Seção users

A lista users define as credenciais de acesso para autenticação no cluster.

Cada entrada contém:

• name: nome do usuário (referenciado pelos contexts).

• user.client-certificate-data e user.client-key-data: par de certificado e chave privada em Base64 (autenticação via certificados).

• user.token: token de autenticação (usado em provedores gerenciados, como EKS, GKE ou AKS).

• user.username / user.password: autenticação básica (raramente usada em produção).

Em ambientes corporativos, é comum o uso de exec plugins para gerar tokens dinâmicos, como provedores OIDC ou o AWS CLI com EKS:

user:
  exec:
    command: aws
    args:
      - "eks"
      - "get-token"
      - "--cluster-name"
      - "meu-cluster"

Exemplos com kubectl config:

Descrição	Comando kubectl
Recupera a lista de usuários disponíveis	kubectl config get-users
Cria credencial (Certificado/Chave - caminho)	kubectl config set-credentials kind-cluster-3 --client-certificate client-certificate.crt --client-key client.key
Cria credencial (Certificado/Chave - embutida)	kubectl config set-credentials kind-cluster-3 --client-certificate client-certificate.crt --client-key client.key --embed-certs
Cria credencial (Usuário/Senha)	kubectl config set-credentials kind-cluster-3 --username username --password password
Cria credencial (Token)	kubectl config set-credentials kind-cluster-3 --token token
Cria credencial OIDC	kubectl config set-credentials kind-cluster-3 --auth-provider=oidc --auth-provider-arg=client-id=foo --auth-provider-arg=client-secret=bar

Seção contexts

A lista contexts combina um cluster, um usuário e, opcionalmente, um namespace padrão.

Cada entrada contém:

• name: nome único do contexto (referenciado por current-context).

• context.cluster: nome do cluster (declarado em clusters).

• context.user: nome do usuário (declarado em users).

• context.namespace (opcional): define o namespace padrão ao usar comandos kubectl.

Exemplos com kubectl config:

Descrição	Comando kubectl
Recupera a lista de contexts disponíveis	kubectl config get-contexts
Cria um novo context	kubectl config set-context prod-admin --cluster kind-cluster-1 --user kind-cluster-1
Cria um novo context com namespace padrão	kubectl config set-context dev-user --cluster kind-cluster-2 --user dev-user --namespace app-frontend
Altera o context atual	kubectl config use-context prod-admin
Remove um context	kubectl config delete-context dev-user

Seção current-context

Define qual contexto está ativo no momento — ou seja, qual cluster, usuário e namespace serão usados por padrão ao executar kubectl sem opções adicionais.

Para verificar o contexto atual:

Para alternar o contexto ativo, você pode usar: