跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

为渲染出的资源命名

Recipe 经常需要为其自身输出所产生的某个东西命名:通过 provides: 发布的主机名、valuesMapping: 中的引用、写入 artifacts: 正文的标识符。 有两个模板上下文键承载可用于此的名称,它们回答的是不同的问题。 读取了错误的键会产生静默出错而非被拒绝的输出——一个指向 未被任何东西生成的资源的地址——因此本页说明哪个键回答哪个问题。

本页还说明这两个键所依据的区别:目标(target)与引用(reference)并非 同一事物,而目标永远不是部署平台会解析的名称。

target 指向一个组件;reference 指向一个渲染出的资源

target 是一种编写层面的身份标识。 它是开发者写下的值,用来说明一条边指向哪个组件——即 uses 块中的 target: my_db——也是构建过程用来查找该组件、在诊断信息中报告该组件以及为其事实建立索引的身份标识。它在每个 provider 下读起来都相同,因为它描述的是你的文档,而不是任何平台。

reference 是让一个渲染出的制品指向另一个制品的东西。 它以某个 provider 自己的词汇写成:在 helm 下是集群内部地址,在 compose 下是服务名,在 terraform 下是插值表达式,在 cloudformation 下是导入值。reference 在每个 provider 下都不同,因为每个平台都以自己的方式解析 reference。

🔴 target 永远不会写入渲染输出。 每个 provider 都会派生自己的名称,因此只要两种拼写不同,把编写时的身份标识当作名称交给平台就是错误的——而它们恰好在 target 自身字母表不允许的那些字符上存在差异。不含此类字符的身份标识会原样保留,这正是这一点容易出错的原因:这个错误一直能正常工作,直到有人用下划线或大写字母为组件命名。

因此,消费者所需的 reference 由生产者发布,因为生产者的 Recipe 才了解其自身 provider 的词汇——消费者可能绑定完全不同的 provider,无法为它不渲染到的平台拼写 reference。消费者读取的只是一个普通的已发布字符串。

完整示例

生产者的 Recipe 发布地址;消费者通过边的别名将其读回。

# The PRODUCER's Recipe — a helm Recipe sourcing a chart the author supplied.
# It publishes an in-cluster address built from the name that chart's own
# templates render their resources against.
spec:
capability: helm
source: ./charts/postgres
provides:
host: "{{ .context.rendered_name }}.svc.cluster.local"
port: "5432"
# The CONSUMER's Aggregate — it names the producer by its TARGET, which is an
# authoring identity and stays in the documents. The uses block is keyed by the
# socket the catalog entity declares, then by the alias you choose for the edge.
spec:
components:
api:
type: core/compute/api-server
uses:
databases:
primary:
target: my_db
inject:
env:
- in: DB_HOST
from: host
- in: DB_PORT
from: port
# The CONSUMER's Recipe — it reads the published REFERENCE, never the target.
# The context keys an edge by its alias, so the socket does not reappear here.
spec:
capability: helm
valuesMapping: |
{
"db_host": "{{ .context.uses.primary.provides.host }}"
}

对于 helm 下由作者提供的 chart,名为 my_db 的组件会以 release 名称 my-zudb 渲染其资源。因此生产者的 chart 会生成一个 metadata.name 为 my-zudb 的 Service,发布的 host 为 my-zudb.svc.cluster.local,消费者连接的是一个确实存在的 Service——无论它是通过 .context.uses.primary.provides.host 读取该值,还是以注入的 DB_HOST 接收它。

若在此处写 {{ .context.uses.primary.target }},发布的将是 my_db.svc.cluster.local。这个值看起来并不像错的:它就是开发者写下的身份标识,拼写与其所写完全一致。它只是不指向任何 Service,而构建过程中没有任何地方会指出这一点。

成对看待这两个键

单独看任何一个键都无法读懂,因为每个键都由另一个键不是什么来定义。

键它命名的对象
{{ .context.instance_id }}该节点的标识,以及为该节点构建、且没有任何 provider 为其派生名称的资源的名称——从你的 artifacts: 块放置的制品集,以及由按标识命名工作负载的 provider(如 compose)从你的 workload: 块合成的工作负载。始终存在。
{{ .context.rendered_name }}所绑定的 provider 为它为该节点渲染的资源派生的名称——对于你提供的源,它是你自己提供的模板用来渲染其资源的名称,例如 chart 读取的 release 名称;对于它合成的 workload:,它是在 provider 按自己的名称而非标识命名这些资源时(如 helm)赋予这些资源的名称。仅当该 provider 派生了名称时才存在。在 Feature 附件自身的模板中,它是宿主 component 的名称——参见下文。

这种划分取决于名称必须在何处可用。你提供的 chart 或 module 有模板,这些模板按平台交给它们的任何标识来命名其资源——因此该名称必须是该平台将使用的名称,并以该平台自己的字母表拼写。合成的工作负载没有你的模板,但其资源仍须带有平台接受的名称:如果 provider 的名称允许编写的名称可能包含的所有字符,它就按标识命名这些资源;否则就按它派生的名称命名——并在此报告该名称,这样你就无须预测它。

