更新模板中函数备注信息

2025-03-13 15:23:42 +08:00
parent 136d42a31e
commit 6754237844
13 changed files with 103 additions and 37 deletions
@@ -2,7 +2,7 @@ apiVersion: v2
 # 针对库类型的 Helm Chart，保持 `version` 和 `appVersion` 定义一致
 version: 1.0.0
 appVersion: 1.0.0
-description: Helm Chart 通用函数及工具库，用于其他 Helm Chart 仓库引用
+description: Helm Chart 通用函数及工具库，用于其他 Helm Chart 仓库引用(基于 Bitnami 进行汉化、修改)
 home: https://colovu.com
 maintainers:
  - name: Endial Fang(endial@126.com)
@@ -234,10 +234,9 @@
 {{- end -}}

 {{/*
-检测 Helm 版本是否为支持对版本（3.3+）。
+检测 Helm 版本是否为支持的版本（3.3+）（true/flase）。
 直到 Helm 3.3.0 版本才引入了 `.Capabilities.HelmVersion` 来检查所使用的 Helm 版本，该属性包含额外的 `{{}}` 结构。
-之所以使用 `regexMatch` 而非 `{{ if .Capabilities.HelmVersion }}` 进行检查，是因为在 Helm 版本低于 3.3 
-时检查 HelmVersion 键会导致 “未找到接口” 错误。
+之所以使用 `regexMatch` 而非 `{{ if .Capabilities.HelmVersion }}` 进行检查，是因为在 Helm 版本低于 3.3时检查 HelmVersion 键会导致 “未找到接口” 错误。
 **当依赖的最低 Helm 版本为 3.3 时，此检查将被移除**
 */}}
 {{- define "common.capabilities.supportsHelmVersion" -}}
@@ -1,5 +1,5 @@
 {{/* 
-检测是否为 Openshift 平台（true/false）
+检测是否为 Openshift 平台（true/false）。
 调用：
  {{- include "common.compatibility.isOpenshift" . -}}
 */}}
@@ -5,8 +5,8 @@
  {{- $validationError01 := include "common.validations.values.single.empty" (dict "valueKey" "path.to.password01" "secret" "secretName" "field" "password-01") -}}
  {{ include "common.errors.upgrade.passwords.empty" (dict "validationErrors" (list $validationError00 $validationError01) "context" $) }}
 参数：
-  - validationErrors - 字符串（必须）。待校验的字符串列表，如果为空返回错误。
-  - context - 上下文（必须）。父级上下文信息。
+  - validationErrors: 字符串（必须）。待校验的字符串列表，如果为空返回错误。
+  - context: 上下文（必须）。父级上下文信息。
 */}}
 {{- define "common.errors.upgrade.passwords.empty" -}}
  {{- $validationErrors := join "" .validationErrors -}}
@@ -1,6 +1,7 @@

 {{/*
-返回合适点镜像名称。如果镜像 Tag 或 digest 未定义，使用图表的 appVersion 作为版本标签。
+返回正确的镜像名称。
+如果镜像 Tag 或 Digest 未定义，使用图表的 appVersion 作为版本标签。
 调用：
  {{ include "common.images.image" ( dict "imageRoot" .Values.path.to.the.image "global" .Values.global "chart" .Chart ) }}
 */}}
@@ -27,7 +28,7 @@
 {{- end -}}

 {{/*
-返回合适到镜像库登陆信息模板。
+返回正确的镜像库登陆信息。
 调用：
  {{ include "common.images.renderPullSecrets" ( dict "images" (list .Values.path.to.the.image1, .Values.path.to.the.image2) "context" $) }}
 */}}
@@ -62,7 +63,7 @@ imagePullSecrets:
 {{- end -}}

 {{/*
-返回合适点镜像版本信息（忽略 revision/prerelease 信息）。
+返回正确的镜像版本信息（忽略 revision/prerelease 信息；若无效，使用图表的 appVersion 作为版本标签）。
 调用：
  {{ include "common.images.version" ( dict "imageRoot" .Values.path.to.the.image "chart" .Chart ) }}
 */}}
