从 Amazon EC2 实例检索配置数据 - Amazon AppConfig
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

从 Amazon EC2 实例检索配置数据

您可以使用代理 Amazon AppConfig 与在亚马逊弹性计算云 (Amazon EC2) Elastic Compute Cloud Linux 实例上运行的 Amazon AppConfig 应用程序集成。代理通过以下方式增强应用程序处理和管理:

  • 代理通过使用 Amazon Identity and Access Management (IAM) 角色并管理配置数据的本地缓存来代表您进行调用 Amazon AppConfig 。通过从本地缓存中提取配置数据,应用程序需要更少的代码更新来管理配置数据,在几毫秒内检索配置数据,并且不受可能中断对此类数据的调用的网络问题的影响。*

  • 该代理为检索和解析 Amazon AppConfig 功能标记提供了原生体验。

  • 该代理开箱即用,提供了缓存策略、轮询间隔和本地配置数据可用性的最佳实践,同时跟踪后续服务调用所需的配置令牌。

  • 在后台运行时,代理会定期轮询 Amazon AppConfig 数据平面以获取配置数据更新。应用程序可以通过连接到端口 2772(可自定义的默认端口值)上的本地主机并调用 HTTP GET 来检索数据。

*Amazon AppConfig 代理会在服务首次检索您的配置数据时缓存数据。因此,检索数据的第一次调用比后续调用慢。

步骤 1:(必需)创建资源并配置权限

要 Amazon AppConfig 与 Amazon EC2 实例上运行的应用程序集成,您 Amazon AppConfig 必须创建项目和配置数据,包括功能标志或自由格式配置数据。有关更多信息,请参阅 在中创建功能标志和自由格式配置数据 Amazon AppConfig

要检索托管的配置数据 Amazon AppConfig,必须将您的应用程序配置为可以访问 Amazon AppConfig 数据平面。要向应用程序授予访问权限,请更新分配给 Amazon EC2 实例角色的 IAM 权限策略。具体而言,您必须将 appconfig:StartConfigurationSessionappconfig:GetLatestConfiguration 操作添加到策略中。示例如下:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "appconfig:StartConfigurationSession", "appconfig:GetLatestConfiguration" ], "Resource": "*" } ] }

有关如何添加权限至策略的信息,请参阅《IAM 用户指南》中的添加和删除 IAM 身份权限

步骤 2:(必需)在 Amazon EC2 实例上安装和启动 Amazon AppConfig 代理

Amazon AppConfig 代理托管在由管理的亚马逊简单存储服务 (Amazon S3) Service 存储桶中。 Amazon使用以下过程在 Linux 实例上安装最新版本的 agent。如果应用程序分布在多个实例中,则必须在托管应用程序的每个实例上执行此过程。

注意

请注意以下信息:

  • Amazon AppConfig 代理适用于运行内核版本 4.15 或更高版本的 Linux 操作系统。不支持基于 Debian 的系统,例如 Ubuntu。

  • 该代理支持 x86_64 和 ARM64 体系结构。

  • 对于分布式应用程序,我们建议将 install 和 startup 命令添加到 Auto Scaling 组的 Amazon EC2 用户数据中。如果这样做,每个实例都会自动运行这些命令。有关更多信息,请参阅适用于 Linux 实例的 Amazon EC2 用户指南中的 启动时对 Linux 实例运行命令。此外,请参阅《Amazon EC2 Auto Scaling 用户指南》中的教程:通过实例元数据检索目标生命周期状态

  • 本主题中的过程介绍如何通过登录实例来运行命令以执行安装代理等操作。您可以从本地客户机运行命令,并使用 Run Command(这是一项功能)来定位一个或多个实例 Amazon Systems Manager。有关更多信息,请参阅 Amazon Systems Manager 用户指南中的 Amazon Systems Manager Run Command

  • Amazon AppConfig 亚马逊 EC2 Linux 实例上的代理是一项systemd服务。

在实例上安装和启动 Amazon AppConfig 代理
  1. 登录您的 Linux 实例。

  2. 打开终端,并使用 x86_64 体系结构的管理员权限运行以下命令:

    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

    如果要安装特定版本的 Amazon AppConfig Agent,请将 URL latest 中的特定版本号替换为特定的版本号。以下是 x86_64 的一个示例:

    sudo yum install https://s3.amazonaws.com/aws-appconfig-downloads/aws-appconfig-agent/linux/x86_64/2.0.2/aws-appconfig-agent.rpm
  3. 请运行以下命令以启动代理:

    sudo systemctl start aws-appconfig-agent
  4. 请运行以下命令以验证代理是否正在运行。

    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 日志

