Deploy do Connector na AWS

Deploy do Connector

O connector é o componente que faz a ponte entre o plano de controle do Apono (SaaS) e os recursos da sua infraestrutura. Ele pode ser implantado de diferentes formas, dependendo do ambiente:

Ambiente	Método de Deploy
Kubernetes	Helm chart ou manifesto YAML
AWS	EC2, ECS ou Fargate
Azure	Container Instance ou AKS
GCP	GKE ou Cloud Run
On-premise	Docker container

Requisitos

A configuração básica do connector exige apenas:

Token de autenticação: Gerado no dashboard do Apono para vincular o connector à conta.
Credenciais locais: IAM role (AWS), managed identity (Azure) ou service account (GCP) com permissões para gerenciar acessos nos recursos desejados.
Acesso de saída (outbound): Conectividade HTTPS com o plano de controle do Apono.

A arquitetura de connector com comunicação outbound é um padrão amplamente adotado em ferramentas SaaS que precisam interagir com infraestruturas privadas. Esse modelo evita a exposição de recursos internos enquanto mantém a conveniência de uma solução gerenciada.

Comunicação e Segurança de Rede

O connector nunca recebe conexões de entrada. Toda a comunicação é iniciada pelo connector em direção ao Apono Cloud (outbound). Isso significa que:

Não é necessário abrir portas de entrada no firewall ou security groups.
O connector pode rodar em subnets privadas sem acesso direto da internet.
Basta garantir acesso HTTPS (porta 443) de saída para os endpoints do Apono.

Permissões Necessárias

O connector precisa de permissões para gerenciar acessos nos recursos que ele controla. As permissões variam conforme o provedor:

AWS: IAM role com permissões para iam:AttachRolePolicy, iam:DetachRolePolicy, iam:AddUserToGroup, iam:RemoveUserFromGroup e similares, conforme os recursos gerenciados.
Azure: Managed identity com permissões de User Access Administrator ou Role Based Access Control Administrator nos scopes desejados.
GCP: Service account com permissões de roles/iam.securityAdmin ou equivalente nos projetos gerenciados.
Kubernetes: Service account com permissões para criar e remover RoleBindings e ClusterRoleBindings.
Bancos de dados: Credenciais com permissão para criar e revogar usuários ou conceder/remover grants.

O princípio do menor privilégio se aplica ao próprio connector: ele deve ter apenas as permissões necessárias para gerenciar acessos nos recursos configurados, e nada além disso.

Deploy na AWS

O Apono oferece templates prontos de CloudFormation e módulos Terraform oficiais para deploy na AWS. Não é necessário montar a infraestrutura manualmente — o próprio Apono disponibiliza o passo a passo diretamente no dashboard, com stacks que criam automaticamente todos os recursos necessários.

O connector roda como um serviço ECS no Fargate, e o processo de deploy cria automaticamente:

Cross Account Role com permissões de leitura para descoberta de recursos.
SNS para notificações entre o connector e o plano de controle.
ECS Task no Fargate que executa o connector dentro da VPC informada.

Pré-requisitos

Permissões de administrador na conta AWS de destino.
Uma VPC com conectividade de saída (outbound).
Pelo menos uma subnet dentro da VPC.
Para deploy em nível de Organization: ID da Organization (o-k012345a67) e ID da Organization Unit Root (r-1a2b).

Cenários de Deploy

O Apono suporta três cenários para AWS:

Cenário	Descrição
Conta única	Connector gerencia acessos em uma conta AWS específica
Organization (Management Account)	Connector instalado na management account, gerencia todas as contas da Organization
Organization (Delegated)	Connector em uma conta membro com permissões delegadas para a management account

Deploy via CloudFormation (Recomendado)

Este deploy instala o connector na management account — a conta raiz que administra a AWS Organization e, tipicamente, onde o IAM Identity Center está configurado. É a partir dessa conta que o connector consegue assumir roles nas contas-membro e gerenciar acessos em toda a Organization.

Se a sua organização segue o princípio de não executar workloads na management account (uma recomendação comum de segurança da AWS), existe a alternativa de fazer o deploy em uma conta-membro com permissões delegadas. Nesse modelo, o connector roda em uma conta separada (ex: a conta de segurança ou de ferramentas) e recebe permissões cross-account para atuar na Organization. Veja a seção Organization (Delegated Permissions) para o passo a passo dessa configuração.

O método mais simples é pelo próprio dashboard do Apono, que gera um link direto para o CloudFormation com os parâmetros já preenchidos.

