Montando um Cluster Kubernetes On-Premise — Parte 3: Inicializando o Master

🇺🇸 English version coming soon.

Nas partes anteriores desta série, preparamos o ambiente (Parte 1) e instalamos o containerd, o kubelet e o kubeadm em todos os nós (Parte 2). Chegou o momento de, finalmente, inicializar o cluster: vamos criar o control-plane no servidor master e deixá-lo pronto para receber os workers e uma rede de pods funcional.

Inicializando o cluster com kubeadm

A forma mais simples de inicializar o cluster é rodando o comando abaixo no servidor master:

# kubeadm init

Ou, especificando parâmetros importantes manualmente — como o CIDR da rede de pods, o endereço IP a ser anunciado pelo API server e a versão do Kubernetes:

# kubeadm init --pod-network-cidr=10.244.0.0/16 --apiserver-advertise-address=10.0.10.100 --kubernetes-version="1.31.1"

Usando um arquivo de configuração (recomendado)

Versões mais recentes do kubelet não aceitam mais determinadas opções via linha de comando (esse comportamento foi descontinuado). Por isso, o recomendado atualmente é criar um arquivo de configuração para o kubeadm, em vez de passar tudo por flags.

Crie o arquivo kubelet.yaml:

apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
---
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
kubernetesVersion: "1.31.1" # Substitua pela versão desejada
controlPlaneEndpoint: "k8s-master"
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration

E execute a inicialização apontando para esse arquivo:

$ sudo kubeadm init --config kubelet.yaml

O que esperar da saída

Se tudo correr bem, a saída do comando será parecida com esta (resumida aqui para facilitar a leitura):

[init] Using Kubernetes version: v1.31.1
[preflight] Running pre-flight checks
[preflight] Pulling images required for setting up a Kubernetes cluster
[preflight] This might take a minute or two, depending on the speed of your internet connection
[preflight] You can also perform this action in beforehand using 'kubeadm config images pull'

[kubelet-start] Writing kubelet environment file with flags to file "/var/lib/kubelet/kubeadm-flags.env"
[kubelet-start] Writing kubelet configuration to file "/var/lib/kubelet/config.yaml"
[kubelet-start] Activating the kubelet service
[certs] Using certificateDir folder "/etc/kubernetes/pki"
[certs] Generating "ca" certificate and key
[certs] Generating "apiserver-kubelet-client" certificate and key

...

[bootstraptoken] configured RBAC rules to allow certificate rotation for all node client certificates in the cluster
[bootstraptoken] creating the "cluster-info" ConfigMap in the "kube-public" namespace
[addons] Applied essential addon: CoreDNS
[addons] Applied essential addon: kube-proxy

Your Kubernetes master has initialized successfully!

To start using your cluster, you need to run the following as a regular user:

  mkdir -p $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config

You should now deploy a pod network to the cluster.
Run "kubectl apply -f [podnetwork].yaml" with one of the options listed at:
  https://kubernetes.io/docs/concepts/cluster-administration/addons/

Then you can join any number of worker nodes by running the following on each as root:

kubeadm join 10.0.10.100:6443 --token d1dyaj.31zxywbg93s1ywjy --discovery-token-ca-cert-hash sha256:71a91721595fde66b6382908d801266602a14de8e16bdb7a3cede21509427009

⚠️ Importante: guarde o comando kubeadm join completo (com o token e o hash do certificado) exibido no final da saída. Ele será necessário para adicionar os workers ao cluster.

Configurando o acesso via kubectl

Para conseguir usar o kubectl como usuário comum (sem precisar de sudo toda vez), copie o arquivo de configuração do administrador:

mkdir -p $HOME/.kube
cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
chown $(id -u):$(id -g) $HOME/.kube/config

Para verificar o estado atual do cluster, rode:

kubectl get pods --all-namespaces

Nesse momento, é normal que alguns pods apareçam com status Pending — isso acontece porque ainda não instalamos uma rede de pods (CNI), e é exatamente esse o próximo passo.

Exemplo de saida:

Instalando a rede de pods (CNI)

O Kubernetes não vem com uma solução de rede pronta — é preciso escolher e instalar um plugin de rede (CNI), responsável por permitir a comunicação entre os pods do cluster. Algumas opções populares são Calico, Canal, Flannel e Weave.

Use apenas uma das opções acima — instalar mais de um CNI no mesmo cluster pode causar conflitos de rede.

Exemplo com Calico:

kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.28.2/manifests/calico.yaml

Exemplo com Flannel:

kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/v0.20.2/Documentation/kube-flannel.yml

Exemplo com Weave:

export kubever=$(kubectl version | base64 | tr -d '\n')
kubectl apply -f "https://cloud.weave.works/k8s/net?k8s-version=$kubever"

kubectl apply -f https://github.com/weaveworks/weave/releases/download/v2.8.1/weave-daemonset-k8s.yaml

Depois de aplicar o manifesto escolhido, rode novamente:

kubectl get pods --all-namespaces

E, em alguns instantes, os pods do namespace kube-system — incluindo o CoreDNS — devem passar para o status Running. Isso confirma que a rede de pods está funcionando corretamente.

A saída deve ser igual a essa:

Próximos passos

Com o control-plane inicializado, o kubectl configurado e a rede de pods instalada, o master do cluster já está totalmente operacional. Falta apenas um passo: adicionar os servidores workers/nodes ao cluster usando o comando kubeadm join que guardamos anteriormente.

Na Parte 4 desta série, vamos unir os workers/nodes ao cluster e validar que todos os nós estão prontos para receber cargas de trabalho.

Continua na Parte 4.