Core Concepts

Conceitos Core

O Yby não é apenas um script de automação; é uma plataforma de engenharia IaC (infraestrutura como código).

1. Engine de Blueprints & Contextos

Ao rodar yby init, a ferramenta usa uma Engine Dinâmica que:

1. Resolve o Contexto: Analisa flags e ambiente.
2. Calcula Variáveis: Nomes de projeto, domínios, slugs.
3. Gera Arquivos: Cria pipelines CI/CD e manifestos Kubernetes sob medida.

Engine de Discovery (Zero-Touch)

O Yby utiliza o Argo CD ApplicationSet para varrer sua organização no GitHub/GitLab.

• Filtro: Ele busca apenas repositórios com o tópico (tag) yby-cluster (configurável).
• Benefício: Basta criar um repo novo, adicionar a tag, e o cluster faz o deploy automaticamente. Nenhuma configuração extra necessária.

Manifesto .yby/environments.yaml

O cérebro do projeto, mapeando nomes lógicos (local, prod) para configurações concretas.

current: local
environments:
  local: { type: "local", values: "config/values-local.yaml" }
  prod:
    type: remote
    values: config/values-prod.yaml
    kube_config: ~/.kube/prod.yaml   # relativo vale a partir da pasta do projeto
    kube_context: prod-admin
    namespace: payments

Os campos kube_config, kube_context e namespace são opcionais e dizem onde o ambiente roda.

Ambiente nos plugins

Os plugins (Sentinel, Viz, Bard...) só recebem um ambiente quando ele é pedido:

• -c/--context antes do nome do plugin: yby -c prod sentinel scan (vale em qualquer forma: -c prod, -cprod, -c=prod, --context=prod). Depois do nome, a flag é do plugin: em yby viz --context x, o --context é o contexto do kubeconfig do Viz.
• YBY_ENV: YBY_ENV=prod yby viz.

Com o ambiente pedido, o plugin recebe, sem que nada rode antes dele, o nome do projeto, o ambiente, a infra (kube_config já resolvido, kube_context e namespace) e os values. Sem ambiente pedido, nenhum vai: o current não conta, e o Viz e o Sentinel ficam no current-context do kubeconfig.

Erros que barram o plugin antes de ele abrir:

• Ambiente pedido que não existe no environments.yaml: ERR_CONFIG_INVALID (rode yby env list).
• Flag antes do nome do plugin que não é do core (o core aceita ali só -c/--context, --log-level e --log-format): ERR_VALIDATION. Para passar a flag ao plugin, escreva-a depois do nome.

Ambientes Cloud (eks, aks, gke)

Além dos tipos local e remote, o Yby suporta tipos de ambiente cloud que integram diretamente com clusters gerenciados:

Tipo	Provider	Descrição
eks	AWS	Amazon Elastic Kubernetes Service
aks	Azure	Azure Kubernetes Service
gke	GCP	Google Kubernetes Engine

Para ambientes cloud, o campo cloud define a configuração do provider:

environments:
  prod-eks:
    type: eks
    description: Cluster EKS de produção
    cloud:
      provider: aws
      region: us-east-1
      cluster: prod-cluster
      profile: prod-profile
  staging-aks:
    type: aks
    description: Cluster AKS de staging
    cloud:
      provider: azure
      resource_group: rg-staging
      cluster: staging-cluster
      subscription: sub-id
  dev-gke:
    type: gke
    description: Cluster GKE de desenvolvimento
    cloud:
      provider: gcp
      project_id: meu-projeto
      zone: us-central1-a
      cluster: dev-cluster

Campos disponíveis em cloud: provider, region, cluster, profile, role_arn, resource_group, subscription, tenant_id, login_mode, project_id, zone.

---

2. Estrutura de Diretórios (infra/)

O yby init gera uma estrutura "Infra-as-Code First":

infra/
├── .yby/                     # Estado Local e Blueprint
├── charts/                   # Helm Charts Locais
│   └── system/               # Chart "Umbrella" de Sistema (CRDs, Controladores)
├── config/                   # Values por Ambiente (Umbrella Pattern)
│   ├── cluster-values.yaml   # Config Global
│   ├── values-local.yaml     # Config Dev (k3d)
│   └── values-prod.yaml      # Config Prod
├── manifests/                # GitOps Root (Argo CD App of Apps)
└── templates/                # Templates Argo Workflows

---

3. Monorepo & Segredos

Estratégia Monorepo

O Yby suporta nativamente monorepos (múltiplos serviços no mesmo repo). Para isso, isole a infraestrutura na pasta infra/:

