Terraform 开发指南

本文主要向大家展示如何为阿里云 Terraform Provider 贡献自己的力量,帮助开发者和志同道合的朋友尽快加入到开源生态的建设中来。

本文面向所有的对Terraform熟悉和感兴趣的朋友,如果您还不了解Terraform,快快戳这里。

本文会从环境搭建和开发规范两个方面向大家展示如何开放 terraform provider。

环境搭建

安装 Golang

本地安装go >1.10.0 详见:https://golang.org/dl/

安装 Terraform

本地安装 Terraform > 0.11, 详见: https://www.terraform.io/intr...

安装 Terraform Provider

1、fork 并下载 repo: https://github.com/alibaba/te...

Terraform 开发指南_第1张图片

2、利用 glide 安装依赖(how to install glide)

Terraform 开发指南_第2张图片

3、设置环境变量,省去每次测试时输入AK的要求

clipboard.png

Resource 开发

Resource 开发是根据阿里云的OpenAPI在terraform provider中实现对阿里云产品和资源的插件。

规划和设计

每个Resource的实现不是根据阿里云帮助文档对OpenAPI的简单调用,要对产品的设计,功能以及使用有较深的理解,通常遵循如下设计原则:

1、自管理

每个resource只管理自身的功能,与其他resource引用或者关联交由关系性资源来完成,如ECS instance只管理实例自身的功能,对于挂哪个数据盘,分配哪个EIP交由attachment资源来完成

2、松耦合

对于资源与资源之间的关系,需要单独定义一个逻辑resource,来完成资源与资源之间的关联,如磁盘挂载,eip的挂载,ess与ecs的关联等

3、参数简洁

参数要尽可能简洁,不要有冗余的参数,以RDS instance为例,对于参数zoneId,VpcId以及VSwitchId而言,只需要定义zoneId和VpcId就是冗余参数,因为在调用具体API之前,可以通过vswitchId来获取这两个参数,但某些特殊的场景除外,比如RDS支持Multiple zone,所以zonId也需要保留。如果可以设置Default,最好显示设置。

4、语义清晰

每个参数字段要具有清晰的语义,帮助用户更好的理解。对于一些公共的,统一的参数,如可用区,slb ID,最好跟其他资源保持一致:availability_zone, load_balancer_id.

5、参数校验

有些参数需要做一些简单的校验,提前提醒客户使用正确的可选值。除此之外,对于某些参数,要做diff判断,以自动屏蔽某些不起作用的参数,如:对于ECS而言,选择PostPaid,意味着所有与PrePaid相关的参数 period,period_unit,renewal_status,auto_renew_period都将失效,具体表现为在执行terraform plan的时候,这些参数不会做diff比较。

基本实现

每个Resource需要实现Create,Read,Update,Delete,Import五个功能:

1、Create

调用产品创建API,实现对某个资源的创建,并将resource id 写入到state文件中

如果资源没有ID,比如安全组规则,那么resource要自己按照一定的规则自行实现一个ID,对terraform而言,该ID是resource的唯一标识,后续对resource的所有操作都需要依赖于该ID进行

Create 的实现逻辑要尽可能简单,以成功创建资源为目标,太多的复杂逻辑会降低资源创建的成功率

复杂的功能实现可交由 Update 来完成

Create之后通常调用Update方法来完成更多功能的实现

2、Update

调用产品的Update或Modify API,实现对resource更多功能的支持以及对已有属性的修改

Update之前要打开Partial d.Partial(true),并在每步修改后进行时时更新,如d.SetPartial("bandwidth"),以保证后面的每一步成功的更改都能被及时的写入到state 文件中。

Update 之后,调用 Read 方法,实现对resource 所有属性的展示。

3、Read

调用 Describe 或者 List API,实现对已有资源的查询和写入state

如果找不到指定的资源,要将resource ID标记为“”,以告诉terraform,当前这个资源已经不存在了。

4、Delete

调用Delete API实现对指定资源的删除和释放

为了保证resource成功释放,需要加入retry策略来避免因资源依赖或者异步操作而引起的删除失败问题

通常,resource释放后要再次调用查询API来完成删除操作的验证

5、Import

调用查询API实现对已有资源的导入

通常只需要方法申明,无需多余的实现逻辑,它会借助Read方法来完成对资源的查询和导入

基本工作原理

执行terraform 命令,完成对资源的管理,主要命令包含以下几个:

1、terraform plan

实现对资源的预览。该命令会调用对应资源的Read 方法来获取模板中定义的资源。如果资源尚未创建,及当前目录下的state文件为空,直接展示即将创建的资源,否则展示要变更的资源

2、terrform apply

实现对资源的创建和更新。新资源调用Create,已有资源调用Update完成对资源的修改。

3、terraform destroy

调用Destroy完成对资源的销毁。

3、terraform import

调用Read方法完成对已有资源的导入,将已有资源加入到terraform的管理序列中来。但要注意,由于已有资源不一定是通过terraform创建的,所有导入成功后,记得运行terraform plan进行对比,手动补齐模板。

注意事项

1、阿里云大部分的API都是异步调用的,而且资源与资源之间会因为一些依赖或者状态问题,导致请求调用失败,此时需要通过Retry来保证操作成功率

2、Terraform 的设计理念是对资源终态的管理,通常不涉及对资源状态的管理,所以ECS 创建后要将其置为 Running状态,其他资源也要在达到对应状态后标记创建完成。通常借助 Wait 来保证。

