> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# EKB - Guia de AWS EKS (Serviços e Infraestrutura)

> Visão geral da arquitetura, descrições dos componentes e fluxo de dados para a infraestrutura de serviços do EKB no AWS EKS.

Este documento fornece uma visão abrangente da arquitetura AWS para a infraestrutura de serviços do EKB. A arquitetura segue padrões cloud-native com serviços gerenciados pela AWS, orquestração Kubernetes e escalonamento automático.

***

# Visão Geral da Arquitetura AWS

A arquitetura segue padrões cloud-native com serviços gerenciados pela AWS, orquestração Kubernetes e escalonamento automático.

***

## Diagrama da Arquitetura

```mermaid theme={null}
flowchart TD
    INTERNET["🌐 INTERNET"]
 
    DNS["Provedor DNS
(Route 53 / Cloudflare / etc.)
──────────────────────────────
• app.seu-domínio — Frontend Web
• api.seu-domínio — Backend FastAPI
• automations.seu-domínio — Automator
• supabase.seu-domínio — Supabase Kong
• signoz.seu-domínio — SigNoz"]
 
    ALB["BALANCEADOR DE CARGO DE APLICAÇÃO
──────────────────────────────
• Terminação SSL via ACM
• Redirect HTTP → HTTPS
• Health Checks e Target Groups
• Roteamento por hostname/caminho"]
 
    subgraph VPC["VPC"]
        subgraph PUB["Sub-redes Públicas (3 AZs)"]
            NAT["NAT Gateway × 3"]
        end
        subgraph PRIV["Sub-redes Privadas (3 AZs)"]
            NODES["Nós Worker do EKS"]
        end
    end
 
    subgraph EKS["CLUSTER EKS"]
        KARPENTER["KARPENTER — Provisionamento Dinâmico de Nós
──────────────────────────────
• Priorização e consolidação de Spot
• Tratamento de interrupção via SQS
• Classes de nós: geral, intensivo em CPU, banco de dados"]
        KEDA["KEDA — Escalonamento Automático de Pods Baseado em Eventos
──────────────────────────────
• Escalonamento por limite de CPU / Memória
• Estabilização rápida de scale-down"]
        PODS["PODS DE APLICAÇÃO
──────────────────────────────
• Frontend Web (porta 3000)
• Backend FastAPI (porta 8001)
• Workers Celery
• Automator (porta 80)
• Serviços Supabase (Kong, Auth, Storage…)
• PostgreSQL Automator (porta 5432)"]
        SIGNOZ["OBSERVABILIDADE — SigNoz (opcional)
──────────────────────────────
• Rastreamento distribuído, métricas, logs
• Agente k8s-infra para métricas do cluster"]
    end
 
    subgraph DATA["CAMADA DE DADOS"]
        REDIS["ELASTICACHE
(Redis)
──────────
• Criptografia
• Multi-AZ
• Porta 6379"]
        MQ["AMAZON MQ
(RabbitMQ)
──────────
• Fila assíncrona
• AMQP/SSL
• Porta 5671"]
        SUPABASE["SUPABASE
(DB / Auth)
──────────
Opção A: Cloud
Opção B: Auto-hospedado
via CNPG HA no EKS"]
    end
 
    INTERNET --> DNS
    DNS --> ALB
    ALB --> VPC
    PUB --> PRIV
    PRIV --> EKS
    EKS --> DATA
```

<Info>
  O Supabase auto-hospedado usa um cluster PostgreSQL HA gerenciado pelo CloudNativePG (`ha-supabase-db`) com pool PgBouncer, MinIO para armazenamento de objetos e a pilha completa de aplicação do Supabase implantada via `helm-deployment/supabase-kubernetes-ha`. O Supabase Cloud é a alternativa se o auto-hospedagem não for necessário.
</Info>

***

## Componentes Principais

### 1. Camada de Rede

#### Provedor DNS