Na prática, quando uma organização chega ao ponto de adotar o Apono e investir em uma ferramenta paga de gerenciamento de acessos, é porque já atingiu um nível de maturidade e escala onde existem múltiplas contas AWS. Se você seguiu as boas práticas da AWS, provavelmente já utiliza AWS Organizations, IAM Identity Center e uma estrutura de contas separadas por ambiente (produção, staging, desenvolvimento, segurança, etc.). O Apono suporta o deploy para uma conta única, conforme descrito na documentação oficial, mas aqui vamos focar no cenário mais comum: a Organization inteira.

Para organizações que utilizam AWS Organizations e querem gerenciar acessos em todas as contas centralizadamente:

Acesse o dashboard do Apono (app.apono.io).
Navegue até Integrations → Catalog.
Selecione AWS no catálogo de integrações.
Escolha o tipo de deploy Organization.
Selecione os tipos de recursos que o Apono deve descobrir e gerenciar na sua Organization (ex: IAM roles, RDS, S3, EC2, EKS, etc.). Essa seleção define o escopo do discovery — quais recursos o connector vai identificar automaticamente nas contas da Organization.
Informe o Organization ID e o escopo de contas que o Apono deve gerenciar. É possível definir o escopo em diferentes níveis:
- Organization Unit Root (r-1a2b): O connector varre todas as contas da Organization. É o cenário mais comum e recomendado para quem quer visibilidade e controle total.
- Organization Unit específica (ou-1a2b-c3d4e5f6): O connector atua apenas nas contas que pertencem àquela OU. Útil para limitar o escopo a um ambiente específico (ex: apenas contas de produção, apenas contas de um time).
- Conta específica: O connector gerencia acessos em uma única conta. Pode ser usado em um piloto inicial antes de expandir para a Organization inteira.
Selecione o nível de permissão desejado:
- Full-Access (Manage IAM): O connector terá permissões para descobrir recursos e gerenciar acessos — ou seja, criar e remover policies, adicionar e remover usuários de grupos, conceder e revogar roles. Esse é o modo necessário para que o Apono funcione como ferramenta de JIT Access, e é o que você vai usar na maioria dos casos.
- Read-Only: O connector terá permissões apenas para descobrir recursos nas contas da Organization, sem capacidade de alterar permissões. Esse modo é útil em uma abordagem de adoção gradual — primeiro você conecta o Apono para visualizar quais recursos existem no seu ambiente, valida o escopo do discovery e depois atualiza o connector para Full-Access quando estiver pronto para gerenciar acessos de fato.
Selecione CloudFormation como método de instalação e clique em Open CloudFormation — você será redirecionado para o console AWS.
No console AWS, selecione a VPC e pelo menos uma subnet, marque o checkbox de acknowledgment para criação de recursos IAM e clique em Create Stack.
O stack será instalado na management account (que gerencia o Identity Center da organização).
Aguarde o stack completar e volte ao dashboard do Apono — o connector deve aparecer com status Connected (indicação verde).

Verifique se o trusted access está ativado para CloudFormation StackSets na sua Organization. Sem isso, o stack não consegue propagar as permissões para as contas membros.

Após o stack completar, o CloudFormation gera dois valores importantes na aba Outputs e Parameters:

AponoConnectorRoleArn (Outputs): O ARN da IAM role criada para o connector. Essa role é o que permite ao connector assumir permissões nas contas da Organization para fazer discovery e gerenciar acessos.
AponoConnectorId (Parameters): O identificador único do connector no Apono Cloud.

Para o cenário de Organization com Management Account (o que acabamos de configurar), esses valores são gerados automaticamente e não precisam de ação adicional — o connector já está funcional. No entanto, guarde esses valores. Eles são necessários nos seguintes casos:

Delegated Permissions: Se no futuro você decidir mover o connector para uma conta membro em vez da management account, precisará do AponoConnectorRoleArn e do AponoConnectorId para criar o stack de delegação na management account (detalhado na seção Organization (Delegated Permissions)).
Troubleshooting de permissões: Se o connector não conseguir acessar recursos em alguma conta, o AponoConnectorRoleArn ajuda a diagnosticar problemas de trust policy ou permissões insuficientes na cross-account role.
Integração com IaC existente: Se você gerencia sua infraestrutura via Terraform ou CDK e precisa referenciar a role do connector em outras configurações (ex: adicionar permissões extras para recursos específicos), o ARN é o identificador necessário.

