Sign in Subscribe
devops

写好DevOps的文档

叶剑烨

• 7 min read

每个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.py
from 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 -l
Available 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_maintenance  Turn 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 [task_name]可以显示该任务完整的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_doc
def 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("\n".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.cycle
Displaying 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更新服务器配置时，会执行一个脚本，它会自动在文档中查找这对标签，并更新其中的内容。这是一个很简单的技术，但对于保持文档与实际环境同步很有帮助。

小结

几乎所有人都承认文档的重要性，但真正愿意在文档上花费精力的团队却十分有限。写这篇文章是希望大家能意识到，文档其实也是代码的一部分，也应该遵循DRY原则，也可以通过编程的手段来动态生成与自动更新。

如果各位对这种文档与代码结合的概念有兴趣，你也许听过Literate programming，那Literate programming与DevOps结合会是什么样子，有兴趣的可以看看这个视频（别问我为何你打不开）。