格里姆

警告：Alpha 版本，可能不适合生产

警告：API 不稳定，可能会发生显着变化

有时您只需要在 K8S 资源定义中替换几个变量，通常在多个文件中使用相同的值。

这个工具的诞生是为了弥合 HELM 和 Kustomize 之间的差距，因为它们对于琐碎但常见的情况都缺乏简单性。但是，虽然 Gryml 在设计时考虑了 k8s，但它本质上是一个通用 YAML 处理器，可用于在需要值替换时自动生成任何 yaml 文件。

我们单独提供完整的功能列表，但在本文档中，我们将介绍最重要的功能。

安装

Gryml 现在在 pypi 中可用（需要 Python 3.7+）：

$ pip install gryml

你应该能够使用 CLI 版本：

$ gryml --help

Gryml 支持 UNIX 管道的输入和输出，所以类似这样的事情也是可能的：

$ echo "{say: something} #{world.greeting}" | gryml - --set world.greeting="hello world!"
---
say: hello world!

但通常你会使用 Gryml 来处理现有的模板文件，如下节所示。

基本

Gryml 可以用作 Unix 风格的 CLI，将传入的文件或目录与值文件或 cmd args 组合为 K8S 资源定义流到标准输出。

这可用于通过 kubectl 应用修改后的定义：

$ gryml <file>|<dir> --set app.name=sample | kubectl apply -f -

Gryml 依赖于 YAML 注释而不是内联模板，这使得它与只能使用原生 k8s 资源定义文件的工具兼容。

让我们看一个简单的例子：

deployment.gryml.yml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: "application" #{"app-" ~ common.name ~ "-suffix"}

name具有默认值的字段"application"具有#{"app-" ~ common.name ~ "-suffix"}Gryml 标记。

我们可以使用以下命令应用该值：

$ gryml deployment.gryml.yml --set common.name=simple

这将导致以下输出：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: "app-simple-suffix" 

注意：如果您的值很简单并且您只是按原样使用它 - 您可以使用简化的标签版本：#{common.name}.

注意：--set如果需要，可以使用多个参数来设置多个值。

默认情况下，包括对象和列表在内的所有值都将替换为简化标记的值，但有时需要将资源定义文件中的静态值与一些动态值结合起来。最常见的用例之一是容器环境变量。

为了促进这一点，Gryml 提供了可以使用以下标记语法应用的“价值策略”：

#[strategy <argument?>]{expression}

支持strategy的情况是以下之一：

• set- (默认) - 替换整个值
• append- 将新数组项添加到现有数组值
• merge-using <key>- 使用两个集合中的字段值合并两个包含对象的数组值，<key>以查找和替换现有项目
• if <expression>- 如果表达式的计算结果为，则删除值或项false
• else-if如果该策略被评估为，则可以在策略之后使用来输出值false
• repeat <key:value?>- 迭代中的值expression并重复数组项
• template jinja- 使用当前值树作为上下文将现有值处理为 Jinja2 模板

价值文件

如果除了--setGryml 支持的标志之外配置很复杂values file。您可以使用 -f <path_to_values_file>参数将 YAML 值文件与--set参数结合使用。请注意， --set参数将覆盖值文件。

此外，values 文件提供了两个重要功能，使 Gryml 能够生成类似于 HELM 图表的非常复杂的配置Gryml directives。

Gryml 指令可以使用"gryml"值文件中的键在列表中定义。

导入其他值文件

可以使用元数据对象的include字段包含其他值文件gryml，例如：

gryml:
 include: 
  - "another.values.yml"
  - "/workspace/root.values.yml"

注意：附加值文件在当前文件和值合并 之前导入，如果您需要在当前文件评估后override应用附加值，您可以使用元数据对象的字段。gryml

输出

在处理完所有值文件和参数并构建最终值树之后，可以引用也将被处理并包含在输出中的 yaml 文件。--set

结合includeandoverride指令，这允许基于不同的初始值文件从单个代码库生成不同的输出。此外，资源定义可以逻辑地组织到单个甚至多个存储库中的库和工件中，然后在值文件中显式组合在一起。

