为数据存储配置 IAM 身份认证

配置 Agent Server 使用云工作负载身份对 PostgreSQL 和 Redis 进行身份认证。

Agent Server 可以使用云工作负载身份，在运行时生成短期有效的 PostgreSQL 和 Redis 凭据。这样就不必在部署配置中保留静态的数据库和缓存密码。连接与连接池行为保持不变。

NOTE

数据存储的 IAM 身份认证需要 langgraph-api>=0.12.0。

支持的服务

Provider 值	PostgreSQL	Redis	凭据来源
aws	Amazon RDS 或 Aurora PostgreSQL	Amazon ElastiCache 预置缓存集群或复制组	AWS SDK 默认凭据链
azure	Azure Database for PostgreSQL Flexible Server	Azure Managed Redis 或 Azure Cache for Redis	Microsoft Entra DefaultAzureCredential
gcp	Cloud SQL for PostgreSQL	Memorystore for Redis Cluster	Google Application Default Credentials（ADC）

WARNING

GCP 的 PostgreSQL provider 支持 Cloud SQL，但不支持 AlloyDB，后者需要不同的 token 作用域。

provider 设置只负责身份认证。在启动 Agent Server 之前，请先配置好网络访问、TLS、数据库用户、缓存用户以及相应的服务商权限。

启用 IAM 身份认证

要启用 IAM 身份认证：

1. 在托管数据存储上启用 IAM 或基于身份的身份认证。

2. 创建数据库或缓存主体，并仅授予 Agent Server 所需的最小权限。

3. 确保每个 Agent Server API 与队列进程都能获取到工作负载身份凭据。

4. 设置一个包含主体名称、但不包含静态密码的连接 URI。

5. 将对应的 provider 选择器设置为 aws、azure 或 gcp：

   AGENT_POSTGRES_IAM_AUTH_PROVIDER=<provider>
   AGENT_REDIS_IAM_AUTH_PROVIDER=<provider>

你可以为 PostgreSQL、Redis 或两者同时启用 IAM 身份认证。当某个选择器未设置时，Agent Server 会继续使用该数据存储连接 URI 中的密码。

根据你的部署类型，使用以下连接 URI 变量：

部署	PostgreSQL URI	Redis URI
独立 Agent Server	DATABASE_URI	REDIS_URI
带控制平面的自托管部署	POSTGRES_URI_CUSTOM	REDIS_URI_CUSTOM

连接 URI 必须满足以下要求：

• 传输安全：PostgreSQL 使用 sslmode=require 或更严格的校验模式，Redis 使用 rediss://。
• 字符编码：对用户名中属于 URI 保留字符的部分进行百分号编码，例如将 @ 编码为 %40。
• 私有证书颁发机构：如果 Redis 的 TLS 使用私有证书颁发机构，请将 REDIS_TLS_CA_CERT 设置为 base64 编码的 PEM CA 证书包。
• 集群模式：如果 Redis 服务使用集群模式，还需设置 REDIS_CLUSTER=true。

配置 AWS

Agent Server 使用 AWS SDK 的默认凭据链来创建 RDS 身份认证令牌和 ElastiCache SigV4 身份认证令牌。

在配置 Agent Server 之前：

• 为 RDS 或 Aurora PostgreSQL 启用 IAM 数据库身份认证。为数据库用户授予 rds_iam 角色，并为工作负载身份授予该用户的 rds-db:connect 权限。
• 为 ElastiCache 用户启用 IAM 身份认证。为工作负载身份授予 elasticache:Connect 权限，作用范围需同时覆盖该 ElastiCache 缓存或复制组以及该 ElastiCache 用户。
• 通过 EKS Pod Identity、服务账户的 IAM 角色（IRSA）、实例配置文件或其他 AWS SDK 凭据来源配置 AWS 凭据。将 AWS_REGION 或 AWS_DEFAULT_REGION 设置为数据存储所在的区域。

在连接 URI 中设置数据库用户名：

AWS_REGION=<region>
AGENT_POSTGRES_IAM_AUTH_PROVIDER=aws
AGENT_REDIS_IAM_AUTH_PROVIDER=aws
DATABASE_URI="postgresql://<rds-user>@<rds-endpoint>:5432/<database>?sslmode=require"
REDIS_URI="rediss://<elasticache-iam-user>@<elasticache-endpoint>:6379"

Redis 用户名必须与启用了 IAM 的 ElastiCache 用户保持一致。Agent Server 支持预置的 ElastiCache 缓存集群和复制组。ElastiCache 的 IAM 身份认证要求启用传输加密，并且需要使用 Valkey 7.2 或更高版本，或者 Redis OSS 7.0 或更高版本。

