AWS IoT Greengrass
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使用密钥资源

AWS IoT Greengrass 使用密钥资源 将来自 AWS Secrets Manager 的密钥集成到 Greengrass 组中。密钥资源是对 Secrets Manager 密钥的引用。有关更多信息,请参阅将密钥部署到 AWS IoT Greengrass 核心

在 AWS IoT Greengrass Core 设备上,连接器和 Lambda 函数可使用密钥资源对服务和应用程序进行身份验证,而无需对密码、令牌或其他凭证进行硬编码。

创建和管理密钥

在 Greengrass 组中,密钥资源引用 Secrets Manager 密钥的 ARN。将密钥资源部署到核心时,密钥值经过加密,可供关联的连接器和 Lambda 函数使用。有关更多信息,请参阅密钥加密

您将使用 Secrets Manager 创建和管理密钥的云版本。使用 AWS IoT Greengrass 创建、管理和部署您的密钥资源。

重要

我们建议您遵循在 Secrets Manager 中轮换密钥的最佳实践。然后,部署 Greengrass 组,以更新密钥的本地副本。有关更多信息,请参阅 AWS Secrets Manager 用户指南 中的轮换 AWS Secrets Manager 密钥

使密钥在 Greengrass 核心上可用

  1. 在 Secrets Manager 中创建密钥。这是密钥的云版本,它集中存储和托管在 Secrets Manager 中。管理任务包括轮换密钥值和应用资源策略。

  2. 在 AWS IoT Greengrass 中创建一个密钥资源。这是一种引用云密钥 ARN 的组资源。每个组一次只能引用一个密钥。

  3. 配置您的连接器或 Lambda 函数。您必须通过指定对应的参数或属性,将资源与连接器或函数相关联。这样可使其获取本地部署的密钥资源值。有关更多信息,请参阅 在连接器和 Lambda 函数中使用本地密钥

  4. 部署 Greengrass 组。在部署期间,AWS IoT Greengrass 提取云密钥的值并在核心上创建(或更新)本地密钥。

每当 AWS IoT Greengrass 检索密钥值时,Secrets Manager 都会在 AWS CloudTrail 中记录事件。AWS IoT Greengrass 不会记录与本地密钥部署或使用相关的任何事件。有关 Secrets Manager 日志记录的更多信息,请参阅AWS Secrets Manager 用户指南中的监控 AWS Secrets Manager 密钥的使用情况

在密钥资源中添加暂存标签

Secrets Manager 使用暂存标签来标识密钥值的特定版本。暂存标签可以是系统定义或用户定义的标签。Secrets Manager 将 AWSCURRENT 标签分配给密钥值的最新版本。暂存标签通常用于管理密钥轮换。有关 Secrets Manager 版本控制的更多信息,请参阅AWS Secrets Manager 用户指南中的 AWS Secrets Manager 的主要术语和概念

密钥资源始终包含 AWSCURRENT 暂存标签,还可以选择包含其他暂存标签(如果 Lambda 函数或连接器需要)。在组部署期间,AWS IoT Greengrass 检索在组中引用的暂存标签值,然后在核心上创建或更新对应的值。

创建和管理密钥资源(控制台)

创建密钥资源(控制台)

在 AWS IoT Greengrass 控制台 中,您将在组的 Resources (资源) 页面的 Secrets (密钥) 选项卡中创建和管理密钥资源。有关创建密钥资源和将其添加到组的教程,请参阅如何创建密钥资源(控制台)Greengrass 连接器入门(控制台)


                    “Resources (资源)”页面上“Secret (密钥)”选项卡中的密钥资源。

注意

或者,控制台允许您在配置连接器或 Lambda 函数时创建密钥和密钥资源。您可以从连接器的 Configure parameters (配置参数) 页面或 Lambda 函数的 Resources (资源) 页面执行此操作。

管理密钥资源(控制台)

