1. Por que k3s?
Kubernetes certificado, binário único, baixo consumo. Ideal para homelab e edge.
- Instalação em segundos
- Traefik e ServiceLB embutidos
- SQLite por padrão (ou etcd)
- Mesmos manifests e Helm charts
2. Instalação
$ # control-plane
curl -sfL https://get.k3s.io | sh -s - \
--write-kubeconfig-mode 644 \
--disable traefik # opcional
$ # workers
# no servidor:
sudo cat /var/lib/rancher/k3s/server/node-token
# em cada worker:
curl -sfL https://get.k3s.io | K3S_URL=https://IP-SERVER:6443 \
K3S_TOKEN=seu-token sh -
3. kubectl
mkdir -p ~/.kube
scp user@server:/etc/rancher/k3s/k3s.yaml ~/.kube/config
# ajuste server: https://IP-REAL:6443
kubectl get nodes
4. Ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: exemplo
annotations:
traefik.ingress.kubernetes.io/router.entrypoints: web
spec:
rules:
- host: app.homelab.local
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: minha-app
port:
number: 80
tip · Use DNS interno (Pi-hole/AdGuard) apontando para o nó de entrada.
5. Longhorn
kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/v1.6.2/deploy/longhorn.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: dados-app
spec:
accessModes: [ReadWriteOnce]
storageClassName: longhorn
resources:
requests:
storage: 10Gi
6. Helm
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install meu-postgres bitnami/postgresql \
--set auth.postgresPassword=senha-forte \
--set primary.persistence.storageClass=longhorn
7. Boas práticas
- Namespaces por app/ambiente
- ResourceQuota e LimitRange
- Monitorar (kube-state-metrics + Prometheus)
- Backup do etcd/SQLite e volumes
- Atualizar k3s periodicamente
8. Comandos e manifestos explicados
Instalação e acesso
| Comando | O que faz |
|---|---|
curl -sfL https://get.k3s.io | sh -s - ... | Baixa o script oficial (-s silencioso, -f falha em erro HTTP, -L segue redirecionamentos) e o executa. O sh -s - repassa os argumentos seguintes ao script. |
--write-kubeconfig-mode 644 | Deixa o kubeconfig legível para qualquer usuário do servidor. Conveniente em homelab, mas evite em ambientes compartilhados. |
--disable traefik | Não instala o Traefik embutido. Se usar, o exemplo de Ingress do artigo, que usa anotações do Traefik, precisa ser trocado pelo do ingress que você escolher. |
sudo cat /var/lib/rancher/k3s/server/node-token | Mostra o token que os workers usam para entrar no cluster. |
K3S_URL=https://IP-SERVER:6443 K3S_TOKEN=... sh - | Instala o k3s como worker, que se junta ao servidor pela porta 6443 da API. |
scp user@server:/etc/rancher/k3s/k3s.yaml ~/.kube/config | Copia o kubeconfig para a sua máquina. Depois, troque 127.0.0.1 pelo IP real do servidor no campo server:. |
kubectl get nodes | Lista os nós. O esperado é o status Ready. |
Ingress, armazenamento e Helm
| Trecho | O que faz |
|---|---|
kind: Ingress com host: app.homelab.local | Regra de entrada: requisições para esse domínio vão ao serviço indicado. |
router.entrypoints: web | Anotação do Traefik que usa a entrada HTTP (porta 80). |
pathType: Prefix e path: / | Vale para todos os caminhos que começam com /. |
backend: service: name: minha-app / port: 80 | Serviço e porta de destino. |
kubectl apply -f <url> | Aplica o manifesto do Longhorn no cluster. |
kind: PersistentVolumeClaim | Pedido de disco para o app. ReadWriteOnce permite uso por um nó de cada vez, storageClassName: longhorn usa o Longhorn, e storage: 10Gi reserva 10 GiB. |
helm repo add e helm install meu-postgres bitnami/postgresql | Cadastra o repositório de charts e instala o PostgreSQL. O --set sobrescreve valores do chart. |
ATENÇÃO Rodar um script baixado com
curl | sh executa código remoto sem revisão. Leia o script antes. E evite --set auth.postgresPassword=... na linha de comando, porque a senha vai para o histórico do terminal; use um arquivo de valores ou um Secret.9. Como conferir se deu certo
| Comando | O que você deve ver |
|---|---|
kubectl get nodes -o wide | todos os nós em Ready, com o IP de cada um |
kubectl get pods -A | pods do sistema em Running ou Completed |
kubectl describe ingress exemplo | o host, o serviço de destino e eventos de erro |
kubectl get pvc | o dados-app em Bound |
10. Erros comuns e como resolver
| Sintoma | Causa provável | Solução |
|---|---|---|
kubectl tenta localhost:8080 e recusa a conexão | Não encontrou o kubeconfig. | Use export KUBECONFIG=~/.kube/config ou copie o arquivo para ~/.kube/config. |
| O kubectl remoto não conecta | O server: do kubeconfig continua 127.0.0.1. | Troque pelo IP real e confira se a porta 6443 está liberada. |
| O Ingress devolve 404 | O host da requisição não bate com o host da regra. | Teste com curl -H "Host: app.homelab.local" http://IP e ajuste o DNS interno. |
O PVC fica em Pending | O Longhorn não está instalado ou o storageClassName está errado. | Veja kubectl get sc e kubectl describe pvc dados-app. |
| O worker não entra no cluster | A porta 6443 está bloqueada ou o token está errado. | Libere a 6443/tcp e confira o token do node-token. |