配置 Azure

Agent Server 使用 DefaultAzureCredential 为 PostgreSQL 和 Redis 获取 Microsoft Entra 令牌。该凭据链支持 Azure Workload Identity、托管标识和服务主体。

在配置 Agent Server 之前：

• 为 Azure Database for PostgreSQL Flexible Server 配置 Microsoft Entra 身份认证。为托管标识或服务主体创建数据库角色，并使用该角色名作为 PostgreSQL URI 的用户名。
• 为 Azure Managed Redis 配置 Microsoft Entra 身份认证并配置数据访问策略。使用托管标识或服务主体的对象 ID 作为 Redis URI 的用户名。
• 为每个 Agent Server 工作负载配置 Azure Workload Identity、托管标识或其他 DefaultAzureCredential 凭据来源。

在连接 URI 中设置 Microsoft Entra 主体标识：

AGENT_POSTGRES_IAM_AUTH_PROVIDER=azure
AGENT_REDIS_IAM_AUTH_PROVIDER=azure
DATABASE_URI="postgresql://<entra-principal-name>@<postgres-host>:5432/<database>?sslmode=require"
REDIS_URI="rediss://<entra-object-id>@<redis-host>:<port>"

在以集群模式使用 Azure Managed Redis 时，请设置 REDIS_CLUSTER=true。Agent Server 会在 Microsoft Entra 令牌过期前刷新令牌，并对已打开的 Redis 连接重新进行身份认证。

配置 GCP

Agent Server 使用 Google ADC 获取 Cloud SQL 登录令牌和 Memorystore 访问令牌。ADC 支持 GKE Workload Identity Federation、附加服务账户、服务账号模拟以及 GOOGLE_APPLICATION_CREDENTIALS。

在配置 Agent Server 之前：

• 配置 Cloud SQL IAM 数据库身份认证，将 IAM 主体添加为数据库用户，并为其授予 roles/cloudsql.instanceUser。数据库权限需另行授予。
• 配置 Memorystore IAM 身份认证，并为工作负载身份授予 roles/redis.dbConnectionUser。
• 为每个 Agent Server 工作负载配置 ADC。相比服务账号密钥，更推荐使用 Workload Identity Federation 或附加服务账户。

在 PostgreSQL URI 中设置 Cloud SQL 的 IAM 数据库用户。Memorystore 只支持 default 这一个 Redis 用户名：

AGENT_POSTGRES_IAM_AUTH_PROVIDER=gcp
AGENT_REDIS_IAM_AUTH_PROVIDER=gcp
DATABASE_URI="postgresql://<cloud-sql-iam-user>@<cloud-sql-host>:5432/<database>?sslmode=require"
REDIS_URI="rediss://default@<memorystore-discovery-endpoint>:<port>"
REDIS_CLUSTER=true

对于服务账户，Cloud SQL 的数据库用户名是其电子邮件地址去掉 .gserviceaccount.com 后缀后的部分。

配置独立 Helm chart

对于 Kubernetes 上的独立 Agent Server 部署，需要在每个 Agent Server 工作负载上设置 provider 选择器。如果启用了独立的队列部署，请使用相同的身份和环境变量来配置 API 部署与队列部署。

下面的示例对两个数据存储都使用 AWS。如果使用其他云服务商，请将每个 provider 的值相应地改为 azure 或 gcp：

postgres:
  external:
    enabled: true
    connectionUrl: "postgresql://<database-user>@<postgres-host>:5432/<database>?sslmode=require"
redis:
  external:
    enabled: true
    connectionUrl: "rediss://<redis-user>@<redis-host>:<port>"

apiServer:
  deployment:
    extraEnv:
      - name: AGENT_POSTGRES_IAM_AUTH_PROVIDER
        value: "aws"
      - name: AGENT_REDIS_IAM_AUTH_PROVIDER
        value: "aws"

queue:
  enabled: true
  deployment:
    extraEnv:
      - name: AGENT_POSTGRES_IAM_AUTH_PROVIDER
        value: "aws"
      - name: AGENT_REDIS_IAM_AUTH_PROVIDER
        value: "aws"

使用云服务商的工作负载身份机制来配置 apiServer.serviceAccount 和 queue.serviceAccount。这两个工作负载都必须能够获取凭据并连接到数据存储。

另请参阅

• 自托管独立服务器
• 自托管 Agent Server 环境变量
• 自托管平台功能
• 面向规模配置 Agent Server

---