Skip to content

Operations

Malindentado edited this page Apr 8, 2026 · 11 revisions

Manual de Operações (Day 2)

Este guia cobre a administração contínua, deployment de aplicações e resolução de problemas no cluster Yby.


1. Acesso e Monitoramento

Acessando Painéis (Seguro)

O comando yby access abre túneis seguros para todos os serviços internos.

yby access
  • Argo CD: Gestão de GitOps.
  • Grafana: Métricas e dashboards.

Acesso via CLI

Para alternar o contexto do kubectl para seu cluster de produção:

yby context use prod

2. Fluxo de GitOps

Regra de Ouro: Nunca edite recursos manualmente (kubectl edit). Toda mudança deve vir do Git.

Atualizar Infraestrutura

  1. Edite config/cluster-values.yaml.
  2. Commit e Push.
  3. O Argo CD sincronizará automaticamente.

Publicar Nova Aplicação

O Yby usa Zero-Touch Discovery. Para criar um novo app:

  1. Crie um novo chart autogerenciado:
    yby chart create nome-do-app
  2. Commite e envie para o repositório (Git Push).
  3. Adicione o tópico yby-cluster (ou o tópico configurado no values.yaml) nas configurações do repositório GitHub.
    • Nota: Sem essa tag, o Argo CD ignorará o repositório como medida de segurança.
  4. O Argo CD detectará o app e fará o deploy automaticamente.

3. Gestão de Segredos & Disaster Recovery (DR)

O Yby suporta três estratégias de segredos. As práticas de DR dependem da estratégia escolhida.

3.1 Sealed Secrets (DR)

Se você usar sealed-secrets, a chave privada vive dentro do cluster. Se perder as chaves mestras, perde todos os segredos.

Backup das Chaves Mestras (Critical):

yby secrets backup master-key-backup.yaml

Armazene este arquivo OFFLINE (Pen Drive, Cofre, 1Password). Nunca commite no Git.

Restaurando um Cluster:

  1. Provisione um novo cluster (yby bootstrap vps).
  2. ANTES de instalar qualquer app, restaure a chave mestra:
    yby secrets restore master-key-backup.yaml
  3. Reinicie o controlador:
    kubectl delete pod -n yby-system -l app.kubernetes.io/name=sealed-secrets

Rotação de Chaves: O controlador cria nova chave a cada 30 dias. Faça backup após cada rotação.

3.2 SOPS + age

Se você usar sops, as chaves age ficam no seu ambiente local. O DR depende de manter backup seguro do arquivo de chave age (geralmente em ~/.config/sops/age/keys.txt).

Para gerar novas chaves age: yby secrets generate-age-key.

3.3 External Secrets Operator (ESO)

Se usar external-secrets, os segredos ficam em provedores externos (Vault, AWS, GCP, Azure). O DR é responsabilidade do provedor. Garanta que as credenciais de acesso ao provedor estejam seguras e documentadas.


4. Webhooks e CI/CD Instantâneo

Por padrão, o Argo CD verifica mudanças a cada 3 minutos. Para deploys instantâneos, configure o Webhook:

  1. Gere o segredo: yby secret webhook.
  2. Adicione no GitHub (Webhooks, Push Event) apontando para o Ingress do ArgoCD.

5. Atualização do CLI

Self-Update (yby upgrade)

O CLI pode se atualizar automaticamente via GitHub Releases:

# Verificar se há atualização disponível
yby upgrade --check

# Atualizar para a versão mais recente
yby upgrade

# Atualizar para uma versão específica
yby upgrade --version v0.6.0

O processo de upgrade:

  1. Verifica a versão mais recente no GitHub.
  2. Baixa o asset correto para seu OS/arquitetura.
  3. Verifica checksum SHA256 contra checksums.txt.
  4. Substitui o binário com rollback automático em caso de falha.

Use --force para reinstalar mesmo se já estiver na versão mais recente.


6. Telemetria

O Yby coleta métricas de execução (duração, sucesso/falha) para diagnóstico de performance. Os dados são persistidos em ~/.yby/telemetry.jsonl com rotação automática (5MB).

# Exportar dados de telemetria
yby telemetry export

# Desabilitar telemetria
# Em ~/.yby/config.yaml:
# telemetry:
#   enabled: false

A telemetria pode ser desabilitada via config (telemetry.enabled: false) ou variável de ambiente (YBY_TELEMETRY_ENABLED=false).


7. Operando em Clusters Cloud (EKS/AKS/GKE)

O Yby suporta clusters K8s gerenciados em clouds públicas (AWS EKS, Azure AKS, GCP GKE) através dos comandos yby cloud.

Conectando a um Cluster Cloud

# Conectar a um cluster EKS
yby cloud connect --provider aws --cluster meu-cluster --region sa-east-1

# Conectar a um cluster AKS
yby cloud connect --provider azure --cluster meu-cluster --resource-group meu-rg

# Conectar a um cluster GKE
yby cloud connect --provider gcp --cluster meu-cluster --project-id meu-projeto --zone us-east1-b

Token Refresh Automático

O Yby usa AutoRefreshTransport para renovar tokens de autenticação automaticamente durante operações longas (deploy, monitoring, bootstrap). Isso evita falhas de 401 Unauthorized em operações que excedem o TTL do token cloud.

Verificando Credenciais

Antes de operações críticas, verifique o estado das credenciais:

# Status das credenciais e conectividade
yby cloud status

# Forçar refresh manual do token
yby cloud refresh

# Listar clusters configurados
yby cloud list

Workflow Típico

# 1. Conectar ao cluster
yby cloud connect --provider aws --cluster prod --region sa-east-1

# 2. Verificar credenciais
yby cloud status

# 3. Operar normalmente (token refresh automático)
yby bootstrap
yby sentinel scan -n default
yby viz

Nota: O build padrão (yby) não inclui SDKs cloud. Para suporte nativo a AWS/Azure/GCP, use o build variant yby-cloud.


8. Troubleshooting (SRE Guide)

Healthcheck

Antes de abrir uma issue, sempre rode yby doctor.

O doctor verifica:

  • Ferramentas obrigatórias: kubectl, helm, argocd, git, direnv, docker
  • Ferramentas opcionais (por estratégia de secrets): kubeseal, sops, age
  • Conexão ao cluster e CRDs instalados (Prometheus, Cert-Manager, KEDA)

Matriz de Solução de Problemas

Sintoma Causa Provável Solução
ArgoCD Travado / App Unhealthy Rede ou OOM yby up --restart ou kubectl rollout restart deploy argocd-server -n argocd
TLS Handshake Timeout Falta de RAM (Cluster) Aumente VM para 4GB+. Verifique kubectl top nodes.
Permission Denied (Docker) Usuário fora do grupo sudo usermod -aG docker $USER
SealedSecret Error (Key) Chave errada ou cluster novo Restaure o backup da chave mestra (yby secrets restore).
"Type mismatch" (Helm) Dependência desatualizada helm dependency update infra/charts/bootstrap

Apagando tudo (Nuke)

Se precisar começar do zero localmente:

yby destroy --all

Isso remove cluster, volumes e caches locais.

Clone this wiki locally