部署于AKS的Spring Boot应用使用Cosmos托管标识连接数据库方案问询

前提准备 #

• 确认AKS集群已开启OIDC颁发者与工作负载标识功能，这是AKS侧使用托管标识的基础依赖
• 在Cosmos DB访问控制(IAM)中为你要使用的系统/用户托管标识分配对应权限：常规数据读写场景分配Cosmos DB Built-in Data Contributor角色即可，仅读场景可以分配Cosmos DB Built-in Data Reader做权限最小化配置

AKS侧配置（采用推荐的工作负载标识方案） #

• 如果使用用户托管标识：先创建用户托管标识，再将该标识与Spring Boot应用对应的Kubernetes ServiceAccount做绑定
• 如果使用系统托管标识：直接使用应用所在节点池的系统托管标识即可，不过更推荐用户托管标识方便权限隔离
• 在Spring Boot应用的Deployment配置中添加工作负载标识的相关标注，开启托管标识凭证自动注入，注入后Pod内会自动生成AZURE_CLIENT_ID、AZURE_TENANT_ID等环境变量以及托管标识令牌挂载文件

Spring Boot应用改造 #

1. 依赖升级：将azure-spring-boot-starter-cosmos版本升级到4.x及以上，该版本原生支持托管标识认证能力
2. 配置调整：删除原有application.yml中的azure.cosmos.connection-string配置，替换为以下配置：

azure:
  cosmos:
    endpoint: <你的Cosmos DB服务端点地址，该地址不属于敏感配置，可以保留>
    database: <目标数据库名称>
    identity:
      enabled: true
      # 仅使用用户托管标识时需要填写下方client-id，使用系统托管标识无需配置该行
      client-id: <用户托管标识的Client ID>

3. 自定义CosmosClient场景改造：如果你是手动初始化CosmosClient而非使用starter自动配置，采用如下方式构建客户端即可：

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.cosmos.CosmosAsyncClient;
import com.azure.cosmos.CosmosClientBuilder;

// 客户端构建逻辑
CosmosAsyncClient cosmosClient = new CosmosClientBuilder()
        .endpoint("<你的Cosmos DB服务端点>")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildAsyncClient();

DefaultAzureCredential会自动读取Pod内注入的托管标识相关信息完成认证，无需额外开发认证逻辑。

故障排查参考 #

• 出现403权限错误：优先检查托管标识的Cosmos DB角色分配是否已生效，角色是否包含所需操作权限
• 出现凭证获取失败：检查应用Pod是否已正确注入工作负载标识相关环境变量，ServiceAccount与托管标识的绑定关系是否正确
• 出现连接超时：检查Cosmos DB防火墙是否已放通AKS集群的出站IP，或者已开启允许Azure服务访问的开关

内容的提问来源于stack exchange，提问作者Indrajit Banerjee