Um Connector ou Vários?

Uma dúvida comum ao planejar o deploy é: vale a pena ter um único connector para toda a Organization ou dividir em múltiplos connectors?

Na maioria dos casos, um único connector cobrindo a Organization inteira é suficiente. Ele já consegue varrer todas as contas, fazer discovery de recursos e gerenciar acessos centralizadamente. Menos connectors significa menos infraestrutura para manter, menos tokens para gerenciar e menos stacks para atualizar.

No entanto, existem cenários onde múltiplos connectors fazem sentido:

Isolamento de rede: Se a sua Organization possui VPCs em regiões diferentes que não se comunicam entre si, cada connector precisa estar em uma VPC com acesso de saída. Um connector em us-east-1 não consegue gerenciar recursos que exigem conectividade de rede local em eu-west-1 (como bancos de dados em subnets privadas).
Segregação por ambiente: Organizações com requisitos rigorosos de compliance podem preferir connectors separados para produção e não-produção. Isso garante que um problema no connector de dev/staging não impacte o gerenciamento de acessos em produção.

Cenário	Recomendação
Organization pequena/média, uma região principal	Um único connector
Organization multi-região com VPCs isoladas	Um connector por região com recursos de rede local
Requisitos de compliance com segregação prod/não-prod	Um connector por ambiente

Na dúvida, comece com um único connector para a Organization inteira. O Apono permite adicionar connectors adicionais a qualquer momento sem impactar os já existentes. Escale conforme a necessidade real — não antecipe complexidade.

O Que o Connector Faz na Prática

Após o deploy e a conexão com o Apono Cloud, o connector passa a executar continuamente as seguintes funções:

Discovery de recursos: O connector varre as contas da Organization e identifica automaticamente os recursos disponíveis — instâncias EC2, bancos RDS, buckets S3, clusters EKS, roles IAM, entre outros. Esses recursos aparecem no catálogo do Apono e ficam disponíveis para configuração de Access Flows. O discovery é contínuo: quando novos recursos são criados na AWS, o connector os detecta e atualiza o catálogo automaticamente.
Provisionamento de acessos: Quando uma solicitação de acesso é aprovada (manual ou automaticamente), o connector recebe a instrução do Apono Cloud e executa a ação na infraestrutura — por exemplo, adicionar um usuário a um grupo IAM, anexar uma policy a uma role, criar credenciais temporárias para um banco de dados, ou criar um RoleBinding no Kubernetes.
Revogação automática de acessos: Quando o tempo do acesso expira, o connector recebe a instrução de revogação e remove a permissão — desanexa a policy, remove o usuário do grupo, revoga as credenciais do banco. Essa revogação é automática e não depende de intervenção humana.
Polling contínuo: O connector não recebe conexões de entrada. Ele faz polling periódico ao Apono Cloud para verificar se existem ações pendentes (concessões ou revogações). Esse modelo garante que o connector funcione em subnets privadas sem exposição à internet.
Reporte de status: O connector reporta seu estado de saúde ao Apono Cloud. Se o connector ficar offline ou com problemas de conectividade, o dashboard exibe o status Disconnected, alertando a equipe.

O connector é stateless — ele não armazena estado localmente. Toda a lógica de decisão (quem pode acessar o quê, por quanto tempo, quem aprova) fica no Apono Cloud. O connector apenas executa as ações na infraestrutura. Isso significa que, se o connector for substituído ou recriado, basta gerar um novo token e fazer o deploy novamente — não há dados locais a serem migrados.

Organization (Delegated Permissions)

Para organizações que não querem instalar o connector diretamente na management account, o Apono suporta um modelo de permissões delegadas — onde o connector roda em uma conta membro, mas recebe permissões para gerenciar acessos em toda a Organization. Esse modelo é comum em organizações que restringem workloads na management account por questões de segurança.

O processo envolve dois stacks CloudFormation: um na conta membro (onde o connector roda) e outro na management account (que delega as permissões).

Passo 1 — Deploy do connector na conta membro:

No dashboard do Apono, siga os mesmos passos do deploy Organization, mas sem marcar a opção "Install and Connect AWS Account".
Após o stack completar na conta membro, copie dois valores:
- AponoConnectorId (aba Parameters do stack)
- AponoConnectorRoleArn (aba Outputs do stack)

Passo 2 — Delegação de permissões na management account:

