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

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.

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

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

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

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

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

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

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.

Etapa 1: Extrair o projeto CDK

Extraia os arquivos do projeto CDK fornecidos pela Certta:

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

Etapa 2: Infraestrutura de rede (opcional)

Pule esta etapa se você já tiver uma VPC. Implante a infraestrutura compartilhada somente se você precisar criar uma nova VPC.

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

# 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

Navegue até o Console da VPC → Suas VPCs
Encontre a VPC criada pela implantação (procure tags com o prefixo shared)
Copie o ID da VPC (formato: vpc-xxxxxxxxxxxxx)

Opção 2: AWS CLI

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

cd src/cdk/allid

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

{
  "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

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.

Etapa 4: Implantar a aplicação All ID

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

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

Cluster ECS + Service Discovery (ClusterStack)
- Cluster ECS Fargate
- Namespace privado do Cloud Map (allid.local)
Banco de dados (DatabaseStack)
- Cluster Aurora MySQL Serverless v2
- Grupo de segurança do banco de dados
- Secrets Manager para credenciais (geradas automaticamente)
Balanceador de carga (LoadBalancerStack)
- Application Load Balancer (voltado para a internet)
- Listener HTTP (porta 80)
- Grupo de segurança com whitelist de IPs
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
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

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.

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.

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.

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.

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)

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:

Inicie uma instância EC2 em uma sub-rede pública da sua VPC
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
Conecte-se ao banco de dados por meio de um túnel SSH:

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

Conecte-se à sua VPN
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:

Garanta que seu host bastion tenha o agente SSM instalado
Conceda as permissões IAM necessárias
Crie uma sessão de encaminhamento de porta:

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)

Não recomendado para produção: Use este método somente para ambientes de desenvolvimento/teste.

Modifique temporariamente o grupo de segurança do RDS para permitir seu IP
Torne a instância RDS publicamente acessível (requer modificação)
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

Navegue até o Console do RDS → Bancos de dados
Encontre o cluster Aurora (procure o nome com allid-database)
Copie o endpoint do escritor (por exemplo, allid-database-cluster.cluster-xxx.us-east-1.rds.amazonaws.com)
Navegue até o Console do Secrets Manager → Secrets
Encontre o segredo do banco de dados (procure o nome com allid-database)
Clique em "Retrieve secret value" para ver nome de usuário e senha

Opção 2: AWS CLI

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

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

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)

Criar bancos de dados:

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

CREATE DATABASE IF NOT EXISTS `peer-default`;
CREATE DATABASE IF NOT EXISTS `peer-client-a`;
CREATE DATABASE IF NOT EXISTS `peer-client-b`;

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:

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

Criar bancos de dados:

Abra a conexão → guia Consulta
Executar:

CREATE DATABASE IF NOT EXISTS `peer-default`;
CREATE DATABASE IF NOT EXISTS `peer-client-a`;
CREATE DATABASE IF NOT EXISTS `peer-client-b`;

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:

Faça login no phpMyAdmin
Crie os bancos de dados usando o botão "Novo"
Selecione cada banco de dados e use a aba "Importar" para enviar e executar o arquivo de dump SQL

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

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.

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.

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.

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

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

Navegue até o Console do Secrets Manager → Secrets
Localize e clique em cada segredo:
- allid-peer-default-router-certificate
- allid-peer-client-a-router-certificate
- allid-peer-client-b-router-certificate
Clique em "Recuperar valor do segredo" → "Editar"
Atualize o JSON com seus certificados reais:

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

Salvar alterações

Opção 2: AWS CLI

# 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-----"
  }'

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

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.

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.

Etapa 7: Obter endpoints

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

Opção 1: Console da AWS

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

Opção 2: AWS CLI

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

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.

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

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.

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):

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

Navegue até o Console ECS → Clusters → allid-cluster
Clique na aba "Serviços"
Verifique se todos os serviços exibem status "Running" e se a contagem desejada corresponde à contagem em execução

AWS CLI:

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

Navegue até o Console CloudWatch → Grupos de logs
Encontre os grupos de logs: /ecs/allid/peer-default, /ecs/allid/facematch, etc.
Verifique os fluxos de logs recentes em busca de erros

AWS CLI:

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

Veja Configuração para a lista completa de variáveis de ambiente, valores necessários e detalhes de configuração.

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)

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

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

Veja Melhores Práticas de Segurança 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

Atualizando a implantação

Atualizar imagens de contêiner

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

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

Reimplante as stacks afetadas:

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

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

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:

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

Em seguida, reimplante:

cdk deploy allid-peer

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

desiredCount: 4, // Alterar de 2 para 4

Em seguida, reimplante:

cdk deploy allid-facematch

Adicionar/remover instâncias peer

Para adicionar uma nova instância peer:

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

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

Implante a stack Peer atualizada:

cdk deploy allid-peer

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

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

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

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

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-----"
  }'

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

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:

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
Se você não tiver uma VPC, implante a infraestrutura compartilhada (veja a Etapa 2):

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

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

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

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

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

Reimplante:

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:

Console do CloudWatch → Grupos de logs
Encontre /ecs/allid/peer-default (ou peer-client-a, peer-client-b)
Clique no fluxo de logs mais recente
Procure mensagens de erro nos logs

AWS CLI:

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

Causas comuns:

Banco de dados não inicializado: Veja a Etapa 5 (inicialização do banco de dados e restauração do dump)
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
Falha na conexão com o banco de dados: Verifique os grupos de segurança e o endpoint do RDS
Serviço Facematch indisponível: Verifique o status do serviço Facematch

Verifique o motivo da parada da tarefa:

Console da AWS:

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

Falhas na verificação de saúde

Verifique o status do serviço ECS:

Console da AWS:

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

Verificar a saúde dos destinos do ALB:

Console da AWS:

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

AWS CLI:

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

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

Console do EC2 → Load Balancers → Encontre seu ALB
Clique na aba "Security"
Clique no grupo de segurança
Verifique as "Inbound rules" - confirme que seu IP está permitido

Adicione seu IP à allowlist:

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

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

Reimplante:

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

Veja Melhores Práticas de Segurança para a lista completa de endereços IP do Certta Router que devem estar na allowlist.

Limpeza

Para remover todos os recursos e parar de gerar custos:

# 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

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.

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

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 para especificações de recursos
Revise Configuração para detalhes das variáveis de ambiente
Revise Melhores Práticas de Segurança para hardening

Atualizado há 5 meses