kubeadm init

Este comando inicializa um nó da camada de gerenciamento do Kubernetes.

Rode este comando para configurar a camada de gerenciamento do Kubernetes

Sinopse

Rode este comando para configurar a camada de gerenciamento do Kubernetes

O comando "init" executa as fases abaixo:

preflight                    Efetua as verificações pré-execução
certs                        Geração de certificados
  /ca                          Gera a autoridade de certificação (CA) auto-assinada do Kubernetes para provisionamento de identidades para outros componentes do Kubernetes
  /apiserver                   Gera o certificado para o servidor da API do Kubernetes
  /apiserver-kubelet-client    Gera o certificado para o servidor da API se conectar ao Kubelet
  /front-proxy-ca              Gera a autoridade de certificação (CA) auto-assinada para provisionamento de identidades para o front proxy
  /front-proxy-client          Gera o certificado para o cliente do front proxy
  /etcd-ca                     Gera a autoridade de certificação (CA) auto-assinada para provisionamento de identidades para o etcd
  /etcd-server                 Gera o certificado para servir o etcd
  /etcd-peer                   Gera o certificado para comunicação entre nós do etcd
  /etcd-healthcheck-client     Gera o certificado para liveness probes fazerem a verificação de integridade do etcd
  /apiserver-etcd-client       Gera o certificado que o servidor da API utiliza para comunicar-se com o etcd
  /sa                          Gera uma chave privada para assinatura de tokens de conta de serviço, juntamente com sua chave pública
kubeconfig                   Gera todos os arquivos kubeconfig necessários para estabelecer a camada de gerenciamento e o arquivo kubeconfig de administração
  /admin                       Gera um arquivo kubeconfig para o administrador e o próprio kubeadm utilizarem
  /kubelet                     Gera um arquivo kubeconfig para o kubelet utilizar *somente* para fins de inicialização do cluster
  /controller-manager          Gera um arquivo kubeconfig para o gerenciador de controladores utilizar
  /scheduler                   Gera um arquivo kubeconfig para o escalonador do Kubernetes utilizar
kubelet-start                Escreve as configurações do kubelet e (re)inicializa o kubelet
control-plane                Gera todos os manifestos de Pods estáticos necessários para estabelecer a camada de gerenciamento
  /apiserver                   Gera o manifesto do Pod estático do kube-apiserver
  /controller-manager          Gera o manifesto do Pod estático do kube-controller-manager
  /scheduler                   Gera o manifesto do Pod estático do kube-scheduler
etcd                         Gera o manifesto do Pod estático para um etcd local
  /local                       Gera o manifesto do Pod estático para uma instância local e de nó único do etcd
upload-config                Sobe a configuração do kubeadm e do kubelet para um ConfigMap
  /kubeadm                     Sobe a configuração ClusterConfiguration do kubeadm para um ConfigMap
  /kubelet                     Sobe a configuração do kubelet para um ConfigMap
upload-certs                 Sobe os certificados para o kubeadm-certs
mark-control-plane           Marca um nó como parte da camada de gerenciamento
bootstrap-token              Gera tokens de autoinicialização utilizados para associar um nó a um cluster
kubelet-finalize             Atualiza configurações relevantes ao kubelet após a inicialização TLS
  /experimental-cert-rotation  Habilita rotação de certificados do cliente do kubelet
addon                        Instala os addons requeridos para passar nos testes de conformidade
  /coredns                     Instala o addon CoreDNS em um cluster Kubernetes
  /kube-proxy                  Instala o addon kube-proxy em um cluster Kubernetes

kubeadm init [flags]

Opções

Opções herdadas de comandos superiores

Fluxo do comando Init

O comando kubeadm init inicializa um nó da camada de gerenciamento do Kubernetes através da execução dos passos abaixo:

1. Roda uma série de verificações pré-execução para validar o estado do sistema antes de efetuar mudanças. Algumas verificações emitem apenas avisos, outras são consideradas erros e cancelam a execução do kubeadm até que o problema seja corrigido ou que o usuário especifique a opção --ignore-preflight-errors=<lista-de-erros-a-ignorar>.

