Como instalar Kubernetes no Ubuntu com K3s

Quer instalar Kubernetes no Ubuntu sem configurar um cluster complexo do zero? O K3s é uma distribuição leve do Kubernetes que simplifica o processo, tornando-se uma opção prática para desenvolvedores que estão aprendendo Kubernetes em um VPS.

Neste guia, você aprenderá a instalar Kubernetes no Ubuntu 24.04 usando K3s, criar um cluster de nó único, implantar uma aplicação Nginx e verificar se tudo funciona.

Você não precisará instalar o Docker nem configurar um runtime de contêiner separado.

O que é K3s e por que usá-lo?

O K3s é uma distribuição leve e certificada pela CNCF, projetada para reduzir a complexidade da instalação e operação do Kubernetes.

Ele reúne componentes essenciais, incluindo um runtime de contêiner e a rede do cluster, em uma instalação simplificada.

Diferentemente de uma instalação tradicional do Kubernetes com kubeadm, o K3s cuida automaticamente de grande parte da configuração inicial.

Uma instalação do K3s em um único nó é um cluster Kubernetes funcional, adequado para desenvolvimento, testes e aprendizado.

Se você não conhece conceitos do Kubernetes como Pods e Deployments, leia primeiro nosso guia O que é Kubernetes?.

Pré-requisitos

Antes de começar, você precisará de:

• Um servidor com Ubuntu 24.04 LTS.
• Acesso SSH com privilégios sudo.
• Pelo menos 2 núcleos de CPU e 2 GB de RAM.
• De preferência, 4 GB de RAM ou mais para um ambiente de aprendizado confortável.
• Espaço suficiente em armazenamento SSD e acesso à internet para baixar imagens de contêiner.

O K3s indica oficialmente 2 núcleos de CPU e 2 GB de RAM como requisitos mínimos para um nó de servidor. As necessidades reais das cargas de trabalho podem ser maiores.

Nota de segurança: Mantenha o acesso SSH disponível e restrinja o acesso à API do Kubernetes na porta 6443. Você não precisa abrir essa porta publicamente para este tutorial. Se estiver usando UFW ou outro firewall, consulte os requisitos oficiais de rede do K3s antes da instalação.

Etapa 1: atualize seu servidor Ubuntu

Conecte-se ao seu servidor Ubuntu por SSH e atualize as informações dos pacotes:

sudo apt update
sudo apt upgrade -y

Verifique a versão do Ubuntu:

lsb_release -a

Você deverá ver Ubuntu 24.04 LTS.

Reinicie o servidor se as atualizações do sistema exigirem isso e, em seguida, reconecte-se por SSH.

O K3s instalará seu próprio runtime de contêiner, portanto, o Docker Engine não é necessário.

Etapa 2: instale Kubernetes no Ubuntu usando K3s

O K3s fornece um script oficial de instalação.

O comando padrão de instalação é:

curl -sfL https://get.k3s.io | sh -

Esse comando baixa e executa o instalador do K3s. Consulte as instruções oficiais de instalação e examine o instalador antes de executá-lo, especialmente em um servidor de produção.

A instalação configura o K3s como um serviço systemd e instala utilitários de gerenciamento do Kubernetes.

Quando o processo terminar, verifique o serviço:

sudo systemctl status k3s

Procure por:

Active: active (running)

Pressione q para sair da exibição de status.

Se o serviço estiver em execução, sua instalação do Kubernetes foi iniciada com sucesso.

Etapa 3: verifique seu cluster Kubernetes

O K3s inclui sua própria ferramenta de linha de comando kubectl para gerenciar recursos do Kubernetes.

Execute:

sudo k3s kubectl get nodes

Após a inicialização do cluster, você verá uma saída semelhante a esta:

NAME        STATUS   ROLES                  AGE   VERSION
ubuntu-vps  Ready    control-plane,master   2m    v1.xx.x+k3s1

Seu nome de host e a versão do Kubernetes serão diferentes.

O valor importante é Ready, que indica que o Kubernetes considera o nó disponível para cargas de trabalho.

Em seguida, verifique os Pods do sistema:

sudo k3s kubectl get pods -A

Isso lista os Pods de todos os namespaces, incluindo os serviços do sistema Kubernetes.

Alguns componentes podem levar um pouco de tempo para inicializar. Verifique novamente se ainda estiverem iniciando.

Agora que você usou o K3s para instalar Kubernetes no Ubuntu, seu cluster está pronto para executar aplicações em contêineres. Vamos implantar o Nginx para confirmar que tudo funciona.

Etapa 4: implante sua primeira aplicação

Agora que o cluster está em execução, vamos implantar um servidor web Nginx simples.