@@ -3,9 +3,9 @@
 调用：
  {{ include "common.ingress.backend" (dict "serviceName" "backendName" "servicePort" "backendPort" "context" $) }}
 参数：
-  - serviceName - 字符串。已存在的后端服务名称。
-  - servicePort - 字符串/整数。已存在的后端服务的端口名称（或端口号）. 根据数据类型不同，生成不同 YAML。
-  - context - 字典（必须）。模板上下文信息。（`$`: 根上下文； `.`: 当前模板上下文）
+  - serviceName: 字符串。已存在的后端服务名称。
+  - servicePort: 字符串/整数。已存在的后端服务的端口名称（或端口号）. 根据数据类型不同，生成不同 YAML。
+  - context: 字典（必须）。父级上下文信息（`$`: 根上下文； `.`: 当前模板上下文）。
 */}}
 {{- define "common.ingress.backend" -}}
 {{- $apiVersion := (include "common.capabilities.ingress.apiVersion" .context) -}}
@@ -25,7 +25,7 @@ service:
 {{- end -}}

 {{/*
-返回 pathType 是否支持（true / false）
+返回是否支持 pathType （true / false）。
 调用：
  {{ include "common.ingress.supportsPathType" . }}
 */}}
@@ -38,7 +38,7 @@ service:
 {{- end -}}

 {{/*
-返回 ingressClassname 是否支持（true / false）
+返回是否支持 ingressClassname （true / false）。
 调用：
  {{ include "common.ingress.supportsIngressClassname" . }}
 */}}
@@ -51,7 +51,7 @@ service:
 {{- end -}}

 {{/*
-返回 cert-manager 需要的注解是否存在（true / false）
+返回 cert-manager 需要的注解（TLS 签名证书）是否存在（true / false）。
 参考：
  https://cert-manager.io/docs/usage/ingress/#supported-annotations
 调用：
@@ -1,5 +1,5 @@
 {{/*
-获取 K8s 标准标签
+获取 K8s 标准标签。
 调用：
  {{ include "common.labels.standard" (dict "customLabels" .Values.commonLabels "context" $) -}}
 */}}
@@ -1,5 +1,5 @@
 {{/*
-获取应用名。
+获取图表名。
 受 K8s DNS 限制，截取为 63 个字符。
 */}}
 {{- define "common.names.name" -}}
@@ -7,7 +7,8 @@
 {{- end -}}

 {{/*
-获取包含图表名称、版本信息的图表名，用于通用标签。
+获取包含图表名称、版本信息的图表名；用于通用标签。
+受 K8s DNS 限制，截取为 63 个字符。
 */}}
 {{- define "common.names.chart" -}}
 {{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" -}}
@@ -50,7 +51,7 @@
 {{- end -}}

 {{/*
-在联合部署中，允许部署的 namespace 被手动控制。
+获取部署的 Namespace。
 */}}
 {{- define "common.names.namespace" -}}
 {{- default .Release.Namespace .Values.namespaceOverride | trunc 63 | trimSuffix "-" -}}
@@ -1,5 +1,6 @@
 {{/*
 根据给出的预设返回对应的 request/limit 资源对象。
+注意：预设资源配置主要用于开发、调试，生产环境建议使用特定的配置。
 调用：
  {{ include "common.resources.preset" (dict "type" "nano") -}}
 */}}
@@ -3,9 +3,9 @@
 调用：
  {{ include "common.secrets.name" (dict "existingSecret" .Values.path.to.the.existingSecret "defaultNameSuffix" "mySuffix" "context" $) }}
 参数：
-  - existingSecret - 字符串（可选）。用户定义的已存在的 Secret。
-  - defaultNameSuffix - 字符串（可选）。用于相同部署时的 Secret 前缀。
-  - context - 字典（必须）。父级上下文信息。
+  - existingSecret: 字符串（可选）。用户定义的已存在的 Secret。允许该值为用户定义的 Secret 的名称字符串。
+  - defaultNameSuffix: 字符串（可选）。用于相同部署时的 Secret 前缀。
+  - context: 字典（必须）。父级上下文信息。
 */}}
 {{- define "common.secrets.name" -}}
 {{- $name := (include "common.names.fullname" .context) -}}