yby init --target-dir infra

O CLI configura o ArgoCD para ler os caminhos relativos corretamente.

Segredos (Múltiplas Estratégias)

O princípio GitOps exige que nada em texto plano vá para o Git. O Yby oferece três estratégias de encriptação, configuráveis via --secrets-strategy no yby init ou --strategy no yby seal:

Estratégia	Ferramenta	Uso recomendado
sealed-secrets	Bitnami Sealed Secrets + kubeseal	Padrão para clusters simples
sops	Mozilla SOPS + age	Encriptação local sem controlador no cluster
external-secrets	External Secrets Operator (ESO)	Integração com provedores externos (Vault, AWS, GCP, Azure)

Workflow (Sealed Secrets — padrão do yby seal):

1. Execute yby seal e siga o wizard interativo (nome, namespace, dados).
2. O CLI gera um Secret Kubernetes e o encripta com kubeseal.
3. Commite o arquivo selado gerado em sealed-secrets/.

Workflow (SOPS):

1. Execute yby seal --strategy sops e siga o wizard.
2. O CLI encripta usando sops com chaves age.
3. Commite o arquivo encriptado gerado em sops-secrets/.

Workflow (External Secrets — ESO): Configurado durante o yby init. Suporta backends: Vault, AWS Secrets Manager, GCP Secret Manager e Azure Key Vault. O ESO sincroniza secrets diretamente do provedor externo para o cluster.

---

4. Ciclo de Vida (yby up vs yby destroy)

O Yby introduz uma abordagem declarativa para o ciclo de vida do ambiente:

yby up (Single Entrypoint)

Comando idempotente que "traz o ambiente à vida", com comportamento adaptativo:

• Contexto Local:
  • Cria/Inicia cluster k3d.
  • Configura espelho Git interno.
  • Abre túneis de rede (Port-Forward).
  • Inicia loop de sincronização de arquivos.
• Contexto Remoto:
  • Verifica credenciais e acesso ao cluster.
  • Garante que a stack de GitOps (ArgoCD) está saudável.
  • Não faz sync de arquivos (usa Git push puro).
• Contexto Cloud (eks/aks/gke):
  • Executa yby cloud connect para autenticar no provider.
  • Gera/renova token via TokenCache com refresh automático.
  • Verifica saúde do cluster remoto e stack GitOps.

yby destroy

Comando seguro para desmontar o ambiente local.

• Remove o cluster k3d e volumes Docker.
• Limpa arquivos de cache locais (.yby/).
• Segurança: Recusa-se a rodar em contextos remotos (prod/staging).

---

5. Stack Opinativa com Flexibilidade Enterprise

O Yby entrega uma stack "batteries-included" com defaults prontos para produção. Os nomes dos componentes (MinIO, Kepler, KEDA, etc.) representam capabilities — não lock-in:

Capability	Default (PME)	Override Enterprise
Object Storage	MinIO	S3, GCS, Azure Blob, Ceph
Energy Metrics	Kepler	Custom exporters, cloud-native
Event Autoscaling	KEDA	HPA nativo, Knative
Monitoring	Prometheus	Thanos, Datadog, New Relic
Ingress	Traefik	Nginx, AWS ALB, Istio
TLS	Let's Encrypt	CA corporativa, Vault

Filosofia: Opinativo por Padrão, Flexível por Design

• PME (sem overrides): yby init gera tudo com os defaults acima. Funciona out-of-the-box.
• Enterprise (com overrides): yby init --config .yby/overrides.yaml parametriza registry, namespaces, ingress, TLS, versões de charts e mais. Veja Enterprise Overrides.

O arquivo de overrides não muda a arquitetura — muda apenas os valores que preenchem os mesmos templates. Isso significa que a mesma estrutura de diretórios, o mesmo GitOps flow e os mesmos comandos funcionam em qualquer escala.

---

6. Padronização de Workloads (yby chart create)

Para evitar o "copia-e-cola" de YAMLs, o Yby oferece um gerador de scaffolds que segue as Golden Paths da organização.

Ao rodar yby chart create meu-app, ele gera os manifestos padrão do Kubernetes em charts/meu-app:

1. Deployment: Com Liveness/Readiness probes configurados.
2. Service & Ingress: Exposição segura padrão.
3. HPA: Autoscaling horizontal pré-configurado.
4. ServiceAccount: Com workload identity se necessário.

Isso garante que todo novo serviço nasça "Production Ready" por padrão.