Ansible Playbook Roles and Include Statements

介绍

虽然可以在一个非常大的文件中编写一个playbook（您可能会以这种方式开始学习playbook），但最终您将需要重新使用文件并开始组织事情。

在基本级别，饱含任务的文件允许您将配置策略分解成较小的文件。 任务包括从其他文件中拉入任务。 由于处理程序也是任务，您还可以从“handler”部分中include处理程序文件。

如果您需要查看这些概念，请参阅“ Playbooks” 。

Playbook还可以包括其他Playbook文件的plays。 当这样做完成时，plays将被插入到Playbook中以形成更长的plays列表。

当你开始思考任务，处理程序，变量等等 - 开始形成更大的概念。 你开始思考建模是什么，而不是如何让东西看起来像什么。 这不再是“这几个主机应用这些主机”，你说“这些主机是dbservers”或“这些主机是web服务器”。 在编程中，我们可以称之为“封装”事情的工作。 例如，您可以驾驶汽车而不知道发动机是如何工作的。

Ansible的角色建立在include文件的想法上，并将它们组合起来形成干净，可重复使用的抽象 - 它们允许您更多地关注大局，只有在需要时才能深入细节。

我们从理解的角度开始，所以角色变得更有意义，但是我们的最终目标应该是理解角色 - 角色很好，每次写剧本时都应该使用它们。

请参阅GitHub上的ansible-examples存储库，了解所有这些的一些示例。 您可能希望在您潜入时在单独的标签中打开此页面。

Task versus Play includes

task和play都使用include关键字，但是以不同的方式实现关键字。 它们之间的区别取决于他们的位置和内容。 如果include在一个play中，它只能是一个“task” include，include一个任务列表; 如果是顶级，它只能include plays。 例如：

# this is a 'play' include
- include: intro_example.yml

- name: another play
  hosts: all
  tasks:
    - debug: msg=hello

    # this is a 'task' include
    - include: stuff.yml

“task” include 可以出现在任务可以的任何地方，但是“play” include 不能在其他play中，只能在同一层次上。 虽然“task”include可以采取其他参数并且让被包含的​​任务继承它们，但是“play”include非常有限，并且大多数指令不起作用。

Task Include Files And Encouraging Reuse

假设您想在play或playbook中重复使用任务列表。 您可以使用include文件来执行此操作。 使用include的任务列表是定义系统将要实现的角色的好方法。 请记住，playbook中play的目标是将一组系统映射到多个角色。 让我们看看这是什么样子

一个task include 文件只包含一个平面的任务列表，如下所示：

---

# possibly saved as tasks/foo.yml

 - name: placeholder foo

   command: /bin/foo

 - name: placeholder bar

   command: /bin/bar

include指令看起来像这样，并且可以混合在一个playbook中的常规任务：

tasks:

  - include: tasks/foo.yml

您也可以将变量传递给include。 我们称之为“参数化include”。
例如，要部署到多个wordpress实例，我可以将所有我的wordpress任务封装在一个wordpress.yml文件中，并使用如下所示：

tasks:
  - include: wordpress.yml wp_user=timmy
  - include: wordpress.yml wp_user=alice
  - include: wordpress.yml wp_user=bob

从1.0开始，变量也可以使用替代语法传递到包含文件，这也支持结构化变量：

tasks:

  - include: wordpress.yml
    vars:
        wp_user: timmy
        ssh_keys:
          - keys/one.txt
          - keys/two.txt


使用任何一种语法，然后可以在包含的文件中使用传入的变量。 我们将在变量中介绍它们。 你可以这样引用它们：

  {{ wp_user }}
（除了明确传递的参数之外，vars部分中的所有变量也可以在这里使用。）

include也可以在'handler'部分使用，例如，如果你想定义如何重新启动apache，你对所有的Playbook只做一次。 你可能会制作一个看似如下的handlers.yml：

---
# this might be in a file like handlers/handlers.yml
- name: restart apache
  service: name=apache state=restarted

而在你的main Playbook文件中，只要把它include进来，放到play的底部：

handlers:
  - include: handlers/handlers.yml


您可以将include与您的常规未包含的task和handler一起混合。

include也可用于将一个play文件导入另一个。 这允许您定义由其他playbook组成更高级的playbook。

例如：

- name: this is a play at the top level of a file
  hosts: all
  remote_user: root

  tasks:

  - name: say hi
    tags: foo
    shell: echo "hi..."

- include: load_balancers.yml
- include: webservers.yml
- include: dbservers.yml


注意，当在一个playbook中include另一个时，不能进行变量替换。

Dynamic versus Static Includes

在“Ansible2.0”中，对“task” include 的内容进行了修改。 “play” include 仍然是“static”或不变。

