Este documento pode estar desatualizado
Este documento possui uma data de atualização mais antiga que o documento original. Portanto, este conteúdo pode estar desatualizado. Se você lê inglês, veja a versão em inglês para acessar a versão mais atualizada: kubeadm join
kubeadm join
Este comando inicializa um nó de processamento do Kubernetes e o associa ao cluster.
Rode este comando em qualquer máquina que você deseje adicionar a um cluster existente
Sinopse
Ao associar um novo nó a um cluster inicializado com kubeadm, temos que estabelecer a confiança bidirecional. Este processo é dividido entre a descoberta (em que o nó estabelece a confiança na camada de gerenciamento do Kubernetes) e a inicialização TLS (em que a camada de gerenciamento do Kubernetes estabelece a confiança no nó).
Existem duas principais formas de descoberta. A primeira delas é o uso de um
token compartilhado, juntamente com o endereço IP do servidor da API. A segunda
é o fornecimento de um arquivo - um subconjunto do arquivo kubeconfig padrão. O
arquivo de descoberta/kubeconfig suporta autenticação por token, plugins de
autenticação do client-go ("exec"), "tokenFile" e "authProvider". Este arquivo
pode ser um arquivo local ou um arquivo baixado através de uma URL HTTPS. Os
formatos são kubeadm join --discovery-token abcdef.1234567890abcdef 1.2.3.4:6443
,
kubeadm join --discovery-file caminho/para/arquivo.conf
, ou
kubeadm join --discovery-file https://endereco/arquivo.conf
. Somente um formato
pode ser utilizado. Se os dados para a descoberta são carregados de uma URL,
o protocolo HTTPS deve ser utilizado. Neste caso, o conjunto de CAs instalado no
host é utilizado para verificar a conexão.
Se você utilizou um token compartilhado para descoberta, você deve também passar
a opção --discovery-token-ca-cert-hash
para validar a chave pública da
autoridade de certificação raiz (CA) apresentada pela camada de gerenciamento do
Kubernetes. O valor desta opção é especificado no formato
"<tipo-de-hash>:<valor-codificado-em-hexadecimal>", onde o tipo de
hash suportado é "sha256". O hash é calculado a partir dos bytes do objeto
Subject Public Key Info (SPKI), como especificado pela RFC7469. Este valor fica
disponível na saída do comando kubeadm init
ou pode ser calculado utilizando
ferramentas padronizadas. A opção --discovery-token-ca-cert-hash
pode ser
especificada múltiplas vezes para permitir informar mais que uma chave pública.
Se você não puder obter o hash da chave pública da autoridade de certificação
de antemão, você pode passar a opção --discovery-token-unsafe-skip-ca-verification
para desabilitar esta verificação. Esta opção enfraquece o modelo de segurança
do kubeadm, já que outros nós podem potencialmente personificar a camada de
gerenciamento do Kubernetes.
O mecanismo de inicialização TLS também é conduzido por um token compartilhado.
Este token é utilizado para temporariamente autenticar-se com a camada de
gerenciamento do Kubernetes para enviar uma requisição de assinatura de
certificado (CSR) para um par de chaves criado localmente. Por padrão, o kubeadm
irá configurar a camada de gerenciamento do Kubernetes para automaticamente
aprovar estas requisições de assinatura. O token é enviado através da opção
--tls-bootstrap-token abcdef.1234567890abcdef
.
Frequentemente, o mesmo token é utilizado para ambas as partes. Neste caso, a
opção --token
pode ser utilizada ao invés de especificar cada token
individualmente.
O comando join [api-server-endpoint]
executa as seguintes fases:
preflight Executa as verificações pré-execução
control-plane-prepare Prepara a máquina para servir um nó da camada de gerenciamento
/download-certs [EXPERIMENTAL] Baixa certificados compartilhados entre nós da camada de gerenciamento do Secret kubeadm-certs
/certs Gera os certificados para os novos componentes da camada de gerenciamento
/kubeconfig Gera o arquivo kubeconfig para os novos componentes da camada de gerenciamento
/control-plane Gera os manifestos para os novos componentes da camada de gerenciamento
kubelet-start Escreve as configurações do kubelet, os certificados, e (re)inicia o kubelet
control-plane-join Associa uma máquina como uma instância da camada de gerenciamento
/etcd Adiciona como um novo membro do etcd local
/update-status Registra o novo nó da camada de gerenciamento no objeto ClusterStatus mantido no ConfigMap kubeadm-config (DESCONTINUADO)
/mark-control-plane Marca um nó como nó da camada de gerenciamento
kubeadm join [api-server-endpoint] [flags]
Opções
--apiserver-advertise-address string | |
Se o nó hospedar uma nova instância da camada de gerenciamento, este é o endereço IP que servidor da API irá anunciar que está aguardando conexões. Quando não especificado, a interface de rede padrão é utilizada. |
|
--apiserver-bind-port int32 Default: 6443 | |
Se o nó hospedar uma nova instância da camada de gerenciamento, a porta que o servidor da API deve conectar-se. |
|
--certificate-key string | |
Chave utilizada para decriptar as credenciais do certificado enviadas pelo comando init. |
|
--config string | |
Caminho para um arquivo de configuração do kubeadm. |
|
--control-plane | |
Cria uma nova instância da camada de gerenciamento neste nó. |
|
--cri-socket string | |
Caminho para o soquete CRI conectar-se. Se vazio, o kubeadm tentará autodetectar este valor; utilize esta opção somente se você possui mais que um CRI instalado ou se você possui um soquete CRI fora do padrão. |
|
--discovery-file string | |
Para descoberta baseada em arquivo, um caminho de arquivo ou uma URL de onde a informação do cluster deve ser carregada. |
|
--discovery-token string | |
Para descoberta baseada em token, o token utilizado para validar a informação do cluster obtida do servidor da API. |
|
--discovery-token-ca-cert-hash strings | |
Para descoberta baseada em token, verifica que a chave pública do CA raiz corresponde a este hash (formato: "<tipo>:<valor>"). |
|
--discovery-token-unsafe-skip-ca-verification | |
Para descoberta baseada em token, permite associar-se ao cluster sem fixação da autoridade de certificação (opção --discovery-token-ca-cert-hash). |
|
--dry-run | |
Não aplica as modificações; apenas imprime as alterações que seriam efetuadas. |
|
-h, --help | |
ajuda para join |
|
--ignore-preflight-errors strings | |
Uma lista de verificações para as quais erros serão exibidos como avisos. Exemplos: 'IsPrivilegedUser,Swap'. O valor 'all' ignora erros de todas as verificações. |
|
--node-name string | |
Especifica o nome do nó. |
|
--patches string | |
Caminho para um diretório contendo arquivos nomeados no padrão "target[suffix][+patchtype].extension". Por exemplo, "kube-apiserver0+merge.yaml" ou somente "etcd.json". "target" pode ser um dos seguintes valores: "kube-apiserver", "kube-controller-manager", "kube-scheduler", "etcd". "patchtype" pode ser "strategic", "merge" ou "json" e corresponde aos formatos de patch suportados pelo kubectl. O valor padrão para "patchtype" é "strategic". "extension" deve ser "json" ou "yaml". "suffix" é uma string opcional utilizada para determinar quais patches são aplicados primeiro em ordem alfanumérica. |
|
--skip-phases strings | |
Lista de fases a serem ignoradas. |
|
--tls-bootstrap-token string | |
Especifica o token a ser utilizado para autenticar temporariamente com a camada de gerenciamento do Kubernetes durante o processo de associação do nó ao cluster. |
|
--token string | |
Utiliza este token em ambas as opções discovery-token e tls-bootstrap-token quando tais valores não são informados. |
Opções herdadas dos comandos superiores
--rootfs string | |
[EXPERIMENTAL] O caminho para o sistema de arquivos raiz 'real' do host. |
Fluxo do comando join
O comando kubeadm join
inicializa um nó de processamento ou um nó da camada
de gerenciamento e o adiciona ao cluster. Esta ação consiste nos seguintes passos
para nós de processamento:
-
O kubeadm baixa as informações necessárias do cluster através servidor da API. Por padrão, o token de autoinicialização e o hash da chave da autoridade de certificação (CA) são utilizados para verificar a autenticidade dos dados baixados. O certificado raiz também pode ser descoberto diretamente através de um arquivo ou URL.
-
Uma vez que as informações do cluster são conhecidas, o kubelet pode começar o processo de inicialização TLS.
A inicialização TLS utiliza o token compartilhado para autenticar temporariamente com o servidor da API do Kubernetes a fim de submeter uma requisição de assinatura de certificado (certificate signing request, ou CSR); por padrão, a camada de gerenciamento assina essa requisição CSR automaticamente.
-
Por fim, o kubeadm configura o kubelet local para conectar no servidor da API com a identidade definitiva atribuída ao nó.
Para nós da camada de gerenciamento, passos adicionais são executados:
-
O download de certificados compartilhados por todos os nós da camada de gerenciamento (quando explicitamente solicitado pelo usuário).
-
Geração de manifestos, certificados e arquivo kubeconfig para os componentes da camada de gerenciamento.
-
Adição de um novo membro local do etcd.
Utilizando fases de associação com o kubeadm
O kubeadm permite que você associe um nó a um cluster em fases utilizando
kubeadm join phase
.
Para visualizar a lista ordenada de fases e subfases disponíveis, você pode
executar o comando kubeadm join --help
. A lista estará localizada no topo da
tela da ajuda e cada fase terá uma descrição ao lado. Note que ao chamar
kubeadm join
todas as fases e subfases serão executadas nesta ordem exata.
Algumas fases possuem opções únicas, portanto, se você desejar ver uma lista das
opções disponíveis, adicione a flag --help
. Por exemplo:
kubeadm join phase kubelet-start --help
De forma semelhante ao comando
kubeadm init phase
,
kubeadm join phase
permite que você ignore uma lista de fases utilizando a
opção --skip-phases
.
Por exemplo:
sudo kubeadm join --skip-phases=preflight --config=config.yaml
Kubernetes v1.22 [beta]
Alternativamente, você pode utilizar o campo skipPhases
no manifesto
JoinConfiguration
.
Descobrindo em qual autoridade de certificação (CA) do cluster confiar
A descoberta do kubeadm tem diversas opções, cada uma com suas próprias contrapartidas de segurança. O método correto para o seu ambiente depende de como você aprovisiona seus nós e as expectativas de segurança que você tem a respeito da rede e ciclo de vida dos seus nós.
Descoberta baseada em token com fixação da autoridade de certificação (CA)
Este é o modo padrão do kubeadm. Neste modo, o kubeadm baixa a configuração do cluster (incluindo a CA raiz) e a valida, utilizando o token, além de verificar que a chave pública da CA raiz corresponda ao hash fornecido e que o certificado do servidor da API seja válido sob a CA raiz.
O hash da chave pública da CA tem o formato sha256:<hash_codificado_em_hexa>
.
Por padrão, o valor do hash é retornado no comando kubeadm join
impresso ao
final da execução de kubeadm init
ou na saída do comando
kubeadm token create --print-join-command
. Este hash é gerado em um formato
padronizado (veja a RFC7469)
e pode também ser calculado com ferramentas de terceiros ou sistemas de
provisionamento. Por exemplo, caso deseje utilizar a ferramenta de linha de
comando do OpenSSL:
openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | openssl rsa -pubin -outform der 2>/dev/null | openssl dgst -sha256 -hex | sed 's/^.* //'
Exemplos de comandos kubeadm join
:
Para nós de processamento:
kubeadm join --discovery-token abcdef.1234567890abcdef --discovery-token-ca-cert-hash sha256:1234..cdef 1.2.3.4:6443
Para nós da camada de gerenciamento:
kubeadm join --discovery-token abcdef.1234567890abcdef --discovery-token-ca-cert-hash sha256:1234..cdef --control-plane 1.2.3.4:6443
Você também pode executar o comando join
para um nó da camada de gerenciamento
com a opção --certificate-key
para copiar certificados para este nó, caso o
comando kubeadm init
tenha sido executado com a opção --upload-certs
.
Vantagens:
-
Permite à inicialização dos nós descobrir uma raiz de confiança para a camada de gerenciamento mesmo que outros nós de processamento ou a rede estejam comprometidos.
-
É conveniente para ser executado manualmente pois toda a informação requerida cabe num único comando
kubeadm join
.
Desvantagens:
- O hash da autoridade de certificação normalmente não está disponível até que a camada de gerenciamento seja aprovisionada, o que pode tornar mais difícil a criação de ferramentas de aprovisionamento automatizadas que utilizem o kubeadm. Uma alternativa para evitar esta limitação é gerar sua autoridade de certificação de antemão.
Descoberta baseada em token sem fixação da autoridade de certificação (CA)
Este modo depende apenas do token simétrico para assinar (HMAC-SHA256) a
informação de descoberta que estabelece a raiz de confiança para a camada de
gerenciamento. Para utilizar este modo, os nós que estão se associando ao cluster
devem ignorar a validação do hash da chave pública da autoridade de
certificação, utilizando a opção --discovery-token-unsafe-skip-ca-verification
.
Você deve considerar o uso de um dos outros modos quando possível.
Exemplo de comando kubeadm join
:
kubeadm join --token abcdef.1234567890abcdef --discovery-token-unsafe-skip-ca-verification 1.2.3.4:6443
Vantagens:
-
Ainda protege de muitos ataques a nível de rede.
-
O token pode ser gerado de antemão e compartilhado com os nós da camada de gerenciamento e de processamento, que por sua vez podem inicializar-se em paralelo, sem coordenação. Isto permite que este modo seja utilizado em muitos cenários de aprovisionamento.
Desvantagens:
- Se um mau ator conseguir roubar um token de inicialização através de algum tipo de vulnerabilidade, este mau ator conseguirá utilizar o token (juntamente com accesso a nível de rede) para personificar um nó da camada de gerenciamento perante os outros nós de processamento. Esta contrapartida pode ou não ser aceitável no seu ambiente.
Descoberta baseada em arquivos ou HTTPS
Este modo fornece uma maneira alternativa de estabelecer uma raiz de confiança entre os nós da camada de gerenciamento e os nós de processamento. Considere utilizar este modo se você estiver construindo uma infraestrutura de aprovisionamento automático utilizando o kubeadm. O formato do arquivo de descoberta é um arquivo kubeconfig comum do Kubernetes.
Caso o arquivo de descoberta não contenha credenciais, o token de descoberta TLS será utilizado.
Exemplos de comandos kubeadm join
:
-
kubeadm join --discovery-file caminho/para/arquivo.conf
(arquivo local) -
kubeadm join --discovery-file https://endereco/arquivo.conf
(URL HTTPS remota)
Vantagens:
- Permite à inicialização dos nós descobrir uma raiz de confiança de forma segura para que a camada de gerenciamento utilize mesmo que a rede ou outros nós de processamento estejam comprometidos.
Desvantagens:
- Requer que você tenha uma forma de carregar a informação do nó da camada de gerenciamento para outros nós em inicialização. Se o arquivo de descoberta contém credenciais, você precisa mantê-lo secreto e transferi-lo através de um canal de comunicação seguro. Isto pode ser possível através do seu provedor de nuvem ou ferramenta de aprovisionamento.
Tornando sua instalação ainda mais segura
Os valores padrão de instalação do kubeadm podem não funcionar para todos os casos de uso. Esta seção documenta como tornar uma instalação mais segura, ao custo de usabilidade.
Desligando a auto-aprovação de certificados de cliente para nós
Por padrão, um auto-aprovador de requisições CSR está habilitado. Este auto-aprovador irá aprovar quaisquer requisições de certificado de cliente para um kubelet quando um token de autoinicialização for utilizado para autenticação. Se você não deseja que o cluster aprove automaticamente certificados de cliente para os kubelets, você pode desligar a auto-aprovação com o seguinte comando:
kubectl delete clusterrolebinding kubeadm:node-autoapprove-bootstrap
Após o desligamento da auto-aprovação, o comando kubeadm join
irá aguardar até
que o administrador do cluster aprove a requisição CSR:
-
Utilizando o comando
kubeadm get csr
, você verá que o CSR original está em estado pendente.kubectl get csr
A saída é semelhante a:
NAME AGE REQUESTOR CONDITION node-csr-c69HXe7aYcqkS1bKmH4faEnHAWxn6i2bHZ2mD04jZyQ 18s system:bootstrap:878f07 Pending
-
O comando
kubectl certificate approve
permite ao administrador aprovar o CSR. Esta ação informa ao controlador de assinatura de certificados que este deve emitir um certificado para o requerente com os atributos requeridos no CSR.kubectl certificate approve node-csr-c69HXe7aYcqkS1bKmH4faEnHAWxn6i2bHZ2mD04jZyQ
A saída é semelhante a:
certificatesigningrequest "node-csr-c69HXe7aYcqkS1bKmH4faEnHAWxn6i2bHZ2mD04jZyQ" approved
-
Este comando muda o estado do objeto CSR para o estado ativo.
kubectl get csr
A saída é semelhante a:
NAME AGE REQUESTOR CONDITION node-csr-c69HXe7aYcqkS1bKmH4faEnHAWxn6i2bHZ2mD04jZyQ 1m system:bootstrap:878f07 Approved,Issued
Esta mudança força com que o fluxo do comando kubeadm join
seja bem-sucedido
somente quando o comando kubectl certificate approve
for executado.
Desligando o acesso público ao ConfigMap cluster-info
Para que o fluxo de associação de um nó ao cluster seja possível utilizando
somente um token como a única informação necessária para validação, um ConfigMap
com alguns dados necessários para validação da identidade do nó da camada de
gerenciamento é exposto publicamente por padrão. Embora nenhum dado deste
ConfigMap seja privado, alguns usuários ainda podem preferir bloquear este
acesso. Mudar este acesso bloqueia a habilidade de utilizar a opção
--discovery-token
do fluxo do comando kubeadm join
. Para desabilitar este
acesso:
- Obtenha o arquivo
cluster-info
do servidor da API:
kubectl -n kube-public get cm cluster-info -o jsonpath='{.data.kubeconfig}' | tee cluster-info.yaml
A saída é semelhante a:
apiVersion: v1
kind: Config
clusters:
- cluster:
certificate-authority-data: <ca-cert>
server: https://<ip>:<port>
name: ""
contexts: []
current-context: ""
preferences: {}
users: []
-
Utilize o arquivo
cluster-info.yaml
como um argumento para o comandokubeadm join --discovery-file
. -
Desligue o acesso público ao ConfigMap
cluster-info
:
kubectl -n kube-public delete rolebinding kubeadm:bootstrap-signer-clusterinfo
Estes comandos devem ser executados após kubeadm init
, mas antes de
kubeadm join
.
Utilizando kubeadm join
com um arquivo de configuração
Cuidado:
O arquivo de configuração ainda é considerado beta e pode mudar em versões futuras.É possível configurar o comando kubeadm join
apenas com um arquivo de
configuração, em vez de utilizar opções de linha de comando, e algumas
funcionalidades avançadas podem estar disponíveis somente como opções no arquivo
de configuração. Este arquivo é passado através da opção --config
e deve conter
uma estrutura JoinConfiguration
. A utilização da opção --config
com outras
opções da linha de comando pode não ser permitida em alguns casos.
A configuração padrão pode ser emitida utilizando o comando kubeadm config print.
Caso sua configuração não esteja utilizando a versão mais recente, é recomendado que você migre utilizando o comando kubeadm config migrate.
Para mais informações sobre os campos e utilização da configuração você pode consultar a referência da API.
Próximos passos
- kubeadm init para inicializar um nó da camada de gerenciamento do Kubernetes.
- kubeadm token para
gerenciar tokens utilizados no comando
kubeadm join
. - kubeadm reset para
reverter quaisquer mudanças feitas nesta máquina pelos comandos
kubeadm init
oukubeadm join
.