本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 在 Amazon EC2 和本地计算机上使用 AWS AppConfig 代理 您可以使用代理 AWS AppConfig 与在亚马逊弹性计算云 (Amazon EC2) Elastic Compute Cloud Linux 实例上运行的 AWS AppConfig 应用程序集成。代理通过以下方式增强应用程序处理和管理： + 代理通过使用 AWS Identity and Access Management (IAM) 角色并管理配置数据的本地缓存来代表您进行调用 AWS AppConfig 。通过从本地缓存中提取配置数据，应用程序需要更少的代码更新来管理配置数据，在几毫秒内检索配置数据，并且不受可能中断对此类数据的调用的网络问题的影响。\$1 + 该代理为检索和解析 AWS AppConfig 功能标记提供了原生体验。 + 该代理开箱即用，提供了缓存策略、轮询间隔和本地配置数据可用性的最佳实践，同时跟踪后续服务调用所需的配置令牌。 + 在后台运行时，代理会定期轮询 AWS AppConfig 数据平面以获取配置数据更新。应用程序可以通过连接到端口 2772（可自定义的默认端口值）上的本地主机并调用 HTTP GET 来检索数据。 \$1AWS AppConfig 代理会在服务首次检索您的配置数据时缓存数据。因此，检索数据的第一次调用比后续调用慢。 **Topics** + [步骤 1：（必需）创建资源并配置权限](#appconfig-integration-ec2-resources-and-permissions) + [步骤 2：（必需）在 Amazon EC2 实例上安装和启动 AWS AppConfig 代理](#appconfig-integration-ec2-installing) + [步骤 3：（可选，但建议使用）将日志文件发送到 CloudWatch 日志](#appconfig-integration-ec2-logs) + [步骤 4：（可选）使用环境变量为 Amazon EC2 配置 AWS AppConfig 代理](#appconfig-integration-ec2-configuring) + [步骤 5：（必需）检索配置数据](#appconfig-integration-ec2-retrieving-data) + [步骤 6（可选，但建议使用）：自动更新代理 AWS AppConfig](#appconfig-integration-ec2-updating-agent) ## 步骤 1：（必需）创建资源并配置权限 要 AWS AppConfig 与 Amazon EC2 实例上运行的应用程序集成，您 AWS AppConfig 必须创建项目和配置数据，包括功能标志或自由格式配置数据。有关更多信息，请参阅 [在中创建功能标志和自由格式配置数据 AWS AppConfig](creating-feature-flags-and-configuration-data.md)。 要检索托管的配置数据 AWS AppConfig，必须将您的应用程序配置为可以访问 AWS AppConfig 数据平面。要向应用程序授予访问权限，请更新分配给 Amazon EC2 实例角色的 IAM 权限策略。具体而言，您必须将 `appconfig:StartConfigurationSession` 和 `appconfig:GetLatestConfiguration` 操作添加到策略中。示例如下： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "appconfig:StartConfigurationSession", "appconfig:GetLatestConfiguration" ], "Resource": "*" } ] } ``` ------ 有关如何添加权限至策略的信息，请参阅**《IAM 用户指南》中的[添加和删除 IAM 身份权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。 ## 步骤 2：（必需）在 Amazon EC2 实例上安装和启动 AWS AppConfig 代理 AWS AppConfig 代理托管在由管理的亚马逊简单存储服务 (Amazon S3) Service 存储桶中。 AWS使用以下过程在 Linux 实例上安装最新版本的 agent。如果应用程序分布在多个实例中，则必须在托管应用程序的每个实例上执行此过程。 **注意** 请注意以下信息： AWS AppConfig 代理适用于运行内核版本 4.15 或更高版本的 Linux 操作系统。不支持基于 Debian 的系统，例如 Ubuntu。 该代理支持 x86\$164 和架构。 ARM64 对于分布式应用程序，我们建议将 install 和 startup 命令添加到 Auto Scaling 组的 Amazon EC2 用户数据中。如果这样做，每个实例都会自动运行这些命令。有关更多信息，请参阅《Amazon EC2 用户指南》**中的[启动时在 Linux 实例上运行命令](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html)。此外，请参阅《*Amazon EC2 Auto Scaling 用户指南*》中的[教程：通过实例元数据检索目标生命周期状态](https://docs.aws.amazon.com/autoscaling/ec2/userguide/tutorial-lifecycle-hook-instance-metadata.html)。 本主题中的过程介绍如何通过登录实例来运行命令以执行安装代理等操作。您可以从本地客户端机器运行命令，并使用 AWS Systems Manager中的工具 Run Command 来定位一个或多个实例。有关更多信息，请参阅 *AWS Systems Manager 用户指南*中的 [AWS Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html)。 AWS AppConfig 亚马逊 EC2 Linux 实例上的代理是一项`systemd`服务。 **在实例上安装和启动 AWS AppConfig 代理** 1. 登录您的 Linux 实例。 1. 打开终端，并使用管理员权限运行以下命令之一： **x86\$164** ``` sudo yum install https://s3.amazonaws.com/aws-appconfig-downloads/aws-appconfig-agent/linux/x86_64/latest/aws-appconfig-agent.rpm ``` **ARM64** ``` sudo yum install https://s3.amazonaws.com/aws-appconfig-downloads/aws-appconfig-agent/linux/arm64/latest/aws-appconfig-agent.rpm ``` 如果要安装特定版本的 AWS AppConfig Agent，请将 URL `latest` 中的特定版本号替换为特定的版本号。以下是 x86\$164 的一个示例： ``` sudo yum install https://s3.amazonaws.com/aws-appconfig-downloads/aws-appconfig-agent/linux/x86_64/2.0.2/aws-appconfig-agent.rpm ``` 1. 请运行以下命令以启动代理： ``` sudo systemctl start aws-appconfig-agent ``` 1. 请运行以下命令以验证代理是否正在运行。 ``` sudo systemctl status aws-appconfig-agent ``` 如果成功，该命令将返回类似以下内容的信息： ``` aws-appconfig-agent.service - aws-appconfig-agent ... Active: active (running) since Mon 2023-07-26 00:00:00 UTC; 0s ago ... ``` **注意** 要停止代理，请运行以下命令： ``` sudo systemctl stop aws-appconfig-agent ``` ## 步骤 3：（可选，但建议使用）将日志文件发送到 CloudWatch 日志 默认情况下， AWS AppConfig 代理会将日志发布到 STDERR。Systemd 将 Linux 实例上运行的所有服务的 STDOUT 和 STDERR 重定向到 systemd 日志。如果您只在一两个实例上运行 AWS AppConfig 代理，则可以查看和管理 systemd 日志中的日志数据。更好的解决方案（我们强烈推荐分布式应用程序使用的解决方案）是将日志文件写入磁盘，然后使用 Amazon CloudWatch 代理将日志数据上传到 AWS 云端。此外，您可以将 CloudWatch 代理配置为从您的实例中删除旧的日志文件，这样可以防止您的实例耗尽磁盘空间。 若要启用磁盘日志记录，必须设置 `LOG_PATH` 环境变量，如 [步骤 4：（可选）使用环境变量为 Amazon EC2 配置 AWS AppConfig 代理](#appconfig-integration-ec2-configuring) 中所述。 要开始使用 CloudWatch 代理，请参阅亚马逊* CloudWatch 用户指南*中的使用代理[从 Amazon EC2 实例和本地服务器收集指标和日志](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。 CloudWatch 您可以使用 “快速设置”（Systems Manager 中的一种工具）来快速安装 CloudWatch 代理。有关更多信息，请参阅 *AWS Systems Manager 用户指南*中的[快速设置主机管理](https://docs.aws.amazon.com/systems-manager/latest/userguide/quick-setup-host-management.html)。 **警告** 如果您选择在不使用 CloudWatch 代理的情况下将日志文件写入磁盘，则必须删除旧的日志文件。 AWS AppConfig 代理每小时自动轮换一次日志文件。如果您不删除旧的日志文件，您的实例可能会耗尽磁盘空间。 在实例上安装 CloudWatch 代理后，创建 CloudWatch 代理配置文件。配置文件指示 CloudWatch 代理如何使用 AWS AppConfig 代理日志文件。有关创建 CloudWatch 代理配置文件的更多信息，请参阅[创建 CloudWatch 代理配置文件](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create-cloudwatch-agent-configuration-file.html)。 将以下`logs`部分添加到实例的 CloudWatch 代理配置文件中，然后保存您的更改： ``` "logs": { "logs_collected": { "files": { "collect_list": [ { "file_path": "/path_you_specified_for_logging", "log_group_name": "${YOUR_LOG_GROUP_NAME}/aws-appconfig-agent.log", "auto_removal": true }, ... ] }, ... }, ... } ``` 如果的值为`true`，`auto_removal`则 CloudWatch 代理会自动删除轮换的 AWS AppConfig 代理日志文件。 ## 步骤 4：（可选）使用环境变量为 Amazon EC2 配置 AWS AppConfig 代理 您可以使用环境变量为 Amazon EC2 配置 AWS AppConfig 代理。要为 `systemd` 服务设置环境变量，请创建一个插入式单元文件。以下示例说明如何创建嵌入式单元文件以将 AWS AppConfig Agent 日志级别设置为。`DEBUG` **如何为环境变量创建插入式单元文件的示例** 1. 登录您的 Linux 实例。 1. 使用管理员权限打开终端，并运行下述命令。该命令创建一个配置目录： ``` sudo mkdir /etc/systemd/system/aws-appconfig-agent.service.d ``` 1. 运行以下命令以创建插入单元文件。*file\$1name*替换为文件名。扩展名必须是 `.conf`： ``` sudo touch /etc/systemd/system/aws-appconfig-agent.service.d/file_name.conf ``` 1. 在插入式单元文件中输入信息。下面的示例添加一个定义环境变量的 `Service` 部分。该示例将 AWS AppConfig 代理日志级别设置为 `DEBUG`。 ``` [Service] Environment=LOG_LEVEL=DEBUG ``` 1. 运行以下命令以重新加载系统配置。 ``` sudo systemctl daemon-reload ``` 1. 运行以下命令以重新启动 AWS AppConfig Agent： ``` sudo systemctl restart aws-appconfig-agent ``` 您可以通过在嵌入式单元文件中指定以下环境变量来为 Amazon EC2 配置 AWS AppConfig 代理。 **注意** 下表包含一个**示例值**列。根据您的显示器分辨率，您可能需要滚动到表的底部，然后向右滚动才能看到该列。 **** | 环境变量 | Details | 默认 值 | 示例值 | | --- | --- | --- | --- | | `ACCESS_TOKEN` | 此环境变量定义从代理 HTTP 服务器请求配置数据时必须提供的令牌。必须在授权类型为 `Bearer` 的 HTTP 请求授权标头中设置令牌的值。见下列。 
GET /applications/my_app/...
                  Host: localhost:2772
                  Authorization: Bearer
| 无 | MyAccessToken | | `BACKUP_DIRECTORY` | 此环境变量使 AWS AppConfig 代理能够将其检索到的每个配置的备份保存到指定目录中。 备份到磁盘的配置未加密。如果您的配置包含敏感数据， AWS AppConfig 建议您在文件系统权限方面采用最小权限原则。有关更多信息，请参阅 [安全性 AWS AppConfig](appconfig-security.md)。 | None（无） | /path/to/backups | | `HTTP_PORT` | 此环境变量指定运行代理的 HTTP 服务器的端口。 | 2772 | 2772 | | `HTTP_HOST` | HTTP\$1HOST 变量控制 AWS AppConfig 代理如何绑定到网络接口。绑定行为因运行时环境而异，以确保最佳的安全性和可访问性。 | ECS，EKS [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/appconfig/latest/userguide/appconfig-integration-ec2.html) EC2 和本地部署 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/appconfig/latest/userguide/appconfig-integration-ec2.html) | 自定义配置选项。您可以使用以下值覆盖默认行为： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/appconfig/latest/userguide/appconfig-integration-ec2.html) | | `LOG_LEVEL` | 此环境变量指定代理记录的详细程度。每个级别包括当前级别和所有更高级别。该值不区分大小写。从最详细到最不详细，日志级别分别为：`trace`、`debug`、`info`、`warn`、`error`、`fatal` 和 `none`。`trace` 日志包含关于 Agent 的详细信息，包括时间信息。 | info | trace debug info warn 错误 fatal none | | `LOG_PATH` | 写入日志的磁盘位置。如果未指定，则日志将写入 stderr。 | 无 | /path/to/logs/agent.log | | `MANIFEST` | 此环境变量将 AWS AppConfig Agent 配置为利用其他每个配置的功能，例如多帐户检索和将配置保存到磁盘。有关使用这些功能的更多信息，请参阅 [使用清单启用其它检索功能](appconfig-agent-how-to-use-additional-features.md)。 | 无 | 使用 AWS AppConfig 配置作为清单时:`MyApp:MyEnv:MyManifestConfig`.当从磁盘加载清单时：`file:/path/to/manifest.json` | | `MAX_CONNECTIONS` | 此环境变量配置代理用于从 AWS AppConfig检索配置的最大连接数。 | 3 | 3 | | `POLL_INTERVAL` | 此环境变量控制代理轮 AWS AppConfig 询更新配置数据的频率。您可以指定间隔的秒数。您还可以指定一个带有时间单位的数字：s 表示秒，m 表示分钟，h 表示小时。如果未指定单位，则代理默认为秒。例如，60 秒、60 秒和 1 分钟会产生相同的轮询间隔。 | 45 秒 | 4545 秒5m1 小时 | | `PREFETCH_LIST` | 此环境变量指定代理启动后立即请求 AWS AppConfig 的配置数据。可以使用逗号分隔的列表提供多个配置标识符。 | 无 | MyApp:MyEnv:MyConfigabcd123:efgh456:ijkl789MyApp:: Config1,:: Config2 MyEnv MyApp MyEnv | | `PRELOAD_BACKUPS` | 如果设置为`true`， AWS AppConfig 代理会将中找到的配置备份加载`BACKUP_DIRECTORY`到内存中，并立即检查服务中是否存在更新的版本。如果设置为 `false`， AWS AppConfig 代理仅在无法从服务中检索配置数据（例如，如果网络出现问题）时，才从配置备份中加载内容。 | true | true false | | PROXY\$1HEADERS | 此环境变量指定 PROXY\$1URL 环境变量中引用的代理所需的标头。其值是以逗号分隔的标头列表。 | 无 | header: value h1: v1, h2: v2 | | PROXY\$1URL | 此环境变量指定用于从代理到的连接的代理 URL AWS 服务，包括 AWS AppConfig。 HTTPS并HTTP URLs 得到支持。 | 无 | http://localhost:7474https://my-proxy.example.com | | `REQUEST_TIMEOUT` | 此环境变量控制代理等待响应的 AWS AppConfig时间。如果服务没有响应，则请求将失败。 如果请求用于初始数据检索，则代理会向应用程序返回错误。 如果在对更新的数据进行后台检查期间发生超时，代理会记录错误，并在短暂延迟后重试。 您可以指定超时的毫秒数。您还可以指定一个带有时间单位的数字：ms 表示毫秒，s 表示秒。如果未指定单位，则代理默认为毫秒。例如，5000、5000ms 和 5s 会产生相同的请求超时值。 | 3000 毫秒 | 30003000 毫秒5 秒 | | ROLE\$1ARN | 此环境变量指定 IAM 角色的亚马逊资源名称 (ARN)。 AWS AppConfig 代理扮演此角色来检索配置数据。 | 无 | arn: aws: iam:: 123456789012: role/ MyRole | | ROLE\$1EXTERNAL\$1ID | 此环境变量指定要与代入角色 ARN 一起使用的外部 ID。 | 无 | MyExternalId | | ROLE\$1SESSION\$1NAME | 此环境变量指定要与代入的 IAM 角色的凭证关联的会话名称。 | 无 | AWSAppConfigAgentSession | | SERVICE\$1REGION | 此环境变量指定了 AWS AppConfig Agent AWS 区域 用来调用 AWS AppConfig 服务的替代方案。如果未定义，代理将尝试确定当前区域。如果不能，则代理无法启动。 | 无 | us-east-1eu-west-1 | | `WAIT_ON_MANIFEST` | 此环境变量将 AWS AppConfig Agent 配置为等到清单处理完毕后再完成启动。 | true | truefalse | ## 步骤 5：（必需）检索配置数据 您可以使用 HTTP localhost 调用从 AWS AppConfig 代理中检索配置数据。以下示例将 `curl` 与 HTTP 客户端一起使用。您可以使用应用程序语言支持的任何可用 HTTP 客户端或可用库（包括 AWS SDK）来调用代理。 **检索任何已部署配置的完整内容** ``` $ curl "http://localhost:2772/applications/application_name/environments/environment_name/configurations/configuration_name" ``` **从 `Feature Flag` 类型的 AWS AppConfig 配置中检索单个标志及其属性** ``` $ curl "http://localhost:2772/applications/application_name/environments/environment_name/configurations/configuration_name?flag=flag_name" ``` **从 `Feature Flag` 类型的 AWS AppConfig 配置访问多个标志及其属性** ``` $ curl "http://localhost:2772/applications/application_name/environments/environment_name/configurations/configuration_name?flag=flag_name_one&flag=flag_name_two" ``` ## 步骤 6（可选，但建议使用）：自动更新代理 AWS AppConfig AWS AppConfig 代理会定期更新。为确保您在实例上运行最新版本的 AWS AppConfig Agent，我们建议您将以下命令添加到您的 Amazon EC2 用户数据中。您可以将命令添加到实例或 EC2 Auto Scaling 组上的用户数据中。每次实例启动或重启时，该脚本都会安装并启动最新版本的代理。 ``` #!/bin/bash # install the latest version of the agent yum install -y https://s3.amazonaws.com/aws-appconfig-downloads/aws-appconfig-agent/linux/x86_64/latest/aws-appconfig-agent.rpm # optional: configure the agent mkdir /etc/systemd/system/aws-appconfig-agent.service.d echo "${MY_AGENT_CONFIG}" > /etc/systemd/system/aws-appconfig-agent.service.d/overrides.conf systemctl daemon-reload # start the agent systemctl start aws-appconfig-agent ```