你会写DevOps的文档吗？
本帖最后由 monicazhang 于 2018-8-23 14:53 编辑每个DevOps都一个百宝箱，里面放着各种命令行脚本，可以用来自动化各式任务。但若文档不全，即便是脚本的作者，时间一久也不敢随便乱用，毕竟运维的大部分工作是管理生产环境，要是出了错，不是轻描淡写就可以蒙混过关的。写好 DevOps 的文档其实也是一门技术活儿，这里给大家分享一些组织运维脚本及其文档的经验。
Fabric的任务管理与文档
在以前的文章中，我们曾经介绍过Glow使用了fabric来执行各种日常管理的任务。Fabric提供了非常好用的任务组织以及查阅任务文档的功能。
Fabric的主文件一般命名为fabfile.py，但任务多了，都写在一个文件里显然很难维护。Fabric有一个很实用的特性，就是当fabfile.py里导入其他模块时，会自动发现里面的fabric任务。利用这个特性，可以把各种任务分类写在不同的模块中，然后在fabfile.py中统一导入。比如 Glow 的 DevOps 代码库的结构大概长这个样子：
$ tree
├── __init__.py
├── fabfile.py
├── fab_scripts
│ ├── __init__.py
│ ├── monitors.py
│ ├── mysql.py
│ ├── nginx.py
│ ├── redis.py
│ ├── scaling.py
│ ├── services.py
在fabfile.py里除了一些最核心的任务脚本外，主要就是一些import语句
# fabfile.pyfrom fab_scripts import monitors
from fab_scripts import mysql
from fab_scripts import nginx
from fab_scripts import redis
from fab_scripts import scaling
from fab_scripts import services
这样我们就把散落在多个文件里的任务聚集到了一起，我们可以用fab -l来列出所有可执行的任务及其描述，其中任务描述来自于对应任务的第一行docstring。例如，
$ fab -lAvailable commands: monitors.get Get YAML definition of monitors monitors.list List names of all monitors monitors.mute Mute specific groups of monitors monitors.mute_all Mute all monitors globally monitors.unmute Unmute specific groups of monitors monitors.unmute_all Unmute all monitors globally mysql.connection_list Show number of DB connections group by host mysql.connection_sources Show number of DB connections group by process nginx.turn_off_maintenanceTurn off site maintenance mode. nginx.turn_on_maintenance Turn on site maintenance mode. Return 503. redis.auto_save Update saving settings for redis instances redis.start_slave Set master and start replication. redis.stop_slave Stop replication and set its master to none. scaling.add_servers Launch more instances in specific server group scaling.create_image Create an image for provisioning new instances scaling.get_latest_tag Get latest tag of deployed code services.cycle Restart application services. services.start Start application services. services.stop Stop application services.
这里可以看到，将任务分写在不同的模块，模块名就起到了Namespace的作用。在显示命令列表时，在同一个Namespace下的命令被聚集到了一起，很好地起到了任务分类的作用。使用fab -d 可以显示该任务完整的docstring。规整的docstring可以让执行任务的用户清楚地理解其作用及参数用法。我们在写fabric任务的docstring时，一般分为三个部分
[*]任务的简单介绍
[*]任务的参数
[*]具体用例
最后一点由为重要，有些任务参数众多，即使读了参数说明，仍会让人有些云里雾里。但几个典型的实际用例，对于用户了解任务的用法会起到至关重要的作用。在下面的例子中，我们展示了deploy任务（代码部署）的说明文档
$ fab -d deploy
Displaying detailed information for task 'deploy':
Deploy code to targeted server_group.
You need put ansible vault password at ~/.ansible_vault_passwd directory,
otherwise you would be prompt to enter vault password.
Args:
server_group: Possible values include prod, stage
release_tags: A list of release tags to be pushed
Examples: # Deploy to stage
fab deploy:stage,glow_stage_1446102452 # Deploy to production
fab deploy:prod,glow_prod_1446102452 # Deploy multiple repo at once
fab deploy:prod,glow_prod_1446102452,nurture_prod_1445102467
动态Docstring
在Python中，docstring其实就是函数的__doc__的属性，所以我们可以像修改普通变量那样动态修改docstring，这给我们生成动态文档或是重用公共的文档提供了可能。例如，我们的services模块下有cycle,start,stop三个任务，分别用来重启，开始，停止我们的microservice。我们当然希望在用fab -d来查看任务的文档说明时，同时可以显示所有可用的microservice。但hard-coded现有的microservice是一个愚蠢的做法，这样我们不但需要把同一段文档复制三份，并且每次新增一个microservice时还要记得来更新文档。这里我们用Python的decorator来动态地把可用服务的信息添加到docstring中。比如cycle任务的定义是这样的：
@task@services_docdef cycle(*services, **kwargs):
"""Restart application services.
Args:
services: list of services need cycle (separate by comma)
Examples:
fab services.cycle:glow-www,glow-forum
"""
注意到这里用了@service_doc这个decorator，它的定义如下：
def services_doc(func):
services = get_available_services()
doc = """
Possible values for services:
{}
""".format(" ".join(" " * 8 + x for x in services))
func.__doc__ += doc return func
我们通过get_available_services来动态取得当前环境下可用的microservice（这里我们不关心get_available_service是如何实现的），并将其添加到函数的docstring之后。这样，当我们查看cycle的方法时，所有可用的microservice也会显示出来。
$ fab -d services.cycleDisplaying detailed information for task 'services.cycle': Restart application services Args: services: list of services need cycle (separate by comma) Examples: fab services.cycle:glow-www,glow-forum Possible values for services: glow-www glow-user glow-forum ...
动态外部文档
除了docstring，我们也经常需要写独立的外部文档。在Glow，这些文档绝大部分都是用Markdown来写的。例如，我们需要写一个介绍生产环境架构的文档，其中肯定会加入生产环境中有哪些服务器，每个服务器的功能描述以及它们的hostname。我们可以用手动的方式来写，但每当为生产环境添加新服务器时，我们必须记得更新这份文档。
而实际情况是，我们从来不在AWS的控制台手动创建服务器，所有的服务器都是由Ansible来创建与维护的。也就是说，所有的服务器配置信息及其功能描述都已经存在于Ansible的playbook中。当我们写外部文档时，应该去引用Ansible中的信息，而不是重写手写一遍。
所以在我们的生产环境文档中会利用HTML注释来指定需要外部引用的部分，然后通过执行脚本将这些引用的内容填充至文档里。例如，在我们的生产环境文档中有这样一段：
## EC2 servers<!-- BEGIN EC2-SERVER-LIST -->| Server group | Instance type | Count | Description |
|:-------------|:--------------|------:|:----------------------|
| bastion | t2.small | 1 | Bastion/Jumper server |
| www | c3.large | 4 | Web servers |
...<!-- END EC2-SERVER-LIST -->
这里<!-- BEGIN EC2-SERVER-LIST -->和<!-- END EC2-SERVER-LIST -->之间的表格就是一个外部引用，每次Ansible更新服务器配置时，会执行一个脚本，它会自动在文档中查找这对标签，并更新其中的内容。这是一个很简单的技术，但对于保持文档与实际环境同步很有帮助。
原创：叶剑烨
页:
[1]