Crie um Deployment:

sudo k3s kubectl create deployment demo-nginx --image=nginx:stable

O Kubernetes cria um Deployment que gerencia um contêiner Nginx.

Verifique o progresso:

sudo k3s kubectl get deployments

Aguarde até que o Deployment mostre uma réplica disponível.

Você também pode inspecionar o Pod:

sudo k3s kubectl get pods

O Pod deverá, após algum tempo, exibir o status Running, com o contêiner pronto.

Se você vir ContainerCreating, a imagem do contêiner ainda pode estar sendo baixada.

Etapa 5: crie um Service do Kubernetes

Um Service do Kubernetes fornece um ponto de acesso de rede estável a uma aplicação, mesmo que seus Pods sejam substituídos.

Disponibilize o Deployment do Nginx internamente:

sudo k3s kubectl expose deployment demo-nginx --type=ClusterIP --port=80

Verifique o Service:

sudo k3s kubectl get services

Você deverá ver um Service chamado demo-nginx, com um endereço ClusterIP e a porta 80.

O tipo ClusterIP torna a aplicação acessível dentro do cluster Kubernetes. Ele não expõe o Nginx diretamente à internet pública.

Etapa 6: teste sua aplicação Nginx

Usaremos o encaminhamento de portas do Kubernetes para testar a aplicação sem configurar um balanceador de carga público.

Execute:

sudo k3s kubectl port-forward service/demo-nginx 8080:80

Mantenha esta sessão SSH aberta.

O comando encaminha a porta 8080 da interface de loopback do servidor para a porta 80 do Service do Nginx.

Abra uma segunda conexão SSH com o mesmo servidor e execute:

curl http://127.0.0.1:8080

Você deverá receber um HTML contendo a página de boas-vindas padrão do Nginx.

Sucesso! Você instalou Kubernetes no Ubuntu usando K3s, implantou uma aplicação em contêiner e acessou-a por meio de um Service do Kubernetes.

Pressione Ctrl+C na primeira sessão para interromper o encaminhamento de portas.

Esse teste verifica apenas o acesso local. A publicação de uma aplicação na internet exige configurações adicionais de rede, DNS, TLS e segurança.

Problemas comuns na instalação do K3s

O serviço K3s não inicia

Verifique os logs do serviço:

sudo journalctl -u k3s -n 50

Procure problemas de permissão, problemas de rede ou falhas em componentes.

O nó do Kubernetes mostra NotReady

Verifique os detalhes do nó:

sudo k3s kubectl describe node

Investigue as condições relatadas, o uso dos recursos do sistema e a rede.

O Pod do Nginx não está em execução

Inspecione o Pod:

sudo k3s kubectl get pods

Em seguida, examine os eventos do Deployment:

sudo k3s kubectl describe deployment demo-nginx

Falhas no download de imagens, recursos insuficientes ou problemas na rede do cluster podem impedir a inicialização dos Pods.

O encaminhamento de portas não funciona

Confirme que o Pod do Nginx está pronto e que o Service existe.

Lembre-se de que o comando de encaminhamento de portas deve continuar em execução enquanto você testa a aplicação pela segunda sessão SSH.

É preciso ter Docker para executar o K3s?

Não. O K3s inclui o containerd, um runtime de contêiner usado para executar cargas de trabalho do Kubernetes.

Você pode implantar imagens de contêiner compatíveis, incluindo imagens criadas com Docker, sem instalar o Docker Engine no servidor K3s.

Quais são os próximos passos?

Seu cluster de nó único é adequado para experimentar conceitos do Kubernetes, mas não é automaticamente um ambiente de alta disponibilidade pronto para produção.

Antes de implantar aplicações essenciais para o negócio, planeje:

• Controle de acesso ao cluster e atualizações de segurança.
• Armazenamento persistente e procedimentos de backup.
• Monitoramento e limites de recursos.
• Exposição segura da aplicação com HTTPS.
• Recuperação após falhas no nó ou no servidor.

Lembre-se de que um cluster de nó único ainda depende de uma única máquina física ou virtual. O Kubernetes não pode eliminar esse ponto único de falha.

Perguntas frequentes

Conclusão

Agora você sabe como instalar Kubernetes no Ubuntu usando K3s, verificar seu cluster de nó único e implantar uma aplicação Nginx.

Com o K3s, você criou um ambiente Kubernetes de nó único funcional, implantou o Nginx, disponibilizou-o por meio de um Service e verificou a aplicação usando o encaminhamento de portas.

Agora você pode explorar Deployments, escalonamento, configuração e gerenciamento de clusters à medida que ganha experiência.