ARN, ou Amazon Resource Name, é o identificador único que a AWS usa para apontar para um recurso específico, como um bucket, uma função ou um usuário. Sempre que você escreve uma política de IAM, configura um gatilho ou referencia um recurso em outro serviço, o ARN entra em cena. Neste guia você entende a estrutura do ARN campo a campo, vê exemplos de serviços comuns e aprende os cuidados ao copiar e compartilhar. Para separar e validar o formato de um ARN, use as ferramentas DevOps, que fazem a análise localmente, sem consultar a AWS.
O que é ARN
Na AWS, há milhões de recursos espalhados por contas e regiões. O ARN é a forma padronizada de nomear cada um deles sem ambiguidade. Ele é usado em políticas de permissão (para dizer a quais recursos uma ação se aplica), em integrações entre serviços e em logs. Ler um ARN com fluência ajuda a depurar permissões e a entender de qual recurso, conta e região algo está falando.
Estrutura geral
O formato é:
arn:partition:service:region:account-id:resourceOs campos são separados por dois pontos. O último campo, o resource, pode conter barras e dois pontos internos, e às vezes inclui um tipo de recurso antes do identificador.
Partition
Indica o conjunto de regiões. Quase sempre é aws. Há também aws-cn (regiões da China) e aws-us-gov (GovCloud dos Estados Unidos). Uma partition fora dessas três é um sinal de que o ARN pode estar incorreto.
Service
O serviço dono do recurso, como s3, iam, lambda, sqs, dynamodb ou kms. É um dos campos mais úteis para entender rapidamente sobre o que o ARN trata.
Region
A região onde o recurso existe, como us-east-1 ou sa-east-1. Recursos globais, como os do IAM e os buckets do S3, deixam esse campo vazio, porque não pertencem a uma região específica.
Account ID
O identificador numérico da conta AWS dona do recurso, com 12 dígitos. Alguns serviços, como o S3, deixam esse campo vazio no ARN. Quando ele aparece com um número diferente de 12 dígitos, vale desconfiar de um erro de cópia.
Resource e resource type
O resource identifica o item. Dependendo do serviço, vem acompanhado de um tipo. Há três formas comuns: só o resource; resourcetype/resource (separado por barra); e resourcetype:resource (separado por dois pontos). Saber qual formato o serviço usa evita interpretar errado, por exemplo confundir o nome de um bucket do S3 com um tipo de recurso.
Exemplos por serviço
| Serviço | Exemplo de ARN |
|---|---|
| S3 (objeto) | arn:aws:s3:::meu-bucket/pasta/arquivo.txt |
| IAM (usuário) | arn:aws:iam::123456789012:user/Joao |
| Lambda | arn:aws:lambda:us-east-1:123456789012:function:minhaFuncao |
| CloudWatch Logs | arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/minhaFuncao |
| KMS | arn:aws:kms:us-east-1:123456789012:key/abcd-1234 |
Repare que o S3 deixa region e account vazios, enquanto Lambda e KMS trazem os dois preenchidos e usam tipo de recurso antes do identificador.
Erros comuns ao copiar ARN
- Cortar parte do resource que contém barras ou dois pontos.
- Trocar a region por engano ao reaproveitar um ARN de outro ambiente.
- Confundir o nome do bucket do S3 com um tipo de recurso.
- Deixar espaços invisíveis no início ou no fim ao colar.
Segurança: não exponha ARNs com credenciais
O ARN traz o ID da conta, que é uma informação a proteger. O perigo aumenta quando ele aparece ao lado de chaves de acesso, tokens ou senhas em repositórios públicos, prints ou mensagens. Trate o ID da conta como dado sensível e nunca compartilhe credenciais junto. Tokens, por exemplo, têm sua própria anatomia: veja o decodificador de JWT para entender o que um token revela ao ser decodificado.
ARN em políticas de IAM e curingas
O uso mais frequente de ARN é em políticas de permissão do IAM, onde o campo Resource diz a quais recursos uma ação se aplica. É aí que aparecem os curingas. O asterisco substitui qualquer sequência, então arn:aws:s3:::meu-bucket/* representa todos os objetos dentro do bucket. Um Resource igual a apenas um asterisco significa qualquer recurso, o que costuma ser amplo demais e deve ser evitado fora de casos bem específicos.
Entender essa estrutura ajuda a aplicar o princípio do menor privilégio: conceder só o acesso necessário, ao recurso necessário. Em vez de liberar um serviço inteiro, restrinja ao bucket, à função ou à tabela específica pelo ARN. Erros comuns incluem usar curingas amplos por preguiça, ou apontar para a região errada ao reaproveitar uma política entre ambientes de desenvolvimento e produção.
Vale também distinguir o ARN do recurso do ARN de algo dentro dele. Um bucket do S3 tem um ARN; cada objeto dentro dele tem outro, com o caminho após a barra. Uma função Lambda tem um ARN; uma versão específica ou um alias têm ARNs próprios. Confundir esses níveis é uma fonte clássica de políticas que não funcionam como esperado. Ler o ARN com atenção, parte por parte, resolve a maioria desses enganos antes que virem um incidente.
Como encontrar o ARN de um recurso
Na prática, há várias formas de obter o ARN. No console da AWS, a maioria das telas de recurso mostra o ARN em algum painel de detalhes, pronto para copiar. Pela linha de comando, comandos de descrição e de listagem retornam o ARN no resultado. Em modelos de infraestrutura como código, funções específicas devolvem o ARN de um recurso recém-criado para você referenciar em outro lugar do mesmo modelo, evitando copiar valores manualmente.
Ao copiar de telas, cuidado com espaços extras e com o recurso ser cortado quando ele contém barras. Ao reutilizar um ARN entre ambientes, troque a região e o ID da conta conforme o destino, em vez de assumir que o mesmo ARN serve para tudo. E lembre que o ARN é a forma canônica de se referir ao recurso: usar o nome simples em vez do ARN, onde a AWS espera um ARN, é uma causa frequente de erro silencioso em políticas e integrações.
Por fim, lembre que o ARN é só o identificador, não a permissão em si. Ter o ARN de um recurso não dá acesso a ele; o acesso depende das políticas associadas a quem faz a chamada. Por isso, ao depurar um problema de permissão, confira duas coisas: se o ARN no campo Resource está correto e se a ação no campo Action corresponde ao que você está tentando fazer. A maioria dos erros de acesso na AWS está em um desses dois pontos, e ler o ARN com calma costuma apontar o caminho.
Quando usar a ferramenta do ValorFinal
Use as ferramentas DevOps para colar um ARN e ver cada parte separada (partition, service, region, account e resource), com avisos de formato, sem nenhuma consulta à AWS. Para redes, veja a calculadora de sub-rede IPv4. Conheça as demais ferramentas de tecnologia.