Abra o CloudFormation na management account. O Apono fornece um link direto para a página de criação rápida de stack.
Em Parameters, preencha os seguintes campos:
- AponoConnectorId: O valor copiado no passo anterior.
- ConnectorRoleArn: O ARN copiado no passo anterior.
- OrganizationId: O ID da Organization (o-k012345a67).
- OrganizationUnitId: O ID da OU root (r-1a2b) ou da OU específica que deseja gerenciar.
No menu Permissions, selecione Full-Access (Manage IAM).
Em Resources, marque o checkbox "Confirmo que o AWS CloudFormation pode criar recursos do IAM com nomes personalizados".
Clique em Create Stack.
(Opcional) Na aba Outputs, copie o valor de ManagementAccountRoleArnOutput — esse ARN pode ser útil para referência futura ou integração com outras ferramentas de IaC.

Após ambos os stacks completarem, o connector na conta membro terá permissões delegadas pela management account para gerenciar acessos em toda a Organization. O status no dashboard do Apono deve mudar para Connected.

A principal vantagem do modelo delegado é que a management account não roda nenhum workload — ela apenas concede as permissões necessárias ao connector via cross-account role. Isso segue a recomendação da AWS de manter a management account limpa e restrita.

O Que o CloudFormation Cria na Sua Conta

Após o deploy, é importante entender quais recursos IAM o CloudFormation criou e qual o papel de cada um. Isso facilita troubleshooting, auditorias de segurança e revisões de permissões.

Roles nas Contas-Membro (Todas as Contas da Organization)

Em cada conta-membro da Organization, o StackSet cria uma role cross-account com o nome:

apono-cross-account-role-AwsIntegrationConnector-xxx

Essa role é a que permite ao connector acessar os recursos de cada conta remotamente. Ela contém:

Permissões de leitura para os tipos de recursos selecionados durante o deploy (EC2, RDS, S3, EKS, IAM, etc.) — usadas para o discovery.
Permissões de escrita (se Full-Access foi selecionado) para gerenciar acessos — como iam:AttachRolePolicy, iam:AddUserToGroup, etc.
Trust policy que permite à role do connector na management account (ou na conta delegada) assumir essa role via sts:AssumeRole.

Se você adicionar novas contas à Organization posteriormente, o StackSet propaga automaticamente essa role para as novas contas — desde que o trusted access para CloudFormation StackSets esteja ativo.

Roles na Conta de Gerenciamento (Management Account)

Na management account, o CloudFormation cria duas roles principais:

Role	Service Principal	Função
`apono-connector-role-xxxxxxxx-xxxx-...`	`ecs-tasks.amazonaws.com`	Role assumida pela ECS Task do Fargate que executa o connector. É a identidade do connector dentro da AWS — permite que ele faça `sts:AssumeRole` nas cross-account roles das contas-membro.
`apono-oidc-role-xxxxxxxx-xxxx-...`	`lambda.amazonaws.com`	Role usada por uma função Lambda auxiliar que o Apono utiliza para operações de autenticação OIDC e validação de tokens entre o connector e o Apono Cloud.

A role do connector (apono-connector-role) é a mais importante — ela é a "identidade" do connector na AWS. Quando o connector precisa fazer discovery ou gerenciar acessos em uma conta-membro, ele usa essa role para assumir a cross-account role daquela conta via sts:AssumeRole. A cadeia de confiança funciona assim:

Nunca modifique ou delete essas roles manualmente. Se precisar atualizar permissões, use o processo de atualização do stack CloudFormation para garantir consistência. Alterações manuais podem quebrar a cadeia de trust e desconectar o connector.

A Função Lambda (OIDC)

A apono-oidc-role está associada a uma função Lambda que o CloudFormation também cria na management account. Essa Lambda é responsável por estabelecer a autenticação entre o connector e o Apono Cloud usando o protocolo OIDC (OpenID Connect).

Na prática, o problema que ela resolve é: como o connector prova sua identidade ao Apono Cloud de forma segura, sem armazenar credenciais estáticas (como API keys ou secrets) no ambiente do cliente?

A resposta é via tokens OIDC de curta duração. O fluxo funciona assim:

O connector precisa se autenticar com o Apono Cloud para fazer polling de ações pendentes.
A Lambda atua como um token endpoint — ela gera tokens OIDC assinados que identificam o connector.
O connector apresenta esse token ao Apono Cloud, que valida a assinatura e confirma a identidade.
O token tem vida curta — se for comprometido, expira rapidamente e não pode ser reutilizado.

