存放在 git 仓库中的 chart
Helm chart 不一定来自 chart 仓库(registry)。本示例获取的 chart 位于一个 git 仓库中——即 Helm 项目自带的 hello-world
示例 chart——并将其构建为 Kubernetes 清单。
开发者的 Aggregate 对此只字未提。它只声明一个
core/compute/server,而该服务器的打包来自何处,由 Recipe 决定,并由 Manifest 绑定。
source 块
source: kind: git-repository url: https://github.com/helm/examples.git ref: hello-world-0.1.0 module_subdir: charts/hello-world三个坐标,各自回答一个不同的问题:
url——要克隆的仓库。https://、ssh://和git://均可接受。私有仓库可以通过 SSH agent 经 SSH 访问,也可以经 HTTPS 访问,此时需在你的 netrc 文件中为其主机添加一条条目——machine github.com login <user> password <token>。写入 URL 本身的凭据会被拒绝,如 身份验证 所述。ref——读取仓库时所用的引用:标签、分支或 提交。它就是仓库作者自己起的名字,不一定 是单纯的版本号——此处的标签还带有 chart 的名称。module_subdir——仓库中作为 chart 的目录。 该仓库在此路径下存放一个 chart,而仓库本身并不是 chart;该 目录也是区分制品的要素之一:同一仓库同一提交下的两个目录是两个制品,而不是一个。
source 种类指定的是传输方式和位置,而不是格式。同一 种类既可获取 chart,也可获取 Terraform 模块或任何其他文件目录; 目录里装的是什么,由使用它的 provider 负责。
lockfile 记录了什么
只有提交所指的内容不会在你不知情时改变。标签或分支是
仓库可以重新指向另一提交的名字,因此 aggrega pull 会解析
该引用并记录两者——你写下的引用,以及它解析到的
提交:
# release-chart.locksource_artifacts: - kind: git-repository url: https://github.com/helm/examples.git module_subdir: charts/hello-world pinned_version: f3dc419e558e6ccebce2ed447384e5d2e11de2f9 digest: sha256:2bee62cfc2efccc61d8e17efeb72f9f77ad7bd87f3ea4e50b1e4219c8d5a2c78 mediatype: application/gzip referenced_by: - entity: recipe uri: helm/hello-world-git:1.0.0 field: spec.source requested_ref: hello-world-0.1.0两者缺一不可。提交是构建所获取的内容,因此构建
可复现。引用是构建查找条目的依据,正因如此,
你可以继续在 Recipe 中写 ref: hello-world-0.1.0,并且仍然
解析到写入 lockfile 时该标签所指向的确切提交。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example chart-from-git-repository然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd chart-from-git-repository构建
aggrega build --release release-chart.yaml --auto-pull本示例包含两个 release,因此需要指定要构建的那个。首次构建
需要 lockfile,所以这里传入了 --auto-pull;事先运行一次
aggrega pull --release release-chart.yaml 效果相同,并且
之后的每次构建都无需任何标志。
渲染出的 Deployment 带有 Release 提供的值,这些值映射到 chart 自己的值名称上:
apiVersion: apps/v1kind: Deploymentmetadata: name: web-hello-world [… omitted: the chart's own labels, and the labels and annotations every rendered document carries]spec: replicas: 2 [… omitted: the selector and the pod template's own labels] spec: serviceAccountName: web-hello-world securityContext: {} containers: - name: hello-world securityContext: {} image: "nginx:1.27.3" imagePullPolicy: IfNotPresent [… omitted: the container port and the two probes]每次构建都会打印一条警告:
warning: node "web": .infra key "compute" is read by no template in recipe "hello-world-git" — correct the spelling, or remove the key这条警告是准确的,值得阅读而非屏蔽。core/compute/server
Component 提供了一个 CPU 和内存规格的调节项;而这个 chart 并未为其暴露任何
值,因此 Recipe 在此不做映射。获取 chart 的 Recipe 映射的是
该 chart 实际接受的内容,编译器会报告未落到任何地方的值,
而不是假装它已生效。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 的工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `chart-from-git-repository` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `chart-from-git-repository`,且不提供 `dir`:它会把示例写入一个新的 `chart-from-git-repository` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `chart-from-git-repository`,`release` 设为 `release-chart.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `chart-from-git-repository/dist/` 下。当引用发生移动时
标签可以在仓库中被重新指向。发生这种情况时,下一次普通的
aggrega pull 会发现该引用解析到的不是它所
记录的提交,并且停止,而不是采用新提交:
# aggrega pull --release release-chart.yaml## [E0130]# lockfile: out of date; it no longer matches what its Release resolves to# ---# source-artifact kind=git-repository url=https://github.com/helm/examples.git# module_subdir=charts/hello-world: reference "hello-world-0.1.0" moved — the# lockfile pins 03f4a18d3c2b77b7ecd91d0324a95910d4f04152, and it now resolves to# f3dc419e558e6ccebce2ed447384e5d2e11de2f9; adopt where it now points with# `aggrega pull --upgrade --release <release>`它会列出两个提交,让你在做决定前确切看到发生了什么变化。 lockfile 保持原样——停止发生在任何写入之前——而 采用新提交需要有意为之:
aggrega pull --upgrade --pin-sources --release release-chart.yaml引用移动正是 --upgrade 的用途:普通的 pull 会保持
lockfile 记录的提交,只有 upgrade 才会采用引用当前
指向的位置。单独使用 --upgrade 会丢弃所有已记录的固定,因此会先请求
确认。还需要 --pin-sources,因为此 Recipe 还会在其旁边的 entity.lock 中记录其
source 的提交:upgrade 会将该固定改写为
新提交,而若没有该标志,pull 会因该锁而停止,并提示
aggrega pin。请将改写后的 entity.lock 与 Recipe 一起提交。
在此工作区中所做的编辑,例如对 Aggregate 或 Release 的修改,属于另一种
漂移:下一次构建会报告它,而普通的
aggrega pull --release release-chart.yaml 会将其清除。
在 ref: 中固定提交而非标签,是获得同样
保证的另一种方式,代价是坐标无人能读懂。
防护用 release
release-negative.yaml 预期会失败,之所以放在这里,是因为只在正常路径上测试的获取
路径无法说明其防护是否有效。它
通过 manifest-negative.yaml 部署同一个 Aggregate,该文件绑定的 Recipe
除引用外与可用的那个完全相同——它指定了一个
仓库中不存在的标签:
aggrega build --release release-negative.yaml --auto-pull# exits non-zero# [E0137]# auto-pull: resolving the source of each Recipe and FeatureRecipe the Release# uses: resolve: resolve source for recipe# "helm/hello-world-git-missing-ref:1.0.0": sourceresolver: kind=git-repository# url=https://github.com/helm/examples.git version=: oci: artifact not found at# remote source (cause: reference not found)[… omitted: the rest of that line, a remediation naming the URL and version to check]仓库可以访问,克隆也会成功;只是其中没有这样的 引用,因此没有可固定的提交,也没有可归档的内容。
本示例对网络的需求
与这里的大多数工作区不同,本工作区在首次
构建时会克隆一个真实的仓库,因此该次构建需要能够出站访问 url 中指定的主机。一旦
lockfile 和解析缓存存在,之后的构建就会从缓存读取,
完全无需网络——aggrega build --release release-chart.yaml --offline
会重新构建出相同的字节。