Operations

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

O yby context use (o mesmo que yby env use) marca o ambiente ativo e, quando ele tem kube_context, troca o contexto do kubectl.

Plugins num Ambiente

O Viz e o Sentinel não leem o ambiente ativo: ficam no current-context do kubeconfig. Para abrir um deles no cluster de um ambiente do .yby/environments.yaml sem trocar nada, passe -c (ou YBY_ENV) antes do nome do plugin; depois do nome, a flag é do plugin.

yby -c staging viz                        # kubeconfig, contexto e namespace do ambiente
yby -c staging sentinel scan              # kubeconfig, contexto e namespace do ambiente
YBY_ENV=staging yby viz

Sem -n, o sentinel scan e o investigate usam o namespace do ambiente pedido; sem ambiente (ou num ambiente sem namespace), o do contexto do kubeconfig, como o kubectl e o Viz; default só quando nenhum dos dois diz. Em scripts, passe -n.

Rode na pasta que tem o .yby/ (num monorepo, em infra/): o -c lê o environments.yaml só da pasta atual. Ambiente que não existe no environments.yaml dá erro antes de o plugin abrir.

---

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 secret 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 secret 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 (o que o yby gera fica em ~/.sops/age-key.txt).

Para gerar as chaves age: yby secret init-sops (grava a chave privada em ~/.sops/age-key.txt e mostra a pública para o .sops.yaml).

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) · beta

Beta: os comandos yby cloud foram testados com os CLIs aws, az e gcloud e conferidos contra a documentação oficial, mas ainda não contra clusters reais. Login, tokens e kubeconfig podem falhar de jeitos que os testes não pegaram; relate nas issues. O que falta para sair do beta está no ROADMAP.

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 (o grupo de recursos vem da listagem do az)
yby cloud connect --provider azure --cluster meu-cluster --region brazilsouth

# Conectar a um cluster GKE (zona ou região; o projeto é o do gcloud config)
yby cloud connect --provider gcp --cluster meu-cluster --region us-central1-a

# Sem flags, o connect detecta os CLIs, lista os clusters e guia a escolha
yby cloud connect

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 cluster
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.

Auditoria de Operações Cloud

O Yby registra automaticamente todas as operações de autenticação cloud (connect, refresh, token renewal) em ~/.yby/audit.log (formato JSONL com rotação em 10MB).

# Consultar log de auditoria
yby cloud audit

# Filtrar por período e provider
yby cloud audit --since 24h --provider aws

# Exportar para compliance/SIEM
yby cloud audit --since 30d --export json > audit-export.json
yby cloud audit --since 30d --export csv > audit-export.csv

Cada entrada registra: provider, método de auth, cluster, identidade, timestamp e resultado da operação.

Dashboard Multi-Cluster

O comando yby cloud dashboard abre o painel dos clusters dos CLIs instalados, com a validade de cada token:

yby cloud dashboard

• Resumo no topo (prontos, tokens perto de vencer, vencidos, clusters parados) e releitura periódica.
• Detalhe do cluster com a identidade (conta, papel, método) e a auditoria recente.
• Leitura parcial (um CLI que não respondeu) avisa na tela e mantém os dados da última leitura, com o horário.

Tecla	Ação
↑ ↓ (ou j k)	mover
↵	abrir o cluster no Viz; abaixo de 120 colunas, abre o detalhe
t	renovar o token do cluster
r	recarregar
/	buscar pelo nome do cluster
?	ajuda
esc	fecha a camada de cima ou limpa a busca
q	sai do nível de cima
ctrl+c	sai de qualquer lugar

---

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	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 secret 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

Isso remove o cluster k3d criado pelo yby up.