Skip to content

Getting Started

Jump to bottom
Malindentado edited this page Oct 25, 2026 · 18 revisions

Getting Started

Comece a usar o Yby CLI em minutos.

📋 Pré-requisitos

Para utilizar todas as funcionalidades do Yby (especialmente o ambiente local dev), você precisará de:

  • Hardware: Mínimo de 4GB de RAM e 2 CPUs (para rodar a stack completa).
  • Linux ou macOS (Windows via WSL2 é suportado, mas experimental).
  • Docker: Essencial para rodar o cluster local (k3d).
  • Git: Para versionamento.

O comando yby doctor verificará essas ferramentas para você.

🚀 Instalação

Consulte o README principal para instruções de instalação.

Setup Inicial (Essencial)

Após instalar o binário, execute o setup para garantir que todas as ferramentas padrão da indústria (k3d, kubectl, helm) estejam instaladas e linkadas corretamente no seu path. O Yby as utiliza por baixo dos panos.

yby setup

O setup suporta dois perfis via --profile:

  • dev (padrão): Instala kubectl, helm, k3d e direnv — stack completa para desenvolvimento local.
  • server: Instala apenas kubectl e helm — minimal para operações remotas em VPS.

🏁 Iniciando um Novo Projeto

A maneira mais rápida de começar é utilizando o wizard interativo.

  1. Crie um diretório para seu projeto (ou use um existente):

    mkdir meurepo && cd meurepo
git init

  2. Rode o comando de inicialização:

    yby init

  3. Responda as perguntas do wizard:

    • Diretório Alvo: Escolha . (raiz) ou infra (para monorepos).
    • Topologia: single (apenas local), standard (local + prod) ou complete (multi-env).
    • Workflow: essential, gitflow ou trunkbased.
    • Estratégia de Secrets: sealed-secrets, sops ou external-secrets.
    • Git URL: Indique seu repositório remoto (ou pule se estiver offline).

    Flags opcionais de features: --enable-kepler, --enable-minio, --enable-keda, --enable-metrics-server.

O Yby vai gerar toda a estrutura de pastas (charts/, .github/, .yby/).

Atualizando um Projeto Existente (yby init --update)

Quando o CLI é atualizado e os templates evoluem, você pode atualizar o scaffold do projeto preservando suas customizações:

yby init --update

O merge inteligente compara cada arquivo via SHA-256:

  • Arquivos que você não alterou: atualizados silenciosamente.
  • Arquivos que você customizou: preservados sem alteração.
  • Conflitos (ambos mudaram): resolução interativa (manter seu, usar scaffold, ou marcadores de conflito estilo Git).

Use --force para sobrescrever tudo (sem merge). As flags --update e --force são mutuamente exclusivas.

3. Ambiente Local (yby up)

Para iniciar o desenvolvimento local:

yby up

Este comando sobe um cluster k3d, inicia o Mirror Git interno e configura o Argo CD.

Modo Offline: Use yby init --offline para pular verificações de Git remoto. O yby up funcionará 100% localmente. Modo Headless: Use yby init --non-interactive com todas as flags necessárias para pipelines de CI/CD.

🎨 Modo visual

As telas do yby seguem o tema do terminal. A ajuda de qualquer comando sai em português com yby <comando> --help:

yby --help

Ajuste Variável de ambiente ~/.yby/config.yaml
Tema (auto, dark, light) YBY_THEME=light ui.theme: light
Glifos em ASCII, para terminais sem Unicode YBY_ASCII=1 ui.ascii: true
Sem cores NO_COLOR=1 —

A variável de ambiente vence o config. No tema claro:

yby up --help no tema claro

☁️ Cloud Setup

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.

Para trabalhar com clusters gerenciados (EKS, AKS, GKE), você precisa do CLI do provider instalado:

Provider Pré-requisito Verificação
AWS (EKS) AWS CLI v2 aws sts get-caller-identity
Azure (AKS) Azure CLI az account show
GCP (GKE) gcloud CLI gcloud auth list

O comando yby doctor verifica automaticamente a disponibilidade dos CLIs cloud na seção Cloud Providers.

Conectando a um Cluster Cloud

Use o wizard guiado para configurar a conexão:

yby cloud connect

Ou crie um ambiente cloud diretamente:

yby env create --cloud-provider aws --cloud-region us-east-1 --cloud-cluster meu-cluster

Comandos úteis para gerenciar conexões cloud:

yby cloud list      # Lista clusters disponíveis no provider
yby cloud status    # Verifica status da conexão atual
yby cloud refresh   # Renova credenciais manualmente
yby cloud dashboard # Dashboard multi-cluster interativo
yby cloud audit     # Consulta log de auditoria de operações cloud
yby env show        # Exibe metadata cloud do ambiente ativo

Auth Avançada (SSO, MFA, etc.)

Para ambientes enterprise com SSO AWS, configure o método de auth no environments.yaml:

cloud:
  provider: aws
  region: us-east-1
  cluster: prod-cluster
  auth:
    method: sso
    sso_start_url: https://my-org.awsapps.com/start
    sso_region: us-east-1
    sso_account: "123456789012"
    sso_role_name: EKSAdmin

Métodos disponíveis por provider:

  • AWS: sso, assume-role, web-identity (IRSA), mfa
  • Azure: devicecode, interactive, certificate, msi
  • GCP: workload-identity, impersonation, connect-gateway

Auditoria de Operações Cloud

O Yby registra todas as operações de autenticação cloud em ~/.yby/audit.log (formato JSONL). Para consultar:

# Últimas 24 horas
yby cloud audit --since 24h

# Filtrar por provider e exportar
yby cloud audit --provider aws --export json
yby cloud audit --since 7d --export csv

IA com Amazon Bedrock

Para usar o Bedrock como provider de IA, configure em ~/.yby/config.yaml:

ai:
  provider: bedrock
  model: anthropic.claude-3-sonnet   # modelo disponível na sua conta

Requer AWS CLI configurado e permissões para as APIs bedrock-runtime:Converse e bedrock-runtime:InvokeModel.

🔌 Projetos Existentes (Monorepos)

Se você já tem um projeto (ex: backend em Node.js) e quer adicionar a infraestrutura do Yby:

  1. Na raiz do repositório, rode: 
    yby init --target-dir infra
  2. Isso criará a pasta infra/ contendo todo o código Terraform/Kubernetes.
  3. O CLI é inteligente: rode yby up da raiz e ele detectará a infra automaticamente.

⚙️ Configuração Global

Para evitar repetir flags a cada execução, crie o arquivo ~/.yby/config.yaml com suas preferências:

ai:
  provider: gemini       # ollama, gemini, openai, bedrock, claude-cli ou gemini-cli
  model: gemini-pro      # modelo específico do provider
  language: pt-BR        # idioma das respostas de IA
log:
  level: info            # debug, info, warn, error
  format: text           # text ou json
telemetry:
  enabled: true

Precedência: Flags de linha de comando sempre têm prioridade sobre variáveis de ambiente, que por sua vez têm prioridade sobre o arquivo de config. Os valores padrão são usados quando nenhuma outra fonte os define.

🏢 Configuração Enterprise (Overrides)

Para ambientes corporativos que precisam customizar registry de imagens, ingress, namespaces ou versões de charts, crie um arquivo de overrides:

yby init --config .yby/overrides.yaml

O Yby também detecta automaticamente o arquivo em .yby/overrides.yaml (projeto) ou ~/.yby/overrides.yaml (global).

# .yby/overrides.yaml — Exemplo para banco digital
registry:
  url: 012345678.dkr.ecr.sa-east-1.amazonaws.com
  pullSecret: regcred

cloud:
  storageClass: gp3

ingress:
  className: nginx

namespaces:
  prefix: "fintech"
  labels:
    cost-center: platform
    team: devops

tls:
  issuer: custom
  caSecretName: corp-ca

helm:
  repoBaseURL: https://charts.internal.corp
  versions:
    argocd: "6.7.0"

Filosofia: Sem overrides, o Yby entrega uma stack opinativa pronta para PMEs. Com overrides, a mesma stack se adapta a qualquer ambiente enterprise. Veja detalhes em Enterprise Overrides.

Próximos Passos:

Yby CLI — Infraestrutura Soberana & Autônoma

Repositório • Reportar Bug • Licença MIT


Idealizado e mantido por Casheiro

🛡️ Governado pelo Matrix Protocol

Clone this wiki locally