* **Finalidade:** Resolução de nomes de domínio; funciona com qualquer provedor (Route 53, Cloudflare, etc.)
* **Domínios** (use seu próprio domínio, por exemplo, `example.com`):
  * `app.example.com` — Frontend Web
  * `api.example.com` — Backend FastAPI
  * `automations.example.com` — Serviço Automator
  * `supabase.example.com` — Supabase Kong (apenas auto-hospedado)
  * `signoz.example.com` — Observabilidade SigNoz (opcional)
* **Validação SSL:** Registros CNAME necessários para validação DNS do ACM

#### Balanceador de Carga de Aplicação (ALB)

* **Finalidade:** Terminação SSL, balanceamento de carga e roteamento baseado em hostname
* **Funcionalidades:**
  * Terminação SSL/TLS usando certificados ACM (wildcard ou por serviço)
  * Redirect HTTP → HTTPS
  * Health checks para todos os target groups
* **Gerenciado por:** AWS Load Balancer Controller (chart Helm em `helm-deployment/infrastructure`)

#### VPC

* **CIDR:** Específico do ambiente (por exemplo, `10.x.0.0/16`)
* **Zonas de Disponibilidade:** 3 AZs na região escolhida
* **Sub-redes:** 3 públicas (NAT Gateways) + 3 privadas (nós EKS)
* **Saída:** NAT Gateway por AZ para egress dos nós

***

### 2. Camada de Computação

#### Cluster EKS

* **Versão:** Kubernetes 1.33
* **Node Group do Sistema:** Node group gerenciado executando o controlador Karpenter (não em nós gerenciados por Karpenter, conforme melhor prática da AWS)
* **Add-ons:** EBS CSI Driver, AWS Load Balancer Controller, CoreDNS, kube-proxy

#### Karpenter — Provisionamento Dinâmico de Nós

* **Finalidade:** Provisionamento de nós sob demanda e otimização de custos
* **Classes de Nós:**
  * **Uso Geral:** Instâncias Spot para a maioria das cargas de trabalho
  * **Intensivo em CPU:** Instâncias de alta CPU para tarefas limitadas por CPU
  * **Intensivo em Memória:** Instâncias otimizadas em memória para grandes conjuntos de dados
  * **Banco de Dados:** Instâncias sob demanda para cargas de trabalho de banco de dados/estatais
  * **GPU:** Instâncias GPU para cargas de trabalho de IA/ML (opcional)
* **Funcionalidades:** Priorização de Spot, consolidação automática, tratamento de interrupção baseado em SQS

#### KEDA — Escalonamento Automático Baseado em Eventos do Kubernetes

* **Finalidade:** Escalonamento horizontal de pods baseado em métricas de recursos
* **Alvos:**

| Serviço         | Réplicas | Limite de CPU | Limite de Memória |
| --------------- | -------- | ------------- | ----------------- |
| Frontend Web    | 2–8      | 60%           | 80%               |
| Backend FastAPI | 2–10     | 70%           | 80%               |
| Workers Celery  | 2–8      | 70%           | 80%               |
| Automator       | 2–8      | 70%           | 80%               |

* **Scale-down:** Janela de estabilização de 30s para resposta rápida

***

### 3. Serviços de Aplicação

#### Frontend Web

* **Porta:** 3000
* **Réplicas:** 2–8 (gerenciado pelo KEDA)
* **Finalidade:** Aplicação React servindo a interface do usuário

#### Backend FastAPI

* **Porta:** 8001
* **Réplicas:** 2–10 (gerenciado pelo KEDA)
* **Finalidade:** Servidor REST API tratando lógica de negócio e acesso a dados

#### Workers Celery

* **Réplicas:** 2–8 (gerenciado pelo KEDA)
* **Finalidade:** Processamento de tarefas em segundo plano (enfileiradas via RabbitMQ)

#### Serviço Automator

* **Porta:** 80
* **Réplicas:** 2–8 (gerenciado pelo KEDA)
* **Finalidade:** Automação e orquestração de workflows