2. Gera uma autoridade de certificação (CA) auto-assinada para criar identidades para cada um dos componentes do cluster. O usuário pode informar seu próprio certificado CA e/ou chave ao instalar estes arquivos no diretório de certificados configurado através da opção --cert-dir (por padrão, este diretório é /etc/kubernetes/pki). Os certificados do servidor da API terão entradas adicionais para nomes alternativos (subject alternative names, ou SANs) especificados através da opção --apiserver-cert-extra-sans. Estes argumentos serão modificados para caracteres minúsculos quando necessário.

3. Escreve arquivos kubeconfig adicionais no diretório /etc/kubernetes para o kubelet, para o gerenciador de controladores e para o escalonador utilizarem ao conectarem-se ao servidor da API, cada um com sua própria identidade, bem como um arquivo kubeconfig adicional para administração do cluster chamado admin.conf.

4. Gera manifestos de Pods estáticos para o servidor da API, para o gerenciador de controladores e para o escalonador. No caso de uma instância externa do etcd não ter sido providenciada, um manifesto de Pod estático adicional é gerado para o etcd.

   Manifestos de Pods estáticos são escritos no diretório /etc/kubernetes/manifests; o kubelet lê este diretório em busca de manifestos de Pods para criar na inicialização.

   Uma vez que os Pods da camada de gerenciamento estejam criados e rodando, a sequência de execução do comando kubeadm init pode continuar.

5. Aplica labels e taints ao nó da camada de gerenciamento de modo que cargas de trabalho adicionais não sejam escalonadas para executar neste nó.

6. Gera o token que nós adicionais podem utilizar para associarem-se a uma camada de gerenciamento no futuro. Opcionalmente, o usuário pode fornecer um token através da opção --token, conforme descrito na documentação do comando kubeadm token.

7. Prepara todas as configurações necessárias para permitir que nós se associem ao cluster utilizando os mecanismos de Tokens de Inicialização e Inicialização TLS:

   • Escreve um ConfigMap para disponibilizar toda a informação necessária para associar-se a um cluster e para configurar regras de controle de acesso baseada em funções (RBAC).

   • Permite o acesso dos tokens de inicialização à API de assinaturas CSR.

   • Configura a auto-aprovação de novas requisições CSR.

   Para mais informações, consulte kubeadm join.

8. Instala um servidor DNS (CoreDNS) e os componentes adicionais do kube-proxy através do servidor da API. A partir da versão 1.11 do Kubernetes, CoreDNS é o servidor DNS padrão. Mesmo que o servidor DNS seja instalado nessa etapa, o seu Pod não será escalonado até que um CNI seja instalado.

   Aviso: O uso do kube-dns com o kubeadm foi descontinuado na versão v1.18 e removido na versão v1.21 do Kubernetes.

Utilizando fases de inicialização com o kubeadm

O kubeadm permite que você crie um nó da camada de gerenciamento em fases utilizando o comando kubeadm init phase.

Para visualizar a lista ordenada de fases e subfases, você pode rodar o comando kubeadm init --help. A lista estará localizada no topo da ajuda e cada fase tem sua descrição listada juntamente com o comando. Perceba que ao rodar o comando kubeadm init todas as fases e subfases são executadas nesta ordem exata.

Algumas fases possuem flags específicas. Caso você deseje ver uma lista de todas as opções disponíveis, utilize a flag --help. Por exemplo:

sudo kubeadm init phase control-plane controller-manager --help

Você também pode utilizar a flag --help para ver uma lista de subfases de uma fase superior:

sudo kubeadm init phase control-plane --help

kubeadm init também expõe uma flag chamada --skip-phases que pode ser utilizada para pular a execução de certas fases. Esta flag aceita uma lista de nomes de fases. Os nomes de fases aceitos estão descritos na lista ordenada acima.

Um exemplo:

