附录1：YAML技巧

本指南的大部分内容都集中在编写模板语言。在这里，我们将看看YAML格式。YAML具有一些有用的特性，可以让我们作为模板的作者，可以使我们的模板更少出错并更易于阅读。

标量和集合

根据YAML规范YAML spec，有两种类型的集合，以及许多标量类型。

这两种类型的集合是maps和sequence：

map:
  one: 1
  two: 2
  three: 3

sequence:
  - one
  - two
  - three

标量值是单个值（与集合相对）

YAML中的标量类型

在Helm的YAML语言中，值的标量数据类型由一组复杂的规则确定，包括用于资源定义的Kubernetes schema。但是，在推断类型时，以下规则成立。

如果一个整数或浮点数是不加引号的单词，它通常被视为一个数字类型：

count: 1
size: 2.34

但如果他们被引号括起来，他们被视为字符串：

count: "1" # <-- string, not int
size: '2.34' # <-- string, not float

布尔值也是如此：

isGood: true   # bool
answer: "true" # string

空值的词是null（not nil）。

请注意，这port: "80"是有效的YAML，并且将通过模板引擎和YAML分析器，但如果Kubernetes预期port为整数，则会失败。

在某些情况下，您可以使用YAML节点标签强制进行特定的类型推断：

coffee: "yes, please"
age: !!str 21
port: !!int "80"

在上面，!!str告诉解析器age是一个字符串，即使它看起来像一个int。而port被视为一个int，即使它被引号括起来。

YAML中的字符串

我们放在YAML文档中的大部分数据都是字符串。YAML有多种表示字符串的方式。本节将介绍这些方法并演示如何使用其中的一些方法。

有三种内置方式来声明一个字符串：

way1: bare words
way2: "double-quoted strings"
way3: 'single-quoted strings'

所有内置样式必须位于同一行上。

单词没有被引用，并且没有escape。出于这个原因，你必须小心你使用什么字符。
双引号的字符串可以使用特定的字符\进行转义。例如"\"Hello\", she said"。你也可以用换行符换行\n。
单引号字符串是“文字”字符串，并且不使用\转义字符。唯一的转义序列是''，它被解码为一个单独的'。

除了单行字符串外，还可以声明多行字符串：

coffee: |
  Latte
  Cappuccino
  Espresso

以上将把coffee的值视为等价于单独字符串Latte\nCappuccino\nEspresso\n。

请注意，|必须后的第一行正确缩进。所以我们可以通过这样做来破坏上面的例子：

coffee: |
         Latte
  Cappuccino
  Espresso

由于Latte不正确缩进，我们会得到如下错误：

Error parsing file: error converting YAML to JSON: yaml: line 7: did not find expected key

在模板中，为了防止出现上述错误，在多行文档中放置假“第一行”内容有时更安全：

coffee: |
  # Commented first line
         Latte
  Cappuccino
  Espresso

请注意，无论第一行是什么，它都将保留在字符串的输出中。因此，例如，如果使用这种技术将文件内容注入到ConfigMap中，那么该注释应该是任何正在读取该条目的预期类型。

控制多行字符串中的空格

在上面的例子中，我们用来|表示一个多行字符串。但请注意，我们的字符串的内容后跟着\n。如果我们希望YAML处理器去掉尾随的换行符，我们可以在|后添加-：

coffee: |-
  Latte
  Cappuccino
  Espresso