#### Supabase Kong

* **Porta:** 8000 (serviço interno do cluster)
* **Finalidade:** API gateway para todos os serviços do Supabase
* **Roteamento:** Tráfego externo alcança Kong via o ingress ALB definido em `odin-services/main-ingress.yaml`

#### SigNoz (opcional)

* **Namespace:** `monitoring`
* **Componentes:** Plataforma SigNoz + agente DaemonSet k8s-infra
* **Finalidade:** Rastreamento distribuído, agregação de métricas, gerenciamento de logs
* **Habilitado por:** `ENABLE_SIGNOZ=true`

***

### 4. Camada de Dados

#### ElastiCache Redis

* **Finalidade:** Cache, armazenamento de sessões e backend de broker/resultados do Celery
* **Configuração:**
  * Tipo de nó: configurável (por exemplo, `cache.t3.micro`)
  * Porta: `6379`
  * Criptografia em repouso e em trânsito
  * Multi-AZ para alta disponibilidade
* **Habilitado por:** `ENABLE_AWS_SERVICES=true`

#### Amazon MQ (RabbitMQ)

* **Finalidade:** Enfileiramento de mensagens para processamento assíncrono de tarefas
* **Configuração:**
  * Engine: RabbitMQ
  * Portas: `5671` (AMQP/SSL), `15671` (Management/SSL)
  * Modo de implantação: instância única ou active/standby
* **Habilitado por:** `ENABLE_AWS_SERVICES=true`

#### Supabase — Opção A: Cloud (gerenciado)

* **Finalidade:** PostgreSQL externo gerenciado, Auth, Storage e Realtime
* **Conexão:** URL do projeto do Supabase e chave de serviço configurados em `values/odin-services.yaml`

#### Supabase — Opção B: Auto-hospedado no EKS

* **Finalidade:** Pilha completa do Supabase rodando dentro do cluster
* **Componentes:**
  * Operador CloudNativePG (`cnpg-system`) — gerencia o ciclo de vida do cluster Postgres
  * HA Supabase DB (`ha-supabase-db`) — Recurso CloudNativePG Cluster com pooler PgBouncer
  * Aplicação do Supabase (namespace `supabase`) — Kong, Auth, Storage (MinIO), Meta, Rest, Realtime, Studio
* **Ordem de implantação:** CloudNativePG → HA Supabase DB → aplicação Supabase
* **Habilitado por:** `ENABLE_CNPG=true`, `ENABLE_HA_SUPABASE_DB=true`, `ENABLE_SUPABASE=true`

#### PostgreSQL Automator

* **Finalidade:** Banco de dados PostgreSQL local para o serviço Automator
* **Porta:** 5432
* **Armazenamento:** Volume persistente EBS
* **Afinidade de nó:** Nós dedicados a banco de dados

***

### 5. Segurança e IAM

#### Funções IAM

| Função                                 | Finalidade                                    |
| -------------------------------------- | --------------------------------------------- |
| Função do Cluster EKS                  | Permissões de API de nível de cluster         |
| Função do Node Group                   | Permissões EC2 dos nós (ECR, SSM, rede)       |
| Função do Controlador Karpenter        | Provisionamento EC2, fila de interrupção SQS  |
| Função do AWS Load Balancer Controller | Gerenciamento ELBv2 e EC2                     |
| Função do EBS CSI Driver               | Gerenciamento do ciclo de vida de volumes EBS |

Os nomes das funções seguem o padrão `<env-name>-<component>` e são criados pelo módulo Terraform do EKS.

#### Grupos de Segurança

* **ALB:** Criado automaticamente pelo AWS Load Balancer Controller (80/443 inbound)
* **Cluster EKS:** Comunicação nó a nó e pod a pod
* **Redis:** Porta 6379 apenas do CIDR da VPC
* **RabbitMQ:** Portas 5671, 15671 apenas do CIDR da VPC

