Terraform配置AKS虚拟节点时aci-connector-linux Pod CrashLoopBackOff问题

问题描述 #

• 操作场景：通过Terraform为Azure Kubernetes集群配置Virtual Nodes（虚拟节点）时出现功能异常
• 故障现象：aci-connector-linux Pod持续处于CrashLoopBackOff状态无法正常启动，Pod事件日志如下：

Events:
  Type     Reason   Age                     From     Message
  ----     ------   ----                    ----     -------
  Normal   Pulled   41m (x50 over 4h26m)    kubelet  Container image "mcr.microsoft.com/oss/virtual-kubelet/virtual-kubelet:1.4.1" already present on machine
  Warning  BackOff  68s (x1222 over 4h26m)  kubelet  Back-off restarting failed container

• 已执行操作：参照官方文档为AKS集群系统分配托管标识授予了Contributor（参与者）角色，故障未修复。

排查与解决方法 #

从事件日志看镜像已经成功拉取到本地，CrashLoopBackOff是容器内进程启动后异常退出导致，按以下优先级排查：

1. 先拉取容器运行日志定位具体报错，不要仅依赖Pod事件判断问题：

kubectl logs -n kube-system <替换为实际的aci-connector-linux Pod全名> -c aci-connector-linux

2. 检查角色分配的作用域是否正确
   绝大多数这类权限问题都是角色绑定的作用域配错了：很多人在Terraform里把Contributor角色绑定在AKS集群资源本身，但虚拟节点要求的权限作用域是虚拟节点所在的子网，而非AKS集群资源。检查你配置的azurerm_role_assignment资源的scope字段，确保传入的是虚拟节点对应子网的资源ID，而非AKS集群ID。
3. 检查AKS网络配置是否符合虚拟节点要求
   • 虚拟节点仅支持Azure CNI网络模式，不支持Kubenet模式，确认Terraform中azurerm_kubernetes_cluster的network_profile.network_plugin值为azure
   • 确认aci_connector_linux配置块中填写的subnet_name和你授权的子网为同一个，且该子网没有配置网络安全组规则拦截AKS节点与ACI实例的通信
4. 检查版本兼容性
   如果你在配置中手动固定了virtual-kubelet镜像版本为1.4.1，先移除固定版本的配置，让AKS自动拉取和当前集群版本匹配的connector镜像。1.4.1版本和1.27以上的部分AKS版本存在启动参数不兼容问题，会导致进程启动直接退出。
5. 权限生效等待
   Azure角色分配完成后最长需要5分钟左右才能全局生效，配置完成后不要立刻重启Pod，等待权限生效后执行以下命令重建Pod即可：

kubectl delete pod -n kube-system -l app=aci-connector-linux

常见报错对应：如果容器日志中出现failed to register node类的权限报错，90%以上都是子网层级的角色分配配置错误，重新正确绑定子网作用域的Contributor权限即可解决。

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