はじめに
Ansible の公式ドキュメントのページの多くは reStructuredText で書かれていて、Sphinx 経由で出力されています。
人間がブラウザで HTML を表示する分には良いのですが、最近ではより AI に読んでもらいやすいように Markdown でデータを取得したいというニーズもでてきているようです。「人間用ホームページをやめました」という場合もあれば、AWS のドキュメントのようにMarkdown 用のボタンがある場合もありますね。
最近知ったのですが、Ansible のドキュメントのページも Accept: text/markdown を付けてリクエストすると、HTML の代わりに Markdown が返ってくることを知りました。
ちょっと試してみます。
おためし
Reusing Ansible artifacts というページで試します。
curl -H "Accept: text/markdown" https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse.html
以下の Markdown が返ってきました。
クリックしてレスポンスボディ全文を見る
<!DOCTYPE html>
* [Blog](https://www.ansible.com/blog) * [Ansible community forum](https://forum.ansible.com/) * [Documentation](https://docs.ansible.com/) [  Ansible Community Documentation ](https://docs.ansible.com/) * [](https://docs.ansible.com/projects/ansible/latest/index.html) * [Using Ansible playbooks](https://docs.ansible.com/projects/ansible/latest/playbook%5Fguide/index.html) * [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook%5Fguide/playbooks.html) * Reusing Ansible artifacts * [ Edit on GitHub](https://github.com/ansible/ansible-documentation/edit/devel/docs/docsite/rst/playbook%5Fguide/playbooks%5Freuse.rst?description=%23%23%23%23%23%20SUMMARY%0A%3C!---%20Your%20description%20here%20--%3E%0A%0A%0A%23%23%23%23%23%20ISSUE%20TYPE%0A-%20Docs%20Pull%20Request%0A%0A%2Blabel:%20docsite%5Fpr) --- # Reusing Ansible artifacts[](#reusing-ansible-artifacts "Link to this heading") You can write a simple playbook in one very large file, and most users learn the one-file approach first. However, breaking your automation work up into smaller files is an excellent way to organize complex sets of tasks and reuse them. Smaller, more distributed artifacts let you reuse the same variables, tasks, and plays in multiple playbooks to address different use cases. You can use distributed artifacts across multiple parent playbooks or even multiple times within one playbook. For example, you might want to update your customer database as part of several different playbooks. If you put all the tasks related to updating your database in a tasks file or a role, you can reuse them in many playbooks while only maintaining them in one place. ## [Creating reusable files and roles](#id1)[](#creating-reusable-files-and-roles "Link to this heading") Ansible offers four distributed, reusable artifacts: variables files, task files, playbooks, and roles. > * A variables file contains only variables. > * A task file contains only tasks. > * A playbook contains at least one play, and may contain variables, tasks, and other content. You can reuse tightly focused playbooks, but you can only reuse them statically, not dynamically. > * A role contains a set of related tasks, variables, defaults, handlers, and even modules or other plugins in a defined file-tree. Unlike variables files, task files, or playbooks, roles can be easily uploaded and shared through Ansible Galaxy. See [Roles](https://docs.ansible.com/projects/ansible/latest/playbook%5Fguide/playbooks%5Freuse%5Froles.html#playbooks-reuse-roles) for details about creating and using roles. New in version 2.4. ## [Reusing playbooks](#id2)[](#reusing-playbooks "Link to this heading") You can incorporate multiple playbooks into a main playbook. However, you can only use imports to reuse playbooks. For example: - import_playbook: webservers.yml - import_playbook: databases.yml Importing incorporates playbooks in other playbooks statically. Ansible runs the plays and tasks in each imported playbook in the order they are listed, just as if they had been defined directly in the main playbook. You can select which playbook you want to import at runtime by defining your imported playbook file name with a variable, then passing the variable with either `--extra-vars` or the `vars` keyword. For example: - import_playbook: "/path/to/{{ import_from_extra_var }}" - import_playbook: "{{ import_from_vars }}" vars: import_from_vars: /path/to/one_playbook.yml If you run this playbook with `ansible-playbook my_playbook -e import_from_extra_var=other_playbook.yml`, Ansible imports both one\_playbook.yml and other\_playbook.yml. ## [When to turn a playbook into a role](#id3)[](#when-to-turn-a-playbook-into-a-role "Link to this heading") For some use cases, simple playbooks work well. However, starting at a certain level of complexity, roles work better than playbooks. A role lets you store your defaults, handlers, variables, and tasks in separate directories, instead of in a single long document. Roles are easy to share on Ansible Galaxy. For complex use cases, most users find roles easier to read, understand, and maintain than all-in-one playbooks. ## [Reusing files and roles](#id4)[](#reusing-files-and-roles "Link to this heading") Ansible offers two ways to reuse files and roles in a playbook: dynamic and static. > * For dynamic reuse, add an `include_*` task in the tasks section of a play: > > * [include\_role](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/include%5Frole%5Fmodule.html#include-role-module) > * [include\_tasks](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/include%5Ftasks%5Fmodule.html#include-tasks-module) > * [include\_vars](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/include%5Fvars%5Fmodule.html#include-vars-module) > * For static reuse, add an `import_*` task in the tasks section of a play: > > * [import\_role](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/import%5Frole%5Fmodule.html#import-role-module) > * [import\_tasks](https://docs.ansible.com/projects/ansible/latest/collections/ansible/builtin/import%5Ftasks%5Fmodule.html#import-tasks-module) Task include and import statements can be used at arbitrary depth. You can still use the bare [roles](https://docs.ansible.com/projects/ansible/latest/playbook%5Fguide/playbooks%5Freuse%5Froles.html#roles-keyword) keyword at the play level to incorporate a role in a playbook statically. However, the bare [include](https://docs.ansible.com/projects/ansible/2.9/modules/include%5Fmodule.html#include-module "(in Ansible v2.9)") keyword, once used for both task files and playbook-level includes, is now deprecated. ### [Includes: dynamic reuse](#id5)[](#includes-dynamic-reuse "Link to this heading") Including roles, tasks, or variables adds them to a playbook dynamically. Ansible processes included files and roles as they come up in a playbook, so included tasks can be affected by the results of earlier tasks within the top-level playbook. Included roles and tasks are similar to handlers - they may or may not run, depending on the results of other tasks in the top-level playbook. The primary advantage of using `include_*` statements is looping. When a loop is used with an include, the included tasks or roles will be executed once for each item in the loop. The file names for included roles, tasks, and vars are templated before inclusion. You can pass variables into includes. See [Variable precedence: where should I put a variable?](https://docs.ansible.com/projects/ansible/latest/playbook%5Fguide/playbooks%5Fvariables.html#ansible-variable-precedence) for more details on variable inheritance and precedence. ### [Imports: static reuse](#id6)[](#imports-static-reuse "Link to this heading") Importing roles, tasks, or playbooks adds them to a playbook statically. Ansible pre-processes imported files and roles before it runs any tasks in a playbook, so imported content is never affected by other tasks within the top-level playbook. The file names for imported roles and tasks support templating, but the variables must be available when Ansible is pre-processing the imports. This can be done with the `vars` keyword or by using `--extra-vars`. You can pass variables to imports. You must pass variables if you want to run an imported file more than once in a playbook. For example: tasks: - import_tasks: wordpress.yml vars: wp_user: timmy - import_tasks: wordpress.yml vars: wp_user: alice - import_tasks: wordpress.yml vars: wp_user: bob See [Variable precedence: where should I put a variable?](https://docs.ansible.com/projects/ansible/latest/playbook%5Fguide/playbooks%5Fvariables.html#ansible-variable-precedence) for more details on variable inheritance and precedence. ### [Comparing includes and imports: dynamic and static reuse](#id7)[](#comparing-includes-and-imports-dynamic-and-static-reuse "Link to this heading") Each approach to reusing distributed Ansible artifacts has advantages and limitations. You may choose dynamic reuse for some playbooks and static reuse for others. Although you can use both dynamic and static reuse in a single playbook, it is best to select one approach per playbook. Mixing static and dynamic reuse can introduce difficult-to-diagnose bugs into your playbooks. This table summarizes the main differences so you can choose the best approach for each playbook you create. | | Include\_\* | Import\_\* | | ------------------------- | --------------------------------------- | ---------------------------------------- | | Type of reuse | Dynamic | Static | | When processed | At runtime, when encountered | Pre-processed during playbook parsing | | Task or play | All includes are tasks | import\_playbook cannot be a task | | Task options | Apply only to include task itself | Apply to all child tasks in import | | Calling from loops | Executed once for each loop item | Cannot be used in a loop | | Using \--list-tags | Tags within includes not listed | All tags appear with \--list-tags | | Using \--list-tasks | Tasks within includes not listed | All tasks appear with \--list-tasks | | Notifying handlers | Cannot trigger handlers within includes | Can trigger individual imported handlers | | Using \--start-at-task | Cannot start at tasks within includes | Can start at imported tasks | | Using inventory variables | Can include\_\*: {{ inventory\_var }} | Cannot import\_\*: {{ inventory\_var }} | | With playbooks | No include\_playbook | Can import full playbooks | | With variables files | Can include variables files | Use vars\_files: to import variables | Note * There are also big differences in resource consumption and performance, imports are quite lean and fast, while includes require a lot of management and accounting. ## [Reusing tasks as handlers](#id8)[](#reusing-tasks-as-handlers "Link to this heading") You can also use includes and imports in the [Handlers: running operations on change](https://docs.ansible.com/projects/ansible/latest/playbook%5Fguide/playbooks%5Fhandlers.html#handlers) section of a playbook. For example, if you want to define how to restart Apache, you only have to do that once for all of your playbooks. You might make a `restarts.yml` file that looks like: # restarts.yml - name: Restart apache ansible.builtin.service: name: apache state: restarted - name: Restart mysql ansible.builtin.service: name: mysql state: restarted You can trigger handlers from either an import or an include, but the procedure is different for each method of reuse. If you include the file, you must notify the include itself, which triggers all the tasks in `restarts.yml`. If you import the file, you must notify the individual task(s) within `restarts.yml`. You can mix direct tasks and handlers with included or imported tasks and handlers. ### [Triggering included (dynamic) handlers](#id9)[](#triggering-included-dynamic-handlers "Link to this heading") Includes are executed at run-time, so the name of the include exists during play execution, but the included tasks do not exist until the include itself is triggered. To use the `Restart apache` task with dynamic reuse, refer to the name of the include itself. This approach triggers all tasks in the included file as handlers. For example, with the task file shown above: - name: Trigger an included (dynamic) handler hosts: localhost handlers: - name: Restart services include_tasks: restarts.yml tasks: - command: "true" notify: Restart services ### [Triggering imported (static) handlers](#id10)[](#triggering-imported-static-handlers "Link to this heading") Imports are processed before the play begins, so the name of the import no longer exists during play execution, but the names of the individual imported tasks do exist. To use the `Restart apache` task with static reuse, refer to the name of each task or tasks within the imported file. For example, with the task file shown above: - name: Trigger an imported (static) handler hosts: localhost handlers: - name: Restart services import_tasks: restarts.yml tasks: - command: "true" notify: Restart apache - command: "true" notify: Restart mysql See also [Utilities modules](https://docs.ansible.com/projects/ansible/2.9/modules/list%5Fof%5Futilities%5Fmodules.html#utilities-modules "(in Ansible v2.9)") Documentation of the `include*` and `import*` modules discussed here. [Working with playbooks](https://docs.ansible.com/projects/ansible/latest/playbook%5Fguide/playbooks.html#working-with-playbooks) Review the basic Playbook language features [Using variables](https://docs.ansible.com/projects/ansible/latest/playbook%5Fguide/playbooks%5Fvariables.html#playbooks-variables) All about variables in playbooks [Conditionals](https://docs.ansible.com/projects/ansible/latest/playbook%5Fguide/playbooks%5Fconditionals.html#playbooks-conditionals) Conditionals in playbooks [Loops](https://docs.ansible.com/projects/ansible/latest/playbook%5Fguide/playbooks%5Floops.html#playbooks-loops) Loops in playbooks [General tips](https://docs.ansible.com/projects/ansible/latest/tips%5Ftricks/ansible%5Ftips%5Ftricks.html#tips-and-tricks) Tips and tricks for playbooks [Galaxy User Guide](https://docs.ansible.com/projects/ansible/latest/galaxy/user%5Fguide.html#ansible-galaxy) How to share roles on galaxy, role management [Communication](https://docs.ansible.com/projects/ansible/latest/community/communication.html#communication) Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide
なるほどなるほど。願わくば、コードがコードブロックで囲われてるとうれしい気もします。
仕組み
この挙動はどうやらドキュメントホスティング先の Read the Docs 共通のようです。
This feature is powered by Cloudflare.
・・ということで、Cloudflare の Markdown 変換のサービスを利用しているそうです。
便利ですねぇ。