#### SSL/TLS

* **Terminação:** No nível do ALB (pods veem HTTP interno simples)
* **Certificados:** Certificados ACM — seja por serviço ou um único wildcard
* **Validação:** Validação DNS CNAME via seu provedor DNS
* **Protocolo mínimo:** TLS 1.2

***

### 6. Infraestrutura como Código

#### Módulos Terraform

* **`modules/eks`:** Cluster EKS, VPC, node groups, Karpenter, IAM, releases Helm
* **Estado:** Bucket S3 com versionamento, tabela de lock DynamoDB

#### Terragrunt

* **Isolamento de ambiente:** Um diretório por ambiente em `terragrunt/environments/`
* **Template:** `env-template-folder` — copie e preencha os placeholders para criar um novo ambiente
* **Configuração DRY:** `root.hcl` compartilhado com overrides por ambiente
* **Flags de habilitação/desabilitação:** Serviços alternados via variáveis de ambiente (`ENABLE_*`)

#### Charts Helm

| Chart                    | Namespace        | Descrição                             |
| ------------------------ | ---------------- | ------------------------------------- |
| `infrastructure`         | `infrastructure` | Controlador ALB                       |
| `odin-services`          | `default`        | Web, API, Workers, Automator, Ingress |
| `aws-ebs-csi-driver`     | `kube-system`    | Provisionamento de volumes EBS        |
| `keda`                   | `keda`           | Escalonamento automático de pods      |
| `cloudnative-pg`         | `cnpg-system`    | Operador PostgreSQL                   |
| `ha-supabase-db`         | `ha-supabase-db` | Cluster HA Postgres + PgBouncer       |
| `supabase-kubernetes-ha` | `supabase`       | Pilha completa do Supabase            |
| `signoz`                 | `monitoring`     | Plataforma de observabilidade         |
| `k8s-infra`              | `monitoring`     | Agente de métricas do cluster         |

***

## Fluxo de Dados

### 1. Fluxo de Solicitação do Usuário

```
Usuário → DNS → ALB (terminação SSL) → Pod EKS (Frontend Web)
                                   → Pod EKS (Backend FastAPI)
                                   → Pod EKS (Supabase Kong)
```

1. O usuário acessa `app.example.com`
2. O DNS resolve para o ALB
3. O ALB termina SSL e roteia por hostname para o target group correto
4. O Frontend Web serve o aplicativo React e faz chamadas de API para `api.example.com`
5. O Backend FastAPI processa solicitações e lê/escreve nos serviços de dados

### 2. Fluxo de Solicitação da API

```
Cliente → ALB → Backend FastAPI → Redis (cache) / RabbitMQ (fila) / Supabase (DB)
```

1. O cliente chama `api.example.com`
2. O ALB roteia para o pod FastAPI
3. O backend verifica o cache Redis; em caso de falha, consulta o banco de dados Supabase
4. Tarefas assíncronas são enfileiradas no RabbitMQ e processadas pelos Workers Celery

### 3. Fluxo de Processamento em Segundo Plano

```
FastAPI → RabbitMQ → Worker Celery → Supabase DB
```

1. O FastAPI enfileira uma tarefa no RabbitMQ
2. O Worker Celery desenfileira e processa a tarefa
3. Os resultados são gravados de volta no banco de dados Supabase

### 4. Workflow do Automator

```
Automator → PostgreSQL (local) → Redis → APIs Externas
```

1. O Automator recebe uma solicitação de workflow
2. O estado do workflow é persistido na instância PostgreSQL local
3. O Redis armazena em cache resultados intermediários
4. APIs externas são chamadas como parte da automação

### 5. Fluxo de Escalonamento

```
Métricas → KEDA → Escalonamento de pods → Karpenter → Provisionamento de nós
```