在以前的Ansible版本中，所有的内容都作为预处理器声明，并在Playbook解析时被读取。 这样就会在包含的文件名中使用诸如库存变量（如分组和主机变量，在分析时间内不可用）等问题。

在Ansible 2.0之后，'task'include可以是'动态'，这意味着在播放执行过程中到达include任务之前，它们不被评估。 此更改允许在include语句中重新引入循环，例如：

  - include ： foo.yml param = {{ item }}
   with_items ：
   - 1
   - 2
   - 3

也可以使用动态包含的任何源的变量：

- include: "{{inventory_hostname}}.yml"

从2.1开始，Ansible尝试检测“task” include何时应该是动态的（请看下面的详细信息，了解检测如何工作）。

动态include引入了一些其他限制，因为在play执行期间到达该任务之前，不会读入include的文件。 使用动态include时，请牢记以下限制：

• 您不能使用notify来触发来自动态include的处理程序名称。
• 您不能使用--start-at-task在动态include内的--start-at-task中开始执行。
• 仅存在于动态include中的标签将不会显示在列表标签​​输出中。
• 仅在动态include中存在的任务不会显示在-list-tasks输出中。

为了解决这些限制，Ansible 2.1引入了include的static选项：

- include: foo.yml
  static: <yes|no|true|false>


默认情况下，从Ansible 2.1开始，当include满足以下条件时，“task”include自动被视为静态而不是动态的

• include不使用任何循环
• include的文件名不使用任何变量
• static选项没有明确禁用（ static: no不存在）
• 强制静态include的ansible.cfg选项（见下文）被禁用

ansible.cfg配置中有两个选项可用于静态include：

• task_includes_static - 强制所有include的任务部分都是静态的。
• handler_includes_static - 强制所有include的处理程序部分都是静态的。

这些选项允许用户强制Playbook的行为与1.9.x和之前完全一样。

“静态”vs“动态”行为如何影响您的任务的一个例子：

- include: "stuff.yml"
  static: no
  when: verto is defined

如果这个任务是“静态的”，那么什么时候被包含的任务所继承，但是强制它是动态的，那么现在什么时候应用于包含任务本身。

Roles

New in version 1.2.

现在你已经了解了任务和处理程序，组织你的剧本的最好方式是什么？ 简单的答案是使用角色！ 角色是基于已知文件结构自动加载某些vars_files，任务和处理程序的方法。 按角色分组内容还可以轻松地与其他用户共享角色。

角色只是围绕'include'指令自动化，如上所述，除了对引用文件的搜索路径处理进行一些改进之外，真的不包含太多额外的魔法。 但是，这可以是一件大事！

示例项目结构：

site.yml
webservers.yml
fooservers.yml
roles/
   common/
     files/
     templates/
     tasks/
     handlers/
     vars/
     defaults/
     meta/
   webservers/
     files/
     templates/
     tasks/
     handlers/
     vars/
     defaults/
     meta/

在一个playbook中，它将如下所示：

---
- hosts: webservers
  roles:
     - common
     - webservers

这为每个角色“x”指定了以下行为：

• 如果roles/ x / tasks / main.yml存在，其中列出的任务将添加到play中
• 如果roles/ x /处理程序/ main.yml存在，列出的处理程序将被添加到play中
• 如果roles/ x / vars / main.yml存在，其中列出的变量将被添加到play中
• 如果roles / x / defaults / main.yml存在，其中列出的变量将被添加到play中
• 如果roles / x / meta / main.yml存在，其中列出的任何角色依赖将被添加到角色列表（1.3和更高版本）
• 任何副本，脚本，模板或包含任务（在角色中）都可以引用roles/ x / {文件，模板，任务} /（目录取决于任务）中的文件，而不必相对或绝对地路径

在Ansys 1.4及更高版本中，您可以配置一个roles_path来搜索角色。 使用它来检查所有常见角色到一个位置，并在多个playbook项目之间轻松分享它们。 有关如何在ansible.cfg中进行设置的详细信息，请参阅配置文件 。

如果任何文件不存在，它们将被忽略。 例如，一个没有'vars /'子目录的角色是可以的。

请注意，您仍然可以在不使用角色的情况下将任务，vars_files和处理程序“松散”列入剧本，但角色是一个很好的组织功能，并被强烈推荐。 如果剧本中有松散的东西，首先评估角色。

此外，如果您希望参数化角色，通过添加变量，您可以这样做：

---

- hosts: webservers
  roles:
    - common
    - { role: foo_app_instance, dir: '/opt/a',  app_port: 5000 }
    - { role: foo_app_instance, dir: '/opt/b',  app_port: 5001 }

虽然这可能不是您经常应该做的事情，但您也可以有条件地使用如下角色：

---

- hosts: webservers
  roles:
    - { role: some_role, when: "ansible_os_family == 'RedHat'" }

这通过将条件应用于角色中的每个任务来起作用。 条件稍后将在文档中介绍。