@@ -32,8 +32,8 @@
 调用：
  {{ include "common.secrets.key" (dict "existingSecret" .Values.path.to.the.existingSecret "key" "keyName") }}
 参数：
-  - existingSecret - 字符串（可选）。用户定义的已存在的 Secret。
-  - key - 字符串（必须）。键名。
+  - existingSecret: 字符串（可选）。用户定义的已存在的 Secret。允许该值为用户定义的 Secret 的名称字符串。
+  - key: 字符串（必须）。键名。
 */}}
 {{- define "common.secrets.key" -}}
 {{- $key := .key -}}
@@ -136,10 +136,10 @@ The order in which this function returns a secret password:
 调用：
  {{ include "common.secrets.lookup" (dict "secret" "secret-name" "key" "keyName" "defaultValue" .Values.myValue "context" $) }}
 参数：
-  - secret - 字符串（必须）。存储密码的 Secret 的名字。
-  - key - 字符串（必须）。Secret 中键的名字。
-  - defaultValue - 字符串（必须）。 `values.yaml`配置文件中该键对应的路径，如："mysql.password"。获取第一个定义的值。
-  - context - 上下文（必须）。 父级上下文信息。
+  - secret: 字符串（必须）。存储密码的 Secret 的名字。
+  - key: 字符串（必须）。Secret 中键的名字。
+  - defaultValue: 字符串（必须）。 `values.yaml`配置文件中该键对应的路径，如："mysql.password"。获取第一个定义的值。
+  - context: 上下文（必须）。 父级上下文信息。
 */}}
 {{- define "common.secrets.lookup" -}}
 {{- $value := "" -}}
@@ -155,12 +155,12 @@ The order in which this function returns a secret password:
 {{- end -}}

 {{/*
-检测是否已存在一个旧版本的 secret定义（true/false）。
+检测是否已存在一个旧版本的 Secret定义（true/false）。
 调用：
  {{ include "common.secrets.exists" (dict "secret" "secret-name" "context" $) }}
 参数：
-  - secret - 字符串（必须）。用于存放密码的 Secret 的名字。
-  - context - 上下文（必须）。父级上下文信息。
+  - secret: 字符串（必须）。用于存放密码的 Secret 的名字。
+  - context: 上下文（必须）。父级上下文信息。
 */}}
 {{- define "common.secrets.exists" -}}
 {{- $secret := (lookup "v1" "Secret" (include "common.names.namespace" .context) .secret) }}
@@ -1,5 +1,5 @@
 {{/*
-返回正确的 Storage Class
+返回正确的 Storage Class。
 调用：
  {{ include "common.storage.class" ( dict "persistence" .Values.path.to.the.persistence "global" $) }}
 */}}
@@ -1,5 +1,5 @@
 {{/*
-返回获取 secret 值的命令。
+返回获取 Secret 值的命令。
 调用：
  {{ include "common.utils.secret.getvalue" (dict "secret" "secret-name" "field" "secret-value-field" "context" $) }}
 */}}