默认情况下, Amazon AppConfig 代理会将日志发布到 STDERR。Systemd 将 Linux 实例上运行的所有服务的 STDOUT 和 STDERR 重定向到 systemd 日志。如果您只在一两个实例上运行 Amazon AppConfig 代理,则可以查看和管理 systemd 日志中的日志数据。更好的解决方案(我们强烈推荐分布式应用程序使用的解决方案)是将日志文件写入磁盘,然后使用 Amazon CloudWatch 代理将日志数据上传到 Amazon 云端。此外,您可以将 CloudWatch 代理配置为从您的实例中删除旧的日志文件,这样可以防止您的实例耗尽磁盘空间。

若要启用磁盘日志记录,必须设置 LOG_PATH 环境变量,如 步骤 4:(可选)使用环境变量为 Amazon EC2 配置 Amazon AppConfig 代理 中所述。

要开始使用 CloudWatch 代理,请参阅亚马逊 CloudWatch 用户指南中的使用代理从 Amazon EC2 实例和本地服务器收集指标和日志。 CloudWatch 您可以使用 “快速设置”(Systems Manager 的一项功能)来快速安装 CloudWatch 代理。有关更多信息,请参阅 Amazon Systems Manager 用户指南中的快速设置主机管理

警告

如果您选择在不使用 CloudWatch 代理的情况下将日志文件写入磁盘,则必须删除旧的日志文件。 Amazon AppConfig 代理每小时自动轮换一次日志文件。如果您不删除旧的日志文件,您的实例可能会耗尽磁盘空间。

在实例上安装 CloudWatch 代理后,创建 CloudWatch 代理配置文件。配置文件指示 CloudWatch 代理如何使用 Amazon AppConfig 代理日志文件。有关创建 CloudWatch 代理配置文件的更多信息,请参阅创建 CloudWatch 代理配置文件

将以下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 }, ... ] }, ... }, ... }

如果的值为trueauto_removal则 CloudWatch 代理会自动删除轮换的 Amazon AppConfig 代理日志文件。

步骤 4:(可选)使用环境变量为 Amazon EC2 配置 Amazon AppConfig 代理

您可以使用环境变量为 Amazon EC2 配置 Amazon AppConfig 代理。要为 systemd 服务设置环境变量,请创建一个插入式单元文件。以下示例说明如何创建嵌入式单元文件以将 Amazon AppConfig Agent 日志级别设置为。DEBUG

如何为环境变量创建插入式单元文件的示例
  1. 登录您的 Linux 实例。

  2. 使用管理员权限打开终端,并运行下述命令。该命令创建一个配置目录:

    sudo mkdir /etc/systemd/system/aws-appconfig-agent.service.d
  3. 运行以下命令以创建插入单元文件。将 file_name 替换为文件的名称。扩展名必须是 .conf

    sudo touch /etc/systemd/system/aws-appconfig-agent.service.d/file_name.conf
  4. 在插入式单元文件中输入信息。下面的示例添加一个定义环境变量的 Service 部分。该示例将 Amazon AppConfig 代理日志级别设置为 DEBUG

    [Service] Environment=LOG_LEVEL=DEBUG
  5. 运行以下命令以重新加载系统配置。

    sudo systemctl daemon-reload
  6. 运行以下命令以重新启动 Amazon AppConfig Agent:

    sudo systemctl restart aws-appconfig-agent

您可以通过在嵌入式单元文件中指定以下环境变量来为 Amazon EC2 配置 Amazon AppConfig 代理。

环境变量 详细信息 默认值

ACCESS_TOKEN

此环境变量定义从代理 HTTP 服务器请求配置数据时必须提供的令牌。必须在授权类型为 Bearer 的 HTTP 请求授权标头中设置令牌的值。下面是一个例子。

GET /applications/my_app/... Host: localhost:2772 Authorization: Bearer <token value>

BACKUP_DIRECTORY

此环境变量使 Amazon AppConfig 代理能够将其检索到的每个配置的备份保存到指定目录中。

重要

备份到磁盘的配置未加密。如果您的配置包含敏感数据, Amazon AppConfig 建议您在文件系统权限方面采用最小权限原则。有关更多信息,请参阅 Amazon AppConfig 中的安全性

None(无)

HTTP_PORT

此环境变量指定运行代理的 HTTP 服务器的端口。

2772

LOG_LEVEL

