Kubernetes - Entendendo o kubeconfig

Sat, Nov 26, 2022

Para explicar sobre o arquivo kubeconfig esta publicação utilizará o minikube, mas as explicações são válidas para quase qualquer outra instalação do Openshift ou Kubernetes.

O Arquivo

O kubeconfig é um arquivo usado por alguns componentes do Kubernetes, como kubelet, kube-controller-manager ou kubectl, para interagir com a API do Kubernetes. Na maioria das vezes, nossa preocupação é com o kubeconfig utilizado pelos comandos kubectl ou oc.

O local padrão do kubeconfig para kubectl ou oc está dentro do diretório .kube do seu usuário. Em vez de usar o nome completo do kubeconfig, o arquivo é chamado apenas de config. Com isso em mente, podemos afirmar que o local padrão do arquivo kubeconfig é ~/.kube/config. Existem outras maneiras de especificar o local do kubeconfig, com a variável de ambiente KUBECONFIG ou com o parâmetro kubectl --kubeconfig.

O kubeconfig é um arquivo YAML que contém grupos de clusters, usuários e contextos.

Um cluster é um cluster do Kubernetes ou Openshift, por exemplo:

Um usuário é a credencial que usaremos para interagir com a API do Kubernetes.

Um contexto é uma combinação de um cluster e um usuário; toda vez que executamos algum comando oc ou kubectl, estamos referenciando um contexto dentro do kubeconfig.

Um kubeconfig de uma nova instalação do minikube é assim:

apiVersion: v1  
kind: Config  
clusters:  
- name: minikube  
  cluster:  
    certificate-authority: /home/hector/.minikube/ca.crt  
    server: https://192.168.39.217:8443  
users:  
- name: minikube  
  user:  
    client-certificate: /home/hector/.minikube/profiles/minikube/client.crt  
    client-key: /home/hector/.minikube/profiles/minikube/client.key  
contexts:  
- name: minikube  
  context:  
    cluster: minikube  
    namespace: default  
    user: minikube  
current-context: minikube

Preste atenção nas seções principais clusters, contexts e users. A seção clusters é uma lista que contém todos os clusters que já conectamos. Nesse caso, há apenas um único com o nome minikube, esse nome é arbitrário e pode ser qualquer nome que você desejar. Dentro do cluster, temos duas chaves:

certificate-authority contém um certificado da CA que assinou todos os certificados internos do Kubernetes, isso pode ser um caminho de arquivo ou uma string base64 do certificado no formato PEM.
server é o endereço do servidor.

A seção users é uma lista que contém todos os usuários que já usamos para conectar a um cluster. Nesse caso, há apenas um único usuário chamado minikube, esse nome é arbitrário e não tem relação com nenhum objeto dentro do Kubernetes ou Openshift. Existem algumas chaves possíveis para um usuário:

client-certificate contém um certificado do usuário assinado pela CA do Kubernetes, isso pode ser um caminho de arquivo ou uma string base64 do certificado no formato PEM.
client-key contém a chave que assinou o certificado do cliente.
token contém um token usado por este usuário quando não há certificado.

A seção contexts especifica uma combinação entre um user e um cluster, definindo também um namespace padrão para esse par. O nome do contexto é arbitrário, mas o user e o cluster devem estar pré-definidos dentro do arquivo kubeconfig. Se o namespace não existir dentro do Kubernetes, os comandos falharão com a mensagem padrão do Kubernetes para um namespace não existente.

Autenticação

Por padrão, não há um objeto usuário dentro de um Kubernetes. Para autenticar o administrador do cluster padrão, o Kubernetes utiliza um certificado X.509. O certificado x509 informará ao Kubernetes sobre o usuário que está tentando acessar.

Para inspecionar um certificado x509, podemos usar o comando openssl. Por causa do exemplo acima, temos um client-certificate apontando para um arquivo, e podemos usar o seguinte comando para inspecioná-lo:

openssl x509 -noout -text -in /home/hector/.minikube/profiles/minikube/client.crt

A saída é extensa mas vamos focar apenas em algumas linhas:

Certificate:  
    Data:  
        Version: 3 (0x2)  
        Serial Number: 2 (0x2)  
        Signature Algorithm: sha256WithRSAEncryption  
        Issuer: CN = minikubeCA  
        Validity  
            Not Before: Nov 23 18:50:27 2022 GMT  
            Not After : Nov 23 18:50:27 2025 GMT  
        Subject: O = system:masters, CN = minikube-user  
        Subject Public Key Info:  
                                ...  
        X509v3 extensions:  
            X509v3 Key Usage: critical  
                Digital Signature, Key Encipherment  
            X509v3 Extended Key Usage:   
                TLS Web Server Authentication, TLS Web Client Authentication  
            X509v3 Basic Constraints: critical  
                CA:FALSE  
                                ...

Estamos procurando as informações do Subject e algumas X509v3 extensions. Não irei explicar os conceitos e os requisitos para essas extensões, mas elas são necessárias para esse tipo de autenticação.

O Subject é uma diretiva X509 que especifica algumas informações, como o CN (Common Name), O (Organization), OU (Organization Unit), C (Country), etc. Veja mais de perto o campo O, o valor é system:masters. Isso está dizendo ao Kubernetes que este certificado pertence a alguém que está dentro do grupo system:masters. Neste caso, não há usuário algum, mas o grupo é suficiente.

Vamos dar uma olhada dentro do Kubernetes e encontrar os objetos RBAC que atendem a essa autenticação:

kubectl get clusterrolebinding cluster-admin -o yaml  
# Saída:  
apiVersion: rbac.authorization.k8s.io/v1  
kind: ClusterRoleBinding  
metadata:  
  labels:  
    kubernetes.io/bootstrapping: rbac-defaults  
  name: cluster-admin  
roleRef:  
  apiGroup: rbac.authorization.k8s.io  
  kind: ClusterRole  
  name: cluster-admin  
subjects:  
- apiGroup: rbac.authorization.k8s.io  
  kind: Group  
  name: system:masters

Este clusterrolebinding conecta a clusterrole cluster-admin ao group system:masters.

A mesma lógica é usada para outros componentes do Kubernetes, como podemos ver dentro de /etc/kubernetes:

ls /etc/kubernetes/*.conf  
# Saída:  
/etc/kubernetes/admin.conf  /etc/kubernetes/controller-manager.conf  /etc/kubernetes/kubelet.conf  /etc/kubernetes/scheduler.conf

Cada um desses arquivos é um kubeconfig para um componente específico com usuário e certificado específicos.

Modificando Contextos

É possível editar o contexto editando manualmente o kubeconfig, mas isso pode levar a erros.

Se quisermos mudar nosso namespace padrão no Kubernetes, podemos executar o seguinte comando:

kubectl config set-context --current --namespace kube-system

Esse comando é mais seguro, ele modificará o kubeconfig para nós, alterando o namespace dentro do contexto atual.

Existem outros comandos que podem ser usados, por exemplo, para mudar completamente um contexto ou até criar um novo do zero.

Conclusão

O arquivo kubeconfig é a maneira padrão de autenticar-se em um cluster Kubernetes, pode ser um pouco críptico devido aos certificados incorporados, mas é fácil de entender se olharmos mais de perto. O kubeconfig pode conter outros clusters, usuários e contextos, e é possível alternar entre eles com kubectl config use-context ou kubectl --context <context>.

O cliente do Openshift é mais amigável ao usuário porque pode criar um kubeconfig após o comando oc login se nenhum existir, mas podemos criar um kubeconfig com kubectl executando alguns comandos kubectl config.