Você está vendo a documentação do Kubernetes versão: v1.31
Kubernetes v1.31 a documentação não é mais mantida ativamente. A versão que você está visualizando no momento é uma cópia estática. Para obter a documentação atualizada, consulte última versão.
Organizando o acesso ao cluster usando arquivos kubeconfig
Utilize arquivos kubeconfig para organizar informações sobre clusters, usuários, namespaces e mecanismos de autenticação. A ferramenta de linha de comando kubectl
faz uso dos arquivos kubeconfig para encontrar as informações necessárias para escolher e se comunicar com o serviço de API de um cluster.
Nota:
Um arquivo que é utilizado para configurar o acesso aos clusters é chamado de kubeconfig. Esta á uma forma genérica de referenciamento para um arquivo de configuração desta natureza. Isso não significa que existe um arquivo com o nomekubeconfig
.Por padrão, o kubectl
procura por um arquivo de nome config
no diretório $HOME/.kube
Você pode especificar outros arquivos kubeconfig através da variável de ambiente KUBECONFIG
ou adicionando a opção --kubeconfig
.
Para maiores detalhes na criação e especificação de um kubeconfig, veja o passo a passo em Configurar Acesso para Múltiplos Clusters.
Suportando múltiplos clusters, usuários e mecanismos de autenticação
Imagine que você possua inúmeros clusters, e seus usuários e componentes se autenticam de várias formas. Por exemplo:
- Um kubelet ativo pode se autenticar utilizando certificados
- Um usuário pode se autenticar através de tokens
- Administradores podem possuir conjuntos de certificados os quais provém acesso aos usuários de forma individual.
Através de arquivos kubeconfig, você pode organizar os seus clusters, usuários, e namespaces. Você também pode definir contextos para uma fácil troca entre clusters e namespaces.
Contexto
Um elemento de contexto em um kubeconfig é utilizado para agrupar parâmetros de acesso em um nome conveniente. Cada contexto possui três parâmetros: cluster, namespace, e usuário.
Por padrão, a ferramenta de linha de comando kubectl
utiliza os parâmetros do contexto atual para se comunicar com o cluster.
Para escolher o contexto atual:
kubectl config use-context
A variável de ambiente KUBECONFIG
A variável de ambiente KUBECONFIG
possui uma lista dos arquivos kubeconfig. Para Linux e Mac, esta lista é delimitada por vírgula. No Windows, a lista é delimitada por ponto e vírgula. A variável de ambiente KUBECONFIG
não é um requisito obrigatório - caso ela não exista o kubectl
utilizará o arquivo kubeconfig padrão localizado no caminho $HOME/.kube/config
.
Se a variável de ambiente KUBECONFIG
existir, o kubectl
utilizará uma configuração que é o resultado da combinação dos arquivos listados na variável de ambiente KUBECONFIG
.
Combinando arquivos kubeconfig
Para inspecionar a sua configuração atual, execute o seguinte comando:
kubectl config view
Como descrito anteriormente, a saída poderá ser resultado de um único arquivo kubeconfig, ou poderá ser o resultado da junção de vários arquivos kubeconfig.
Aqui estão as regras que o kubectl
utiliza quando realiza a combinação de arquivos kubeconfig:
-
Se o argumento
--kubeconfig
está definido, apenas o arquivo especificado será utilizado. Apenas uma instância desta flag é permitida.Caso contrário, se a variável de ambiente
KUBECONFIG
estiver definida, esta deverá ser utilizada como uma lista de arquivos a serem combinados, seguindo o fluxo a seguir:- Ignorar arquivos vazios.
- Produzir erros para aquivos cujo conteúdo não for possível desserializar.
- O primeiro arquivo que definir um valor ou mapear uma chave determinada, será o escolhido.
- Nunca modificar um valor ou mapear uma chave.
Exemplo: Preservar o contexto do primeiro arquivo que definir
current-context
. Exemplo: Se dois arquivos especificarem umred-user
, use apenas os valores do primeirored-user
. Mesmo se um segundo arquivo possuir entradas não conflitantes sobre a mesma entradared-user
, estas deverão ser descartadas.
Para um exemplo de definição da variável de ambiente
KUBECONFIG
veja Definido a variável de ambiente KUBECONFIG.Caso contrário, utilize o arquivo kubeconfig padrão encontrado no diretório
$HOME/.kube/config
, sem qualquer tipo de combinação. -
Determine o contexto a ser utilizado baseado no primeiro padrão encontrado, nesta ordem:
- Usar o conteúdo da flag
--context
caso ela existir. - Usar o
current-context
a partir da combinação dos arquivos kubeconfig.
Um contexto vazio é permitido neste momento.
- Usar o conteúdo da flag
-
Determinar o cluster e o usuário. Neste ponto, poderá ou não existir um contexto. Determinar o cluster e o usuário no primeiro padrão encontrado de acordo com a ordem à seguir. Este procedimento deverá executado duas vezes: uma para definir o usuário a outra para definir o cluster.
- Utilizar a flag caso ela existir:
--user
ou--cluster
. - Se o contexto não estiver vazio, utilizar o cluster ou usuário deste contexto.
O usuário e o cluster poderão estar vazios neste ponto.
- Utilizar a flag caso ela existir:
-
Determinar as informações do cluster atual a serem utilizadas. Neste ponto, poderá ou não existir informações de um cluster.
Construir cada peça de informação do cluster baseado nas opções à seguir; a primeira ocorrência encontrada será a opção vencedora:
- Usar as flags de linha de comando caso existirem:
--server
,--certificate-authority
,--insecure-skip-tls-verify
. - Se algum atributo do cluster existir a partir da combinação de kubeconfigs, estes deverão ser utilizados.
- Se não existir informação de localização do servidor falhar.
- Usar as flags de linha de comando caso existirem:
-
Determinar a informação atual de usuário a ser utilizada. Construir a informação de usuário utilizando as mesmas regras utilizadas para o caso de informações de cluster, exceto para a regra de técnica de autenticação que deverá ser única por usuário:
- Usar as flags, caso existirem:
--client-certificate
,--client-key
,--username
,--password
,--token
. - Usar os campos
user
resultado da combinação de arquivos kubeconfig. - Se existirem duas técnicas conflitantes, falhar.
- Usar as flags, caso existirem:
-
Para qualquer informação que ainda estiver ausente, utilizar os valores padrão e potencialmente solicitar informações de autenticação a partir do prompt de comando.
Referências de arquivos
Arquivos e caminhos referenciados em um arquivo kubeconfig são relativos à localização do arquivo kubeconfig.
Referências de arquivos na linha de comando são relativas ao diretório de trabalho vigente.
No arquivo $HOME/.kube/config
, caminhos relativos são armazenados de forma relativa, e caminhos absolutos são armazenados de forma absoluta.