**同时声明了所提供的源和 workload: 的节点会同时输出两类内容,并且不需要第三个键。**在 helm 下,两者都以同一个 release 名称命名,因此 rendered_name 对两者都适用:chart 自身的资源无论其模板如何组合都带有该名称,而每个合成的 Service 为 <rendered_name>-<service key>。在按标识命名合成工作负载的 provider 下,用 instance_id 命名该工作负载的资源,用该 provider 为所提供输出报告的名称来命名所提供输出的资源。

两者之所以可能不同,原因在于字母表。编写的 component 名称可以包含下划线或大写字母;chart 的 release 名称则不可以,而派生过程不会把这类字符折叠为相似的字符——那会让两个你能区分的 component 在集群中得到同一个名称——而是将其显式写出。有关该 provider 自己的字母表和长度限制,参见 ../providers/helm.md 中的“How the release name is derived”。

哪些 provider 报告名称,以及其他 provider 为何不报告

helm 报告一个名称:release 名称。来源 chart 以 .Release.Name 读取它,并通常以它命名自己的资源;该 provider 为组件合成的每个资源也以它命名——控制器直接使用 release 名称,每个 Service 则为 <release name>-<service key>。因此,为任一种输出发布的地址都由 rendered_name 构建。对于只放置制品集的节点,它不报告名称:该集合中的名称就是其作者所写的名称。

# A synthesized helm Recipe publishing the address of the Service its workload
# declares under the key `default`.
spec:
capability: helm
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
containers:
main:
image: "valkey/valkey:8"
ports:
redis: 6379
services:
default:
type: ClusterIP
ports:
redis: 6379
provides:
host: "{{ .context.rendered_name }}-default"
port: "6379"

名为 cache 的组件发布 cache-default,名为 my_cache 的组件发布 my-zucache-default——两种情况下都是构建所输出的 Service 的名称。

其他四个 provider 不报告名称,而且原因并不相同。它们都不是有待支持的 provider——每种情况下,要么没有可报告的派生名称,要么你需要的名称已可通过其他方式获取。

  • cloudformation 和 compose——名称由你编写,或者标识即名称。 cloudformation Recipe 自行编写其资源的逻辑 id,provider 完全按所写内容读取;你提供的 compose 文件自行命名其服务,provider 合并该文件并为其添加标签,而不重命名其中任何内容。compose 合成的 workload 以节点的标识命名,compose 文件按原样接受该标识,因此 {{ .context.instance_id }} 就是该名称。没有需要报告的派生,名称就是你自己文档中写明的名称。该名称是 workload 的主服务,即对端访问的那个服务;它携带的 sidecar 或 init 服务由同一标识和容器名称以 -- 连接而命名,如sidecar 或 init 服务如何命名所述。

  • **terraform——名称取决于文件的放置位置。**贡献者的 module 块以其配置写入的输出目录命名,而该目录在组装边界的文件时确定,而非在渲染节点时确定。在 Recipe 的模板运行时,该位置尚不存在。

  • **helm-chart——它派生的名称是所放置 chart 自身的地址,这与该 chart 的模板渲染时所依据的名称是两回事。**该 provider 将你 vendor 的 chart 的 name 字段设置为贡献它的对象的编码标识,这同时也是 umbrella 绑定该子 chart 所用的别名,以及其 values 所归属的键。对于组件,该标识就是 {{ .context.instance_id }} 所携带的内容,因此所放置 chart 的名称已可通过表明其含义的键获取。被 vendor 的 chart 自身模板渲染时所依据的名称是 release 名称,它由 umbrella 的 release 在安装时提供,而非由该 provider 派生——因此这里没有可供此键报告的此类名称。参见 ../providers/helm-chart.md“The chart name the umbrella owns”。

在未报告名称的情况下读取该键

在其 provider 未报告此类名称的节点上读取 {{ .context.rendered_name }} 会使构建中止,诊断信息会说明应改写哪个键。它不会渲染空值:少了一段的地址是一个会被部署的错误产物,这比停止的构建更糟。

中止时给出哪种补救办法取决于节点,而不取决于你在何处写下该引用:

  • 一个自身不提供 source 的节点,在一个不为其报告名称的 provider 下,其资源以其标识命名,因此中止信息会指明 {{ .context.instance_id }}——存在一个正确的值,诊断会明确指出。
  • 一个确实提供了 source 的节点,在一个不为其派生名称的 provider 下,没有替代值。中止信息会说明这一点,而不是给出一个替代值,因为在那里让你改用标识,会命名你的节点并不具有的资源。

该拒绝涵盖 provides: 以及 Recipe 内联编写的其他所有模板——它的 valuesMapping:、它的 workload: 主体、每个 artifacts: 条目,以及每个 pipeline 步骤的 with: 和 when:。