sudo kubeadm init phase control-plane all --config=configfile.yaml
sudo kubeadm init phase etcd local --config=configfile.yaml
# agora você pode modificar os manifestos da camada de gerenciamento e do etcd
sudo kubeadm init --skip-phases=control-plane,etcd --config=configfile.yaml

O que este exemplo faz é escrever os manifestos da camada de gerenciamento e do etcd no diretório /etc/kubernetes/manifests, baseados na configuração descrita no arquivo configfile.yaml. Isto permite que você modifique os arquivos e então pule estas fases utilizando a opção --skip-phases. Ao chamar o último comando, você cria um nó da camada de gerenciamento com os manifestos personalizados.

Como alternativa, você pode também utilizar o campo skipPhases na configuração InitConfiguration.

Utilizando kubeadm init com um arquivo de configuração

É possível configurar o comando kubeadm init com um arquivo de configuração ao invés de argumentos de linha de comando, e algumas funcionalidades mais avançadas podem estar disponíveis apenas como opções do arquivo de configuração. Este arquivo é fornecido utilizando a opção --config e deve conter uma estrutura ClusterConfiguration e, opcionalmente, mais estruturas separadas por ---\n. Combinar a opção --config com outras opções de linha de comando pode não ser permitido em alguns casos.

A configuração padrão pode ser emitida utilizando o comando kubeadm config print.

Se a sua configuração não estiver utilizando a última versão, é 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 página de referência da API.

Utilizando kubeadm init com feature gates

O kubeadm suporta um conjunto de feature gates que são exclusivos do kubeadm e podem ser utilizados somente durante a criação de um cluster com kubeadm init. Estas funcionalidades podem controlar o comportamento do cluster. Os feature gates são removidos assim que uma funcionalidade atinge a disponibilidade geral (general availability, ou GA).

Para informar um feature gate, você pode utilizar a opção --feature-gates do comando kubeadm init, ou pode adicioná-las no campo featureGates quando um arquivo de configuração é utilizado através da opção --config.

A utilização de feature gates dos componentes principais do Kubernetes com o kubeadm não é suportada. Ao invés disso, é possível enviá-los através da personalização de componentes com a API do kubeadm.

Lista dos feature gates:

Descrição dos feature gates:

PublicKeysECDSA

Pode ser utilizado para criar um cluster que utilize certificados ECDSA no lugar do algoritmo RSA padrão. A renovação dos certificados ECDSA existentes também é suportada utilizando o comando kubeadm certs renew, mas você não pode alternar entre os algoritmos RSA e ECDSA dinamicamente ou durante atualizações.

RootlessControlPlane

Quando habilitada esta opção, os componentes da camada de gerenciamento cuja instalação de Pods estáticos é controlada pelo kubeadm, como o kube-apiserver, kube-controller-manager, kube-scheduler e etcd, têm seus contêineres configurados para rodarem como usuários não-root. Se a opção não for habilitada, estes componentes são executados como root. Você pode alterar o valor deste feature gate antes de atualizar seu cluster para uma versão mais recente do Kubernetes.

UnversionedKubeletConfigMap

Esta opção controla o nome do ConfigMap onde o kubeadm armazena os dados de configuração do kubelet. Quando esta opção não for especificada ou estiver especificada com o valor true, o ConfigMap será nomeado kubelet-config. Caso esteja especificada com o valor false, o nome do ConfigMap incluirá as versões maior e menor do Kubernetes instalado (por exemplo, kubelet-config-1.28). O kubeadm garante que as regras de RBAC para leitura e escrita deste ConfigMap serão apropriadas para o valor escolhido. Quando o kubeadm cria este ConfigMap (durante a execução dos comandos kubeadm init ou kubeadm upgrade apply), o kubeadm irá respeitar o valor da opção UnversionedKubeletConfigMap. Quando tal ConfigMap for lido (durante a execução dos comandos kubeadm join, kubeadm reset, kubeadm upgrade...), o kubeadm tentará utilizar o nome do ConfigMap sem a versão primeiro. Se esta operação não for bem-sucedida, então o kubeadm irá utilizar o nome legado (versionado) para este ConfigMap.

