T
traeai
登录
返回首页
AWS Machine Learning Blog

Amazon Quick ARNs: Cross-account migration and namespace permissions

6.9Score
Amazon Quick ARNs: Cross-account migration and namespace permissions

TL;DR · AI 摘要

Amazon Quick ARNs: Cross-account migration and namespace permissions Artificial Intelligence Amazon Quick ARNs: Cross-ac...

核心要点

  • 主题聚焦：Amazon Quick ARNs: Cross-account migration and n
  • 来源：AWS Machine Learning Blog，建议结合原文判断细节。
  • AI 分析暂不可用，本条为保底评分与摘要。
#AI#编程#后端#安全#产品
打开原文

Amazon Quick ARNs：跨账户迁移和命名空间权限 | 人工智能

Amazon Quick ARNs：跨账户迁移和命名空间权限

你将仪表板从开发环境迁移到生产环境，但权限没有随之转移。你与财务团队共享了一个仪表板，但他们一直收到“访问被拒绝”的提示。你设置了用于多租户隔离的命名空间，但相同的用户名在一个命名空间中可以使用，而在另一个命名空间中却不行。

这些都是 Amazon Quick 管理员经常处理的实际任务，而正确处理这些任务需要对 Amazon 资源名称（ARN）的工作方式有清晰的理解。

Amazon Quick 是一个统一的、由人工智能驱动的商业智能服务，帮助你构建交互式仪表板、以自然语言查询数据、自动化工作流程，并直接将分析嵌入到应用程序中。随着你在多个 AWS 账户和命名空间中扩展部署，理解 Amazon Quick 如何通过 ARNs 识别和保护资源变得至关重要。

在本文中，我们将介绍 Amazon Quick ARNs 的结构，并提供一个实用的思维方式来处理它们。到文章结束时，你将能够通过查看一个 ARN 立即了解它对你的迁移策略意味着什么，更快地诊断权限问题，并自信地设计多租户架构。

关于命名的说明

Amazon Quick 是你今天使用的服务，但 ARNs 和 API 端点仍然使用“quicksight”作为服务标识符。我们保留这一点是为了与现有的 AWS 身份和访问管理（IAM）策略、自动化和客户环境中的集成保持兼容性。

在本文中，你会看到如下 ARN：

code
arn:aws:quicksight:us-east-1:123456789012:dashboard/...

“quicksight”部分指的是 Amazon Quick 中的 Quick Sight 功能。现有的代码、IAM 策略和 CLI 命令在当前实现中无需修改即可继续使用。有关更多信息，请参阅 Amazon Quick Sight 资源 ARNs。

将 ARNs 视为邮政地址

就像“123 Main Street, Springfield, MA”唯一标识一个位置一样，ARN 在 AWS 中唯一标识一个资源。以下是一个 ARN 组件的视觉表示：

以下是组件的对应关系：

组件

类比

代表什么

aws

星球

AWS 分区 - aws / aws-cn / aws-gov-us

quicksight

国家

AWS 分区内的服务

us-east-1

州

AWS 区域

111111111111

城市

AWS 账户 ID

dashboard

街道

资源类型

04f736b4-bd1b-…

门牌号

唯一资源 ID

账户 ID 是地址的一部分。搬到一个新的城市，即使你获得了一条具有相同街道号码的房子，你的地址也会改变。同样的情况也适用于 Amazon Quick 资源。将仪表板从开发账户迁移到生产账户时，ARN 会改变，因为账户 ID 不同。

实际应用中的示例：开发/测试/生产

AnyCompany 为他们的 Amazon Quick 部署设置了三个 AWS 账户：

  • 开发（账户：111111111111）：分析师在此构建新的仪表板。
  • 测试（账户：222222222222）：仪表板在此测试后发布。
  • 生产（账户：333333333333）：业务用户在此访问已批准的仪表板。

AnyCompany 的数据分析师 Saanvi 在开发环境中构建了一个销售仪表板：

code
arn:aws:quicksight:us-east-1:111111111111:dashboard/sales-dash-001

