> 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 a AWS CDK (Cloud Development Kit) como Infrastructure as Code.

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á a você 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 configurada com credenciais
* AWS CDK >= 2.x (`npm install -g aws-cdk`)

**Conta da AWS**:

* Conta da AWS com permissões apropriadas
* Permissões para criar: ECS, RDS, ALB, CloudFormation, papéis 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 2 AZs) para o Application Load Balancer
  * Sub-redes privadas (mínimo 2 AZs) para serviços ECS
  * Sub-redes isoladas (mínimo 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êiner da Certta
* URIs do repositório ECR para as imagens Peer e Facematch
* Versões/tags das imagens a serem implantadas

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

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

## Estrutura do projeto

A Certta fornecerá a você arquivos do projeto CDK. A estrutura do pacote:

```
allid-ecs-quickstart/
│
└── src/
    └── cdk/
        │
        ├── allid/                      # Aplicação All ID (obrigatória)
        │   ├── src/
        │   │   ├── main.ts                  # Ponto de entrada principal (orquestra todas as stacks)
        │   │   ├── stacks/
        │   │   │   ├── cluster-stack.ts         # Cluster ECS + Service Discovery
        │   │   │   ├── 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 de 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**: Implante somente se você precisar criar uma nova VPC. Se você já tiver uma VPC, pule 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" %}
**Pule esta etapa se você já tiver uma VPC**. Implante a infraestrutura compartilhada somente se você precisar criar uma nova VPC.
{% endhint %}

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

```bash
# Navegar para o projeto shared
cd src/cdk/shared

# Instalar dependências
npm install

# Inicializar o 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. Navegue até 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ê 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": "engineering"
    },
    "us-east-1": {
      "dev": {
        "vpc-id": "vpc-xxxxxxxxxxxxx",
        "peer-ecr-repository-uri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/peer-v2",
        "peer-version": "latest",
        "facematch-ecr-repository-uri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/facematch",
        "facematch-version": "latest",
        "router-rest-url": "https://mtls.us.prd.caf.io/v1/allid"
      }
    }
  }
}
```

**Valores de configuração a atualizar**:

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

{% hint style="info" %}
**Múltiplos ambientes**: Você pode configurar múltiplos 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 que você está no diretório allid
cd src/cdk/allid

# Instalar dependências
npm install

# Inicializar o 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 + Service Discovery** (`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 (geradas automaticamente)
3. **Balanceador de carga** (`LoadBalancerStack`)
   * Application Load Balancer (voltado para a internet)
   * Listener HTTP (porta 80)
   * Grupo de segurança com whitelist de IPs
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 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-alvo do ALB com roteamento baseado em caminho
     * Registro de serviço Cloud Map
     * Conexão de 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 lida automaticamente com as dependências entre as 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 serão reiniciados automaticamente e ficarão saudáveis 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-{nome}`:

* `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 para o host bastion
   * Acesso MySQL do host bastion para o grupo de segurança do RDS
