本地Helm仓库无法从Azure容器注册表(ACR)更新问题咨询

基本信息 #

• 已在本地添加ACR作为仓库并完成认证
• 分别尝试过helm repo add和az acr helm repo add命令添加仓库
• 使用ACR管理员用户进行认证
• 操作系统为Windows
• 测试过Helm v3.10.1和v3.10.2版本

场景1 #

• 执行az acr helm push --name someacr .\someapi1-0.1.3.tgz推送Helm Chart
• 可在Azure门户中看到该Chart
• 执行helm repo update --debug无报错
• 执行helm search repo -l无结果，helm pull也无法拉取Chart

场景2 #

• 执行az acr helm push --name someacr .\someapi1-0.1.3.tgz推送Helm Chart
• 无法在Azure门户中看到该Chart
• 执行helm repo update --debug无报错
• 执行helm search repo -l可以看到该Chart，helm pull也能成功下载Chart

核心疑问 #

1. 为何使用Helm原生方式推送后，本地仓库无法查看或拉取Chart，无法正常使用ACR？
2. 使用az acr helm工具推送后，为何Azure门户看不到Chart，但本地仓库更新正常且能拉取？

问题分析与解决方案 #

针对疑问1：Helm原生方式推送后本地无法查看/拉取Chart #

Helm v3原生的helm push命令基于OCI镜像规范推送Chart，而ACR同时支持两种Helm存储模式：

• 传统Helm仓库模式（兼容Helm v2，依赖index.yaml索引文件）
• OCI artifact模式（Helm v3推荐）

当你用Helm原生helm push推送时，Chart会以OCI artifact形式存储在ACR中，但你通过helm repo add添加的是ACR的传统Helm仓库地址（格式为https://<acr-name>.azurecr.io/helm/v1/repo），这个仓库的index.yaml不会自动同步OCI格式的Chart，因此helm search repo和helm pull无法识别到对应内容。而Azure门户默认展示传统Helm仓库的Chart，所以能在门户看到但本地无法访问。

解决办法：

• 将ACR作为OCI仓库添加到本地Helm：

  helm repo add --oci <自定义仓库名> oci://<acr-name>.azurecr.io/helm
  

• 拉取Chart时使用OCI格式命令：

  helm pull oci://<acr-name>.azurecr.io/helm/someapi1 --version 0.1.3
  

针对疑问2：az acr helm push推送后门户看不到但本地正常 #

az acr helm系列命令是ACR为兼容Helm v2提供的遗留工具，操作的是传统Helm仓库，出现该问题通常有以下原因：

1. 仓库名称不匹配：az acr helm push默认推送到名为repo的默认仓库，若推送时通过--repo参数指定了自定义仓库名，Azure门户默认只展示repo仓库的Chart，自定义仓库的内容不会在首页显示，但本地Helm客户端配置正确后可正常访问。
2. 门户缓存延迟：ACR门户对传统Helm仓库的索引同步存在延迟，推送后需等待5-10分钟再刷新查看。
3. 索引文件生成异常：推送过程中若因网络波动等导致index.yaml生成失败，门户无法读取Chart信息，但本地helm repo update会重新拉取正确索引，因此能正常访问。

解决办法：

• 检查推送命令是否指定了--repo参数，若有，需在ACR门户的「Helm仓库」页面切换到对应仓库查看。
• 等待一段时间后刷新门户，确认Chart是否显示。
• 重新推送并添加--debug参数排查索引生成情况：

  az acr helm push --name someacr --debug .\someapi1-0.1.3.tgz
  

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