@@ -9,7 +9,7 @@ export {{ $varname }}=$(kubectl get secret --namespace {{ include "common.names.
 {{- end -}}

 {{/*
-将给定字段（横线分割）转换为容器的ENV变量（全大写）
+将给定字段（横线分割）转换为容器的 ENV 变量（全大写）
 调用：
  {{ include "common.utils.fieldToEnvVar" dict "field" "my-password" }}
 */}}
@@ -61,7 +61,7 @@ export {{ $varname }}=$(kubectl get secret --namespace {{ include "common.names.
 {{- end -}}

 {{/*
-对`path` 中包含的*单个*资源（ConfigMap、Secret）的模板进行校验和计算，以便用于*Pod*注解，同时排除元数据。
+对`path` 中包含的*单个*资源（ConfigMap、Secret）的模板进行*校验和*计算，以便用于*Pod*注解；校验和计算排除元数据。
 调用：
  {{ include "common.utils.checksumTemplate" (dict "path" "/configmap.yaml" "context" $) }}
 */}}
@@ -1,5 +1,5 @@
 {{/*
-使用滚动 TAG 时的警告信息。
+使用滚动 TAG 时的警告信息（如：latest）。
 调用：
  {{ include "common.warnings.rollingTag" .Values.path.to.the.imageRoot }}
 */}}
@@ -9,3 +9,67 @@
 WARNING: Rolling tag detected ({{ .repository }}:{{ .tag }}), please note that it is strongly recommended to avoid using rolling tags in a production environment.
 {{- end }}
 {{- end -}}
+
+{{/*
+在所有部署中针对设置默认 Resource 时的警告信息。
+调用：
+  {{ include "common.warnings.resources" (dict "sections" (list "path1" "path2") context $) }}
+举例:
+  {{- include "common.warnings.resources" (dict "sections" (list "csiProvider.provider" "server" "volumePermissions" "") "context" $) }}
+The list in the example assumes that the following values exist:
+  - csiProvider.provider.resources
+  - server.resources
+  - volumePermissions.resources
+  - resources
+*/}}
+{{- define "common.warnings.resources" -}}
+{{- $values := .context.Values -}}
+{{- $printMessage := false -}}
+{{ $affectedSections := list -}}
+{{- range .sections -}}
+  {{- if eq . "" -}}
+    {{/* Case where the resources section is at the root (one main deployment in the chart) */}}
+    {{- if not (index $values "resources") -}}
+    {{- $affectedSections = append $affectedSections "resources" -}}
+    {{- $printMessage = true -}}
+    {{- end -}}
+  {{- else -}}
+    {{/* Case where the are multiple resources sections (more than one main deployment in the chart) */}}
+    {{- $keys := split "." . -}}
+    {{/* We iterate through the different levels until arriving to the resource section. Example: a.b.c.resources */}}
+    {{- $section := $values -}}
+    {{- range $keys -}}
+      {{- $section = index $section . -}}
+    {{- end -}}
+    {{- if not (index $section "resources") -}}
+      {{/* If the section has enabled=false or replicaCount=0, do not include it */}}
+      {{- if and (hasKey $section "enabled") -}}
+        {{- if index $section "enabled" -}}
+          {{/* enabled=true */}}
+          {{- $affectedSections = append $affectedSections (printf "%s.resources" .) -}}
+          {{- $printMessage = true -}}
+        {{- end -}}
+      {{- else if and (hasKey $section "replicaCount")  -}}
+        {{/* We need a casting to int because number 0 is not treated as an int by default */}}
+        {{- if (gt (index $section "replicaCount" | int) 0) -}}
+          {{/* replicaCount > 0 */}}
+          {{- $affectedSections = append $affectedSections (printf "%s.resources" .) -}}
+          {{- $printMessage = true -}}
+        {{- end -}}
+      {{- else -}}
+        {{/* Default case, add it to the affected sections */}}
+        {{- $affectedSections = append $affectedSections (printf "%s.resources" .) -}}
+        {{- $printMessage = true -}}
+      {{- end -}}
+    {{- end -}}
+  {{- end -}}
+{{- end -}}
+{{- if $printMessage }}
+
+WARNING: There are "resources" sections in the chart not set. Using "resourcesPreset" is not recommended for production. For production installations, please set the following values according to your workload needs:
+{{- range $affectedSections }}
+  - {{ . }}
+{{- end }}
+info https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+{{- end -}}
+{{- end -}}