首页 > 代码库 > Ansible Playbook Roles and Include Statements
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”
Ansible Playbook Roles and Include Statements