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

```yaml
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:

```yaml
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/`:

```bash
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](Enterprise-Overrides.md).

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.