Esse modelo segue o padrão de IAM OIDC Federation da AWS — em vez de trocar credenciais estáticas entre o connector e o SaaS, toda a autenticação é baseada em tokens temporários. É o mesmo princípio usado por GitHub Actions e GitLab CI para autenticar com a AWS sem armazenar access keys.

A Lambda OIDC é um componente interno do Apono e não requer configuração ou manutenção manual. Ela é criada e gerenciada automaticamente pelo stack CloudFormation. Você não precisa invocá-la diretamente — o connector a utiliza de forma transparente.

Recursos ECS (O Connector em Si)

Além das roles IAM e da Lambda, o CloudFormation cria toda a infraestrutura necessária para rodar o connector como um serviço gerenciado no ECS Fargate:

Recurso	Função
ECS Cluster	Cluster dedicado para o connector. Roda exclusivamente a task do Apono — não compartilha recursos com outros serviços.
ECS Task Definition	Define o container do connector: imagem Docker do Apono, variáveis de ambiente (token, connector ID), limites de CPU/memória e a IAM role associada (`apono-connector-role`).
ECS Service	Garante que a task esteja sempre rodando. Se o container falhar ou for encerrado, o ECS reinicia automaticamente uma nova instância.
Security Group	Controla o tráfego de rede da task. Permite apenas tráfego de saída (outbound) — o connector não recebe conexões de entrada, apenas faz polling ao Apono Cloud.
CloudWatch Log Group	Armazena os logs do container do connector. Útil para troubleshooting quando o connector apresenta problemas de conectividade ou erros de permissão.

O connector roda no Fargate — o que significa que não há instâncias EC2 para gerenciar. A AWS cuida da infraestrutura computacional, e você paga apenas pelo tempo de execução do container. Como o connector é leve (baixo consumo de CPU e memória), o custo operacional é mínimo.

A task é implantada na VPC e subnet que você selecionou durante o deploy. O único requisito de rede é que a subnet tenha acesso de saída à internet (via NAT Gateway ou Internet Gateway) para que o connector consiga se comunicar com o Apono Cloud. Não é necessário abrir nenhuma porta de entrada.

Se precisar verificar os logs do connector, acesse o CloudWatch na conta onde o stack foi criado e procure pelo log group com prefixo apono. Os logs mostram eventos de discovery, polling, concessão e revogação de acessos — e são o primeiro lugar para investigar quando algo não funciona como esperado.

Deploy via Terraform

Documentação Oficial Terraform

Se quiser manter todo esse deploy via terraform é possível utilizando o link acima. Na verdade vai aplicar um cloudformation via terraform.

Usaremos terraform mais pra frente, mas não para o conector, mas para definir nossos flows. O Apono oferece um provider para terraform que exploraremos mais adiante.

Deploy via EKS

Para organizações que preferem rodar o connector no Kubernetes em vez do ECS, o Apono também oferece um template CloudFormation específico para EKS. O fluxo é semelhante ao do ECS — selecionando a opção EKS no dashboard do Apono durante a configuração, mas eu não vejo muita vantagens nisso. Na minha opinião é adicionar mais camadas de controle desnecessárias para uma item tão simples.

Atualizando o Connector

Para atualizar um connector já implantado, o Apono fornece um template atualizado que pode ser aplicado sobre o stack existente:

# Atualizar o stack CloudFormation com o template mais recente
aws cloudformation update-stack \
  --stack-name apono-connector \
  --template-url <url-do-template-atualizado> \
  --parameters \
    ParameterKey=VpcId,UsePreviousValue=true \
    ParameterKey=SubnetIds,UsePreviousValue=true \
    ParameterKey=AponoToken,UsePreviousValue=true \
  --capabilities CAPABILITY_NAMED_IAM

Após a atualização, verifique na aba Stack Info do CloudFormation se o status mudou para UPDATE_COMPLETE.

Verificando o Deploy

Após o deploy, verifique se o connector está funcionando:

No dashboard do Apono, navegue até Integration na aba connectors.
O connector deve aparecer com status Connected (indicação verde).
Se o status for Disconnected, verifique:
- O stack do CloudFormation completou sem erros.
- A subnet tem acesso de saída à internet (NAT Gateway ou Internet Gateway).
- O token está correto e não expirou.

Após a conexão bem-sucedida, você pode criar Access Flows para recursos AWS como IAM roles, RDS, S3, EC2 (via SSM) e outros. Cada recurso adicional pode ser conectado individualmente pelo catálogo de integrações do Apono.