Harbor 栈——作为一个 release 部署的容器镜像仓库
本示例从一个由开发者编写的 Aggregate,将一个真实的容器镜像仓库编译为 Kubernetes
清单。
容器镜像仓库由许多协同工作的服务组成——由 API 和令牌服务构成的控制平面、OCI blob 存储及其控制器、Web 控制台、异步工作层、漏洞扫描器、关系型后端、键值缓存,以及位于它们前面的反向代理。目录将这一切描述为一个 Component,因为镜像仓库自己的维护者发布了一个 Helm chart,按照其服务所需的顺序,将整个仓库作为单个 release 部署。该 Component 声明镜像仓库;该 Recipe 封装该 chart。
镜像仓库作为一个模块导入:模块是一个可复用的子 aggregate,它组合该 Component 并导出其发布的地址。顶层 Aggregate 按名称导入该模块,并向其传入镜像仓库的三个密钥;运维人员在 Release 中为该模块的 component 设定规模。
文件
| 文件 | 角色 |
|---|---|
aggregate.yaml | 开发者意图:导入容器镜像仓库模块(core/harbor),并从自身的参数向其传入镜像仓库的三个密钥。 |
manifest-helm-synth.yaml | 将镜像仓库的组件类型映射到封装其 Helm chart 的 Recipe,并将凭据 Feature 映射到读取命名空间中已有 Secret 的实现——管理员密码除外,它按名称绑定到根据模块参数生成 Secret 的实现。 |
release-helm-synth.yaml | Kubernetes 目标的运维记录。指明保存 Aggregate 向下传递的三个密钥的 Secret,按模块作用域 ID 为模块的组件设定规格,并通过指明保存令牌签名密钥、各服务共享密钥以及用于加密已存储凭据的密钥的 Secret,将它们附加到该组件;其余均采用 schema 默认值。 |
演示内容
- 作为一个 Component 的多服务产品。 使该 registry 成为一个 Component 而非多个的,不是它的规模,而是其连接关系在哪里维护:反向代理路由、控制平面用来校验每次 pull 和 push 的令牌服务密钥、每个服务读取的后端和缓存连接设置、使各服务缓存键空间相互隔离的逻辑数据库划分,以及启动顺序——这一切都由交付该产品的人在 chart 内部与产品保持同步。使用者声明一个 registry,就能得到这些彼此一致的配置。
- 封装的 chart。 该 Recipe 在
source:中指定 chart,并在其上叠加一个valuesMapping:——values 模板就是全部实现,Helm provider 基于它渲染 chart 自身的模板。这里不合成任何 workload。 - 固定版本的外部输入。 chart 是构建时获取的输入,因此它像任何依赖一样被固定:lockfile 在
source_artifacts下记录 chart 的版本、解析后的 URL 以及 tarball 的摘要。基于已填充的 lockfile 进行的构建会从内容存储提供该 chart,并依据该摘要对其进行校验。 - 整个平台使用一个发布的地址。 chart 的反向代理
将浏览器路径
/路由到控制台,将 registry 和 API 路径 (/v2/、/api/、/service/、/c/)路由到控制平面,因此容器客户端登录、推送和拉取所用的主机,与浏览器访问控制台的主机相同。provides.host发布的正是该 Service,使用者无需第二个地址即可访问任一组路径。 - 它的两个公开名称。 该模块将这一个地址导出为
registry, 即镜像客户端和 API 通信的端点,以及ui,即 Web 端点。 两者都解析到同时提供两组路径的地址,因此使用者可以连接到最能描述其意图的那个名称。 - 运维人员为模块的 component 设置规格。 该 Release 通过模块作用域 ID(
harbor.registry)定位模块的 component 来设置计算资源,开发者的 Aggregate 无需重复声明物理规格。 - 分组值的完整性规则。
infra.compute包含一个 CPU 键和一个内存键,若某个分组将其中任一个留空,Recipe 就会中止。以 CPU 限制而无内存限制渲染出的控制平面,与该 Component 声明的默认值所描述的控制平面存在实质差异,而渲染输出中没有任何内容会表明这一点——因此构建会停止,并指出缺失的键。分组中省略的键采用该 Component 的默认值。 - 没有默认值的六个密钥。 令牌服务用来签署 registry 令牌的密钥及其证书;registry 自身各服务相互认证并签署上传状态所用的三个 secret;防请求伪造密钥;以及控制平面加密存储凭据所用的密钥,都没有默认值:一个目录的每个读者都持有的密钥,会让任何人都能签发 registry 信任的令牌,或读取它存储的内容。该 Component 将这些槽位声明为必需,因此留空其中任一个的构建会中止并指出该槽位。构建不读取这六个值,也不渲染其中任何一个:每个 workload 都从它指定的 Secret 中读取各值。
- 由 Release 附加的三个密钥。 该模块既不附加
令牌签名密钥,也不附加控制平面的共享 secret,也不附加加密存储凭据所用的密钥,因此由 Release 将这三者都附加到模块的 component 上,即
token_key、core_secret和secret_key,每个都通过core/referenced-secret并以infra.origin指定一个 Secret,而 Manifest 将该 Feature 绑定到k8s-existing-secret。控制平面从各自指定的 Secret 挂载令牌签名密钥和加密密钥,各服务则从它们的 Secret 读取共享 secret。 - 由模块填充的凭据。 管理员账户的密码、跨站请求伪造密钥、worker 层的共享 secret 以及 blob
存储的上传状态 secret,同样是该 Component 上的凭据槽位,模块通过
core/referenced-secret凭据 Feature,用自身的参数(admin_password、csrf_key、jobservice_secret、registry_http_secret)填充每一个,因此每个 workload 都按名称从 Secret 中读取它们。由于模块附加了该 Feature,Manifest 会映射它。这三个密钥在模块中同样没有默认值,因此 Aggregate 声明自己的参数并通过aggregates.harbor.parameters向下传递,由 Release 提供它们,而k8s-existing-secret将每个值读取为命名空间中已存在的 Secret 的名称;未提供值的 Release 会使构建中止,并指出该参数。本示例将管理员密码保留为模块的开发默认值,Manifest 按名称将这一个附加项绑定到k8s-secret-from-parameter,后者会生成一个携带该密码的 Secret。其余密码会写入 Release 渲染的配置中,因此改为通过设置infra来替换它们;若未设置,每个密码都取 Recipe 所给出的开发值。 - 基于本会自行生成材料的 chart 产生确定性输出。 若不加干预,该 chart 在未提供 secret 时会自行生成——控制平面的共享 secret 和令牌签名 secret、worker 层和 blob 存储的 secret、防请求伪造密钥,以及 blob 存储的哈希密码,它在每次渲染时都会用新的盐重新哈希。改为逐一提供这些值:六个密钥始终来自 Release 指定的 Secret,密码在槽位已填充时按名称取自附加的凭据,未填充时取固定的开发值,因此对相同输入的两次渲染会输出逐字节相同的内容。
- 可复现的镜像。 registry 运行的每个镜像都固定到一个明确的
tag。该产品以同一个 tag 发布所有镜像,因此
infra.engine_version可一次选定全部镜像;infra.overrides.image替换单个服务的固定版本,而infra.overrides.image_prefix可为从镜像仓库拉取的 Release 统一迁移所有镜像。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example harbor-stack然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd harbor-stack构建
此工作区不包含 .aggrega-config.yaml,因此标准库实体从 hub 注册表 hub.aggrega.ai 解析,无需 catalog 标志。该 Recipe 会获取一个 chart,因此请先将依赖解析到 lockfile 中:
aggrega pull --release release-helm-synth.yamlaggrega build --release release-helm-synth.yaml渲染产物位于 dist/ 下。
在应用它们之前,请在部署该 registry 的命名空间中创建该 Release 指定的六个 Secret:harbor-token-key,在数据键 tls.key 下保存一个 RSA 私钥,并在 tls.crt 下保存基于该私钥的证书;
harbor-core-secret,在数据键 secret 下保存一个 16 个字符的密钥;
harbor-secret-key,在 secretKey 下保存一个 16 个字符的密钥;
harbor-csrf-key,在 CSRF_KEY 下保存一个 32 个字符的密钥;以及
harbor-jobservice-secret 和 harbor-registry-http-secret,分别在 JOBSERVICE_SECRET 和 REGISTRY_HTTP_SECRET 下保存一个
16 个字符的密钥。例如:
openssl req -x509 -newkey rsa:4096 -nodes -days 3650 -subj "/CN=harbor-token-ca" \ -keyout tls.key -out tls.crtkubectl create secret tls harbor-token-key --key tls.key --cert tls.crtkubectl create secret generic harbor-core-secret --from-literal=secret="$(openssl rand -hex 8)"kubectl create secret generic harbor-secret-key --from-literal=secretKey="$(openssl rand -hex 8)"kubectl create secret generic harbor-csrf-key --from-literal=CSRF_KEY="$(openssl rand -hex 16)"kubectl create secret generic harbor-jobservice-secret --from-literal=JOBSERVICE_SECRET="$(openssl rand -hex 8)"kubectl create secret generic harbor-registry-http-secret --from-literal=REGISTRY_HTTP_SECRET="$(openssl rand -hex 8)"如果 registry 的服务找不到这些 Secret,registry 将无法启动。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自行创建任何文件夹。如果工作区文件夹中还没有 `harbor-stack` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `harbor-stack`,且不设置 `dir`:它会把示例写入新的 `harbor-stack` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `harbor-stack`,`release` 设为 `release-helm-synth.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我这次构建写入了哪些文件;它们位于 `harbor-stack/dist/` 下。组合后的镜像仓库是什么样子
构建会输出该 chart 为此配置定义的资源:
反向代理、控制台、控制平面、工作层和 blob 存储的 Deployment;后端、缓存和扫描器的 StatefulSet;blob 存储和工作层日志的持久卷声明;各服务读取的 ConfigMap 和 Secret;以及位于它们前面的 Service。此外,凭据 Feature 输出一个 Secret,
harbor-zdregistry-admin-password,其中携带该模块为管理员密码提供的开发默认值,控制平面从这个 Secret 而不是 chart 自身的 Secret 中读取该密码。六个密钥都不会输出 Secret:
控制平面从 harbor-token-key 挂载令牌签名密钥,从 harbor-secret-key 挂载加密密钥,其余密钥由各服务从
harbor-core-secret、harbor-csrf-key、harbor-jobservice-secret 和
harbor-registry-http-secret 读取,即该 Release 指定的这些 Secret。
这些 Service 中恰好有一个是消费方连接的地址——
dist/app/helm/harbor.registry-service-default-harbor-zdregistry.yaml:
apiVersion: v1kind: Servicemetadata: name: harbor-zdregistry [… omitted: the namespace, the chart's labels, and the labels and annotations every rendered document carries]spec: type: ClusterIP ports: - name: http port: 80 targetPort: 8080 selector: release: harbor-zdregistry app: "harbor" component: nginx它的选择器指向反向代理,正是这一点让镜像仓库拥有单一地址。port 跟随 infra.port;其后的代理监听 chart 固定的端口,由该 Service 转发到该端口,因此修改 infra.port 改变的是发布的地址,而不是监听端口。
命名:发布地址的开关不是为资源命名的开关
该 chart 从一个顶层名称开关派生出大部分资源名称,然后为它们添加后缀——控制平面的 Service 是 <instance>-core,控制台的是 <instance>-portal,blob 存储的是 <instance>-registry,工作层、扫描器、后端和缓存依此类推。没有任何资源直接使用该名称本身命名。
对外发布的 Service 由一个独立的、作用于暴露范围的开关命名,其默认值是一个与顶层名称无关的固定字面量。只固定顶层开关的 Recipe 会发布一个没有任何 Service 响应的地址,而同一命名空间中的两个实例都会以该固定字面量生成 Service,从而发生冲突。因此该 Recipe 根据实例 ID 同时设置这两个开关,这就是上面生成的 Service 以实例命名的原因,也是 provides.host 所指的地址确实存在的原因。
在封装任何平台 chart 时,这一点都值得仔细阅读:provides.host 必须指向该 chart 实际创建的 Service,而由哪个开关决定这一点是该 chart 自身的属性,而不是各 chart 之间通用的约定。
此配置未包含的内容
chart 的 Ingress 保持关闭,反向代理改为以集群内部 Service 的形式暴露,因为该 Component 发布的是集群内地址,而不是外部主机名。单一的外部端点在 ingress 层组装,路由到本模块导出的地址。传输安全处于关闭状态,因为 chart 自带的证书来源会在渲染时生成证书颁发机构和已签名的证书,而对相同输入进行两次渲染无法复现这些内容。Prometheus-operator 监视器也处于关闭状态。
registry 的指标同样处于关闭状态。该 Component 的 values.metrics_enabled 会为控制平面、worker 层、blob 存储以及一个新增的 exporter 开启指标,并发布这四个 Service 供抓取器发现;但同一个 chart 设置还会向每个集群内调用方开放 blob 存储的调试监听器——包括性能剖析、执行跟踪和运行时变量,且不对调用方进行任何校验。本模块将该值保留为默认值 false,因此本示例不渲染任何指标;自行声明该 Component 的 Aggregate 可以设置它。尽管如此,exporter 的镜像仍与其他镜像一样被固定。