现在的coffee值将是:Latte\nCappuccino\nEspresso(没有尾随 \n）。

其他时候，我们可能希望保留所有尾随空格。我们可以用|+符号来做到这一点：

coffee: |+
  Latte
  Cappuccino
  Espresso


another: value

现在的值coffee将会是Latte\nCappuccino\nEspresso\n\n\n。

文本块内部的缩进被保留，并保留换行符：

coffee: |-
  Latte
    12 oz
    16 oz
  Cappuccino
  Espresso

在上述情况下，coffee将是Latte\n 12 oz\n 16 oz\nCappuccino\nEspresso。

缩进和模板

在编写模板时，可能会发现自己希望将文件内容注入模板。正如我们在前几章中看到的，有两种方法可以做到这一点：

使用{{ .Files.Get "FILENAME" }}得到chart中的文件的内容。
使用{{ include "TEMPLATE" . }}渲染模板，然后其内容放入chart。

将文件插入YAML时，最好理解上面的多行规则。通常情况下，插入静态文件的最简单方法是做这样的事情：

myfile: |
{{ .Files.Get "myfile.txt" | indent 2 }}

请注意我们如何执行上面的缩进：indent 2告诉模板引擎使用两个空格缩进“myfile.txt”中的每一行。请注意，我们不缩进该模板行。那是因为如果我们做了，第一行的文件内容会缩进两次。

折叠多行字符串

有时候你想在你的YAML中用多行代表一个字符串，但是当它被解释时，要把它当作一个长行。这被称为“折叠”。要声明一个折叠块，使用>代替|：

coffee: >
  Latte
  Cappuccino
  Espresso

coffee的值将会是Latte Cappuccino Espresso\n。请注意，除最后一个换行符之外的所有内容都将转换为空格。您可以将空格控件与折叠文本标记组合起来，因此·将替换或去掉所有换行符。

请注意，在折叠语法中，缩进文本将导致行被保留。

coffee: >-
  Latte
    12 oz
    16 oz
  Cappuccino
  Espresso

以上将产生Latte\n 12 oz\n 16 oz\nCappuccino Espresso。请注意，空格和换行符都还在那里。

将多个文档嵌入到一个文件中

可以将多个YAML文档放入单个文件中。这是通过在一个新文档前加---,在文档结束加...来完成的


---
document:1
...
---
document: 2
...

在许多情况下，无论是---或...可被省略。

Helm中的某些文件不能包含多个文档。例如，如果文件内部提供了多个values.yaml文档，则只会使用第一个文档。

但是，模板文件可能有多个文档。发生这种情况时，文件（及其所有文档）在模板渲染期间被视为一个对象。但是，最终的YAML在被送到Kubernetes之前被分成多个文件。

我们建议每个文件在绝对必要时才使用多个文档。在一个文件中有多个文件可能很难调试。

YAML是JSON的Superset

因为YAML是JSON的超集，所以任何有效的JSON文档都应该是有效的YAML。

{
  "coffee": "yes, please",
  "coffees": [
    "Latte", "Cappuccino", "Espresso"
  ]
}

以上是下面另一种表达方式：

coffee: yes, please
coffees:
- Latte
- Cappuccino
- Espresso

这两者可以混合使用（小心使用）：

coffee: "yes, please"
coffees: [ "Latte", "Cappuccino", "Espresso"]

所有这三个都应该解析为相同的内部表示。

虽然这意味着诸如values.yaml可能包含JSON数据的文件，但Helm不会将文件扩展名.json视为有效的后缀。

YAML锚

YAML规范提供了一种方法来存储对某个值的引用，并稍后通过引用来引用该值。YAML将此称为“锚定”：

coffee: "yes, please"
favorite: &favoriteCoffee "Cappucino"
coffees:
  - Latte
  - *favoriteCoffee
  - Espresso

在上面，&favoriteCoffee设置一个引用到Cappuccino。之后，该引用被用作*favoriteCoffee。所以coffees变成了 Latte, Cappuccino, Espresso。

虽然在少数情况下锚点是有用的，但它们的一个方面可能导致细微的错误：第一次使用YAML时，引用被扩展，然后被丢弃。

所以如果我们要解码然后重新编码上面的例子，那么产生的YAML将是：

coffee: yes, please
favorite: Cappucino
coffees:
- Latte
- Cappucino
- Espresso

因为Helm和Kubernetes经常读取，修改并重写YAML文件，锚将会丢失。

附录 1：Yaml 技巧