为何符合条件的GCE VM未通过OSConfig访客策略安装指定来宾软件

问题现象 #

在GCP项目$GCP_PROJECT_ID中新建GCE实例$GCE_INSTANCE_NAME，执行以下命令查询生效的OS Config访客策略时返回无匹配结果：

gcloud beta compute os-config guest-policies lookup \
$GCE_INSTANCE_NAME \
--zone=$GCE_INSTANCE_ZONE

返回结果：

No effective guest policy found for [projects/$GCP_PROJECT_NAME/zones/$GCE_INSTANCE_ZONE/instances/$GCE_INSTANCE_NAME].

另一台操作系统版本、GCE元数据、GCE标签完全相同的实例$GCE_ANOTHER_INSTANCE执行相同命令可正常返回目标访客策略$GUEST_POLICY_NAME。

差异产生的可能原因 #

• OS Config代理状态异常
  新建实例未正常运行OS Config代理，或代理版本低于策略要求的最低版本。自定义镜像可能未预装该代理，或实例启动后代理未完成初始化就执行了查询操作。
• 实例级OS Config功能被禁用
  新建实例元数据中存在osconfig-disabled=true配置，该参数优先级高于全局配置，会直接阻断OS Config服务的策略下发。
• 服务账号权限缺失
  新建实例关联的服务账号缺少roles/osconfig.serviceAgent或roles/osconfig.guestPolicyReader等必要权限，导致服务端无法向该实例推送策略。
• 策略绑定范围未覆盖新建实例可用区
  若访客策略$GUEST_POLICY_NAME仅绑定到$GCE_ANOTHER_INSTANCE所在的区域/可用区，未包含$GCE_INSTANCE_NAME所在的$GCE_INSTANCE_ZONE，则新建实例无法匹配到该策略。
• 策略同步延迟
  OS Config服务的策略同步存在1~5分钟的延迟，新建实例创建完成后立即执行查询，可能无法返回尚未同步完成的策略。
• 策略筛选规则存在隐性差异
  即使两台实例的标签、元数据表面一致，需检查策略筛选规则是否排除了特定实例ID、实例名称前缀，或存在标签键值大小写、空格等不易察觉的差异。
• 区域OS Config API未启用
  若$GCE_INSTANCE_ZONE所属区域的OS Config API未启用，该区域内所有实例都无法查询到访客策略。

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