YAML 及其结构

YAML（YAML 不是标记语言）是一种数据序列化语言。在 Ansible 中，我们使用 YAML 编写配置文件，因为它对人类友好。

YAML 文件可以使用 .yaml 或 .yml 作为文件扩展名。以下代码片段展示了两个 YAML 文件：config.yaml 和 config.yml：

1config.yaml
2config.yml

YAML 文件的组成部分

当我们使用 YAML 编写配置时，整体配置结构由以下几个主要部分组成：

• 文档分隔符
• 键值对
• 缩进
• 列表
• 字典
• 注释

文档分隔符

YAML 文件通常以三个连字符 --- 开头。虽然这是可选的，但建议在所有配置文件中始终包含它。以下是展示 YAML 文件开头方式的示例配置：

1# sample_file.yml
2---
3# 配置继续

键值对

在 YAML 中，我们使用键值对来定义元素的属性。一个键后通常跟一个冒号（:），然后是对应的值。是否需要将值用引号括起来取决于其数据类型。字符串类型的值通常用双引号或单引号包裹，而数字和布尔值一般不需要。

以下示例展示了在 Ansible 配置中定义 MySQL 数据库所需属性的典型写法：

1# ...
2mysql_db:
3  name: "mydb"
4  state: present
5  login_user: "user"
6  login_password: "password"
7  login_host: 127.0.0.1

需要注意的是，在 第 3 至第 7 行，我们通过键值对定义了 name、state、login_user、login_password 和 login_host 这些属性。

缩进

缩进 在编写 YAML 配置时至关重要，因为它决定了配置文件中数据的层级关系。我们可以使用两个空格来定义不同元素的结构及其相互关系（YAML 不允许使用制表符进行缩进）。以下是一个包含父键及其子键的 YAML 示例：

1parent_key:
2  child_key1: value1
3  child_key2: value2

上述代码显示了一个 parent_key 和两个子键 child_key1 与 child_key2，它们均以两个空格缩进，表明它们属于父键的嵌套内容。

现在来看另一个例子，我们定义一个创建目录的任务：

1---
2- name: Sample playbook
3  hosts: localhost
4  tasks:
5    - name: Create directory
6      file:
7        path: /path/to/directory
8        state: directory

在此例中，我们对 第 5 行 的任务名称进行了缩进。同时，在 第 6 至第 8 行 使用了 file 模块。我们在 path 和 state 属性前留出两个空格，表示它们是嵌套在 file 父键下的。

列表

我们可以使用列表来组织属于同一类别的多个元素。例如，当需要列出多个主机或合并多个任务到一个 play 中时，可以使用列表。其基本语法如下：

1key_name:
2  - item1
3  - item2
4  - item3

上述代码展示了三个属于 key_name 类别的项目：item1、item2 和 item3。下面是一个更实际的例子，展示如何在 Playbook 中定义主机列表：

1---
2- name: Sample Playbook against a list of hosts
3  hosts:
4    - host1
5    - host2
6    - host3

在此示例中，host1、host2 和 host3 三个主机被定义在 hosts 类别下。

字典

字典（也称为映射）是包含键值对的关联数组。其基本语法如下：

1parent_key:
2  key1: value1
3  key2: value2
4  key3: value3

上述代码展示了三个键值对属于同一个类别。

我们还可以定义更复杂的映射，其中包含嵌套的字典和列表。例如：

1parent_map:
2  key1: value1
3  key2:
4    sub_key1: sub_value1
5    sub_key2: sub_value2
6  key3:
7    - item1
8    - item2
9  key4:
10    nested_map:
11      inner_key: inner_value
12      another_inner_key: another_inner_value

在这个复杂映射中，我们有四个键及其对应值：

• 第一个键仅有一个值；
• 第二个键包含一个带有两个子键的字典；
• 第三个键包含一个包含两个项目的列表；
• 第四个键包含一个嵌套的映射。

再看一个例子：

1vars:
2  server_configuration:
3    web_server:
4      port: 80
5      virtual_hosts:
6        - name: example.com
7          document_root: /var/www/example
8        - name: test.com
9          document_root: /var/www/test
10    database_server:
11      host: db.example.com
12      username: db_user
13      password: db_password

该示例展示了为某些 Web 服务器和数据库服务器定义变量的方法。

• 我们有一个 vars 键，其值是一个名为 server_configuration 的嵌套字典。
• server_configuration 包含两个键：web_server 和 database_server，以及它们各自的值。

注释

注释在配置中必不可少，因为它们有助于文档说明和后续参考。在 YAML 配置中，我们可以添加单行或多行注释：

• 单行注释：以 # 符号开头，用于注释任意单词或语句。典型的用法如下，这是一个带单行注释的 Playbook 示例：

1---
2# A sample single-line comment
3key: value

• 多行注释：跨越多行文本的注释，可通过 YAML 提供的 | 或 > 块标量来实现。以下示例中，我们定义了两个键 key1 和 key2，并为其添加多行注释以说明每个键的作用：

1key1: >
2  An example of a multiline comment.
3  This comment describes what we are doing with `key1`
4
5key2: |
6  Another example of a multiline comment.
7  This comment describes what we are doing with `key2`

此外，也可以使用多个单行注释跨越多行，代替使用一个长的多行注释。

分析一个示例 YAML 文件

现在让我们通过以下代码片段熟悉 YAML 文件的结构：

1# Sample YAML Configuration
2--- # 文档分隔符（可选）
3database:
4  host: "localhost"
5  port: 3306
6  username: "db_user"
7  password: "db_password"
8
9websites:
10  - name: "Our Website"
11    url: "https://www.ourwebsite.com"
12    pages:
13      - "Home"
14      - "About"
15      - "Contact"
16
17  - name: "Second Website"
18    url: "https://www.secondwebsite.com"
19    pages:
20      - "Home"
21      - "Products"
22      - "Contact"
23
24# This is an example of combining several single-line comments 
25# together to mimick a multi-line comment
26# Another line
27logs:
28  - name: "Access Logs"
29    location: "/var/log/nginx/access.log"
30    retention_days: 30  # Comment to describe the retention days
31
32  - name: "Error Logs"
33    location: "/var/log/nginx/error.log"
34    retention_days: 60

• 第 3 至第 7 行：database 部分定义了建立数据库连接所需的参数，包括 host、port、username 和 password。
• 第 9 至第 22 行：websites 部分组织了网站信息，包括 name、url 和 pages。
• 第 27 至第 34 行：logs 部分列出了日志条目，指定了它们的 name、location 和 retention_days。

在整个配置中，我们同时使用了单行和多行注释，以方便后期维护和理解。