Adicionando parâmetros do kube-proxy

Para informações sobre como utilizar parâmetros do kube-proxy na configuração do kubeadm, veja:

• referência do kube-proxy

Para informações sobre como habilitar o modo IPVS com o kubeadm, veja:

• IPVS

Informando opções personalizadas em componentes da camada de gerenciamento

Para informações sobre como passar as opções aos componentes da camada de gerenciamento, veja:

• opções da camada de gerenciamento

Executando o kubeadm sem uma conexão à internet

Para executar o kubeadm sem uma conexão à internet, você precisa baixar as imagens de contêiner requeridas pela camada de gerenciamento.

Você pode listar e baixar as imagens utilizando o subcomando kubeadm config images:

kubeadm config images list
kubeadm config images pull

Você pode passar a opção --config para os comandos acima através de um arquivo de configuração do kubeadm para controlar os campos kubernetesVersion e imageRepository.

Todas as imagens padrão hospedadas em registry.k8s.io que o kubeadm requer suportam múltiplas arquiteturas.

Utilizando imagens personalizadas

Por padrão, o kubeadm baixa imagens hospedadas no repositório de contêineres registry.k8s.io. Se a versão requisitada do Kubernetes é um rótulo de integração contínua (por exemplo, ci/latest), o repositório de contêineres gcr.io/k8s-staging-ci-images é utilizado.

Você pode sobrescrever este comportamento utilizando o kubeadm com um arquivo de configuração. Personalizações permitidas são:

• Fornecer um valor para o campo kubernetesVersion que afeta a versão das imagens.
• Fornecer um repositório de contêineres alternativo através do campo imageRepository para ser utilizado no lugar de registry.k8s.io.
• Fornecer um valor específico para os campos imageRepository e imageTag, correspondendo ao repositório de contêineres e tag a ser utilizada, para as imagens dos componentes etcd ou CoreDNS.

Caminhos de imagens do repositório de contêineres padrão registry.k8s.io podem diferir dos utilizados em repositórios de contêineres personalizados através do campo imageRepository devido a razões de retrocompatibilidade. Por exemplo, uma imagem pode ter um subcaminho em registry.k8s.io/subcaminho/imagem, mas quando utilizado um repositório de contêineres personalizado, o valor padrão será meu.repositoriopersonalizado.io/imagem.

Para garantir que você terá as imagens no seu repositório personalizado em caminhos que o kubeadm consiga consumir, você deve:

• Baixar as imagens dos caminhos padrão registry.k8s.io utilizando o comando kubeadm config images {list|pull}.
• Subir as imagens para os caminhos listados no resultado do comando kubeadm config images list --config=config.yaml, onde config.yaml contém o valor customizado do campo imageRepository, e/ou imageTag para os componentes etcd e CoreDNS.
• Utilizar o mesmo arquivo config.yaml quando executar o comando kubeadm init.

Imagens personalizadas para o sandbox (imagem pause)

Para configurar uma imagem personalizada para o sandbox, você precisará configurar o agente de execução de contêineres para utilizar a imagem. Verifique a documentação para o seu agente de execução de contêineres para mais informações sobre como modificar esta configuração; para alguns agentes de execução de contêiner você também encontrará informações no tópico Agentes de Execução de Contêineres.

Carregando certificados da camada de gerenciamento no cluster

Ao adicionar a opção --upload-certs ao comando kubeadm init você pode subir temporariamente certificados da camada de gerenciamento em um Secret no cluster. Este Secret expira automaticamente após 2 horas. Os certificados são encriptados utilizando uma chave de 32 bytes que pode ser especificada através da opção --certificate-key. A mesma chave pode ser utilizada para baixar certificados quando nós adicionais da camada de gerenciamento estão se associando ao cluster, utilizando as opções --control-plane e --certificate-key ao rodar kubeadm join.