🔴 两种导入形式都不在其范围内。 通过 $import: 提供的 valuesMapping:、workload: 或 artifacts: 条目——无论导入指向本地文件还是库条目——在渲染解析它之前,在你的 Recipe 中不含任何文本,因此此类主体内部对该键的引用不会被检查。在导入节点的 provider 报告名称时,它渲染该 provider 报告的名称;在其未报告名称时,它渲染空值而不是中止。因此,只有当导入某个主体的每个 Recipe 都绑定一个会报告名称的 provider 时,该导入主体才应读取该键——例如一个为提供 chart 的 helm Recipes 编写、并在其描述中说明这一点的库条目。若主体面向的导入方的 provider 可能不报告名称,则应改为通过导入方 Recipe 设置的值来获取名称。

Recipe 的 locals: 条目完全不读取该键。local 与 Recipe 的 source: 模板共享上下文,而节点是否提供 source 正是名称所依赖的因素之一,因此在那里不提供该名称。所以,无论 provider 报告什么,local 中对 {{ .context.rendered_name }} 的引用都会中止,并给出针对渲染上下文未定义的引用的诊断(E0060),该诊断会列出 .context.instance_id 作为 .context 在那里提供的唯一键。请在需要它的 provides: 条目或内联模板中读取该键。

关于 Feature 附件自身的模板

在 Feature 附件的 FeatureRecipe 编写的模板上——它的 locals:、source:、provides:、 injectMapping:、valuesMapping:、workload:、每个 artifacts: 条目,以及每个 pipeline 步骤的 with: 和 when:——{{ .context.rendered_name }} 是宿主 component 的名称:即宿主自身的 provider 为其为宿主渲染的资源所报告的名称,也就是宿主自身的 Recipe 读取的值。它与 {{ .context.instance_id }} 配对,后者在这些模板上是宿主 component 的标识;附件本身是 .attachment_name。写在某个 component 的某个连接上的附件读取的是消费方 component 的名称,因为该 component 是它的宿主。

这正是用来构建附件自身资源名称的键。一个以其所附加的 component 来命名 Secret、route 或 policy 的 FeatureRecipe 需要一个平台接受的名称,而按原样书写的宿主标识只要含有下划线或大写字母就不是这样的名称。在 helm 下,名为 my_db 的 component 报告 my-zudb,因此对于附件 root,名为 {{ .context.rendered_name }}-{{ .attachment_name }} 的 Secret 渲染为 my-zudb-root,而 {{ .context.instance_id }} 会得到 my_db-root,集群会拒绝它。 无论附件通过哪个 provider 渲染,该值始终是宿主的值。

只要宿主的 provider 报告名称,该键就存在——在 helm 下,即其 Recipe 提供 chart 或声明 workload: 的宿主——而在其未报告名称时则不存在:仅放置一个 artifact 集的宿主,以及使用其他任何 provider 的宿主。在此类宿主的附件上读取它会使构建中止,并给出针对渲染上下文未定义的引用的诊断(E0060),该诊断会列出 .context 在那里定义的键。{{ .context.instance_id }} 就在其中,而在此类宿主上宿主自身的资源正是以它命名的,因此为可能不报告名称的宿主编写的 FeatureRecipe 应改为读取标识。

该拒绝涵盖 FeatureRecipe 内联编写的模板,但其 injectMapping: 除外。 injectMapping:,以及 FeatureRecipe 通过 $import: 提供的 valuesMapping:、workload: 或 artifacts: 条目,不会被检查:在不报告名称的宿主上,那里的引用会渲染空值,而不是中止。

当附件交付由其作者提供的 chart 时,该 chart 的模板会针对宿主 component 的 release 名称渲染,这是有意为之:若改为从附件派生该名称,会重命名 chart 作者声明且可能已部署的资源。.attachment_name 是用来区分同一宿主上两个附件的值——参见 ../providers/helm.md “How the release name is derived”。

由连接的附加项派生的名称

连接所携带的附加项是消费方组件的附加项,其名称为 <alias>.<slot>——例如,在别名 gpt 下编写的连接,其 credential 槽位对应 gpt.credential(参见 Aggregate 的连接条目)。这个组合而成的名称就是其 FeatureRecipe 渲染时所用的 .attachment_name,并且它带有点号。

由此产生两类名称,它们对点号的处理方式不同。

由 FeatureRecipe 组合的名称保留其模板写入的任何内容。 标准库中的凭据实现将其资源命名为 {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }},因此名为 router 的组件在其 gpt 连接上的凭据会渲染为名为 router-gpt.credential 的资源,点号保留,这是一个有效的 Kubernetes 对象名称。在这类名称中,点号是否保留完全取决于模板是否保留它。

由构建根据附加项标识派生的名称会把点号转写掉。 标识标签和输出文件由宿主组件和附加项名称组合而成,所用的编码与所有由标识派生的名称相同,该编码将点号写为 zd,将大写字母写为其码点的转义,因为该标识既用作资源名称也用作标签,而 Service 名称两者都不允许:以别名 gptPro 编写的连接会得到 cfr--router--gpt-zx000050ro-zdcredential。上述资源的标签为 aggrega.ai/component-id: cfr--router--gpt-zdcredential(app.kubernetes.io/name 同理),在 helm provider 下输出为 router--gpt-zdcredential--router-secret-router-gpt-credential.yaml。关于点号为何被转写而不是被替换,参见命名约定中的“分隔符不会进入名称”。