此环境变量指定代理记录的详细程度。每个级别包括当前级别和所有更高级别。变量是区分大小写的。从最详细到最不详细,日志级别为:debuginfowarnerrornoneDebug 包含有关代理的详细信息,包括计时信息。

info

LOG_PATH

写入日志的磁盘位置。如果未指定,则日志将写入 stderr。

MANIFEST

此环境变量将 Amazon AppConfig Agent 配置为利用其他每个配置的功能,例如多帐户检索和将配置保存到磁盘。您可以输入以下值之一:

  • "app:env:manifest-config"

  • "file:/fully/qualified/path/to/manifest.json"

有关使用这些功能的更多信息,请参阅 其他检索功能

true

MAX_CONNECTIONS

此环境变量配置代理用于从 Amazon AppConfig检索配置的最大连接数。

3

POLL_INTERVAL

此环境变量控制代理轮 Amazon AppConfig 询更新配置数据的频率。您可以指定间隔的秒数。您还可以指定一个带有时间单位的数字:s 表示秒,m 表示分钟,h 表示小时。如果未指定单位,则代理默认为秒。例如,60 秒、60 秒和 1 分钟会产生相同的轮询间隔。

45 秒

PREFETCH_LIST

此环境变量指定代理启动后立即请求 Amazon AppConfig 的配置数据。

PRELOAD_BACKUPS

如果设置为true, Amazon AppConfig 代理会将中找到的配置备份加载BACKUP_DIRECTORY到内存中,并立即检查服务中是否存在更新的版本。如果设置为false,则只有在无法从服务中检索配置数据时(例如,如果您的网络出现问题), Amazon AppConfig 代理才会加载配置备份中的内容。

true
PROXY_HEADERS 此环境变量指定 PROXY_URL 环境变量中引用的代理所需的标头。其值是以逗号分隔的标头列表。每个标头使用以下形式:
"header: value"
PROXY_URL 此环境变量指定用于从代理到的连接的代理 URL Amazon Web Services,包括 Amazon AppConfig。 HTTPS并支持 HTTP URL。

REQUEST_TIMEOUT

此环境变量控制代理等待响应的 Amazon AppConfig时间。如果服务没有响应,则请求将失败。

如果请求用于初始数据检索,则代理会向应用程序返回错误。

如果在对更新的数据进行后台检查期间发生超时,代理会记录错误,并在短暂延迟后重试。

您可以指定超时的毫秒数。您还可以指定一个带有时间单位的数字:ms 表示毫秒,s 表示秒。如果未指定单位,则代理默认为毫秒。例如,5000、5000ms 和 5s 会产生相同的请求超时值。

3000 毫秒
ROLE_ARN 此环境变量指定 IAM 角色的亚马逊资源名称 (ARN)。 Amazon AppConfig 代理扮演此角色来检索配置数据。
ROLE_EXTERNAL_ID 此环境变量指定要与代入角色 ARN 一起使用的外部 ID。
ROLE_SESSION_NAME 此环境变量指定要与代入的 IAM 角色的凭证关联的会话名称。
SERVICE_REGION 此环境变量指定了 Amazon AppConfig Agent Amazon Web Services 区域 用来调用 Amazon AppConfig 服务的替代方案。如果未定义,代理将尝试确定当前区域。如果不能,则代理无法启动。

WAIT_ON_MANIFEST

此环境变量将 Amazon AppConfig Agent 配置为等到清单处理完毕后再完成启动。

true

步骤 5:(必需)检索配置数据

您可以使用 HTTP localhost 调用从 Amazon AppConfig 代理中检索配置数据。以下示例将 curl 与 HTTP 客户端一起使用。您可以使用应用程序语言支持的任何可用 HTTP 客户端或可用库(包括 Amazon SDK)来调用代理。

检索任何已部署配置的完整内容

$ curl "http://localhost:2772/applications/application_name/environments/environment_name/configurations/configuration_name"

Feature Flag 类型的 Amazon AppConfig 配置中检索单个标志及其属性

$ curl "http://localhost:2772/applications/application_name/environments/environment_name/configurations/configuration_name?flag=flag_name"

Feature Flag 类型的 Amazon AppConfig 配置访问多个标志及其属性

$ curl "http://localhost:2772/applications/application_name/environments/environment_name/configurations/configuration_name?flag=flag_name_one&flag=flag_name_two"

步骤 6(可选,但建议使用):自动更新代理 Amazon AppConfig

Amazon AppConfig 代理会定期更新。为确保您在实例上运行最新版本的 Amazon 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