> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-api/caf-api-pt-br/all-id/production-guidance/ecs.md).

# AWS ECS (CDK)

Guia completo para implantar o All ID no AWS ECS Fargate usando CDK.

## Visão geral

Este guia explica como implantar o All ID usando o AWS CDK (Cloud Development Kit) como Infraestrutura como Código.

A implantação requer:

* **CDK da aplicação All ID** (`allid/`) - Serviços da aplicação (ECS, RDS, ALB)
* **VPC existente** - Você deve fornecer um ID de VPC no contexto do CDK

{% hint style="info" %}
**Requisitos de rede**: O CDK do All ID requer uma VPC existente com sub-redes públicas, privadas e isoladas. Se você ainda não tiver uma VPC, a Certta fornece um projeto CDK de referência (`shared/`) que cria uma infraestrutura de rede pronta para produção.
{% endhint %}

{% hint style="success" %}
A Certta fornecerá um pacote contendo:

* Projeto CDK do All ID (obrigatório)
* Projeto CDK de infraestrutura de rede de referência (opcional, use se precisar criar uma nova VPC)
* Exemplos de configuração e documentação
  {% endhint %}

## Pré-requisitos

Antes de implantar, certifique-se de ter:

**Ferramentas**:

* Node.js >= 18.x
* AWS CLI configurado com credenciais
* AWS CDK >= 2.x (`npm install -g aws-cdk`)

**Conta AWS**:

* Conta AWS com permissões adequadas
* Permissões para criar: ECS, RDS, ALB, CloudFormation, roles IAM, grupos de segurança
* Credenciais da AWS configuradas (`aws configure`)

**Infraestrutura de rede**:

* ID de VPC existente com:
  * Sub-redes públicas (mínimo de 2 AZs) para o Application Load Balancer
  * Sub-redes privadas (mínimo de 2 AZs) para serviços ECS
  * Sub-redes isoladas (mínimo de 2 AZs) para o banco de dados RDS
  * Internet Gateway e NAT Gateway configurados

