如何使用 Ansible 编写过程文档

在 Ansible 中，文档就是 playbook，因此文档自然会随着代码一起演变

We don't make software for free, we make it for freedom

图片来源

Opensource.com

“文档是写给未来的自己的情书。” —Damian Conway

我使用 Ansible 作为我的个人笔记本，用于记录编码过程——包括我经常使用的和很少使用的过程。这个过程简化了我的工作，并减少了执行重复性任务所需的时间，这些任务需要按特定顺序执行特定命令才能完成特定结果。

通过使用 Ansible 编写文档，我不需要记住每个命令的所有参数或特定过程所涉及的所有步骤，并且很容易与我的团队成员分享细节。

传统的文档编写方法，如维基或共享驱动器，对于通用文档很有用，但不可避免地会过时，并且无法跟上基础设施和环境的快速变化。对于特定过程，最好使用像 Ansible 这样的工具直接在代码中编写文档。

Ansible 的优势

在我们开始之前，让我们回顾一下一些基本的 Ansible 概念：playbook 是使用 play 对过程的高级组织；play 是针对一组主机的特定过程；task 是特定操作，module 是代码单元，inventory 是受管节点的列表。

Ansible 的最大优势在于文档本身就是 playbook，因此它会随着代码一起演变并包含在代码内部。这不仅有用，而且也很实用，因为使用 Ansible 不仅仅是记录解决方案，您还可以编写一个 playbook，允许您编写过程和命令，重现它们并自动执行它们。这样，您可以在六个月后回顾，并能够快速理解并再次执行它们。

诚然，这种解决问题的方式起初可能会花费更多时间，但从长远来看肯定会节省大量时间。通过勇敢而有纪律地采用这些新习惯，您将在每次迭代中提高您的技能。

以下是一些其他重要的元素和支持工具，可以简化您的流程。

使用源代码控制

“先做到，然后做好，然后做得更好。” —Addy Osmani

在使用 Ansible playbook 时，实施 playbook 即代码策略非常重要。实现这一目标的一个好方法是使用源代码控制存储库，该存储库允许您从一个简单的解决方案开始并迭代以改进它。

当您与其他开发人员协作、恢复以前的版本以及备份您的工作时，源代码控制存储库提供了许多优势。但在创建文档时，它的主要优势在于您可以获得关于您正在做什么的可追溯性，并且可以围绕小的更改进行迭代以改进您的工作。

最流行的源代码控制系统是 Git，但还有其他系统，例如 Subversion、Bazaar、BitKeeper 和 Mercurial。

记住幂等性

在基础设施自动化中，幂等性是指达到一个特定的最终状态，无论执行该过程多少次，该状态都保持不变。因此，当您准备自动化您的过程时，请记住期望的结果，并编写能够始终如一地实现这些结果的脚本和命令。

这个概念存在于大多数 Ansible 模块中，因为在您指定所需的最终状态后，Ansible 将实现它。例如，有用于创建文件系统、修改 iptables 和管理 cron 条目的模块。默认情况下，所有这些模块都是幂等的，因此您应该优先考虑使用它们。

如果您使用一些较低级别的模块，例如 command 或 shell，或者开发自己的模块，请注意编写具有幂等性的代码，并且可以安全地重复多次以获得相同的结果。

当您准备用于自动化的过程时，幂等性概念非常重要，因为它允许您评估几种方案并合并那些将使您的代码更安全并创建一个指向所需结果的抽象级别的方案。

测试它！

测试您的部署工作流程可以在您的代码到达生产环境时减少意外情况的发生。Ansible 认为您不需要另一个框架来验证基础设施中的基本内容是正确的。但您的重点应该是应用程序测试，而不是基础设施测试。

Ansible 的文档提供了几种用于您的过程的测试策略。对于测试 Ansible playbook，您可以使用 Molecule，它旨在帮助开发和测试 Ansible 角色。Molecule 支持使用多个实例、操作系统/发行版、虚拟化提供程序、测试框架和测试场景进行测试。这意味着 Molecule 将运行所有测试步骤：linting 验证、检查 playbook 语法、构建 Docker 环境、针对 Docker 环境运行 playbook、再次运行 playbook 以验证幂等性，以及清理所有内容。使用 Molecule 测试 Ansible 角色是对 Molecule 的一个很好的介绍。

运行它！

运行 Ansible playbook 会创建以不友好且难以阅读的方式格式化的日志。在这些情况下，Ansible Run Analysis (ARA) 是运行 Ansible playbook 的一个很好的补充工具，因为它提供了一个直观的界面来浏览它们。阅读使用 ARA 分析 Ansible 运行了解更多信息。

请记住使用 Ansible Vault 保护您的密码和其他敏感信息。Vault 可以加密二进制文件、group_vars、host_vars、include_vars 和 var_files。但是当您以 -v（详细）模式运行 playbook 时，此加密数据会暴露，因此最好将其与关键字 no_log 设置为 true 结合使用，以隐藏任何任务的信息，因为它指示不应记录或显示参数的值。

一个基本示例

您是否需要连接到服务器以生成报告文件并将文件复制到另一台服务器？或者您是否需要大量的特定参数才能连接？也许您不确定在哪里存储这些参数。或者您的过程是否花费很长时间，因为您需要从多个来源收集所有参数？

假设您有一个网络拓扑，其中有一些限制，并且您需要将文件从您可以访问的服务器 (server1) 复制到由第三方 (server2) 管理的另一台服务器。连接参数为

Source server: server1
Target server: server2
  Port: 2202
  User: transfers
  SSH Key: transfers_key
  File to copy: file.log
  Remote directory: /logs/server1/

在这种情况下，您需要连接到 server1 并使用这些参数复制文件。您可以使用单行命令来完成此操作

ssh server1 "scp -P 2202 -oUser=transfers -i ~/.ssh/transfers_key file.log server2:/logs/server1/"

现在您的 playbook 可以执行该过程了。

有用的组合

如果您生成大量的 Ansible playbook，您可以使用其他工具（如 AWX (Ansible Works Project)）来组织所有过程，AWX 提供了一个基于 Web 的用户界面、一个 REST API 和一个构建在 Ansible 之上的任务引擎，以便用户可以更好地控制他们在 IT 环境中使用 Ansible 项目。

其他有趣的组合是 Ansible 与 Rundeck，后者将过程作为自助服务作业提供，以及 Jenkins 用于持续集成和持续交付过程。