Terraform创建Azure DevOps代理池报访问拒绝错误如何解决

根因说明 #

官方microsoft/azuredevops provider提供的azuredevops_agent_pool资源，默认调用Azure DevOps组织层级的管理接口创建跨项目共享代理池，这类接口不校验项目级权限，哪怕你持有单个项目的管理员权限、甚至能在Web UI正常创建代理池，只要没有对应组织层级的管理权限，调用接口就会返回你遇到的Access denied报错。
很多人能在Web UI创建通常是两个原因：要么创建时选的是项目专属代理池（走项目级接口），要么当时账号被临时授予了对应资源的操作权限，和Terraform调用的接口权限校验逻辑不一致。

分步排查修复 #

• 校验PAT的配置有效性
  首先确认Terraform使用的PAT是在目标组织下创建的组织级PAT，而非单项目范围内生成的PAT：进入组织设置-个人访问令牌页，找到对应PAT，确认「可访问的组织」选中了你的目标组织，授权范围里明确勾选了Agent Pools - Read & manage权限，不要只选通用的项目级读写范围。

  注意：PAT的权限是你账号本身权限的子集，就算PAT勾选了全访问范围，如果你账号本身没有对应组织级权限，接口依然会返回拒绝。

• 补全组织层级代理池管理权限
  你当前持有的项目级全权限不覆盖组织级资源操作，按以下路径配置：
  1. 进入Azure DevOps组织设置-安全-权限页
  2. 找到你操作账号所属的组织级安全组：如果需要管理全组织资源，直接把账号加入Project Collection Administrators（项目集合管理员）组；如果不想给过高权限，就单独给账号授予组织层级「代理池」资源的管理权限
  3. 不要在单个项目的权限配置页给代理池相关权限，这类配置仅对当前项目下的代理队列生效，不影响组织级资源。
• 核对Terraform资源选型是否匹配需求
  如果你不需要创建跨项目共享的组织级代理池，只是要给单个项目配置专属代理池，不要用azuredevops_agent_pool资源，替换为项目级的azuredevops_agent_queue资源即可，这类资源走项目级权限校验，你现有的项目管理员权限就可以操作，参考配置：

  # 读取目标项目信息
  data "azuredevops_project" "target" {
    name = "你的项目名称"
  }
  # 创建项目级专属代理池
  resource "azuredevops_agent_queue" "project_pool" {
    project_id = data.azuredevops_project.target.id
    name       = "项目专属代理池名称"
  }
  

  如果你确实需要创建组织级共享代理池，保留azuredevops_agent_pool资源即可，参考最小配置：

  resource "azuredevops_agent_pool" "org_pool" {
    name           = "组织共享代理池名称"
    pool_type      = "automation"
    auto_provision = true # 自动同步到所有项目的代理队列
    auto_update    = true
  }
  

• 权限生效验证
  Azure DevOps权限配置存在1-5分钟的缓存同步周期，改完权限不要立刻执行Terraform操作，等缓存同步后，可以先用同PAT调用Azure DevOps CLI测试代理池创建接口，接口返回成功后再执行terraform plan、terraform apply即可。

常见踩坑提示 #

• 不要混淆「项目管理员」和「项目集合管理员」两个角色：前者是项目级角色，默认无组织级共享资源的操作权限；后者才是组织级管理员角色，拥有全组织资源的操作权限。
• 如果PAT创建时选了「所有可访问组织」范围，很容易出现组织匹配错误，建议PAT明确绑定到单个目标组织使用。

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