Knative Serving v1.23.0 镜像离线收集推送手册

日期:2026-08-05
组件:Knative Serving v1.23.0 + net-kourier v1.23.0(官方 release YAML,经 gh-proxy.com 下载)
目标仓库:Harbor 192.168.122.156:30000,项目 knative(HTTP 明文,已在节点 containerd insecure-registries 中注册)
镜像源:DaoCloud gcr.m.daocloud.io/knative-releases(gcr.io 镜像)、docker.m.daocloud.io(docker.io 镜像)
结果:8 个镜像(7 组件 + 1 验证示例)全部推送成功,linux/amd64 可用

1. 背景与目标

Knative 官方镜像全部托管在 gcr.io/knative-releases(envoy 在 docker.io),离线集群不可达。与 monitoring/longhorn 不同:

官方 YAML 用 repo@sha256:<digest> 固化镜像,没有 tag;skopeo list-tags 对 gcr 镜像返回空,必须按 digest 复制;
同步目标 tag 取 digest 前 16 位(如 cmd/controller:ca5062ece0329d00),离线 YAML 同步改写为 tag 引用 —— 规避 attestation 层 fallback 导致 digest 变化后与 YAML 摘要不匹配的问题。

2. 工具准备

工具	版本	用途
curl	-	经 gh-proxy.com 下载 release YAML、Harbor API 校验
skopeo	1.4.1	跨仓库复制镜像
python3	3.x	Harbor API 校验(URL 双重编码)

bash

skopeo login --tls-verify=false -u admin -p '<密码>' 192.168.122.156:30000

# 创建 knative 项目(push 前项目必须存在;已存在返回 409 忽略)
curl -s -X POST -u 'admin:<密码>' -H 'Content-Type: application/json' \
  -d '{"project_name":"knative","public":true}' \
  "http://192.168.122.156:30000/api/v2.0/projects"

3. 下载 release 并提取镜像清单

bash

BASE="https://gh-proxy.com/https://github.com"
curl -sL -o serving-crds.yaml "$BASE/knative/serving/releases/download/knative-v1.23.0/serving-crds.yaml"
curl -sL -o serving-core.yaml "$BASE/knative/serving/releases/download/knative-v1.23.0/serving-core.yaml"
curl -sL -o kourier.yaml      "$BASE/knative-extensions/net-kourier/releases/download/knative-v1.23.0/kourier.yaml"

# 提取(注意:① grep 要兼容 "- image:" 前缀;② "disabled" 是 configmap 示例值需剔除;
#          ③ net-kourier 的镜像在 kourier.yaml 里,只扫 serving-core.yaml 会漏)
grep -hoE 'image: [^ ]+' serving-core.yaml kourier.yaml | awk '{print $2}' | grep -v disabled | sort -u > images.txt

v1.23.0 提取结果 7 个镜像(清单见附录 A):serving 5 个(activator/autoscaler/controller/queue/webhook,digest 固化)+ net-kourier 1 个 + envoy 1 个。

queue 镜像是关键:config-deployment.queue-sidecar-image 引用它,所有 Revision Pod 都注入该 sidecar,漏同步会导致全部业务 Pod ImagePullBackOff。

4. 推送镜像到私有仓库

同步脚本见 midddleware/knative/sync-images.sh,核心逻辑:

bash

SRC_GCR="gcr.m.daocloud.io/knative-releases"
DST="192.168.122.156:30000/knative"

# digest 镜像:源按 digest 复制,目标用 digest 前 16 位做 tag
skopeo copy --all --retry-times=3 --dest-tls-verify=false \
  "docker://$SRC_GCR/knative.dev/serving/cmd/controller@sha256:<hex>" \
  "docker://$DST/knative.dev/serving/cmd/controller:<hex前16位>"

# tag 镜像(envoy/helloworld-go):保持原 tag
skopeo copy --all --retry-times=3 --dest-tls-verify=false \
  "docker://docker.m.daocloud.io/envoyproxy/envoy:v1.37-latest" \
  "docker://$DST/envoyproxy/envoy:v1.37-latest"

踩坑记录(重点)