3. Conecte-se ao banco de dados por meio de um 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 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. Garanta que seu host bastion tenha o agente SSM instalado
2. Conceda as permissões IAM necessárias
3. Crie uma 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 seu IP
2. Torne a instância RDS publicamente acessível (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. Navegue até o Console do RDS → Bancos de dados
2. Encontre o cluster Aurora (procure o nome com `allid-database`)
3. Copie o **endpoint do escritor** (por exemplo, `allid-database-cluster.cluster-xxx.us-east-1.rds.amazonaws.com`)
4. Navegue até o Console do Secrets Manager → Secrets
5. Encontre o segredo do banco de dados (procure o nome com `allid-database`)
6. Clique em "Retrieve secret value" para ver nome de usuário e 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

# Obter 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 a seguir para criar 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, nome de 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;

# Restaurar 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
   * Nome de 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
   * Nome de usuário: `{DB_USERNAME}`
   * Senha: armazenar no Keychain/Vault
2. **Criar bancos de dados**:

   * Abra a conexão → guia Consulta
   * 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 "Importar de arquivo autônomo"
   * 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 "Iniciar importação"

#### Opção D: phpMyAdmin (interface web)

Se você tiver o phpMyAdmin implantado em seu ambiente:

1. Faça login no phpMyAdmin
2. Crie os bancos de dados usando o botão "Novo"
3. Selecione cada banco de dados e use a aba "Importar" 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 o 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 Serviço Peer falhará ao iniciar se o banco de dados correspondente não estiver inicializado. Entre em contato com seu gerente técnico de contas da Certta para obter o arquivo de dump SQL.
{% endhint %}

## Etapa 6: Atualizar certificados mTLS do Router

Os Serviços Peer exigem certificados mTLS para se comunicar com o Serviço Router 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 Serviços Peer possam iniciar com sucesso.

{% hint style="warning" %}
**Valores de placeholder**: O CDK criou segredos com texto de placeholder `REPLACE_WITH_ACTUAL_PRIVATE_KEY` e `REPLACE_WITH_ACTUAL_CERTIFICATE`. Os Serviços Peer não conseguem iniciar até que você substitua estes por certificados reais.
{% endhint %}

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

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

1. Navegue até o Console do Secrets Manager → Secrets
2. Localize 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 "Recuperar valor do segredo" → "Editar"
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 peer padrão (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 peer do 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 peer do 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 seu gerente técnico de conta da Certta para obter:

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

{% hint style="info" %}
**Formatação de certificados**: Se você tiver arquivos de certificado (`.pem` ou `.key` ), 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 de texto simples.

Para usuários da 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 Serviços Peer reiniciarão automaticamente e ficarão saudáveis em alguns minutos. O ECS detectará a mudança de configuração e reimplantará as tarefas.
{% endhint %}

## Etapa 7: Obter endpoints

Após a implantação ser concluída, obtenha o endpoint da aplicação:

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

1. Navegue até o Console EC2 → Balanceadores de carga
2. Encontre o balanceador de carga (procure um nome com `allid-load-balancer`)
3. Copie o **nome DNS** (por exemplo, `allid-load-balancer-123456789.us-east-1.elb.amazonaws.com`)

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

```bash
# Liste todos os balanceadores de carga 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 multitenant. 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 os novos peers ANTES de implantar.
{% endhint %}

## Etapa 8: Validar 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 nome DNS real do seu 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 ECS → Clusters → `allid-cluster`
2. Clique na aba "Serviços"
3. Verifique se todos os serviços exibem status "Running" e se a contagem desejada corresponde à contagem em execução

**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 não conseguirem iniciar):

**Console da AWS**:

1. Navegue até o Console CloudWatch → Grupos de logs
2. Encontre os grupos de logs: `/ecs/allid/peer-default`, `/ecs/allid/facematch`, etc.
3. Verifique os fluxos de logs 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 em três camadas:

```
┌─────────────────────────────────────────┐
│ Sub-redes públicas (2 AZs)              │
│ • Balanceador de carga de aplicação     │
│ • Gateway da Internet                   │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│ Sub-redes privadas (2 AZs)              │
│ • Serviço Peer (ECS Fargate)           │
│ • Serviço Facematch (ECS Fargate)      │
│ • Gateway NAT (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 (multitenant)

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

```
/default/*   → peer-default   (Grupo de destino 1)
/client-a/*  → peer-client-a  (Grupo de destino 2)
/client-b/*  → peer-client-b  (Grupo de destino 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 de forma independente dos outros peers
* Compartilha o mesmo pool de serviços 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 Serviço Router
* Flags de recurso (RabbitMQ, Redis, comunicação com o Router)

**Segredos** são injetados via segredos da tarefa 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` (por exemplo, `allid-peer-default-router-certificate`)

{% hint style="warning" %}
Os segredos de certificado do Router são criados com valores de placeholder durante a implantação. Você deve atualizá-los com certificados reais antes que os Serviços Peer 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 privilégio mínimo.

**Grupos de segurança**:

* O ALB aceita tráfego somente de IPs na lista de permissões
* Os Serviços Peer aceitam tráfego somente do ALB e da VPC interna
* Facematch aceita tráfego somente dos Serviços Peer
* O banco de dados aceita tráfego somente dos Serviços Peer

**Lista de permissões de IP**:

* O ALB está configurado para aceitar tráfego somente de 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 endurecimento de segurança
  {% endhint %}

## Atualizando a implantação

### Atualizar imagens de contêiner

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

# Reimplantar os Serviços Peer (implanta todos os 3 peers)
cdk deploy allid-peer

# Reimplantar o Serviço Facematch
cdk deploy allid-facematch
```

### Atualizar 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 Serviços Peer**: Edite a contagem desejada em `src/cdk/allid/src/constructs/peer-construct.ts`:

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

Em seguida, reimplante:

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

**Dimensionar o Serviço Facematch**: Edite a contagem desejada em `src/cdk/allid/src/stacks/facematch-stack.ts`:

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

Em seguida, 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 de 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;

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

4. **Atualize o segredo de 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 Serviço Peer não conseguirá 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 não encontrada"

**Causa**: ID da VPC não 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 Serviço Peer não iniciará

**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 fluxo de logs mais recente
4. Procure mensagens de erro nos logs

**AWS CLI**:

```bash
# Acompanhe os logs de 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 da parada da tarefa**:

**Console da AWS**:

1. Console ECS → Clusters → allid-cluster
2. Clique no serviço (por exemplo, peer-default)
3. Vá para a aba "Tasks" → clique nas tarefas interrompidas
4. Verifique o campo "Motivo da parada"

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

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

**Console da AWS**:

1. Console ECS → Clusters → allid-cluster → Serviços
2. Verifique o status de cada serviço
3. Consulte a aba "Eventos" para mensagens recentes

**Verificar a saúde dos destinos do ALB**:

**Console da AWS**:

1. Console do EC2 → Grupos de destino
2. Encontre grupos de destino com `allid` prefixo
3. Clique em cada grupo de destino
4. Vá para a aba "Targets"
5. Verifique o status de saúde dos destinos registrados (deve ser "healthy")

**AWS CLI**:

```bash
# Listar grupos de destino
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**:

* Grupos de segurança bloqueando o tráfego entre o ALB e os serviços de peer
* Serviço não registrado no Cloud Map (a resolução DNS falha)
* Erros de conexão com o banco de dados (verifique o segredo das credenciais)
* Serviço Facematch não está respondendo

### Não é possível 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 grupo de segurança do ALB**:

**Console da AWS**:

1. Console do EC2 → Load Balancers → Encontre seu ALB
2. Clique na aba "Security"
3. Clique no grupo de segurança
4. Verifique as "Inbound rules" - confirme que 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. Reimplante:

```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 gerar 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 implantou)
cd ../shared
cdk destroy --all
```

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

* o banco de dados Aurora MySQL e todos os dados
* logs do CloudWatch
* segredos do Secrets Manager (credenciais do banco de dados, certificados do Router)
* serviços e tarefas 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óximos passos

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


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.