{% hint style="info" %}
**Não tem uma VPC?** A Certta fornece um projeto CDK de referência que cria toda a infraestrutura de rede necessária. Veja [Etapa 2: Infraestrutura de rede](#step-2-network-infrastructure-optional) abaixo.
{% endhint %}

**Imagens de contêiner**:

* Acesso ao registro privado de contêineres da Certta
* URIs dos repositórios ECR para as imagens Peer e Facematch
* Versões/tags de imagem a serem implantadas

{% hint style="warning" %}
**Importante**: Entre em contato com o gerente de conta técnico da Certta para obter:

* Arquivos do projeto CDK (All ID + infraestrutura de rede opcional)
* Credenciais do registro de contêineres e URIs das imagens
* Certificados do serviço Router para comunicação mTLS
  {% endhint %}

## Estrutura do projeto

A Certta fornecerá os arquivos do projeto CDK. A estrutura do pacote:

```
allid-ecs-quickstart/
│
└── src/
    └── cdk/
        │
        ├── allid/                      # Aplicação All ID (obrigatório)
        │   ├── src/
        │   │   ├── main.ts                  # Ponto de entrada principal (orquestra todas as stacks)
        │   │   ├── stacks/
        │   │   │   ├── cluster-stack.ts         # Cluster ECS + Descoberta de serviço
        │   │   │   ├── database-stack.ts        # Aurora MySQL Serverless v2
        │   │   │   ├── load-balancer-stack.ts   # Application Load Balancer
        │   │   │   ├── peer-stack.ts            # Serviços Peer multi-tenant (cria 3 peers)
        │   │   │   └── facematch-stack.ts       # Serviço Facematch (CPU: 1024, RAM: 2 GB)
        │   │   └── constructs/
        │   │       ├── peer-construct.ts        # Instância única do peer (usada pelo peer-stack)
        │   │       ├── task-definition-construct.ts
        │   │       └── fargate-service-construct.ts
        │   ├── utils/                       # Utilitários auxiliares
        │   ├── constants.ts                 # Constantes de configuração
        │   ├── cdk.json                     # Configuração e contexto do CDK
        │   └── package.json
        │
        └── shared/                          # Infraestrutura de rede (opcional)
            ├── src/
            │   ├── stacks/
            │   │   └── network-stack.ts     # VPC, sub-redes, gateways
            │   └── utils/                   # Utilitários auxiliares
            ├── cdk.json                     # Configuração do CDK
            └── package.json
```

{% hint style="info" %}
**A infraestrutura compartilhada é opcional**: Só implante se você precisar criar uma nova VPC. Se você já tiver uma VPC, ignore o `shared/` projeto e configure o ID da sua VPC em `src/cdk/allid/cdk.json`.
{% endhint %}

## Etapa 1: Extrair o projeto CDK

Extraia os arquivos do projeto CDK fornecidos pela Certta:

```bash
# Extrair o pacote
tar -xzf allid-ecs-quickstart.tar.gz
cd allid-ecs-quickstart
```

## Etapa 2: Infraestrutura de rede (opcional)

{% hint style="warning" %}
**Ignore esta etapa se você já tiver uma VPC**. Só implante a infraestrutura compartilhada se você precisar criar uma nova VPC.
{% endhint %}

Se você precisar criar uma nova VPC, implante a infraestrutura de rede de referência:

```bash
# Acessar o projeto shared
cd src/cdk/shared

# Instalar dependências
npm install

# Bootstrap do CDK (somente na primeira vez)
cdk bootstrap

# Definir variáveis de ambiente
export CDK_DEFAULT_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
export CDK_DEFAULT_REGION=us-east-1

# Implantar a infraestrutura de rede
cdk deploy --all --require-approval never
```

**O que é implantado**:

* VPC com blocos CIDR específicos do ambiente
* 2 sub-redes públicas (em 2 zonas de disponibilidade)
* 2 sub-redes privadas (em 2 zonas de disponibilidade)
* 2 sub-redes isoladas (em 2 zonas de disponibilidade) para bancos de dados
* Internet Gateway para acesso público à internet
* NAT Gateway para acesso de saída das sub-redes privadas
* Endpoints de VPC para serviços da AWS (S3, ECR, CloudWatch, Secrets Manager)

**Tempo de implantação**: \~5-10 minutos

Após a implantação, obtenha o ID da VPC:

**Opção 1: Console da AWS**

1. Acesse o Console da VPC → Suas VPCs
2. Encontre a VPC criada pela implantação (procure tags com o prefixo `shared`)
3. Copie o ID da VPC (formato: `vpc-xxxxxxxxxxxxx`)

**Opção 2: AWS CLI**

```bash
# Listar todas as VPCs para encontrar a que você acabou de criar
aws ec2 describe-vpcs --query 'Vpcs[*].[VpcId, Tags[?Key==`Name`].Value | [0], CidrBlock]' --output table
```

Salve este ID da VPC — você vai precisar dele na próxima etapa.

## Etapa 3: Configurar o contexto do CDK

Edite `src/cdk/allid/cdk.json` para configurar sua implantação:

```bash
cd src/cdk/allid
```

**Atualize a seção de contexto** com os valores específicos do seu ambiente:

```json
{
  "context": {
    "prefix": "allid",
    "tags": {
      "business-unity-id": "allid",
      "workload-id": "allid",
      "cost-center": "engenharia"
    },
    "us-east-1": {
      "dev": {
        "vpc-id": "vpc-xxxxxxxxxxxxx",
        "peer-ecr-repository-uri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/peer",
        "peer-version": "v2.6.0",
        "facematch-ecr-repository-uri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/facematch",
        "facematch-version": "v2.6.0",
        "router-rest-url": "https://mtls.us.prd.caf.io/v1/allid"
      }
    }
  }
}
```

**Valores de configuração a serem atualizados**:

| Campo                          | Descrição                                          | Como obter                                                                            |
| ------------------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `vpc-id`                       | Seu ID de VPC                                      | Da Etapa 2 (se a infraestrutura compartilhada foi implantada) ou da sua VPC existente |
| `peer-ecr-repository-uri`      | Registro de contêiner do serviço Peer              | Fornecido pela Certta                                                                 |
| `peer-version`                 | Tag da imagem do Peer a ser implantada             | Fornecido pela Certta (por exemplo, `latest`, hash do commit)                         |
| `facematch-ecr-repository-uri` | Registro de contêiner do Facematch                 | Fornecido pela Certta                                                                 |
| `facematch-version`            | Tag da imagem do Facematch a ser implantada        | Fornecido pela Certta (por exemplo, `latest`, hash do commit)                         |
| `router-rest-url`              | Endpoint do Certta Router para sua região/ambiente | Fornecido pela Certta                                                                 |

{% hint style="info" %}
**Múltiplos ambientes**: Você pode configurar vários ambientes (dev, stg, prd) no mesmo `cdk.json` arquivo. O CDK usará o contexto com base na região e nas variáveis de ambiente.
{% endhint %}

## Etapa 4: Implantar a aplicação All ID

Implante os serviços da aplicação All ID:

```bash
# Certifique-se de estar no diretório allid
cd src/cdk/allid

# Instalar dependências
npm install

# Bootstrap do CDK (somente na primeira vez)
cdk bootstrap

# Definir variáveis de ambiente
export CDK_DEFAULT_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
export CDK_DEFAULT_REGION=us-east-1

# Revisar o que será criado (opcional)
cdk diff

# Implantar todas as stacks da aplicação
cdk deploy --all
```

**O que é implantado**:

1. **Cluster ECS + Descoberta de serviço** (`ClusterStack`)
   * Cluster ECS Fargate
   * Namespace privado do Cloud Map (`allid.local`)
2. **Banco de dados** (`DatabaseStack`)
   * Cluster Aurora MySQL Serverless v2
   * Grupo de segurança do banco de dados
   * Secrets Manager para credenciais (gerado automaticamente)
3. **Balanceador de carga** (`LoadBalancerStack`)
   * Application Load Balancer (voltado para a internet)
   * Listener HTTP (porta 80)
   * Grupo de segurança com whitelisting de IP
4. **Serviço Facematch** (`FacematchStack`)
   * Definição de tarefa ECS (CPU: 1024, Memória: 2048 MB)
   * Serviço Fargate com 2 instâncias
   * Registro de serviço do Cloud Map (`facematch.allid.local`)
   * Grupo de segurança para comunicação interna
5. **Serviços Peer** (`PeerStack`)
   * Cria 3 instâncias Peer (default, client-a, client-b)
   * Cada peer tem:
     * Definição de tarefa ECS (CPU: 256, Memória: 512 MB)
     * Serviço Fargate com 1 instância
     * Grupo de destino do ALB com roteamento baseado em caminho
     * Registro de serviço do Cloud Map
     * Conexão do banco de dados com o RDS
     * Segredo do certificado mTLS do Router (placeholder)

**Tempo de implantação**: \~15-20 minutos

{% hint style="info" %}
O CDK trata automaticamente das dependências das stacks e as implanta na ordem correta: cluster → banco de dados → load balancer → facematch → peer.
{% endhint %}

{% hint style="warning" %}
**Importante**: Após a implantação, os Serviços Peer inicialmente falharão ao iniciar. Você deve concluir as Etapas 5 e 6 (inicialização do banco de dados e atualização dos certificados do Router) para torná-los operacionais. Os serviços reiniciarão automaticamente e ficarão íntegros assim que essas etapas forem concluídas.
{% endhint %}

## Etapa 5: Inicializar o banco de dados

O Serviço Peer requer que um esquema de banco de dados seja inicializado. A Certta fornecerá um arquivo de dump SQL que deve ser restaurado no banco de dados Aurora MySQL.

{% hint style="danger" %}
**Crítico**: Os Serviços Peer estão falhando ao iniciar porque o esquema do banco de dados não foi inicializado. Conclua esta etapa para permitir que os serviços se tornem operacionais.
{% endhint %}

{% hint style="info" %}
**Configuração multi-tenant**: Cada instância peer usa seu próprio banco de dados. Os nomes dos bancos seguem o padrão `peer-{name}`:

* `peer-default` (para o peer padrão)
* `peer-client-a` (para o peer client-a)
* `peer-client-b` (para o peer client-b)
  {% endhint %}

### Métodos de acesso ao banco de dados

O banco de dados Aurora MySQL é implantado em sub-redes isoladas, sem acesso direto à internet. Você precisa estabelecer uma conexão segura para acessá-lo.

**Opção 1: Host bastion (recomendado para produção)**

Implante um host bastion (instância EC2) em uma sub-rede pública para atuar como servidor de salto:

1. Inicie uma instância EC2 em uma sub-rede pública da sua VPC
2. Configure os grupos de segurança para permitir:
   * Acesso SSH do seu IP ao host bastion
   * Acesso MySQL do host bastion ao grupo de segurança do RDS
3. Conecte-se ao banco de dados por meio de túnel SSH:

```bash
# Túnel SSH para o host bastion
ssh -i your-key.pem -L 3306:DATABASE_ENDPOINT:3306 ec2-user@BASTION_IP

# Em outro terminal, conecte-se ao banco de dados via localhost
mysql -h 127.0.0.1 -u DB_USERNAME -p
```

**Opção 2: Conexão VPN**

Se você tiver uma conexão VPN configurada para a sua VPC:

1. Conecte-se à sua VPN
2. Acesse o banco de dados diretamente usando seu endpoint privado

**Opção 3: AWS Systems Manager Session Manager**

Use o Session Manager para acesso seguro sem expor portas SSH:

1. Certifique-se de que seu host bastion tenha o agente SSM instalado
2. Conceda as permissões IAM necessárias
3. Criar sessão de encaminhamento de porta:

```bash
aws ssm start-session \
  --target INSTANCE_ID \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{"portNumber":["3306"],"localPortNumber":["3306"],"host":["DATABASE_ENDPOINT"]}'
```

**Opção 4: Acesso público temporário (somente desenvolvimento)**

{% hint style="danger" %}
**Não recomendado para produção**: Use este método somente para ambientes de desenvolvimento/teste.
{% endhint %}

1. Modifique temporariamente o grupo de segurança do RDS para permitir o seu IP
2. Torne a instância RDS acessível publicamente (requer modificação)
3. Reverta as alterações após a inicialização do banco de dados

### Obtenha o endpoint e as credenciais do banco de dados

**Opção 1: Console da AWS**

1. Acesse o Console do RDS → Bancos de dados
2. Encontre o cluster Aurora (procure pelo nome com `allid-database`)
3. Copie o **endpoint do writer** (ex.: `allid-database-cluster.cluster-xxx.us-east-1.rds.amazonaws.com`)
4. Acesse o Console do Secrets Manager → Secrets
5. Encontre o segredo do banco de dados (procure pelo nome com `allid-database`)
6. Clique em "Recuperar valor secreto" para ver o usuário e a senha

**Opção 2: AWS CLI**

```bash
# Listar clusters RDS para encontrar seu banco de dados
aws rds describe-db-clusters --query 'DBClusters[*].[DBClusterIdentifier, Endpoint, Port]' --output table

# Listar segredos para encontrar as credenciais do banco de dados
aws secretsmanager list-secrets --query 'SecretList[*].[Name, ARN]' --output table

# Obtenha o valor específico do segredo (substitua SECRET_ARN pelo ARN real acima)
aws secretsmanager get-secret-value --secret-id SECRET_ARN --query 'SecretString' --output text | jq
```

### Criar e inicializar bancos de dados

Você pode usar qualquer uma das ferramentas abaixo para criar os bancos de dados e restaurar o dump:

#### Opção A: Cliente de linha de comando MySQL

Melhor para automação e pipelines de CI/CD:

```bash
# Conecte-se ao Aurora MySQL (substitua pelo seu endpoint, usuário e senha acima)
mysql -h {DB_ENDPOINT} -u {DB_USERNAME} -p

# Criar bancos de dados
CREATE DATABASE IF NOT EXISTS `peer-default`;
CREATE DATABASE IF NOT EXISTS `peer-client-a`;
CREATE DATABASE IF NOT EXISTS `peer-client-b`;
EXIT;

# Restaure o dump em cada banco de dados (a Certta fornecerá o arquivo de dump SQL)
mysql -h {DB_ENDPOINT} -u {DB_USERNAME} -p peer-default < allid-dump.sql
mysql -h {DB_ENDPOINT} -u {DB_USERNAME} -p peer-client-a < allid-dump.sql
mysql -h {DB_ENDPOINT} -u {DB_USERNAME} -p peer-client-b < allid-dump.sql
```

#### Opção B: DBeaver (ferramenta GUI)

Recomendado para gerenciamento visual do banco de dados:

1. **Criar uma nova conexão**:
   * Banco de dados: MySQL
   * Host: `{DB_ENDPOINT}` (acima)
   * Porta: 3306
   * Usuário: `{DB_USERNAME}` (do Secrets Manager)
   * Senha: `{DB_PASSWORD}` (do Secrets Manager)
2. **Criar bancos de dados**:

   * Clique com o botão direito na conexão → Editor SQL → Novo Script SQL
   * Executar:

   ```sql
   CREATE DATABASE IF NOT EXISTS `peer-default`;
   CREATE DATABASE IF NOT EXISTS `peer-client-a`;
   CREATE DATABASE IF NOT EXISTS `peer-client-b`;
   ```
3. **Restaurar dump**:
   * Clique com o botão direito em cada banco de dados → Ferramentas → Executar Script
   * Selecione o `allid-dump.sql` arquivo fornecido pela Certta
   * Clique em "Start" para executar

#### Opção C: MySQL Workbench (Ferramenta GUI)

Ferramenta GUI alternativa para gerenciamento do MySQL:

1. **Criar uma nova conexão**:
   * Nome da conexão: `Banco de dados All ID`
   * Nome do host: `{DB_ENDPOINT}`
   * Porta: 3306
   * Usuário: `{DB_USERNAME}`
   * Senha: Armazenar no Keychain/Vault
2. **Criar bancos de dados**:

   * Abra a conexão → aba Query
   * Executar:

   ```sql
   CREATE DATABASE IF NOT EXISTS `peer-default`;
   CREATE DATABASE IF NOT EXISTS `peer-client-a`;
   CREATE DATABASE IF NOT EXISTS `peer-client-b`;
   ```
3. **Importar dump**:
   * Servidor → Importação de dados
   * Selecione "Import from Self-Contained File"
   * Escolha `allid-dump.sql` arquivo
   * Selecione o banco de dados de destino (repita para cada um: peer-default, peer-client-a, peer-client-b)
   * Clique em "Start Import"

#### Opção D: phpMyAdmin (Interface Web)

Se você tiver o phpMyAdmin implantado no seu ambiente:

1. Faça login no phpMyAdmin
2. Crie bancos de dados usando o botão "New"
3. Selecione cada banco de dados e use a aba "Import" para enviar e executar o arquivo de dump SQL

{% hint style="info" %}
**Solução de problemas de conexão**: Se você não conseguir se conectar ao banco de dados, verifique:

* Você estabeleceu acesso adequado (host bastion, VPN ou Session Manager)
* O grupo de segurança do RDS permite conexões da sua origem
* O endpoint e as credenciais do banco de dados estão corretos
  {% endhint %}

{% hint style="danger" %}
**Crítico**: Cada Peer Service falhará ao iniciar se o banco de dados correspondente não estiver inicializado. Entre em contato com o gerente técnico de conta da Certta para obter o arquivo de dump SQL.
{% endhint %}

## Etapa 6: Atualizar certificados mTLS do Router

Os Peer Services exigem certificados mTLS para se comunicar com o Router Service da Certta. O CDK criou automaticamente segredos de placeholder durante a implantação. Você deve atualizar esses segredos com os certificados reais antes que os Peer Services possam iniciar com sucesso.

{% hint style="warning" %}
**Valores de placeholder**: O CDK criou segredos com texto de placeholder `SUBSTITUA_PELA_CHAVE_PRIVADA_REAL` e `SUBSTITUA_PELO_CERTIFICADO_REAL`. Os Peer Services estão falhando ao iniciar até que você substitua isso por certificados reais.
{% endhint %}

**Atualize os segredos de certificado para cada instância peer**:

**Opção 1: Console da AWS** (recomendado)

1. Acesse o Console do Secrets Manager → Secrets
2. Encontre e clique em cada segredo:
   * `allid-peer-default-router-certificate`
   * `allid-peer-client-a-router-certificate`
   * `allid-peer-client-b-router-certificate`
3. Clique em "Retrieve secret value" → "Edit"
4. Atualize o JSON com seus certificados reais:

```json
{
  "private-key": "-----BEGIN PRIVATE KEY-----\nMIIE...content...\n-----END PRIVATE KEY-----",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIID...content...\n-----END CERTIFICATE-----"
}
```

5. Salvar alterações

**Opção 2: AWS CLI**

```bash
# Atualize o certificado padrão do peer (substitua pelo conteúdo real)
aws secretsmanager update-secret \\
  --secret-id allid-peer-default-router-certificate \\
  --secret-string '{
    "private-key": "-----BEGIN PRIVATE KEY-----\nYOUR_KEY_HERE\n-----END PRIVATE KEY-----",
    "certificate": "-----BEGIN CERTIFICATE-----\nYOUR_CERT_HERE\n-----END CERTIFICATE-----"
  }'

# Atualize o certificado do peer client-a
aws secretsmanager update-secret \\
  --secret-id allid-peer-client-a-router-certificate \\
  --secret-string '{
    "private-key": "-----BEGIN PRIVATE KEY-----\nYOUR_KEY_HERE\n-----END PRIVATE KEY-----",
    "certificate": "-----BEGIN CERTIFICATE-----\nYOUR_CERT_HERE\n-----END CERTIFICATE-----"
  }'

# Atualize o certificado do peer client-b
aws secretsmanager update-secret \\
  --secret-id allid-peer-client-b-router-certificate \\
  --secret-string '{
    "private-key": "-----BEGIN PRIVATE KEY-----\nYOUR_KEY_HERE\n-----END PRIVATE KEY-----",
    "certificate": "-----BEGIN CERTIFICATE-----\nYOUR_CERT_HERE\n-----END CERTIFICATE-----"
  }'
```

{% hint style="danger" %}
**Crítico**: Entre em contato com o gerente de conta técnico da Certta para obter:

* arquivos de certificado mTLS (chave privada e certificado) para seu ambiente
* Instruções adequadas de formatação para os certificados
  {% endhint %}

{% hint style="info" %}
**Formatação dos certificados**: Se você tiver arquivos de certificado (`.pem` ou `.key` arquivos), você precisa formatá-los para JSON substituindo quebras de linha por `\n`. O Console da AWS lida com isso automaticamente quando você cola certificados multilinha no modo texto simples.

Para usuários de CLI, você pode usar ferramentas de processamento de texto como `awk` ou `sed` para formatar os certificados, ou usar o console para um gerenciamento mais fácil.
{% endhint %}

{% hint style="success" %}
**Os serviços se recuperarão automaticamente**: Depois que você atualizar os certificados, os Peer Services reiniciarão automaticamente e ficarão saudáveis em poucos minutos. O ECS detectará a alteração de configuração e fará o redeploy das tasks.
{% endhint %}

## Etapa 7: Obter endpoints

Após a conclusão da implantação, obtenha o endpoint da aplicação:

**Opção 1: Console da AWS**

1. Navegue até o Console EC2 → Load Balancers
2. Encontre o load balancer (procure pelo nome com `allid-load-balancer`)
3. Copie o **nome DNS** (ex.: `allid-load-balancer-123456789.us-east-1.elb.amazonaws.com`)

**Opção 2: AWS CLI**

```bash
# Liste todos os load balancers para encontrar o seu
aws elbv2 describe-load-balancers --query 'LoadBalancers[*].[LoadBalancerName, DNSName]' --output table
```

{% hint style="info" %}
A implantação cria 3 instâncias peer com roteamento baseado em caminho para suporte multi-tenant. Cada peer tem seu próprio endpoint isolado com prefixo de caminho.
{% endhint %}

**Endpoints da API** (3 instâncias peer por padrão):

```
# Peer padrão
http://{alb-dns}/default/v1/biometric-validation-responder

# Peer do Cliente A
http://{alb-dns}/client-a/v1/biometric-validation-responder

# Peer do Cliente B
http://{alb-dns}/client-b/v1/biometric-validation-responder
```

**Endpoints de verificação de saúde**:

```
http://{alb-dns}/default/status
http://{alb-dns}/client-a/status
http://{alb-dns}/client-b/status
```

{% hint style="warning" %}
Para adicionar/remover peers, edite `src/cdk/allid/src/stacks/peer-stack.ts` e modifique o `peerConfigs` array. Lembre-se de criar o banco de dados correspondente e atualizar o segredo do certificado do Router para novos peers ANTES de implantar.
{% endhint %}

## Etapa 8: Validar a implantação

Teste se todos os serviços estão saudáveis:

**Teste os endpoints dos peers** (usando o DNS do ALB da Etapa 7):

```bash
# Substitua {URL} pelo seu nome DNS real do ALB
curl -f http://{URL}/default/status
curl -f http://{URL}/client-a/status
curl -f http://{URL}/client-b/status
```

Todos os endpoints devem retornar HTTP 200 com informações de status.

**Verifique o status dos serviços ECS**:

**Console da AWS**:

1. Navegue até o Console do ECS → Clusters → `allid-cluster`
2. Clique na aba "Services"
3. Verifique se todos os serviços mostram status "Running" e se desired count corresponde ao running count

**AWS CLI**:

```bash
# Liste todos os serviços no cluster
aws ecs list-services --cluster allid-cluster --output table

# Verifique o status detalhado (substitua os nomes dos serviços se forem diferentes)
aws ecs describe-services \\
  --cluster allid-cluster \\
  --services peer-default peer-client-a peer-client-b facematch \\
  --query 'services[*].[serviceName, runningCount, desiredCount]' \\
  --output table
```

Todos os serviços devem mostrar `runningCount` correspondendo a `desiredCount`.

**Verifique os logs do CloudWatch** (se os serviços falharem ao iniciar):

**Console da AWS**:

1. Navegue até o Console do CloudWatch → Grupos de logs
2. Encontre grupos de logs: `/ecs/allid/peer-default`, `/ecs/allid/facematch`, etc.
3. Verifique os streams de log recentes em busca de erros

**AWS CLI**:

```bash
# Liste os grupos de logs
aws logs describe-log-groups --log-group-name-prefix /ecs/allid --output table

# Acompanhe o log específico (substitua o nome do grupo de logs)
aws logs tail /ecs/allid/peer-default --follow
```

## Visão geral da arquitetura

### Camadas de rede

A implantação cria uma arquitetura de rede de três camadas:

```
┌─────────────────────────────────────────┐
│ Sub-redes públicas (2 AZs)                  │
│ • Application Load Balancer             │
│ • Internet Gateway                      │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│ Sub-redes privadas (2 AZs)                 │
│ • Serviço Peer (ECS Fargate)            │
│ • Serviço Facematch (ECS Fargate)       │
│ • NAT Gateway (internet de saída)       │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│ Sub-redes isoladas (2 AZs)                │
│ • Banco de dados Aurora MySQL                 │
│ • Sem acesso à internet                    │
└─────────────────────────────────────────┘
```

### Comunicação entre serviços

```
Internet → ALB (HTTP:80) → Peer (8080) → Facematch (8080)
                              ↓
                         Banco de dados (3306)
```

### Roteamento baseado em caminho (multi-tenant)

O ALB usa roteamento baseado em caminho para suportar várias instâncias peer:

```
/default/*   → peer-default   (Target Group 1)
/client-a/*  → peer-client-a  (Target Group 2)
/client-b/*  → peer-client-b  (Target Group 3)
```

Cada instância peer:

* Tem seu próprio serviço ECS
* Tem seu próprio banco de dados isolado (peer-default, peer-client-a, peer-client-b)
* Opera independentemente dos outros peers
* Compartilha o mesmo pool de serviço Facematch

## Gerenciamento de configuração

O projeto CDK configura automaticamente variáveis de ambiente e segredos para todos os serviços.

**Variáveis de ambiente** são definidas em `src/cdk/allid/src/constructs/peer-construct.ts` e incluem:

* Conexão com o banco de dados (host, porta, nome do banco de dados)
* Endpoint do serviço Facematch
* URL do Router Service
* Flags de recursos (RabbitMQ, Redis, comunicação com o Router)

**Segredos** são injetados via segredos da task ECS e incluem:

* Credenciais do banco de dados (geradas automaticamente pelo CDK)
* Certificados mTLS do Router (criados com placeholders, devem ser atualizados manualmente)

{% hint style="info" %}
Veja [Configuração](/caf-api/caf-api-pt-br/all-id/configuration.md) para a lista completa de variáveis de ambiente, valores necessários e detalhes de configuração.
{% endhint %}

### Gerenciamento de segredos

O CDK cria automaticamente segredos no AWS Secrets Manager:

**Convenção de nomenclatura dos segredos**:

* Credenciais do banco de dados: `allid-database-secret-<random-suffix>`
* Certificados do Router: `allid-peer-{name}-router-certificate` (ex.: `allid-peer-default-router-certificate`)

{% hint style="warning" %}
Os segredos do certificado do Router são criados com valores de placeholder durante a implantação. Você deve atualizá-los com certificados reais antes que os Peer Services possam iniciar com sucesso (veja a Etapa 6).
{% endhint %}

## Segurança

O CDK configura automaticamente grupos de segurança e whitelist de IP seguindo os princípios de menor privilégio.

**Grupos de segurança**:

* O ALB aceita tráfego apenas de IPs na whitelist
* Os Peer Services aceitam tráfego apenas do ALB e da VPC interna
* O Facematch aceita tráfego apenas dos Peer Services
* O banco de dados aceita tráfego apenas dos Peer Services

**Whitelist de IP**:

* O ALB está configurado para aceitar tráfego apenas dos endereços IP do Certta Router
* Configure IPs adicionais em `src/cdk/allid/src/stacks/load-balancer-stack.ts`

{% hint style="info" %}
Veja [Melhores práticas de segurança](/caf-api/caf-api-pt-br/all-id/security-best-practices.md) para:

* Lista completa de endereços IP do Certta Router
* Recomendações de segmentação de rede
* Melhores práticas de gerenciamento de segredos
* Opções adicionais de fortalecimento de segurança
  {% endhint %}

## Atualizando a implantação

### Atualize as imagens dos contêineres

1. Atualize as versões das imagens em `src/cdk/allid/cdk.json`:

```json
{
  "context": {
    "us-east-1": {
      "dev": {
        "peer-version": "new-commit-hash",
        "facematch-version": "new-commit-hash"
      }
    }
  }
}
```

2. Reimplante as stacks afetadas:

```bash
cd src/cdk/allid

# Reimplante os Peer Services (implanta os 3 peers)
cdk deploy allid-peer

# Reimplante o serviço Facematch
cdk deploy allid-facematch
```

### Atualize as variáveis de ambiente

1. Edite as variáveis em `src/cdk/allid/src/constructs/peer-construct.ts`
2. Reimplante a stack Peer:

```bash
cd src/cdk/allid
cdk deploy allid-peer
```

Isso atualizará todas as instâncias peer (default, client-a, client-b) com a nova configuração.

### Dimensionar serviços

**Dimensionar Peer Services**: Edite o desired count em `src/cdk/allid/src/constructs/peer-construct.ts`:

```typescript
desiredCount: 2, // Alterar de 1 para 2
minHealthyPercent: 50,
maxHealthyPercent: 200,
```

Depois reimplante:

```bash
cdk deploy allid-peer
```

**Dimensionar serviço Facematch**: Edite o desired count em `src/cdk/allid/src/stacks/facematch-stack.ts`:

```typescript
desiredCount: 4, // Alterar de 2 para 4
```

Depois reimplante:

```bash
cdk deploy allid-facematch
```

### Adicionar/remover instâncias peer

Para adicionar uma nova instância peer:

1. **Edite a configuração do CDK** em `src/cdk/allid/src/stacks/peer-stack.ts`:

```typescript
const peerConfigs: PeerConfig[] = [
  { name: "default" },
  { name: "client-a" },
  { name: "client-b" },
  { name: "client-c" },  // Adicionar novo peer
];
```

2. **Implante a stack Peer atualizada**:

```bash
cdk deploy allid-peer
```

O CDK criará automaticamente o segredo do certificado do Router com valores de placeholder.

3. **Crie e inicialize o banco de dados** para o novo peer (veja a Etapa 5):

```bash
mysql -h {DB_ENDPOINT} -u {DB_USERNAME} -p

CREATE DATABASE IF NOT EXISTS `peer-client-c`;
EXIT;

# Restaure o dump
mysql -h {DB_ENDPOINT} -u {DB_USERNAME} -p peer-client-c < allid-dump.sql
```

4. **Atualize o segredo do certificado do Router** com certificados reais (veja a Etapa 6):

```bash
aws secretsmanager update-secret \\
  --secret-id allid-peer-client-c-router-certificate \\
  --secret-string '{
    "private-key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
    "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  }'
```

{% hint style="info" %}
O novo Peer Service falhará ao iniciar inicialmente (como na implantação inicial), mas ficará saudável automaticamente após você concluir as etapas 3 e 4 (inicialização do banco de dados e atualização do certificado).
{% endhint %}

## Solução de problemas

### A implantação falha com "VPC not found"

**Causa**: O ID da VPC não foi configurado corretamente em `cdk.json` ou a VPC não existe.

**Solução**:

1. **Verifique o ID da VPC**:
   * Console da AWS: Navegue até o Console da VPC → Suas VPCs
   * Procure a VPC que você deseja usar e copie o ID da VPC
2. **Se você não tiver uma VPC**, implante a infraestrutura compartilhada (veja a Etapa 2):

```bash
cd src/cdk/shared
npm install
cdk bootstrap
cdk deploy --all --require-approval never
```

3. **Obtenha o ID da VPC**:
   * Console da AWS: Console da VPC → Suas VPCs → encontre sua VPC
   * AWS CLI: Liste todas as VPCs:

```bash
aws ec2 describe-vpcs --query 'Vpcs[*].[VpcId, CidrBlock, Tags[?Key==`Name`].Value | [0]]' --output table
```

4. **Atualize `src/cdk/allid/cdk.json`** com o ID correto da VPC:

```json
{
  "context": {
    "us-east-1": {
      "dev": {
        "vpc-id": "vpc-xxxxxxxxxxxxx"
      }
    }
  }
}
```

5. **Reimplante**:

```bash
cd src/cdk/allid
cdk deploy --all --require-approval never
```

### O Peer Service não inicia

**Verifique os logs do CloudWatch**:

**Console da AWS**:

1. Console do CloudWatch → Grupos de logs
2. Encontre `/ecs/allid/peer-default` (ou peer-client-a, peer-client-b)
3. Clique no stream de log mais recente
4. Procure mensagens de erro nos logs

**AWS CLI**:

```bash
# Acompanhe os logs para um peer específico
aws logs tail /ecs/allid/peer-default --follow
```

**Causas comuns**:

1. **Banco de dados não inicializado**: Veja a Etapa 5 (inicialização do banco de dados e restauração do dump)
2. **Certificados do Router não atualizados**: Veja a Etapa 6 (atualize os segredos com certificados reais) - o CDK cria segredos com valores de placeholder que devem ser substituídos
3. **Falha na conexão com o banco de dados**: Verifique os grupos de segurança e o endpoint do RDS
4. **Serviço Facematch indisponível**: Verifique o status do serviço Facematch

**Verifique o motivo de parada da task**:

**Console da AWS**:

1. Console do ECS → Clusters → allid-cluster
2. Clique no serviço (ex.: peer-default)
3. Vá para a aba "Tasks" → Clique nas tasks paradas
4. Verifique o campo "Stopped reason"

### Falhas na verificação de saúde

**Verifique o status do serviço ECS**:

**Console da AWS**:

1. Console do ECS → Clusters → allid-cluster → Services
2. Verifique o status de cada serviço
3. Veja a aba "Events" para mensagens recentes

**Verifique a saúde dos targets do ALB**:

**Console da AWS**:

1. Console do EC2 → Target Groups
2. Encontre target groups com `allid` prefixo
3. Clique em cada target group
4. Vá para a aba "Targets"
5. Verifique o status de saúde dos targets registrados (deve ser "healthy")

**AWS CLI**:

```bash
# Listar target groups
aws elbv2 describe-target-groups --query 'TargetGroups[?contains(TargetGroupName, `allid`)][TargetGroupName, TargetGroupArn]' --output table

# Verificar a saúde (substitua TARGET_GROUP_ARN pelo ARN real acima)
aws elbv2 describe-target-health --target-group-arn TARGET_GROUP_ARN
```

**Problemas comuns**:

* Security groups bloqueando o tráfego entre o ALB e os Peer Services
* Serviço não registrado no Cloud Map (a resolução DNS falha)
* Erros de conexão com o banco de dados (verifique o secret de credenciais)
* Serviço Facematch não respondendo

### Não consegue acessar o ALB

**Verifique se seu IP está na allowlist**:

```bash
# Substitua {URL} pelo DNS real do seu ALB
curl -v http://{URL}/default/status
```

Se você receber timeout de conexão ou 403 Forbidden, seu IP não está na allowlist.

**Verifique o security group do ALB**:

**Console da AWS**:

1. Console do EC2 → Load Balancers → Encontre seu ALB
2. Clique na aba "Security"
3. Clique no security group
4. Verifique "Inbound rules" - confira se seu IP está permitido

**Adicione seu IP à allowlist**:

1. Edite `src/cdk/allid/src/stacks/load-balancer-stack.ts`:

```typescript
const allowedCidrBlocks = [
  // Adicione seu IP à lista
  "YOUR_IP_HERE/32",
];
```

2. Redeploy:

```bash
cd src/cdk/allid
cdk deploy allid-load-balancer
```

{% hint style="info" %}
Veja [Melhores práticas de segurança](/caf-api/caf-api-pt-br/all-id/security-best-practices.md) para a lista completa de endereços IP do Certta Router que devem estar na allowlist.
{% endhint %}

## Limpeza

Para remover todos os recursos e parar de incorrer em custos:

```bash
# Destruir a aplicação All ID (na ordem de dependência)
cd src/cdk/allid

cdk destroy allid-peer
cdk destroy allid-facematch
cdk destroy allid-load-balancer
cdk destroy allid-database
cdk destroy allid-cluster

# Destruir a infraestrutura compartilhada (somente se você a tiver implantado)
cd ../shared
cdk destroy --all
```

{% hint style="danger" %}
**Aviso**: Isso exclui permanentemente todos os recursos, incluindo:

* Banco de dados Aurora MySQL e todos os dados
* logs do CloudWatch
* Secrets do Secrets Manager (credenciais do banco de dados, certificados do Router)
* Serviços e tasks do ECS

Certifique-se de ter backups antes de destruir. Snapshots do banco de dados NÃO são criados automaticamente durante a destruição.
{% endhint %}

**Criar snapshot do banco de dados antes da limpeza** (opcional):

```bash
aws rds create-db-cluster-snapshot \
  --db-cluster-identifier allid-database-cluster \
  --db-cluster-snapshot-identifier allid-final-snapshot-$(date +%Y%m%d)
```

## Próximas etapas

* Revisar [Requisitos técnicos](/caf-api/caf-api-pt-br/all-id/technical-requirements.md) para especificações de recursos
* Revisar [Configuração](/caf-api/caf-api-pt-br/all-id/configuration.md) para detalhes das variáveis de ambiente
* Revisar [Melhores práticas de segurança](/caf-api/caf-api-pt-br/all-id/security-best-practices.md) para endurecimento


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/caf-api/caf-api-pt-br/all-id/production-guidance/ecs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.