Data Source 开发

Data Source 开发是调用阿里云资源的查询API完成对特定资源的查询和展示。

规划和设计

每个Data Source的实现要根据API的字段和资源属性,为用户提供更好的查询体验,最好可以支持模糊查询。参数设计原则除了与Resource设计原则类似外,还应该提供一个参数output_file来将查询到的结果输出到文件中,供用户参考。

基本实现

每个Data Source只需实现Read方法,该方法用来查询并过滤符合条件的所有的resource,然后将过滤的结果以列表的方式展示出来。在具体实现过程中,需要注意以下几点:

1、每一个data source仍然需要一个唯一的ID来表示当前这个data source。 通常是取所有结果的hash值。

2、对于一些相互依赖性的资源,在展示他们自身功能属性的同时,会将依赖该资源的其他资源一并做一个简单的展示,以免去用户多次查询的麻烦,例如,vswitch的data source,除了展示自身属性外,还将该vswitch下的所有instance的id一并进行了查询。

测试

在完成模块开发后,要对每个resource和data source的功能进行测试,测试的方法是编写对应的测试用例。

测试用例的编写要遵循以下几个原则:

1、测试用例要尽可能覆盖所有的应用场景,尤其对一些主要功能的修改,要使用单独的case

2、测试用例不是完成任务,是每一次功能变更的检验,测试用例也完善,模块的稳定性也高,因为功能的持续更新和迭代必须要保证原有功能的可用。

3、如何运行测试用例

以ECS instance 举例,运行如下的测试命令,可以实现对目录alicloud下所有以TestAccAlicloudInstance为前缀的测试用例的运行:

clipboard.png

其中,timeout 表示这个测试用例运行的超时时长。
如果想要精确到具体的测试用例,补全测试用例的名称即可。

文档
文档是用户使用provider的基础,文档的编写非常重要,需遵循如下几个原则:

1、文档中参数描述要清楚明白,每个参数功能,使用,是否是必填参数,是否支持修改,是否有限定值,是否有默认值,都要显示标明,而且要跟代码中定义的保持一致

2、文档使用纯英文编写,但不是对帮助文档的直接翻译,要根据具体情况和场景做最友好的阅读体验。如果对英文不自信,可参考帮助文档的国际版 https://www.alibabacloud.com/...

3、通常,每个文档都要写一个简单的当前资源的使用实例,以供参考

4、文档的输出参数也要进行说明,而且要跟代码中定义的保持一致

5、如果当前资源支持import功能,文档最后要显示标注,详见其他resource 文档

6、如果当前资源有一些暂时不支持的功能,或者使用上有需要提前注意的地方,要在文档中显示添加Note

7、resource 文档放在目录website/docs/r下,data source 文档放在目录website/docs/d下。每新增一个文档,要修改文件website/alicloud.erb 来完成侧边栏展示

样例

为了更好的帮助用户使用新增的resource,在完成以上工作后,需要为当前的这个resource或者当前这类resource增加一个example,来指导用户编写对应的模板。该样例是一个真实的可运行的模板,通常包含以下四部分:

1、main.tf:资源的定义模板

2、variables.tf:模板所依赖的参数定义和参数值

3、outputs.tf:资源的输出值

4、README.md:模板的简单介绍和使用说明

代码提交

完成了以上功能的实现和代码的编写后,接下来最关键的就是代码的提交,我们的代码最好优先提交到dev分支,具体的步骤分为以下几步:

Commit

为了避免出现代码的错乱,降低review的复杂度,Commit要细化,每一功能点或者一次的修改(不论改动有多小)对应一个Commit。为了防止功能和代码的相互冲突,每个功能点对应一个branch。

Rebase

提交代码前一定要Rebase,具体操作步骤如下:

1、Configuring Your Remotes

Rebase之前,首先需要配置你的Remote,假定你origin 指向了你的fork:

Terraform 开发指南_第3张图片

接着,将主仓库配置为你的remote,如起名为“alicloud”

Terraform 开发指南_第4张图片

检查当前仓库的状态

clipboard.png

1、Rebasing Your Branch

完成commit和remote配置后,即可进行rebase操作:

clipboard.png

如果有冲突,解决冲突后继续 rebase,直到所有冲突都解决,之后再次检查状态:

Terraform 开发指南_第5张图片

1、Uploading Your Code

完成rebase操作后,上传代码:

clipboard.png

如遇到提交失败,可使用-f 或者--force 来强制提交

1、Submitting Your Pull Request

完成代码上传后,在Github控制台将你的代码提交到主仓库的dev分支,并对PR做一个简单的描述和介绍。

2、Updating Your Pull Request

如果代码有问题,在Review结束后,需要对已提交的代码做修改,首先将上次提交进行回退:

clipboard.png

之后,stash并利用rebase下载最新的代码,以避免不必要的冲突:

Terraform 开发指南_第6张图片

rebase顺利执行之后,恢复stash代码:

clipboard.png

根据review意见,继续修改代码,之后再次进行代码commit,rebase和push即可。

写在最后

本文主要讲述了如何为阿里云的Terraform-Provider贡献代码的一些流程和注意事项,欢迎大家积极加入到Terraform Provider的建设中来,谢谢大家。

本文作者:箫竹aron

阅读原文

本文为云栖社区原创内容,未经允许不得转载。

你可能感兴趣的:(运维,系统设计,开源工具,测试)