depaula/workshop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(aula-12): simplificar para helm install direto

Browse Source 
Remove indireção GitOps (factory/monitoring repo) que adicionava
complexidade sem valor pedagógico. O foco da aula é observabilidade,
não pipeline de deploy.

Antes: setup.sh → cria repo → push manifests → ArgoCD app → sync → instala
Agora: setup.sh → helm install → pronto

README reescrito com foco em "o que monitorar" (PVC cheio, CrashLoop,
CPU saturada) em vez de "como instalar via GitOps".
This commit is contained in:
ArgoCD Setup
2026-03-14 02:11:10 -03:00
parent e8c793058c
commit 61866c1920
3 changed files with 276 additions and 879 deletions
Download Patch File Download Diff File Expand all files Collapse all files

541
aula-12/README.md
View File

@@ -1,209 +1,166 @@
# Aula 12 - Victoria Metrics (Observabilidade)
# Aula 12 - Observabilidade (Victoria Metrics + Grafana)
Stack completo de monitoramento com Victoria Metrics, Grafana e alertas, instalado via **GitOps com ArgoCD**.
Instale monitoramento no cluster e aprenda a **ver o que está acontecendo** — CPU, memória, disco, pods crashando, PVCs enchendo.
## Por que Victoria Metrics?
## Por que esta aula existe
### Alternativa ao Prometheus
Nas aulas anteriores construímos um cluster completo: Kubernetes, Gitea, ArgoCD, auto-scaling. Mas se um pod estiver em CrashLoop, um PVC estiver 95% cheio, ou um node estiver com CPU saturada — **como você sabe?**
Victoria Metrics oferece **compatibilidade total** com Prometheus, mas com vantagens:
Sem observabilidade, você descobre problemas quando o **usuário reclama**. Com observabilidade, você descobre **antes do usuário**.
| Feature | Prometheus | Victoria Metrics |
|---------|------------|------------------|
| Consumo de RAM | Alto | ~7x menor |
| Compressão | Básica | ~10x melhor |
| Velocidade | Normal | ~2-3x mais rápido |
| Setup HA | Complexo (Thanos) | Simples |
| API | PromQL | PromQL + extensões |
## O que instalamos
### Diferença da Aula-05
```
helm install monitoring vm/victoria-metrics-k8s-stack
```
| Aula-05 (KEDA) | Aula-12 (Observabilidade) |
|----------------|---------------------------|
| Foco: Auto-scaling | Foco: Monitoramento |
| VM básico (sem Grafana) | VM + Grafana completo |
| Queries para KEDA | Queries para operações |
| Ambiente local | Cluster Hetzner + GitOps |
Um único comando. Sem GitOps intermediário, sem repositório extra, sem pipeline de CI. O foco desta aula é **usar** o monitoramento, não instalar infraestrutura.
## Arquitetura
### Componentes
```
┌─────────────────────────────────────────────────────────────────┐
│ Victoria Metrics Stack │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ vmagent │ │ vmsingle │ │ Grafana │ │
│ │ (coleta) │──│ (storage) │──│ (visualização) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
│ │ │ │ │
│ ┌──────┴──────┐ ┌─────┴─────┐ ┌─────┴─────┐ │
│ │ node-export │ │ vmalert │ │ Dashboards│ │
│ │ kube-state │ │ (alertas) │ │ pré-config│ │
│ └─────────────┘ └───────────┘ └───────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ vmagent │ │ vmsingle │ │ Grafana │ │
│ │ (coleta) │─►│ (storage) │◄─│ (visualização) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
│ │ │ │ │
│ ┌──────┴──────┐ ┌─────┴─────┐ ┌─────┴─────┐ │
│ │ node-export │ │ vmalert │ │ 20+ dash- │ │
│ │ kube-state │ │ (alertas) │ │ boards │ │
│ └─────────────┘ └───────────┘ └───────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
### Componentes
| Componente | O que faz |
|------------|-----------|
| **vmagent** | Scrapes métricas de todos os pods, nodes, services a cada 30s |
| **vmsingle** | Armazena métricas (14 dias de retenção, 10Gi PVC) |
| **vmalert** | Avalia regras de alerta (PVC cheio, pod crashando, CPU alta) |
| **Grafana** | UI com 20+ dashboards pré-configurados |
| **kube-state-metrics** | Expõe estado dos objetos K8s (pods, deployments, PVCs) |
| **node-exporter** | Expõe métricas do SO (CPU, RAM, disco, rede) |
| Componente | Função |
|------------|--------|
| **vmsingle** | Armazena métricas (modo single-node) |
| **vmagent** | Coleta métricas via scrape |
| **vmalert** | Avalia regras e dispara alertas |
| **Grafana** | Interface de visualização |
| **kube-state-metrics** | Métricas de objetos K8s (pods, deployments) |
| **node-exporter** | Métricas de nodes (CPU, RAM, disco) |
### Por que Victoria Metrics e não Prometheus?
## Pré-requisitos
Compatível com PromQL, mas mais leve:
- Cluster Kubernetes Hetzner (aula-08)
- ArgoCD instalado (aula-11)
- Gitea com org `factory` (aula-11)
| | Prometheus | Victoria Metrics |
|---|---|---|
| RAM | Alto | ~7x menor |
| Compressão em disco | Básica | ~10x melhor |
| Velocidade de query | Normal | ~2-3x mais rápido |
| HA | Complexo (Thanos) | Simples |
## Estrutura
Para um cluster pequeno na Hetzner, Victoria Metrics é a escolha pragmática.
```
aula-12/
├── README.md # Este arquivo
├── setup.sh # Instalação automatizada
├── cleanup.sh # Remoção via ArgoCD
│
├── gitops/ # Conteúdo para Gitea
│ └── apps/
│ └── victoria-metrics/
│ ├── Chart.yaml # Helm chart wrapper
│ ├── values.yaml # Configurações do stack
│ └── templates/
│ └── alerts.yaml # VMRule customizado
│
├── argocd/
│ └── application.yaml # ArgoCD Application CRD
│
├── alerts/
│ └── vmalert-rules.yaml # Referência (aplicada via gitops/)
│
└── queries/
└── useful-queries.md # Queries PromQL úteis
```
## Instalação (GitOps)
### 1. Executar Setup
## Instalação
```bash
cd aula-12
export KUBECONFIG=$(pwd)/../aula-08/kubeconfig
./setup.sh
```
O script:
1. Cria repositório `factory/monitoring` no Gitea
2. Faz push dos manifests GitOps
3. Cria namespace `monitoring`
4. Aplica ArgoCD Application
5. Aguarda sincronização
O script pergunta:
1. Domínio base (herda da aula-10)
2. Hostname do Grafana (ex: `grafana.kube.quest`)
3. TLS (Let's Encrypt / CloudFlare / HTTP)
### 2. Fluxo GitOps
Depois faz `helm install` direto — sem GitOps, sem repos intermediários.
## Acesso ao Grafana
### Via Ingress
```
┌──────────────────┐ push ┌──────────────────┐
│ aula-12/ │ ──────────► │factory/monitoring │
│ gitops/ │ │ (Gitea) │
└──────────────────┘ └────────┬─────────┘
│
sync │
▼
┌──────────────────┐
│ ArgoCD │
└────────┬─────────┘
│
apply │
▼
┌──────────────────┐
│ Kubernetes │
│ ns: monitoring │
└──────────────────┘
URL: https://grafana.kube.quest
Username: admin
Password: (exibida no setup.sh)
```
### 3. Verificar Instalação
### Via Port-Forward
```bash
# Status do ArgoCD Application
kubectl get application monitoring -n argocd
# Pods rodando
kubectl get pods -n monitoring
# Serviços
kubectl get svc -n monitoring
```
## Configuração de DNS
Antes de acessar o Grafana, configure o DNS:
```bash
# Obter IP do Load Balancer
kubectl get svc -n ingress-nginx ingress-nginx-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
```
Configure o registro DNS:
- **grafana.kube.quest** → IP do Load Balancer (ex: 49.13.44.102)
## Acessar Grafana
### Via Ingress (Recomendado)
Após configurar o DNS:
- **URL**: https://grafana.kube.quest
- Certificado TLS via Let's Encrypt (automático)
### Credenciais
- **Usuário**: admin
- **Senha**: (gerada automaticamente)
```bash
# Obter senha do Grafana
kubectl get secret monitoring-grafana -n monitoring \
-o jsonpath='{.data.admin-password}' | base64 -d; echo
```
### Via Port-Forward (Alternativa)
Se não tiver DNS configurado:
```bash
# Port-forward Grafana
kubectl port-forward -n monitoring svc/monitoring-grafana 3000:80
# Acessar
open http://localhost:3000
```
## Dashboards Incluídos
### Obter senha
O chart `victoria-metrics-k8s-stack` já inclui **20+ dashboards** via Grafana sidecar:
```bash
kubectl get secret -n monitoring -l app.kubernetes.io/name=grafana \
-o jsonpath='{.items[0].data.admin-password}' | base64 -d; echo
```
### Dashboards Principais
## O que monitorar (casos reais)
| Dashboard | Descrição |
|-----------|-----------|
### 1. PVC enchendo
O problema mais comum em clusters pequenos. Um volume Hetzner de 10Gi enche silenciosamente.
```promql
# PVCs acima de 80%
(kubelet_volume_stats_used_bytes / kubelet_volume_stats_capacity_bytes) > 0.8
```
Dashboard: **Kubernetes / Views / Persistent Volumes**
### 2. Pod em CrashLoop
Quando um pod reinicia repetidamente sem ficar Ready.
```promql
# Pods que restartaram mais de 5x na última hora
sum(increase(kube_pod_container_status_restarts_total[1h])) by (pod, namespace) > 5
```
Dashboard: **Kubernetes / Views / Pods**
### 3. Node com CPU saturada
```promql
# CPU por node (%)
100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)
```
Dashboard: **Node Exporter / Nodes**
### 4. Memória por namespace
Quem está consumindo mais memória no cluster?
```promql
sum(container_memory_working_set_bytes{container!=""}) by (namespace)
```
Dashboard: **Kubernetes / Views / Namespaces**
### 5. Network throughput
```promql
# Bytes recebidos por pod (rate 5min)
sum(rate(container_network_receive_bytes_total[5m])) by (pod)
```
## Dashboards incluídos
O chart já vem com **20+ dashboards** configurados:
| Dashboard | Uso |
|-----------|-----|
| **Kubernetes / Views / Global** | Visão geral do cluster |
| **Kubernetes / Views / Namespaces** | Recursos por namespace |
| **Kubernetes / Views / Nodes** | CPU, memória, disco por node |
| **Kubernetes / Views / Pods** | Métricas detalhadas de pods |
| **Node Exporter / Nodes** | Métricas de sistema operacional |
| **Node Exporter / USE Method / Node** | Utilização, Saturação, Erros |
| **VictoriaMetrics / vmagent** | Status da coleta de métricas |
| **VictoriaMetrics / vmsingle** | Status do storage de métricas |
| **Node Exporter / Nodes** | Métricas do SO |
| **Node Exporter / USE Method** | Utilização, Saturação, Erros |
| **VictoriaMetrics / vmagent** | Status da coleta |
| **VictoriaMetrics / vmsingle** | Status do storage |
### Ver Todos os Dashboards
No Grafana:
1. Menu lateral → **Dashboards**
2. Ou acesse: https://grafana.kube.quest/dashboards
## Alertas Configurados
## Alertas configurados
| Alerta | Condição | Severidade |
|--------|----------|------------|
@@ -215,274 +172,56 @@ No Grafana:
| NodeLowMemory | RAM livre < 10% | warning |
| NodeDiskFull | Disco > 85% | critical |
### Verificar Alertas
```bash
# Ver alertas ativos
kubectl get vmrule -n monitoring
# Ver status no VMAlert
# Ver alertas
kubectl port-forward -n monitoring svc/vmalert 8880:8880
open http://localhost:8880/alerts
```
## Queries PromQL Úteis
## Integração com KEDA (Aula-05)
### Uso de Storage
```promql
# Uso de PVC em porcentagem
kubelet_volume_stats_used_bytes / kubelet_volume_stats_capacity_bytes * 100
# PVCs acima de 80%
(kubelet_volume_stats_used_bytes / kubelet_volume_stats_capacity_bytes) > 0.8
# Espaço disponível por PVC
kubelet_volume_stats_available_bytes
```
### CPU e Memória
```promql
# CPU por pod (cores)
sum(rate(container_cpu_usage_seconds_total{container!=""}[5m])) by (pod, namespace)
# Memória por namespace
sum(container_memory_working_set_bytes{container!=""}) by (namespace)
# CPU por node (%)
100 - (avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)
```
### Pods e Containers
```promql
# Pods restartando na última hora
sum(increase(kube_pod_container_status_restarts_total[1h])) by (pod, namespace) > 0
# Pods não Ready
kube_pod_status_ready{condition="false"}
# Pods em CrashLoopBackOff
kube_pod_container_status_waiting_reason{reason="CrashLoopBackOff"}
```
### Network
```promql
# Bytes recebidos por pod
sum(rate(container_network_receive_bytes_total[5m])) by (pod)
# Bytes enviados por pod
sum(rate(container_network_transmit_bytes_total[5m])) by (pod)
```
## Integrações
### Com KEDA (Aula-05)
Victoria Metrics pode alimentar KEDA para auto-scaling:
Victoria Metrics pode alimentar KEDA para auto-scaling baseado em métricas:
```yaml
triggers:
- type: prometheus
metadata:
serverAddress: http://vmsingle-vm.monitoring:8429
serverAddress: http://vmsingle-monitoring-victoria-metrics-k8s-stack.monitoring:8429
query: sum(kube_deployment_status_replicas_unavailable{deployment="myapp"})
threshold: '1'
```
### Com Alertmanager
## Auto-Resize de PVC (Opcional)
Para notificações (Slack, Email, PagerDuty):
Expansão automática de volumes quando atingirem 80%.
```yaml
# values.yaml
vmalert:
alertmanager:
url: http://alertmanager.monitoring:9093
```bash
helm repo add pvc-autoresizer https://topolvm.github.io/pvc-autoresizer/
helm install pvc-autoresizer pvc-autoresizer/pvc-autoresizer \
--namespace pvc-autoresizer \
--create-namespace \
--set controller.args.prometheusURL=http://vmsingle-monitoring-victoria-metrics-k8s-stack.monitoring:8429 \
--set controller.args.noAnnotationCheck=true
# Habilitar no StorageClass
kubectl annotate storageclass hcloud-volumes resize.topolvm.io/enabled="true"
```
Com isso, **todos os PVCs** no cluster são monitorados e expandidos automaticamente.
## Troubleshooting
### Grafana não carrega dashboards
```bash
# Verificar configmap de dashboards
kubectl get configmap -n monitoring | grep dashboard
# Verificar logs do sidecar
kubectl logs -n monitoring -l app.kubernetes.io/name=grafana -c sc-dashboard
```
### Métricas não aparecem
```bash
# Verificar targets do vmagent
kubectl port-forward -n monitoring svc/vmagent 8429:8429
open http://localhost:8429/targets
# Verificar scrape configs
kubectl get configmap -n monitoring vmagent-config -o yaml
```
### VMAlert não dispara alertas
```bash
# Verificar regras carregadas
kubectl port-forward -n monitoring svc/vmalert 8880:8880
open http://localhost:8880/rules
# Verificar logs
kubectl logs -n monitoring -l app=vmalert
```
### ArgoCD mostra OutOfSync
```bash
# Ver diff
argocd app diff monitoring
# Forçar sync
argocd app sync monitoring --prune
```
## Auto-Resize de PVC (Opcional)
Expansão automática de volumes quando atingirem 80% da capacidade.
### Arquitetura
```
┌─────────────────────────────────────────────────────────────────────┐
│ FLUXO DE MÉTRICAS │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ kubelet ──────────► vmagent ──────────► vmsingle │
│ (expõe stats (scrape (armazena │
│ do volume) 30s) métricas) │
│ │
│ Métrica: kubelet_volume_stats_used_bytes │
│ Métrica: kubelet_volume_stats_capacity_bytes │
│ │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ FLUXO DE RESIZE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ pvc-autoresizer ───── query ────► vmsingle │
│ │ (consulta % usado) │
│ │ │
│ │ Se usado > 80% (free < 20%): │
│ │ │
│ ▼ │
│ kubectl patch PVC ──────► Kubernetes ──────► Hetzner CSI │
│ (spec.resources. (detecta mudança (expande volume │
│ requests.storage no request) online, sem │
│ += 10Gi) downtime) │
│ │ │
│ ▼ │
│ Pod restart ──────► Filesystem resize ──────► Capacidade OK │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### Componentes e Responsabilidades
| Componente | Função | Faz resize? |
|------------|--------|-------------|
| **kubelet** | Expõe métricas de volume | ❌ |
| **vmagent** | Coleta métricas (scrape) | ❌ |
| **vmsingle** | Armazena métricas | ❌ |
| **pvc-autoresizer** | Monitora + patch PVC | ✅ |
| **Hetzner CSI** | Expande volume físico | ✅ |
### Pré-requisitos
- StorageClass com `allowVolumeExpansion: true` (já configurado)
- Hetzner CSI Driver (suporta online resize)
- Victoria Metrics coletando métricas do kubelet
### Instalar pvc-autoresizer
```bash
# Adicionar repo Helm
helm repo add pvc-autoresizer https://topolvm.github.io/pvc-autoresizer/
# Instalar com Victoria Metrics + modo automático (sem annotations)
helm install pvc-autoresizer pvc-autoresizer/pvc-autoresizer \
--namespace pvc-autoresizer \
--create-namespace \
--set controller.args.prometheusURL=http://vmsingle-monitoring-victoria-metrics-k8s-stack.monitoring:8429 \
--set controller.args.noAnnotationCheck=true \
--set controller.args.initialResizeGroupByPvc=true
# Habilitar auto-resize no StorageClass
kubectl annotate storageclass hcloud-volumes resize.topolvm.io/enabled="true"
```
### Comportamento Automático
Com `--no-annotation-check`, **todos os PVCs** em StorageClasses com a annotation `resize.topolvm.io/enabled: "true"` são automaticamente monitorados.
**Defaults aplicados:**
- Threshold: 10% livre (expande quando usado > 90%)
- Increase: 10% do tamanho atual
**PVCs futuros** não precisam de annotations - funcionam automaticamente!
### Annotations para Override (Opcional)
Para customizar o comportamento de um PVC específico:
```bash
kubectl annotate pvc <nome-pvc> -n <namespace> \
resize.topolvm.io/storage_limit="10Ti" \
resize.topolvm.io/threshold="20%" \
resize.topolvm.io/increase="10Gi"
```
### Configuração das Annotations (Override)
| Annotation | Valor | Descrição |
|------------|-------|-----------|
| `storage_limit` | `10Ti` | Limite máximo (10TB = max Hetzner) |
| `threshold` | `20%` | Expandir quando free < 20% (usado > 80%) |
| `increase` | `10Gi` | Quanto aumentar por vez |
**Nota:** Sem `storage_limit`, o PVC pode expandir até o máximo do Hetzner (10TB).
### Alerta de Notificação
Quando um PVC é redimensionado, o alerta **PVCAutoResized** é disparado automaticamente (severity: info).
### Verificar Funcionamento
```bash
# Logs do controller
kubectl logs -n pvc-autoresizer deployment/pvc-autoresizer-controller
# Ver PVCs com auto-resize habilitado
kubectl get pvc -A -o jsonpath='{range .items[*]}{.metadata.namespace}/{.metadata.name}: {.metadata.annotations.resize\.topolvm\.io/storage_limit}{"\n"}{end}'
```
### Referência
- [pvc-autoresizer GitHub](https://github.com/topolvm/pvc-autoresizer)
---
## Retenção de Dados
Configuração padrão: **14 dias**
Para alterar:
```yaml
# gitops/apps/victoria-metrics/values.yaml
vmsingle:
retentionPeriod: "30d"
```
## Cleanup
@@ -491,17 +230,11 @@ vmsingle:
./cleanup.sh
```
O script remove:
1. ArgoCD Application
2. Namespace `monitoring`
3. Repositório Gitea (opcional)
**Nota**: Dados de métricas serão perdidos!
Remove o Helm release e o namespace `monitoring`. Dados de métricas serão perdidos.
## Referências
- [Victoria Metrics Docs](https://docs.victoriametrics.com/)
- [victoria-metrics-k8s-stack Chart](https://github.com/VictoriaMetrics/helm-charts/tree/master/charts/victoria-metrics-k8s-stack)
- [Grafana Dashboards](https://grafana.com/grafana/dashboards/)
- [PromQL Cheat Sheet](https://promlabs.com/promql-cheat-sheet/)
- [pvc-autoresizer](https://github.com/topolvm/pvc-autoresizer) - Auto-resize de volumes
- [pvc-autoresizer](https://github.com/topolvm/pvc-autoresizer)