问题	现象	原因与解法
skopeo 1.4.1 复制含 attestation 层镜像失败	`unsupported MIME type for compression: application/vnd.in-toto+json`(`knative-samples/helloworld-go` 命中)	buildkit 镜像带 in-toto 层,`--all` 重建 manifest 列表失败。解法:fallback `--override-os linux --override-arch amd64` 单架构复制(脚本已内置,集群全 amd64 满足需求)
digest 固化镜像无法用 tag 查源	`skopeo list-tags docker://gcr.m.daocloud.io/knative-releases/...` 返回 `[]`	gcr 镜像仅按 digest 发布,源地址直接拼 `@sha256:<hex>`
Harbor API artifact 查询 404 假象	仓库名 `knative.dev/serving/cmd/controller` 多级路径直接拼 URL 404	repository_name 需双重 URL 编码(`/` → `%252F`,Harbor 路由先解码一次),与 monitoring 手册的分页坑不同
镜像清单提取遗漏	只扫 serving-core.yaml 漏掉 net-kourier 镜像(在 kourier.yaml,且行首是 `- image:`)	两文件合并扫描,grep 兼容列表前缀
同步速度慢	单镜像 5-8 分钟	DaoCloud gcr 镜像站限速,8 个镜像全程约 40 分钟,建议放后台/分批执行

5. 验证

以 artifact 级查询为准(repository_name 双重编码):

bash

miss=0
while read -r pair; do
  repo="${pair%%:*}"; tag="${pair##*:}"
  enc=$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(urllib.parse.quote(sys.argv[1],safe=''),safe=''))" "$repo")
  code=$(curl -s -o /dev/null -w "%{http_code}" -u 'admin:<密码>' \
    "http://192.168.122.156:30000/api/v2.0/projects/knative/repositories/$enc/artifacts/$tag")
  [ "$code" != "200" ] && { echo "MISSING: $repo:$tag"; miss=$((miss+1)); }
done < images-harbor.txt    # Harbor 侧 repo:tag 清单(digest 前 16 位 tag)
echo "缺失: $miss / 8"        # 本次实测:缺失: 0 / 8

6. 集群侧使用

离线化 YAML(registry + digest→tag 改写,已在 midddleware/knative/ 内生成):

bash

sed -E "s|gcr\.io/knative-releases/(knative\.dev/[a-z0-9/._-]+)@sha256:([0-9a-f]{16})[0-9a-f]*|192.168.122.156:30000/knative/\1:\2|g" serving-core.yaml > serving-core-offline.yaml

三处必须同时保证(漏一个都会 ImagePullBackOff):

serving-core-offline.yaml 中 5 个组件镜像;
kourier-offline.yaml 中 net-kourier + envoy 镜像;
config-deployment.queue-sidecar-image(config-knative.yaml 中已固化为 Harbor 地址)。

另外 Knative controller 解析 tag→digest 只走 HTTPS,对 HTTP Harbor 必须配置 config-deployment.registries-skipping-tag-resolving: 192.168.122.156:30000。

附录 A:镜像清单(7 组件 + 1 示例)

# 源(gcr.io / docker.io 原路径,离线 YAML 中替换为 192.168.122.156:30000/knative/ 前缀)
gcr.io/knative-releases/knative.dev/net-kourier/cmd/kourier@sha256:eedfe3938f1efa93230863099f96400a0567909d383a585021f8727fa3a6cf0b
gcr.io/knative-releases/knative.dev/serving/cmd/activator@sha256:e5ab46f3b73fa2e3898fe47f6a3a0c2bd765596f4fb36ceb4c28c35d0a74b2e5
gcr.io/knative-releases/knative.dev/serving/cmd/autoscaler@sha256:879da127b23db65d862cafa6b23fb987381d0e44150f0027d44e1f5aee83bde2
gcr.io/knative-releases/knative.dev/serving/cmd/controller@sha256:ca5062ece0329d002a81940cf4268d7898866434d70049bb93f27d3a786d3292
gcr.io/knative-releases/knative.dev/serving/cmd/queue@sha256:a3cc71ce80dbc6df8781f15eac2cf3531a4c9815271799afd8776bef9e6aeaf2
gcr.io/knative-releases/knative.dev/serving/cmd/webhook@sha256:3846e9a416665c5b9ec2e4de246cfcb5c4ab0d01ba19348aa008caf30144b650
docker.io/envoyproxy/envoy:v1.37-latest
# 验证示例
gcr.io/knative-samples/helloworld-go:latest

Knative Serving v1.23.0 镜像离线收集推送手册 ​

1. 背景与目标 ​

2. 工具准备 ​

3. 下载 release 并提取镜像清单 ​

4. 推送镜像到私有仓库 ​

踩坑记录(重点) ​

5. 验证 ​

6. 集群侧使用 ​

附录 A:镜像清单(7 组件 + 1 示例) ​

Knative Serving v1.23.0 镜像离线收集推送手册

1. 背景与目标

2. 工具准备

3. 下载 release 并提取镜像清单

4. 推送镜像到私有仓库

踩坑记录(重点)

5. 验证

6. 集群侧使用

附录 A:镜像清单(7 组件 + 1 示例)