最后，您可能希望为您指定的角色分配标签。 你可以这样内联：

---

- hosts: webservers
  roles:
    - { role: foo, tags: ["bar", "baz"] }

请注意，此标记将使用指定的标记标记该角色中的所有任务 ，覆盖角色中指定的任何标记。 如果您发现自己构建了许多标签的角色，并且希望在不同时间调用角色的子集，那么您应该考虑将该角色分解为多个角色。
如果play仍然有“task”部分，这些任务在应用角色后执行。

如果要在应用角色之后定义某些任务发生在AND之前，您可以执行以下操作：

---

- hosts: webservers

  pre_tasks:
    - shell: echo 'hello'

  roles:
    - { role: some_role }

  tasks:
    - shell: echo 'still busy'

  post_tasks:
    - shell: echo 'goodbye'

Role Default Variables

1.3版新功能

角色默认变量允许您为include或依赖的角色设置默认变量（见下文）。 要创建默认值，只需在您的角色目录中添加一个defaults / main.yml文件。

这些变量将具有可用的任何变量的最低优先级，并且可以容易地被任何其他变量覆盖，包括库存变量。

Role Dependencies

1.3版新功能

角色相关性允许您在使用角色时自动拉入其他角色。 角色依赖关系存储在包含在角色目录中的meta / main.yml文件中。 此文件应包含要在指定角色之前插入的角色和参数列表，例如role / myapp / meta / main.yml中的以下内容 ：

---
dependencies:
  - { role: common, some_parameter: 3 }
  - { role: apache, apache_port: 80 }
  - { role: postgres, dbname: blarg, other_parameter: 12 }

角色依赖也可以指定为完整路径，就像顶级角色一样：

---
dependencies:
   - { role: '/path/to/common/roles/foo', x: 1 }

角色依赖关系还可以从源代码控制repos或tar文件（通过galaxy ）使用逗号分隔格式的路径，可选版本（标签，提交，分支等）和可选的友好角色名称（尝试导出角色名称从repo名称或归档文件名）。 通过命令行或通过require.yml传递给ansible-galaxy。
角色依赖性始终在包含它们的角色之前执行，并且是递归的。 默认情况下，角色也只能作为依赖关系添加一次 - 如果另一个角色也将其列为依赖关系，则不会再次运行。 可以通过向meta / main.yml文件添加allow_duplicates ：yes来覆盖此行为。 
例如，名为“car”的角色可以向其依赖关系添加名为“wheel”的角色，如下所示：

---
dependencies:
- { role: wheel, n: 1 }
- { role: wheel, n: 2 }
- { role: wheel, n: 3 }
- { role: wheel, n: 4 }


而用于wheel的meta / main.yml包含以下内容：

---
allow_duplicates: yes
dependencies:
- { role: tire }
- { role: brake }

所产生的执行顺序如下：

tire(n=1)
brake(n=1)
wheel(n=1)
tire(n=2)
brake(n=2)
wheel(n=2)
...
car

Embedding Modules and Plugins In Roles

这是一个与大多数用户不相关的高级主题。

这是一个与大多数用户不相关的高级主题。

如果您编写自定义模块（请参阅开发模块 ）或插件（请参阅开发插件 ），则可能希望将其作为角色的一部分进行分发。 一般来说，Ansible作为一个项目非常有兴趣将高质量的模块引入到可插拔的核心中，所以这不应该是规范，但很容易做到。

一个很好的例子是，如果您在一家名为AcmeWidgets的公司工作，并写了一个内部模块，帮助您配置内部软件，并希望组织中的其他人轻松使用此模块，但您不想告诉大家如何配置其可执行库路径。

除了角色的“任务”和“处理程序”结构之外，还添加一个名为“library”的目录。 在这个'库'目录中，直接在其中包含模块。

假设你有这个：

roles/
   my_custom_modules/
       library/
          module1
          module2

该模块将可用于角色本身以及此角色之后调用的任何角色，如下所示：

- hosts: webservers
  roles:
    - my_custom_modules
    - some_other_role_using_my_custom_modules
    - yet_another_role_using_my_custom_modules

在某些限制下，还可以使用Ansible核心分发中的模块进行修改，例如在生产版本发布之前使用模块的开发版本。 然而，这并不总是可取的，因为API签名可能在核心组件中发生变化，但并不总是保证工作。 

对于核心模块来说，它可以是一个方便的补丁，但是如果你有这个好的理由。 自然，该项目倾向于通过拉动请求将贡献引导回github。

可以使用相同的机制将插件嵌入和分配到角色中，并使用相同的模式。 例如，对于过滤器插件：

roles/
   my_custom_filter/
       filter_plugins
          filter1
          filter2
然后可以在模板或jinja模板中使用任何角色“my_custom_filter”