Terraform部署Linux VM无法注册到Azure DevOps环境的问题排查

核心原因：custom_data执行环境与SSH会话的差异 #

Ubuntu虚拟机的custom_data默认通过cloud-init以root用户在系统初始化阶段执行，而你手动SSH执行脚本用的是普通用户（比如ubuntu），两者的执行上下文、环境变量、路径规则都有区别，这是导致azagent安装失败的主要原因。

具体排查与修复步骤 #

• 修正脚本的用户上下文
  如果你的注册脚本中使用了~/azagent这类相对路径，root用户执行时会把文件夹创建在/root/azagent而非普通用户的/home/ubuntu/azagent，导致你找不到文件。同时Azure DevOps Agent官方不建议用root用户运行，必须切换到普通用户执行注册流程。
  修复示例：

  # 切换到ubuntu用户执行azagent注册
  su - ubuntu -c '
  mkdir -p ~/azagent && cd ~/azagent
  # 替换为你的Azure DevOps Agent下载链接
  wget https://vstsagentpackage.azureedge.net/agent/2.220.5/vsts-agent-linux-x64-2.220.5.tar.gz
  tar zxvf vsts-agent-linux-x64-2.220.5.tar.gz
  # 替换为你的组织URL、令牌、环境/池名称，添加参数跳过交互
  ./config.sh --unattended --url https://dev.azure.com/your-org --token YOUR_PAT_TOKEN --pool Production --agent $(hostname) --acceptTeeEula --work _work
  '
  

• 确保脚本完全非交互
  手动执行时你可能会手动确认条款或输入信息，但cloud-init是无交互环境，脚本中如果存在需要用户输入的步骤会直接失败。必须给azagent的config.sh添加--unattended和--acceptTeeEula参数，跳过所有交互环节。

• 查看cloud-init详细日志
  启动诊断的控制台输出不够详细，直接登录虚拟机查看/var/log/cloud-init-output.log，这个日志会完整记录custom_data脚本的每一步执行结果、错误信息和返回码，能精准定位哪条命令失败（比如下载超时、权限不足、参数错误等）。

• 统一脚本中的命令路径
  cloud-init的环境变量PATH比SSH会话更精简，脚本中尽量使用命令的绝对路径（比如/usr/bin/docker而非docker），或者在脚本开头添加export PATH=$PATH:/usr/local/bin补充路径，避免因命令找不到导致执行失败。

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