Greengrass 组中的密钥资源的管理任务包括向组添加密钥资源、从组中移除密钥资源以及更改包含在密钥资源中的暂存标签集。

如果您指向与 Secrets Manager 不同的密钥,还必须编辑使用该密钥的任何连接器:

  1. 在组配置页面上,选择 Connectors (连接器)

  2. 从连接器的上下文菜单中,选择 Edit (编辑)

  3. Edit parameters (编辑参数) 页面将显示一条消息,以通知您密钥 ARN 已发生更改。要确认更改,请选择 Save (保存)

如果您在 Secrets Manager 中删除了一个密钥,请从组中以及引用了该密钥的连接器和 Lambda 函数中移除对应的密钥资源。否则,在组部署期间,AWS IoT Greengrass 将返回“找不到密钥”错误。还可根据需要更新 Lambda 函数代码。

创建和管理密钥资源 (CLI)

创建密钥资源 (CLI)

在 AWS IoT Greengrass API 中,密钥是一种组资源。以下示例通过包括密钥资源(名为 MySecretResource)的初始版本,创建资源定义。有关创建密钥资源和将其添加到组版本的教程,请参阅Greengrass 连接器入门 (CLI)

密钥资源引用对应的 Secrets Manager 密钥 ARN,并包括除 AWSCURRENT(其始终包括在内)之外的两个暂存标签。

aws greengrass create-resource-definition --name MyGreengrassResources --initial-version '{ "Resources": [ { "Id": "my-resource-id", "Name": "MySecretResource", "ResourceDataContainer": { "SecretsManagerSecretResourceData": { "ARN": "arn:aws:secretsmanager:us-west-2:123456789012:secret:greengrass-SomeSecret-KUj89s", "AdditionalStagingLabelsToDownload": [ "Label1", "Label2" ] } } } ] }'

管理密钥资源 (CLI)

Greengrass 组中的密钥资源的管理任务包括向组添加密钥资源、从组中移除密钥资源以及更改包含在密钥资源中的暂存标签集。

在 AWS IoT Greengrass API 中,这些更改通过使用版本来实施。

AWS IoT Greengrass API 使用版本来管理组。版本是不可变的,因此要添加或更改组组件(例如,组的设备、函数和资源),您必须创建全新的或更新的组件的版本。然后,您应创建和部署包含目标版本的组版本。要详细了解组,请参阅AWS IoT Greengrass 组

例如,要更改密钥资源的暂存标签集,请执行以下操作:

  1. 创建资源定义版本,其中包含更新后的密钥资源。以下示例将向上一部分的密钥资源添加第三个暂存标签。

    注意

    要向版本添加更多资源,请将其纳入 Resources 数组中。

    aws greengrass create-resource-definition --name MyGreengrassResources --initial-version '{ "Resources": [ { "Id": "my-resource-id", "Name": "MySecretResource", "ResourceDataContainer": { "SecretsManagerSecretResourceData": { "ARN": "arn:aws:secretsmanager:us-west-2:123456789012:secret:greengrass-SomeSecret-KUj89s", "AdditionalStagingLabelsToDownload": [ "Label1", "Label2", "Label3" ] } } } ] }'
  2. 如果密钥资源的 ID 发生更改,请更新使用该密钥资源的连接器和函数。在新版本中,更新与资源 ID 对应的参数或属性。如果密钥的 ARN 发生更改,则您还必须更新使用该密钥的任何连接器所对应的参数。

    注意

    资源 ID 是客户提供的任意标识符。

  3. 创建组版本,其中包含您要发送给核心的每个组件的目标版本。

  4. 部署组版本。

有关演示如何创建和部署密钥资源、连接器与函数的教程,请参阅Greengrass 连接器入门 (CLI)

如果您在 Secrets Manager 中删除了一个密钥,请从组中以及引用了该密钥的连接器和 Lambda 函数中移除对应的密钥资源。否则,在组部署期间,AWS IoT Greengrass 将返回“找不到密钥”错误。还可根据需要更新 Lambda 函数代码。您可以部署不包含对应密钥资源的资源定义版本,以删除本地密钥。

