本文主要向大家展示如何为阿里云 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...
2、利用 glide 安装依赖(how to install glide)
3、设置环境变量,省去每次测试时输入AK的要求
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为前缀的测试用例的运行:
其中,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:
接着,将主仓库配置为你的remote,如起名为“alicloud”
检查当前仓库的状态
1、Rebasing Your Branch
完成commit和remote配置后,即可进行rebase操作:
如果有冲突,解决冲突后继续 rebase,直到所有冲突都解决,之后再次检查状态:
1、Uploading Your Code
完成rebase操作后,上传代码:
如遇到提交失败,可使用-f 或者--force 来强制提交
1、Submitting Your Pull Request
完成代码上传后,在Github控制台将你的代码提交到主仓库的dev分支,并对PR做一个简单的描述和介绍。
2、Updating Your Pull Request
如果代码有问题,在Review结束后,需要对已提交的代码做修改,首先将上次提交进行回退:
之后,stash并利用rebase下载最新的代码,以避免不必要的冲突:
rebase顺利执行之后,恢复stash代码:
根据review意见,继续修改代码,之后再次进行代码commit,rebase和push即可。
写在最后
本文主要讲述了如何为阿里云的Terraform-Provider贡献代码的一些流程和注意事项,欢迎大家积极加入到Terraform Provider的建设中来,谢谢大家。
本文作者:箫竹aron
本文为云栖社区原创内容,未经允许不得转载。