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
--apiserver-advertise-address string | |
O endereço IP que o servidor da API irá divulgar que está escutando. Quando não informado, a interface de rede padrão é utilizada. | |
--apiserver-bind-port int32 Padrão: 6443 | |
Porta para o servidor da API conectar-se. | |
--apiserver-cert-extra-sans strings | |
Nomes alternativos (Subject Alternative Names, ou SANs) opcionais a serem adicionados ao certificado utilizado pelo servidor da API. Pode conter endereços IP ou nomes DNS. | |
--cert-dir string Padrão: "/etc/kubernetes/pki" | |
O caminho para salvar e armazenar certificados. | |
--certificate-key string | |
Chave utilizada para encriptar os certificados da camada de gerenciamento no Secret kubeadm-certs. | |
--config string | |
Caminho para um arquivo de configuração do kubeadm. | |
--control-plane-endpoint string | |
Especifica um endereço IP estável ou nome DNS para a camada de gerenciamento. | |
--cri-socket string | |
Caminho para o soquete CRI se conectar. 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. | |
--dry-run | |
Não aplica as modificações; apenas imprime as alterações que seriam efetuadas. | |
--feature-gates string | |
Um conjunto de pares chave=valor que descreve feature gates para várias funcionalidades. As opções são: | |
-h, --help | |
ajuda para init | |
--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. | |
--image-repository string Padrão: "registry.k8s.io" | |
Seleciona um registro de contêineres de onde baixar imagens. | |
--kubernetes-version string Padrão: "stable-1" | |
Seleciona uma versão do Kubernetes específica para a camada de gerenciamento. | |
--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. | |
--pod-network-cidr string | |
Especifica um intervalo de endereços IP para a rede do Pod. Quando especificado, a camada de gerenciamento irá automaticamente alocar CIDRs para cada nó. | |
--service-cidr string Padrão: "10.96.0.0/12" | |
Utiliza um intervalo alternativo de endereços IP para VIPs de serviço. | |
--service-dns-domain string Padrão: "cluster.local" | |
Utiliza um domínio alternativo para os serviços. Por exemplo, "myorg.internal". | |
--skip-certificate-key-print | |
Não exibe a chave utilizada para encriptar os certificados da camada de gerenciamento. | |
--skip-phases strings | |
Lista de fases a serem ignoradas. | |
--skip-token-print | |
Pula a impressão do token de autoinicialização padrão gerado pelo comando 'kubeadm init'. | |
--token string | |
O token a ser utilizado para estabelecer confiança bidirecional entre nós de carga de trabalho e nós da camada de gerenciamento. O formato segue a expressão regular [a-z0-9]{6}.[a-z0-9]{16} - por exemplo, abcdef.0123456789abcdef. | |
--token-ttl duration Padrão: 24h0m0s | |
A duração de tempo de um token antes deste ser automaticamente apagado (por exemplo, 1s, 2m, 3h). Quando informado '0', o token não expira. | |
--upload-certs | |
Sobe os certificados da camada de gerenciamento para o Secret kubeadm-certs. |
Opções herdadas de comandos superiores
--rootfs string | |
[EXPERIMENTAL] O caminho para o sistema de arquivos raiz 'real' do host. |
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:
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>
.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.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 chamadoadmin.conf
.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.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ó.
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.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.
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.
Kubernetes v1.22 [beta]
Como alternativa, você pode também utilizar o campo skipPhases
na configuração
InitConfiguration
.
Utilizando kubeadm init com um arquivo de configuração
Cuidado:
O arquivo de configuração ainda é considerado uma funcionalidade de estado beta e pode mudar em versões futuras.É 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:
Feature gate | Valor-padrão | Versão Alfa | Versão Beta |
---|---|---|---|
PublicKeysECDSA | false | 1.19 | - |
RootlessControlPlane | false | 1.22 | - |
UnversionedKubeletConfigMap | true | 1.22 | 1.23 |
Nota:
Assim que um feature gate atinge a disponibilidade geral, ele é removido desta lista e o seu valor fica bloqueado emtrue
por padrão. Ou seja, a funcionalidade
estará sempre ativa.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
eetcd
, 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á nomeadokubelet-config
. Caso esteja especificada com o valorfalse
, o nome do ConfigMap incluirá as versões maior e menor do Kubernetes instalado (por exemplo,kubelet-config-1.32
). 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 comandoskubeadm init
oukubeadm upgrade apply
), o kubeadm irá respeitar o valor da opçãoUnversionedKubeletConfigMap
. Quando tal ConfigMap for lido (durante a execução dos comandoskubeadm 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.
Nota:
Informar a opçãoUnversionedKubeletConfigMap
com o valor false
é suportado,
mas está descontinuado.Adicionando parâmetros do kube-proxy
Para informações sobre como utilizar parâmetros do kube-proxy na configuração do kubeadm, veja:
Para informações sobre como habilitar o modo IPVS com o kubeadm, veja:
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:
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 deregistry.k8s.io
. - Fornecer um valor específico para os campos
imageRepository
eimageTag
, 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 comandokubeadm config images {list|pull}
. - Subir as imagens para os caminhos listados no resultado do comando
kubeadm config images list --config=config.yaml
, ondeconfig.yaml
contém o valor customizado do campoimageRepository
, e/ouimageTag
para os componentes etcd e CoreDNS. - Utilizar o mesmo arquivo
config.yaml
quando executar o comandokubeadm 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.
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
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 comandoskubeadm init
ekubeadm join
.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
oukubeadm join