她使用资产包 API 将其迁移到测试环境。现在，仪表板有了一个新的 ARN：

code
arn:aws:quicksight:us-east-1:222222222222:dashboard/sales-dash-001

发生了变化和未发生变化的内容：

  • 账户 ID 发生了变化（111111111111 → 222222222222）。
  • 资源 ID 保持不变（sales-dash-001）。
  • 区域保持不变（us-east-1）。

尽管 QA 环境中的仪表板与开发环境中的仪表板共享相同的资源 ID，但它们是不同的资源。不同的 ARN 表示在 AWS 宇宙中的不同地址。

为什么在迁移过程中权限不会转移

在开发环境中，Saanvi 授予了她的团队查看权限：

code
# 开发账户权限
qs.update_dashboard_permissions(
    AwsAccountId='111111111111',
    DashboardId='sales-dash-001',
    GrantPermissions=[{
        'Principal': 'arn:aws:quicksight:us-east-1:111111111111:group/default/DataAnalysts',
        'Actions': ['quicksight:DescribeDashboard', 'quicksight:QueryDashboard']
    }]
)

迁移至 QA 环境后，仪表板没有任何权限。Amazon QuickSight 将权限存储为资源 ARN 与主体 ARN 之间的关系。原始权限表示“账户 111111111111 中的 DataAnalysts 组可以查看此仪表板。”但在 QA 环境中：

  • 仪表板具有新的 ARN（不同的账户）。
  • 账户 111111111111 中的 DataAnalysts 组在账户 222222222222 中不存在。
  • QA 环境中的 DataAnalysts 组具有不同的 ARN（它引用了 QA 账户的账户 ID）。

权限不会迁移，因为它们引用了特定于账户的 ARN。您必须在每个目标环境中重新建立权限，无论是导入期间还是导入之后。

依赖链是如何工作的

Saanvi 的仪表板并不是孤立存在的。它依赖于：

  • 一个数据集（sales-data），用于转换原始数据。
  • 一个数据源（sales-db-connection），用于连接到数据库。

每个资源都有自己的 ARN，仪表板在内部引用它们：

code
开发账户（111111111111）：
├── 仪表板：arn:aws:quicksight:...:111111111111:dashboard/sales-dash-001
│   └── 引用：arn:aws:quicksight:...:111111111111:dataset/sales-data
│       └── 引用：arn:aws:quicksight:...:111111111111:datasource/sales-db-connection

当 Asset Bundle APIs 将捆绑包导入目标账户时，它们会自动更新这些内部 ARN 引用以反映新的账户 ID：

code
QA 账户（222222222222）：
├── 仪表板：arn:aws:quicksight:...:222222222222:dashboard/sales-dash-001
│   └── 引用：arn:aws:quicksight:...:222222222222:dataset/sales-data
│       └── 引用：arn:aws:quicksight:...:222222222222:datasource/sales-db-connection

导入过程会自动处理这种 ARN 转换，但仅限于捆绑包中包含的资源。如果您仅导入仪表板而没有其数据集和数据源依赖项，仪表板将引用目标账户中不存在的资源。

始终在导出捆绑包中包含所有依赖项（使用 IncludeAllDependencies=True）。导入过程会自动更新内部 ARN 引用，但仅限于捆绑包中包含的资源。

使用 OverrideParameters 重用现有资源

一个常见场景：QA 环境中已经配置了用于 QA 数据库的数据源。您不希望有重复。您希望导入的仪表板使用现有的连接。

StartAssetBundleImportJob API 中的 OverrideParameters 处理了这种情况。它允许您在导入过程中覆盖数据源连接参数、凭据和资源 ID 行为：

code
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}}'
                }
            }
        }]
    }
)

关于 OverrideParameters 的注意事项：

  • ResourceIdOverrideConfiguration 控制导入的资源 ID 是否添加前缀（有助于避免 ID 冲突）。
  • 使用 DataSources，您可以按数据源覆盖连接参数和凭据。
  • 凭据方法：您可以使用 CredentialPair（用户名/密码）、CopySourceArn（从现有数据源复制）或 SecretArn（直接引用 AWS Secrets Manager 的秘密）。当您的组织在 AWS Secrets Manager 中管理数据库凭据时，请使用 SecretArn：