这基本上提供了一种动态生成“图表”的方法，显着减少不同资源定义之间的重复代码量，同时从相同的值派生相关部分。

价值转换管道

Gryml 值表达式支持 Jinja2 过滤器（尽管我们称它们为值转换管道）。Gryml 还定义了一些适用于 k8s 的附加管道。

目前 Gryml Core 定义了以下管道：

• lowercase- AAA -> aaa
• limit(<n>)- 将字符串的长度限制为 n 个符号
• k8sName- 将字符串的长度限制为 64 个符号
• b64enc- 将值转换为 base64 编码的字符串
• randstr- 使用该值作为生成的字母数字字符串的长度
• source- 使用值作为将作为字符串加载的文件名（相对于当前上下文）
• sha256- 将值转换为 sha256 哈希
• valmap(<pipe>)- 当值是字典时，将管道应用于每个字段值，保留键

图表管理和从 HELM 迁移

与 HELM 不同，Gryml 目前不会在生成的资源定义中添加任何标签，也无法管理发布版本。

然而，仍然可以在每个输出的 yaml 定义中生成和使用“通用”标签和注释，以便可以一次过滤和删除它们。

我们将来可能会引入grymlctl实用程序来直接管理 kubernetes 集群并处理 gryml 包。

高级示例

Deployment让我们用已经添加的 Gryml com-tags来看看这个定义。

deployment.gryml.yml

apiVersion: apps/v1 #{apiVersion.deployment}
kind: Deployment
metadata:
  name: "application" #{"test-" ~ name ~ "-suffix"}
spec:
  replicas: 1 #{replicas}
  strategy:
    type: Recreate #{strategy}
  selector:
    matchLabels:
      application: "application" #{name}
  template:
    metadata:
      labels:
        application: "application" #{name}

    spec:
      serviceAccountName: serviceAccount #{serviceAccountName}
      containers:
        - name: main #{"main-" ~ roleContainerSuffix}
          image: image #{imageRef}

          env: #[merge-using name]{env.common}
            - name: DEMO_GREETING
              value: "Hello from the environment"
            - name: DEMO_FAREWELL
              value: "Such a sweet sorrow"

        #[if useSecondary]
        - name: secondary #{"secondary-" ~ roleContainerSuffix}
          image: image #{imageRef}

          env: #[append]{env.common}
            - name: DEMO_FAREWELL
              value: "Such a sweet sorrow"

现在让我们创建值文件：

base.gryml.yml

apiVersion:
  deployment: 'apps/v1'

values.gryml.yml

gryml:
  include:
    - base.gryml.yml

  override:
    - context.gryml.yml

  output:
    - deployment.gryml.yml

name: 'custom-name'
role: 'test'
image: 'custom-image'
tag: 'latest'

useSecondary: false

replicas: 2
serviceAccountName: 'custom-serviceAccount'

env:
  common:
    - name: "COMMON_GREETING"
      value: "Common hello"
    - name: "DEMO_GREETING"
      value: "Hello from the custom environment"

context.gryml.yml

# Note: dynamic derived values are supported using the com-tags
imageRef: = #{image ~ ":" ~ tag}
roleContainerSuffix: = #{name ~ "-" ~ role ~ "-container"}

现在您可以只执行 exec: gryml -f values.gryml.yml，因此您应该能够看到 deployment.gryml.yml带有替换值的文件内容。

最佳实践

• 避免输出 yaml 文件中的复杂逻辑，而是在值文件中实现此逻辑
• 多个值文件之间的单独配置，而不是将其组合成一个

图书馆

Gryml 可以在没有 CLI 的情况下轻松用作 python 模块：

from gryml.core import Gryml
from pathlib import Path

gryml = Gryml()

values = gryml.load_values(
    Path("values-file.yaml"), 
    base_values=None, 
    process=True, 
    mutable=True,
    load_nested=True, 
    load_sources=True
)