O seguinte comando de fase pode ser usado para subir os certificados novamente após a sua expiração:

kubeadm init phase upload-certs --upload-certs --certificate-key=ALGUM_VALOR --config=ALGUM_ARQUIVO_YAML

Se a opção --certificate-key não for passada aos comandos kubeadm init e kubeadm init phase upload-certs, uma nova chave será gerada automaticamente.

O comando abaixo pode ser utilizado para gerar uma nova chave sob demanda:

kubeadm certs certificate-key

Gerenciamento de certificados com o kubeadm

Para informações detalhadas sobre gerenciamento de certificados com o kubeadm, consulte Gerenciamento de Certificados com o kubeadm. O documento inclui informações sobre a utilização de autoridades de certificação (CA) externas, certificados personalizados e renovação de certificados.

Gerenciando o arquivo drop-in do kubeadm para o kubelet

O pacote kubeadm é distribuído com um arquivo de configuração para rodar o kubelet utilizando systemd. Note que o kubeadm nunca altera este arquivo. Este arquivo drop-in é parte do pacote DEB/RPM do kubeadm.

Para mais informações, consulte Gerenciando o arquivo drop-in do kubeadm para o systemd.

Usando o kubeadm com agentes de execução CRI

Por padrão, o kubeadm tenta detectar seu agente de execução de contêineres. Para mais detalhes sobre esta detecção, consulte o guia de instalação CRI do kubeadm.

Configurando o nome do nó

Por padrão, o kubeadm gera um nome para o nó baseado no endereço da máquina. Você pode sobrescrever esta configuração utilizando a opção --node-name. Esta opção passa o valor apropriado para a opção --hostname-override do kubelet.

Note que sobrescrever o hostname de um nó pode interferir com provedores de nuvem.

Automatizando o kubeadm

Ao invés de copiar o token que você obteve do comando kubeadm init para cada nó, como descrito no tutorial básico do kubeadm, você pode paralelizar a distribuição do token para facilitar a automação. Para implementar esta automação, você precisa saber o endereço IP que o nó da camada de gerenciamento irá ter após a sua inicialização, ou utilizar um nome DNS ou um endereço de um balanceador de carga.

1. Gere um token. Este token deve ter a forma <string de 6 caracteres>.<string de 16 caracteres>. Mais especificamente, o token precisa ser compatível com a expressão regular: [a-z0-9]{6}\.[a-z0-9]{16}.

   O kubeadm pode gerar um token para você:

    kubeadm token generate
   

2. Inicialize o nó da camada de gerenciamento e os nós de carga de trabalho de forma concorrente com este token. Conforme os nós forem iniciando, eles deverão encontrar uns aos outros e formar o cluster. O mesmo argumento --token pode ser utilizado em ambos os comandos kubeadm init e kubeadm join.

3. O mesmo procedimento pode ser feito para a opção --certificate-key quando nós adicionais da camada de gerenciamento associarem-se ao cluster. A chave pode ser gerada utilizando:

   kubeadm certs certificate-key
   

Uma vez que o cluster esteja inicializado, você pode buscar as credenciais para a camada de gerenciamento no caminho /etc/kubernetes/admin.conf e utilizá-las para conectar-se ao cluster.

Note que este tipo de inicialização tem algumas garantias de segurança relaxadas pois ele não permite que o hash do CA raiz seja validado com a opção --discovery-token-ca-cert-hash (pois este hash não é gerado quando os nós são provisionados). Para detalhes, veja a documentação do comando kubeadm join.

Próximos passos

• kubeadm init phase para entender mais sobre as fases do comando kubeadm init
• kubeadm join para inicializar um nó de carga de trabalho do Kubernetes e associá-lo ao cluster
• kubeadm upgrade para atualizar um cluster do Kubernetes para uma versão mais recente
• kubeadm reset para reverter quaisquer mudanças feitas neste host pelos comandos kubeadm init ou kubeadm join