code
'Credentials': {
    'SecretArn': 'arn:aws:secretsmanager:us-east-1:222222222222:secret:qa-db-creds'
}

在迁移过程中，您对如何解析 ARN 引用有完全的控制权。您可以保留 ID、映射到现有资源，或重新配置连接，所有操作都可以通过导入配置完成。

命名空间：多租户环境中的身份识别方式

Amazon Quick 的命名空间在单个 AWS 账户内提供多租户隔离。它们通常用于以下场景：

  • 将 Amazon Quick 嵌入到多个客户中的 SaaS 提供商。
  • 具有严格部门边界的大型企业。
  • 需要隔离用户群体的公司。

最重要的概念是：命名空间影响的是主体 ARN，而不是资产 ARN。

多租户示例

AnyCompany 是一家为客户提供分析服务的 SaaS 公司。他们使用一个 Amazon Quick 账户，并通过命名空间实现隔离：

code
Account: 444444444444
├── Namespace: HR
│   ├── Users: alice, bob
│   └── Groups: Analysts, Executives
├── Namespace: Marketing
│   ├── Users: charlie, diana
│   └── Groups: Analysts, Executives
└── Namespace: default (AnyCompany 内部用户)
    ├── Users: admin, sarah
    └── Groups: PlatformTeam

查看 HR 命名空间中的用户 “alice”：

code
arn:aws:quicksight:us-east-1:444444444444:user/HR/alice

以及 HR 命名空间中的 “Analysts” 组：

code
arn:aws:quicksight:us-east-1:444444444444:group/HR/Analysts

命名空间（HR）嵌入在 ARN 中。与资产 ARN 相比，资产 ARN 没有命名空间部分：

code
仪表板 ARN（无命名空间）：
arn:aws:quicksight:us-east-1:444444444444:dashboard/shared-metrics

用户 ARN（有命名空间）：
arn:aws:quicksight:us-east-1:444444444444:user/HR/alice

资产存在于命名空间之外。用户和组存在于命名空间内部。这就是跨命名空间共享的支持方式：一个仪表板可以与多个命名空间中的用户共享。但这也意味着您必须始终指定完整的主体 ARN。命名空间是身份的一部分。

相同的用户名，不同的用户

考虑同一账户中的两个命名空间：HR 命名空间和 Marketing 命名空间。两者都有一个名为 “nikki_wolf” 的用户：

code
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

这些是完全不同的主体。它们共享一个用户名，但由于命名空间不同，其 ARN 也不同。

为 HR 的 nikki_wolf 授予仪表板访问权限，而 Marketing 的 nikki_wolf 仍然无法查看它。不同的 ARN，不同的身份。

不同命名空间中的相同用户名代表完全不同的主体。在授予权限或排查权限问题时，始终使用完整的主体 ARN（包括命名空间）。

跨命名空间共享

AnyCompany 想要与所有客户共享一个平台范围的公告仪表板：

code
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']
        }
    ]
)

一个仪表板（一个 ARN）向来自三个不同命名空间的主体授予了权限。该仪表板不属于任何命名空间。它存在于账户级别，并可以与任何人共享。

仪表板和其他资产是与命名空间无关的。通过向其完整的主体 ARN 授予权限，您可以将单个资产与来自任意数量命名空间的主体共享。

通配符权限

Amazon Quick 支持用于命名空间作用域授权的通配符主体 ARN：

