O problema que todo administrador do Amazon Quick já enfrentou
Você migra dashboards do ambiente de desenvolvimento para produção — e as permissões simplesmente somem. Você compartilha um painel com o time de Finanças e eles continuam recebendo “acesso negado”. Você configura namespaces para isolamento multi-tenant e o mesmo nome de usuário funciona em um namespace, mas não em outro.
Esses são cenários reais que administradores do Amazon Quick enfrentam com frequência. Resolver esses problemas exige entender como os Nomes de Recursos da Amazon (ARNs — Amazon Resource Names) funcionam dentro do serviço. A AWS publicou um guia técnico detalhado sobre esse tema, e a CloudTroop traz aqui uma leitura comentada para o público brasileiro.
Uma nota importante sobre nomenclatura
O Amazon Quick é o nome atual do serviço, mas os ARNs e endpoints de API ainda utilizam quicksight como identificador de serviço. Isso foi mantido para garantir compatibilidade com políticas existentes do Serviço de Gerenciamento de Identidade e Acesso (IAM — Identity and Access Management), automações e integrações já em produção. Portanto, você continuará vendo ARNs no formato:
arn:aws:quicksight:us-east-1:123456789012:dashboard/...
O trecho quicksight refere-se à capacidade Quick Sight dentro do Amazon Quick. Códigos, políticas IAM e comandos de interface de linha de comando (CLI — Command Line Interface) existentes continuam funcionando sem modificação. Para mais detalhes, consulte a documentação de ARNs de Recursos do Amazon Quick Sight.
ARNs como endereços postais
Uma forma simples de entender ARNs: pense neles como endereços postais. Assim como “Rua Principal, 123, São Paulo, SP” identifica um local único, um ARN identifica de forma única um recurso dentro da AWS. Veja como os componentes se mapeiam:
- aws → Partição da AWS (aws / aws-cn / aws-gov-us)
- quicksight → O serviço dentro da partição
- us-east-1 → Região da AWS
- 111111111111 → ID da conta AWS
- dashboard → Tipo de recurso
- 04f736b4-bd1b-… → ID único do recurso
O ponto mais importante aqui: o ID da conta faz parte do endereço. Se você muda de conta, o endereço muda — mesmo que o ID do recurso seja idêntico. Migrar um dashboard de desenvolvimento para produção gera um ARN diferente, porque o ID da conta é diferente.
Migração entre contas: o que muda e o que permanece
Imagine uma empresa com três contas AWS para seu ambiente Amazon Quick: Desenvolvimento (conta 111111111111), Qualidade/Testes (conta 222222222222) e Produção (conta 333333333333).
Uma analista cria um dashboard de vendas em Desenvolvimento:
arn:aws:quicksight:us-east-1:111111111111:dashboard/sales-dash-001
Ao usar as APIs de Asset Bundle para migrar para Qualidade/Testes, o dashboard recebe um novo ARN:
arn:aws:quicksight:us-east-1:222222222222:dashboard/sales-dash-001
O que mudou: o ID da conta (111111111111 → 222222222222). O que permaneceu: o ID do recurso (sales-dash-001) e a região (us-east-1). O dashboard em Qualidade/Testes é um recurso diferente do original, mesmo compartilhando o mesmo ID de recurso.
Por que permissões não migram automaticamente
O Amazon Quick armazena permissões como relacionamentos entre ARNs de recursos e ARNs de principais (usuários ou grupos). Uma permissão concedida em Desenvolvimento diz, essencialmente: “o grupo DataAnalysts da conta 111111111111 pode visualizar este dashboard.”
Após a migração para Qualidade/Testes, três coisas mudam:
- O dashboard tem um novo ARN (conta diferente).
- O grupo DataAnalysts da conta
111111111111 não existe na conta 222222222222.
- Um grupo DataAnalysts em Qualidade/Testes teria um ARN diferente, referenciando o ID da conta de destino.
Conclusão: permissões precisam ser reestabelecidas em cada ambiente de destino, seja durante a importação ou logo após.
A cadeia de dependências e a transformação automática de ARNs
Um dashboard não existe de forma isolada. Ele depende de datasets, que por sua vez dependem de fontes de dados (data sources). Cada um tem seu próprio ARN, e o dashboard referencia todos eles internamente.
Quando as APIs de Asset Bundle importam um bundle para a conta de destino, elas atualizam automaticamente essas referências internas de ARN para refletir o novo ID de conta. Porém, essa transformação funciona apenas para os ativos incluídos no bundle. Se você importar somente o dashboard sem seus datasets e fontes de dados, ele ficará referenciando recursos que não existem na conta de destino.
A recomendação da AWS é clara: sempre inclua todas as dependências na exportação, usando IncludeAllDependencies=True.
Reutilizando recursos existentes com OverrideParameters
Um cenário comum: o ambiente de Qualidade/Testes já tem uma fonte de dados configurada para o banco de dados de QA. Você não quer criar uma duplicata — quer que o dashboard importado use a conexão existente.
O parâmetro OverrideParameters na API StartAssetBundleImportJob resolve isso. Ele permite sobrescrever parâmetros de conexão, credenciais e comportamento de IDs de recursos durante a importação:
response = qs.start_asset_bundle_import_job(
AwsAccountId='222222222222',
AssetBundleImportJobId='import-sales-dash-to-qa',
AssetBundleImportSource={'Body': bundle_bytes},
OverrideParameters={
'ResourceIdOverrideConfiguration': {
'PrefixForAllResources': False
},
'DataSources': [{
'DataSourceId': 'sales-db-connection',
'DataSourceParameters': {
'AthenaParameters': {
'WorkGroup': 'qa-workgroup'
}
},
'Credentials': {
'CredentialPair': {
'Username': 'qa_service_user',
'Password': '{{resolve:secretsmanager:qa-db-creds:SecretString:password}}'
}
}
}]
}
)
Para credenciais, há três métodos disponíveis: CredentialPair (usuário e senha), CopySourceArn (copiar de uma fonte de dados existente) ou SecretArn (referenciar diretamente um segredo no AWS Secrets Manager). A AWS recomenda o uso de SecretArn quando a organização gerencia credenciais no Secrets Manager:
'Credentials': {
'SecretArn': 'arn:aws:secretsmanager:us-east-1:222222222222:secret:qa-db-creds'
}
Namespaces: como a identidade funciona em ambientes multi-tenant
Os namespaces do Amazon Quick oferecem isolamento multi-tenant dentro de uma única conta AWS. São amplamente usados por provedores de Software como Serviço (SaaS — Software as a Service) que embarcam analytics para múltiplos clientes, empresas com fronteiras departamentais rígidas e companhias que precisam isolar populações de usuários.
O conceito mais importante aqui: namespaces afetam ARNs de principais (usuários e grupos), não ARNs de ativos (dashboards, datasets).
Mesmo nome de usuário, pessoas diferentes
Considere dois namespaces na mesma conta: HR e Marketing. Ambos têm um usuário chamado nikki_wolf:
HR nikki_wolf: arn:aws:quicksight:us-east-1:444444444444:user/HR/nikki_wolf
Marketing nikki_wolf: arn:aws:quicksight:us-east-1:444444444444:user/Marketing/nikki_wolf
São dois principais completamente diferentes. Compartilham o nome de usuário, mas seus ARNs são distintos porque o namespace é diferente. Conceder acesso a um dashboard para o nikki_wolf do HR não dá acesso ao nikki_wolf do Marketing. Sempre use o ARN completo do principal, incluindo o namespace, ao conceder ou depurar permissões.
Ativos vivem fora dos namespaces; principais vivem dentro
Os ARNs de ativos não contêm namespace:
Dashboard ARN (sem namespace): arn:aws:quicksight:us-east-1:444444444444:dashboard/shared-metrics
User ARN (com namespace): arn:aws:quicksight:us-east-1:444444444444:user/HR/alice
Isso é o que viabiliza o compartilhamento entre namespaces: um único dashboard pode ser compartilhado com usuários de múltiplos namespaces, desde que as permissões sejam concedidas com os ARNs completos de cada principal.
Compartilhamento entre namespaces
Para compartilhar um dashboard de anúncios com todos os clientes, basta conceder permissões a grupos de diferentes namespaces:
qs.update_dashboard_permissions(
AwsAccountId='444444444444',
DashboardId='platform-announcements',
GrantPermissions=[
{
'Principal': 'arn:aws:quicksight:us-east-1:444444444444:group/HR/Executives',
'Actions': ['quicksight:DescribeDashboard', 'quicksight:QueryDashboard']
},
{
'Principal': 'arn:aws:quicksight:us-east-1:444444444444:group/Marketing/Executives',
'Actions': ['quicksight:DescribeDashboard', 'quicksight:QueryDashboard']
},
{
'Principal': 'arn:aws:quicksight:us-east-1:444444444444:group/default/PlatformTeam',
'Actions': ['quicksight:DescribeDashboard', 'quicksight:QueryDashboard', 'quicksight:UpdateDashboard']
}
]
)
Permissões com wildcard por namespace
O Amazon Quick suporta ARNs com wildcard para concessões de acesso amplas dentro de um namespace:
arn:aws:quicksight:us-east-1:444444444444:user/HR/*
Isso concede acesso a todos os usuários atuais e futuros do namespace HR. O wildcard se aplica apenas ao namespace especificado — usuários do Marketing não ganham acesso. Wildcards também funcionam no OverridePermissions durante a importação de asset bundles. A AWS recomenda usá-los com cuidado para permissões de escrita ou administração; para acesso somente leitura, são uma boa opção.
Fluxo completo: migração de ponta a ponta
Aqui está um exemplo completo combinando todos os conceitos anteriores. O cenário: uma empresa migrando sua suíte de Analytics de Vendas do ambiente de Desenvolvimento para Produção, com três dashboards, cinco datasets, duas fontes de dados (Amazon Athena e Amazon Redshift) e usuários em dois namespaces (SalesTeam e Executives).
Passo 1: Exportar do ambiente de desenvolvimento
export_response = qs.start_asset_bundle_export_job(
AwsAccountId='111111111111',
AssetBundleExportJobId='sales-analytics-export',
ResourceArns=[
'arn:aws:quicksight:us-east-1:111111111111:dashboard/sales-overview',
'arn:aws:quicksight:us-east-1:111111111111:dashboard/sales-details',
'arn:aws:quicksight:us-east-1:111111111111:dashboard/sales-trends'
],
IncludeAllDependencies=True,
ExportFormat='QUICKSIGHT_JSON'
)
Passo 2: Importar para produção com overrides
import_response = qs.start_asset_bundle_import_job(
AwsAccountId='333333333333',
AssetBundleImportJobId='sales-analytics-import',
AssetBundleImportSource={'Body': bundle_bytes},
OverrideParameters={
'ResourceIdOverrideConfiguration': {
'PrefixForAllResources': False
},
'DataSources': [
{
'DataSourceId': 'dev-athena-source',
'Name': 'Production Athena',
'DataSourceParameters': {
'AthenaParameters': {'WorkGroup': 'prod-workgroup'}
}
},
{
'DataSourceId': 'dev-redshift-source',
'Name': 'Production Redshift',
'DataSourceParameters': {
'RedshiftParameters': {
'Host': 'prod-cluster.xxxxx.us-east-1.redshift.amazonaws.com',
'Database': 'analytics',
'Port': 5439
}
},
'Credentials': {
'SecretArn': 'arn:aws:secretsmanager:us-east-1:333333333333:secret:prod-db-creds'
}
}
]
},
OverridePermissions={
'Dashboards': [{
'DashboardIds': ['sales-overview', 'sales-details', 'sales-trends'],
'Permissions': {
'Principals': [
'arn:aws:quicksight:us-east-1:333333333333:user/SalesTeam/*'
],
'Actions': ['quicksight:DescribeDashboard', 'quicksight:QueryDashboard']
}
}]
}
)
Usar OverridePermissions junto com OverrideParameters define as permissões durante a importação, reduzindo a janela em que recursos existem sem controles de acesso adequados.
Passo 3: Conceder permissões granulares adicionais
qs.update_dashboard_permissions(
AwsAccountId='333333333333',
DashboardId='sales-trends',
GrantPermissions=[{
'Principal': 'arn:aws:quicksight:us-east-1:333333333333:group/Executives/Leadership',
'Actions': ['quicksight:DescribeDashboard', 'quicksight:QueryDashboard']
}]
)
Referência rápida: formatos de ARN
ARNs de ativos (sem namespace):
- Dashboard:
arn:aws:quicksight:{region}:{account}:dashboard/{id}
- Analysis:
arn:aws:quicksight:{region}:{account}:analysis/{id}
- Dataset:
arn:aws:quicksight:{region}:{account}:dataset/{id}
- Data Source:
arn:aws:quicksight:{region}:{account}:datasource/{id}
- Theme:
arn:aws:quicksight:{region}:{account}:theme/{id}
- Folder:
arn:aws:quicksight:{region}:{account}:folder/{id}
- Topic:
arn:aws:quicksight:{region}:{account}:topic/{id}
ARNs de principais (com namespace):
- Usuário:
arn:aws:quicksight:{region}:{account}:user/{namespace}/{username}
- Grupo:
arn:aws:quicksight:{region}:{account}:group/{namespace}/{groupname}
- Wildcard (todos os usuários do namespace):
arn:aws:quicksight:{region}:{account}:user/{namespace}/*
Funções utilitárias para scripts de migração
A AWS disponibiliza funções Python para facilitar a manipulação de ARNs em scripts e pipelines de Integração e Entrega Contínua (CI/CD — Continuous Integration/Continuous Delivery):
def parse_asset_arn(arn: str) -> dict:
"""Parse an Amazon Quick asset ARN into components."""
parts = arn.split(':')
resource_parts = parts[5].split('/', 1)
return {
'region': parts[3],
'account_id': parts[4],
'resource_type': resource_parts[0],
'resource_id': resource_parts[1]
}
def parse_principal_arn(arn: str) -> dict:
"""Parse an Amazon Quick principal ARN into components."""
parts = arn.split(':')
resource_parts = parts[5].split('/')
return {
'region': parts[3],
'account_id': parts[4],
'principal_type': resource_parts[0],
'namespace': resource_parts[1],
'principal_name': resource_parts[2]
}
def transform_arn_for_account(source_arn: str, target_account: str) -> str:
"""Transform an ARN to a different account."""
parsed = parse_asset_arn(source_arn)
return f"arn:aws:quicksight:{parsed['region']}:{target_account}:{parsed['resource_type']}/{parsed['resource_id']}"
def build_principal_arn(account: str, namespace: str, principal_type: str, name: str, region: str = 'us-east-1') -> str:
"""Build a principal ARN."""
return f"arn:aws:quicksight:{region}:{account}:{principal_type}/{namespace}/{name}"
Guia de troubleshooting para problemas comuns
“Resource not found” após migração
Sintoma: Dashboard carrega, mas exibe erros de “Dataset not found”. Causa: O dashboard referencia um ARN de dataset da conta de origem, ou as dependências não foram incluídas no bundle. Solução: Verifique se todas as dependências foram exportadas com IncludeAllDependencies=True e confirme que o job de importação foi concluído com sucesso via DescribeAssetBundleImportJob.
“Access denied” para usuário que deveria ter acesso
Sintoma: Usuário não consegue ver um dashboard compartilhado com ele. Diagnóstico: Verifique em qual namespace o usuário está e se o ARN do principal no grant corresponde exatamente ao ARN real do usuário:
# Check what permissions exist
perms = qs.describe_dashboard_permissions(
AwsAccountId=account_id,
DashboardId='the-dashboard'
)
print("Granted to:", [p['Principal'] for p in perms['Permissions']])
# Check the user's actual ARN
user = qs.describe_user(
AwsAccountId=account_id,
Namespace='Finance',
UserName='nikki_wolf'
)
print("User ARN:", user['User']['Arn'])
Atenção: Se o recurso estiver em uma pasta restrita, não é possível compartilhá-lo diretamente, independentemente da correção do ARN. O acesso a recursos em pastas restritas só ocorre por meio das permissões do container da hierarquia da pasta restrita.
“Invalid principal” ao conceder permissões
Sintoma: A API retorna erro ao tentar conceder permissões. Causa: O ARN do principal está malformado, ou o usuário/grupo não existe no namespace especificado. Solução: Verifique se o principal existe antes de conceder permissões:
try:
qs.describe_user(
AwsAccountId=account_id,
Namespace='Finance',
UserName='nikki_wolf'
)
print("User exists, safe to grant permissions")
except qs.exceptions.ResourceNotFoundException:
print("User does not exist in this namespace")
Os quatro pontos fundamentais sobre ARNs no Amazon Quick
O guia da AWS resume o entendimento de ARNs no Amazon Quick em quatro conceitos-chave:
- ARNs são vinculados à conta. Ao migrar entre contas, o endereço muda mesmo que o ID do recurso permaneça igual.
- Permissões referenciam ARNs completos, não nomes. Conceder acesso a um usuário exige especificar conta e namespace — você sempre está concedendo a um ARN específico.
- Ativos vivem fora dos namespaces; principais vivem dentro. Isso viabiliza o compartilhamento entre namespaces, mas exige ARNs completos de principais em toda operação.
- O mesmo nome de usuário em namespaces diferentes representa pessoas diferentes. A migração muda ARNs mas preserva IDs de recursos; as APIs de Asset Bundle cuidam das atualizações de referências internas.
Próximos passos
Para começar a aplicar esses conceitos no seu ambiente, a AWS recomenda:
Fonte
Amazon Quick ARNs: Cross-account migration and namespace permissions (https://aws.amazon.com/blogs/machine-learning/amazon-quick-arns-cross-account-migration-and-namespace-permissions/)