1. O KEDA avalia as métricas de CPU/Memória em relação aos limites configurados
2. Os pods são escalonados horizontalmente dentro da faixa de réplicas configurada
3. Se a capacidade do cluster for insuficiente, o Karpenter provisiona novos nós EC2 (preferindo Spot)
4. Quando a carga diminui, o KEDA reduz os pods; o Karpenter consolida e termina nós ociosos

### 6. Fluxo de Segurança

```
Internet → ALB (TLS 1.2+, ACM) → Grupos de Segurança → Pods → Funções IRSA IAM → APIs AWS
```

1. Todo o tráfego externo termina TLS no ALB
2. Os grupos de segurança aplicam acesso de rede de menor privilégio
3. Os pods se comunicam com serviços AWS via IRSA (IAM Roles for Service Accounts)

***

## Resumo de Alta Disponibilidade

| Funcionalidade                   | Implementação                                                          |
| -------------------------------- | ---------------------------------------------------------------------- |
| Implantação Multi-AZ             | 3 AZs para nós EKS, Redis, sub-redes                                   |
| Balanceamento de carga           | ALB com múltiplos target groups                                        |
| Redundância de pods              | Mínimo de 2 réplicas por serviço                                       |
| HA de banco de dados             | Cluster CloudNativePG com PgBouncer (auto-hospedado) ou Supabase Cloud |
| Redundância de cache             | ElastiCache Multi-AZ                                                   |
| Escalonamento automático de nós  | Karpenter com mix Spot + On-Demand                                     |
| Escalonamento automático de pods | KEDA baseado em CPU/Memória                                            |
| Observabilidade                  | SigNoz (opcional)                                                      |
| Gerenciamento de estado          | S3 com versionamento + lock DynamoDB                                   |

***

## Otimização de Custos

* **Instâncias Spot:** O Karpenter prioriza Spot para todas as cargas de trabalho que não são de banco de dados
* **Consolidação de nós:** O Karpenter reivindica automaticamente nós subutilizados
* **Dimensionamento correto de pods:** O KEDA reduz pods durante períodos de baixa atividade
* **On-Demand apenas quando necessário:** A classe de nós de banco de dados usa On-Demand para estabilidade

***

## Manutenção e Operações

### Processo de Implantação

```bash theme={null}
cd terragrunt/environments/<nome-do-seu-ambiente>
# Defina as variáveis de ambiente ENABLE_* e domínio/certificado necessárias
terragrunt apply
# Atualizações contínuas: reaplique após atualizar tags de imagem ou arquivos de valores
```

Consulte o [Guia de Implantação Terragrunt](/on-premise/kubernetes-deployment/terragrunt-deployment.mdx) para a sequência completa de implantação.

### Estratégia de Backup

* **Snapshots EBS:** Snapshots automáticos para volumes persistentes (DB do Automator, Supabase MinIO)
* **CloudNativePG:** Arquivamento WAL contínuo + backups base agendados (se configurado)
* **Supabase Cloud:** Backups diários gerenciados (opção cloud)
* **Estado IaC:** Bucket S3 versionado

### Recuperação de Desastres

* **Multi-AZ:** Todos os serviços estatais abrangem múltiplas zonas de disponibilidade
* **HA CloudNativePG:** Failover automático entre o primário do Postgres e réplicas
* **Supabase Cloud:** Redundância entre regiões (opção cloud)
* **Estado Terraform:** Versionamento S3 permite reversão para qualquer estado anterior

***

## Recursos Adicionais

* [AWS Load Balancer Controller](https://kubernetes-sigs.github.io/aws-load-balancer-controller/)
* [Documentação Karpenter](https://karpenter.sh/docs/)
* [Documentação KEDA](https://keda.sh/docs/)
* [Documentação CloudNativePG](https://cloudnative-pg.io/documentation/)
* [Supabase Self-hosting](https://supabase.com/docs/guides/self-hosting)
* [Documentação SigNoz](https://signoz.io/docs/)
* [Guia de Implantação Terragrunt](/on-premise/kubernetes-deployment/terragrunt-deployment.mdx)