在连接器和 Lambda 函数中使用本地密钥

Greengrass 连接器和 Lambda 函数使用本地密钥与服务和应用程序交互。系统默认使用 AWSCURRENT 值,但密钥资源中包含的其他暂存标签的值也可以使用。

连接器和函数必须在其可访问本地密钥之前进行配置。这样可以将密钥资源与连接器或函数关联。

连接器

如果连接器需要访问本地密钥,则连接器会提供一些参数,您通过这些参数配置连接器访问密钥所需的信息。

有关各个连接器的要求的信息,请参阅AWS 提供的 Greengrass 连接器

用于访问和使用密钥的逻辑内置在连接器中。

Lambda 函数

要允许 Greengrass Lambda 函数访问本地密钥,您需配置该函数的属性。

  • 要了解如何在 AWS IoT Greengrass 控制台中执行此操作,请参阅 如何创建密钥资源(控制台)

  • 要通过 AWS IoT Greengrass API 执行此操作,您需在 ResourceAccessPolicies 属性中提供以下信息。

    • ResourceId:Greengrass 组中密钥资源的 ID。这是引用对应 Secrets Manager 密钥 ARN 的资源。

    • Permission:函数对资源的访问权限类型。密钥资源仅支持 ro(只读)权限。

    以下示例将创建可以访问 MyApiKey 密钥资源的 Lambda 函数。

    aws greengrass create-function-definition --name MyGreengrassFunctions --initial-version '{ "Functions": [ { "Id": "MyLambdaFunction", "FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:myFunction:1", "FunctionConfiguration": { "Pinned": false, "MemorySize": 16384, "Timeout": 10, "Environment": { "ResourceAccessPolicies": [ { "ResourceId": "MyApiKey", "Permission": "ro" } ], "AccessSysfs": true } } } ] }'

     

    为在运行时访问本地密钥,Greengrass Lambda 函数从 AWS IoT Greengrass Core 开发工具包 (v1.3.0 or later) 中的 secretsmanager 客户端调用 get_secret_value 函数。

    下面的示例介绍如何使用适用于 Python 的 AWS IoT Greengrass Core 开发工具包获取密钥。它将密钥名称传递给 get_secret_value 函数。SecretId 可以是 Secrets Manager 密钥(不是密钥资源)的名称或 ARN。

    import greengrasssdk # Creating a Greengrass Core SDK client client = greengrasssdk.client('secretsmanager') # This handler is called when the function is invoked # It uses the secretsmanager client to get the value of a secret def function_handler(event, context): response = client.get_secret_value(SecretId='greengrass-MySecret-abc') raw_secret = response.get('SecretString')

    对于文本类型密钥,get_secret_value 函数返回一个字符串。对于二进制类型密钥,它返回一个采用 base64 编码的字符串。

    重要

    确保您的用户定义的 Lambda 函数安全地处理密钥并且不记录存储在密钥中的任何敏感数据。有关更多信息,请参阅 AWS Secrets Manager 用户指南 中的降低记录和调试 Lambda 函数的风险。尽管本文档专门提到了轮换函数,但该建议也适用于 Greengrass Lambda 函数。

    默认情况下,返回密钥的当前值。这是 AWSCURRENT 暂存标签附加到的版本。要访问不同版本,请将相应暂存标签的名称传递给可选的 VersionStage 参数。例如:

    import greengrasssdk # Creating a greengrass core sdk client client = greengrasssdk.client('secretsmanager') # This handler is called when the function is invoked # It uses the secretsmanager client to get the value of a specific secret version def function_handler(event, context): response = client.get_secret_value(SecretId='greengrass-MySecret-abc', VersionStage='MyTargetLabel') raw_secret = response.get('SecretString')

    有关调用 get_secret_value 的另一个示例函数,请参阅创建 Lambda 函数部署程序包