code
arn:aws:quicksight:us-east-1:444444444444:user/HR/*

这将向 HR 命名空间中的所有用户（包括当前和未来的用户）授予访问权限：

code
qs.update_dashboard_permissions(
    AwsAccountId='444444444444',
    DashboardId='customer-a-overview',
    GrantPermissions=[{
        'Principal': 'arn:aws:quicksight:us-east-1:444444444444:user/HR/*',
        'Actions': ['quicksight:DescribeDashboard', 'quicksight:QueryDashboard']
    }]
)

请记住以下几点：

  • 通配符仅适用于指定的命名空间。Marketing 用户不会获得访问权限。
  • 在资产包导入期间的 OverridePermissions 中也支持通配符，因此您可以在迁移管道中设置广泛的权限模式。
  • 通配符最适合用于只读访问模式。对于写入或管理访问，建议使用基于组的显式授权。

通配符授予命名空间中所有当前和未来用户的访问权限。它们简化了广泛的只读访问，但在写入权限方面应谨慎使用。

综合运用：端到端迁移

以下是一个完整的工作流程，结合了前面各部分的所有内容。

场景：AnyCompany 正在将其销售分析套件从开发环境迁移到生产环境。他们有：

  • 三个仪表板。
  • 五个数据集。
  • 两个数据源（一个 Amazon Athena，一个 Amazon Redshift）。
  • 两个命名空间中的用户（SalesTeam、Executives）。

步骤 1：从开发环境导出

使用 StartAssetBundleExportJob API 将仪表板及其所有依赖项（数据集、数据源）打包成一个可移植的包。设置 IncludeAllDependencies=True 可以支持自动捕获完整的依赖树，而无需手动跟踪每个引用的资源。

code
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'
)

步骤 2：使用覆盖设置导入到生产环境

生产环境已经配置了数据源。将导入的资产映射到这些数据源，并在导入过程中设置权限：

code
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']
            }
        }]
    }
)

将 OverridePermissions 与 OverrideParameters 一起使用，可以在导入过程中设置权限，而不是作为单独的步骤，从而减少资源在没有适当访问控制的情况下存在的窗口。

步骤 3：授予额外的细粒度权限

步骤 2 中的通配符为整个 SalesTeam 命名空间提供了广泛的读取权限。对于特定角色的访问，例如将某些仪表板限制在 Executives 命名空间中的 Leadership 组，可以在导入后单独授予权限：

code
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']
    }]
)

ARN 转换摘要

资源 | 开发 ARN | 生产 ARN --- | --- | --- 资产 | …111111111111:dashboard/sales-overview | …333333333333:dashboard/sales-overview 数据集 | …111111111111:dataset/sales-data | …333333333333:dataset/sales-data 数据源 | …111111111111:datasource/dev-athena-source | …333333333333:datasource/dev-athena-source

资源 ID 保持不变，账户 ID 发生了变化。导入过程会自动更新内部引用。您通过 OverridePermissions 设置权限，并进行后续授权。

使用 OverrideParameters 重新配置数据源连接，使用 OverridePermissions 在导入过程中设置访问控制。这使您能够在一次 API 调用中完成完整且可重复的迁移。

快速参考：ARN 格式

注意：ARN 使用 “quicksight” 作为标识符以保持向后兼容性。

资源 ARN（无命名空间）

ARN 格式

arn:aws:quicksight:{region}:{account}:dashboard/{id}

分析

arn:aws:quicksight:{region}:{account}:analysis/{id}

arn:aws:quicksight:{region}:{account}:dataset/{id}

arn:aws:quicksight:{region}:{account}:datasource/{id}

主题

arn:aws:quicksight:{region}:{account}:theme/{id}

文件夹

arn:aws:quicksight:{region}:{account}:folder/{id}

主题

arn:aws:quicksight:{region}:{account}:topic/{id}

主体 ARN（带命名空间）

主体类型

用户

arn:aws:quicksight:{region}:{account}:user/{namespace}/{username}

组

arn:aws:quicksight:{region}:{account}:group/{namespace}/{groupname}

通配符（命名空间中的所有用户）

arn:aws:quicksight:{region}:{account}:user/{namespace}/*

工具函数

以下 Python 辅助函数使解析、转换和编程方式构建 ARN 变得更容易。在迁移脚本和 CI/CD 管道中使用它们，以避免手动字符串操作错误。

code
def parse_asset_arn(arn: str) -> dict:
    """将 Amazon Quick 资源 ARN 解析为组件。"""
    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:
    """将 Amazon Quick 主体 ARN 解析为组件。"""
    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:
    """将 ARN 转换到不同的账户。"""
    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:
    """构建主体 ARN。"""
    return f"arn:aws:quicksight:{region}:{account}:{principal_type}/{namespace}/{name}"

故障排除指南

以下部分涵盖了迁移和权限管理过程中最常见的与 ARN 相关的问题，以及解决这些问题的诊断步骤。

迁移后出现“资源未找到”

症状：仪表板加载但显示“数据集未找到”错误。

原因：仪表板引用了源账户中的数据集 ARN，或者依赖项未包含在导入包中。

修复：确认所有依赖项都已包含在导出中（使用 IncludeAllDependencies=True），或使用 ResourceIdOverrideConfiguration 将其映射到现有目标资源。通过调用 DescribeAssetBundleImportJob 确认导入任务是否成功完成。

用户应有访问权限却收到“访问被拒绝”

症状：用户无法查看已与他们共享的仪表板。

诊断检查清单：

  • 用户属于哪个命名空间？
  • 您授予了哪些主体 ARN 的权限？
  • 它们是否匹配？
  • 资源是否位于受限文件夹中？
python
# 检查存在哪些权限
perms = qs.describe_dashboard_permissions(
    AwsAccountId=account_id,
    DashboardId='the-dashboard'
)
print("已授予给:", [p['Principal'] for p in perms['Permissions']])

# 检查用户的实际 ARN
user = qs.describe_user(
    AwsAccountId=account_id,
    Namespace='Finance',
    UserName='nikki_wolf'
)
print("用户 ARN:", user['User']['Arn'])

受限文件夹：如果资源位于受限文件夹中，无论 ARN 是否正确，都无法直接共享该资源。您只能通过受限文件夹层次结构内的容器权限访问受限文件夹中的资源。ARN 和权限可能看起来正确，但文件夹级别的限制优先于这些设置。

授予权限时出现“无效主体”

症状：尝试授予权限时，API 返回错误。

原因：主体 ARN 格式错误，或用户/组在指定的命名空间中不存在。

修复：在授予权限之前验证主体是否存在：

python
try:
    qs.describe_user(
        AwsAccountId=account_id,
        Namespace='Finance',
        UserName='nikki_wolf'
    )
    print("用户存在，可以安全地授予权限")
except qs.exceptions.ResourceNotFoundException:
    print("此命名空间中不存在该用户")

结论

在本文中，我们展示了 Amazon Quick ARNs 在跨账户迁移和命名空间权限场景中的工作方式。理解 Amazon Quick ARNs 的关键在于以下四点：

  • ARNs 是与账户绑定的。当您在账户之间迁移时，即使资源 ID 保持不变，地址也会发生变化。
  • 权限引用完整的 ARNs，而不是名称。向“nikki_wolf”授予访问权限需要指定账户和命名空间。您始终是向特定的 ARN 授予权限。
  • 资产位于命名空间之外，而主体位于命名空间内部。这支持跨命名空间共享，但也意味着每次都需要完整的主体 ARN。不同命名空间中的相同用户名代表不同的人。
  • 迁移会更改 ARNs，但保留资源 ID。Asset Bundle API 会处理内部引用的更新。您可以在导入期间使用 OverridePermissions 设置权限，或在之后单独授予它们。

下一步

要在您自己的环境中应用这些概念：

  • 查阅 Asset Bundle Operations 文档，设置您的第一个跨账户迁移管道。
  • 如果您计划构建多租户架构，请探索 Amazon Quick 命名空间。
  • 参考 StartAssetBundleImportJob API，了解完整的 OverrideParameters 和 OverridePermissions 架构。
  • 查阅 Amazon Quick 权限，了解 IAM 集成模式。
  • 参考 Amazon Quick ARNs 清单，了解所有资源 ARN 格式。

在 AWS 管理控制台中亲自尝试此解决方案，并告诉我们它在您的迁移和多租户场景中效果如何。

作者简介

'"`

AI 可能会生成不准确的信息，请核实重要内容

Amazon Quick ARNs: Cross-account migration and namespace permissions | AWS Machine Learning Blog | traeai