转自:https://container-solutions.com/write-terraform-provider-part-1/

This is the first part of a series of blog posts that explain how to write Terraform providers.

Before we start I would like to state that this article asumes a couple of things from you:

  1. You have (some) experience with Terraform, the different provisioners and providers that come out of the box,
    its configuration files, tfstate files, etc.
  2. You are comfortable with the Go language and its code organization.

Because bootstrapping a Terraform provider can take some effort feel free to clone this Github repository to use it as your Terraform provider/plugin skeleton. It’ll also help you go along with all the steps that we will mention later on.


Let’s say that you want to write a Terraform provider for your awesome (cloud) provider. In practice, your Terraform configuration file would look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
provider"awesome"{
  api_key     ="securetoken=="
  endpoint    ="https://api.example.org/v1"
  timeout     =60
  max_retries=5
}
 
resource"awesome_machine""speedy-server"{
  name="speedracer"
  cpus=4
  ram  =16384
}
 

So, your provider called awesome supports four different fields:

  • api_key
  • endpoint
  • timeout
  • max_retries

You also want to have your own resource called machine (notice here that because of the way Terraform works your resource name is prefixed with the name of your provider, hence awesome_machine and not just machine) which supports the following fields:

  • name
  • cpus
  • ram

Where to start?

Start by calling plugin.Serve, passing along a “provider” function that returns a terraform.ResourceProvider.

1
2
3
4
5
6
7
func main(){
  opts:=plugin.ServeOpts{
    ProviderFunc:Provider,// Read on to find the definition of this "Provider" function.
  }
  plugin.Serve(&opts)
}
 

Then define a function that returns an object that implements the terraform.ResourceProvider interface, specifically a schema.Provider:

1
2
3
4
5
6
7
8
func Provider()terraform.ResourceProvider{
  return&schema.Provider{
    Schema:        map[string]*schema.Schema{...},
    ResourcesMap:  map[string]*schema.Resource,
    ConfigureFunc:func(*schema.ResourceData)(interface{},error){...},
  }
}
 

This schema.Provider struct has three fields:

  • Schema: List of all the fields for your provider to work. Things like access tokens, log levels, endpoints, region, etc.
    The value of this field is a map[string]*schema.Schema, or in Spanish: a linked list where the key is a string and the value is a pointer to a schema.Schema.
    A minimalistic example schema would look like this:

    1
    2
    3
    4
    5
    6
    7
    8
    map[string]*schema.Schema{
      "api_key":&schema.Schema{
        Type:        schema.TypeString,
        Required:    true,
        Description:"Some short description here."
      }
    }
     

    Here we are saying that api_key is our configuration field in our configuration file; we are also specifying its type (schema.TypeString and not just string as this is required for Terraform to perform some validations when parsing the configuration file); we are also saying that is a required field: if the user does not specify a value for this field in the configuration file Terraform will throw an error and stop execution. Finally we add a short description to the field. There are more configuration options that can be specified for a schema field. You can see the complete list of fields of this struct here.

  • ResourcesMap: List of resources that you want to support in your Terraform configuration file. For example, if we were writing a Terraform provider for AWS and we wanted to support S3 buckets, Elastic Balancers and EC2 instances this is the place where you want to declare those resources.
    The value for this field is a map[string]*schema.Resource, similar to the one of the Schema field, the difference being that this list points to schema.Resource. Let’s take a look at one of the resources from the skeleton:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    map[string]*schema.Resource{
      "awesome_machine":&schema.Resource{
        Schema:map[string]*schema.Schema{
          "name":&schema.Schema{
            Type:     schema.TypeString,
            Required:true,
          },
        },
        SchemaVersion:1,
        Create:        func(d *schema.ResourceData,metainterface{}){},
        Read:          func(d *schema.ResourceData,metainterface{}){},
        Update:        func(d *schema.ResourceData,metainterface{}){},
        Delete:        func(d *schema.ResourceData,metainterface{}){},
      },
    }
     

    What we are doing here is until now pretty straight forward: we are declaring a list of resources. Each resource declaration has its own structure which is made out of a schema.Schema (we saw this already in the previous example when configuring the schema.Provider) and you probably also noticed that there are also a couple more fields like the SchemaVersion but I want to draw your attention specially towards the CreateReadUpdate & Delete ones. These are the four operations that Terraform will perform over the resources of your infrastructure and they will be called according to the case for each resource. This means that if you are creating four resources the Create function will be called four times. The same applies for the rest of the cases.
    The signature for these functions is func(*ResourceData, interface{}).
    The ResourceData type will provide you with some goodies for getting the values from the configuration file:

    • Get(key string): fetches the value for the given key. If the given key is not defined in the structure it will return nil. If the key has not been set in the configuration file then it will return the key’s type’s default value (0 for integers, “” for strings and so on).
    • GetChange(key string): Returns the old and new value for the given key.
    • HasChange(key string): Returns whether or not the given key has been changed.
    • SetId(): Sets the id for the given resource. If set to blank then the resource will be marked for deletion.

    It also offers a couple more methods (GetOkSetConnInfoSetPartial) that we won’t cover on this post.

    The second argument passed to the CRUD functions will be the value returned by your ConfigureFunc of your schema.Provider.
    Following our example, meta in this case can be safely casted to our ExampleClient like this:

    1
    2
    client:=meta.(*ExampleClient)
     

    Let’s now take a look at the createFunc source:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    func createFunc(d *schema.ResourceData,metainterface{})error{
      client:=meta.(*ExampleClient)
      machine:=Machine{
        Name:d.Get("name").(string),
        CPUs:d.Get("cpus").(int),
        RAM:  d.Get("ram").(int),
      }
     
      err:=client.CreateMachine(&machine)
      iferr!=nil{
        returnerr
      }
     
      d.SetId(machine.Id())
     
      returnnil
    }
     

    As mentioned before we know that meta is indeed a pointer to our ExampleClientso we cast it. The client offers a CreateMachine method which receives a pointer to a Machine object, so we initialize that object populating its fields with the values that the user put in the configuration file using the Get method of the ResourceData that has been passed to our function. Then we perform the client.CreateMachine call, passing along the machine that we declared before. After that we check for errors and make an early return in case that something went wrong with the creation of the machine. Finally, if everything went fine we will make a call to SetId. This not only sets the resource ID in the tfstate file but also tells Terraform that the resource was successfully created.
    For updating resources leverage the HasChange and GetChange functions. I will leave the implementation to your imagination and awesome software development capabilities.
    It is important also to mention that if at any point you set your resource id to blank Terraform will understand that the resource no longer exists. This is convenient, for example, when you want to synchronize your remote state with your local state (when a resource has been removed remotely). This is a common task for the readFunc function.

  • ConfigureFunc: Make use of this function when you need to initialize some client with the credentials defined in the Schema part. You can find its signature here.

Any other example?

Check the skeleton project. I recommend you use it for when you’re starting fresh with a new Terraform provider. Another good place to look for examples of complex use cases is the builtin providers that come along with Terraform.

Unit tests

When it comes to unit testing I suggest that you leave your Terraform provider as lightweight as possible. In the cases that we have worked on here at Container Solutions we have all the business logic in the client libraries (check for instance this Cobbler clientlibrary that we wrote) and has so far worked charms for us. Perhaps your use case is different. Perhaps not. Drop me a line either in the comments sections or on Twitter (@mongrelion). I would love to hear from you regarding this specific matter.

Final notes

This is not a full-grown Terraform provider. Far from it. But it will help you get started. Most of the documentation is in Terraform’s source code which can be tricky at first to browse around. This is a small effort to gather some of the basic concepts to reduce the barrier and help other developers get started as quick as possible. And again, as stated in the beginning of this article, this is only the first part of a series of upcoming blog posts that will talk more about Terraform providers.

Some of the things that we want to talk about in the future are:

  • Partial state (or how to recover from faulty resource modification)
  • More complex schema definitions
  • How to run callbacks once all your resources have been created/updated/deleted

And possibly much more. Leave a comment if there is anything else that you would like us to cover on these series and thanks for reading!

 
 
 
 

Write your own Terraform provider: Part 1的更多相关文章

  1. 京东云携手HashiCorp,宣布推出Terraform Provider

    2019年4月23日消息,京东云携手云基础设施自动化软件的领导者HashiCorp,宣布推出Terraform Provider for JD Cloud,这意味着用户能够在京东云上轻松使用简单模板语 ...

  2. terraform plugin 版本以及changlog 规范

    文章来自官方文章,转自:https://www.terraform.io/docs/extend/best-practices/versioning.html 里面包含了版本命名的规范,以及chang ...

  3. Developer Friendly | 基础设施即代码的事实标准Terraform已支持京东云!

    Developer Friendly | 基础设施即代码的事实标准Terraform已支持京东云! Chef.Puppet.Ansible.SaltStack 都可以称为配置管理工具,这些工具的主要目 ...

  4. 网易云terraform实践

    此文已由作者王慎为授权网易云社区发布. 欢迎访问网易云社区,了解更多网易技术产品运营经验. 一.terraform介绍 随着应用上云的常态化,资源栈动态管理的需求对用户也变得更加急切.资源编排(Res ...

  5. 零基础教程!一文教你使用Rancher 2.3和Terraform运行Windows容器

    本文来自Rancher Labs 介 绍 在Kubernetes 1.14版本中已经GA了对Windows的支持.这一结果凝结了一群优秀的工程师的努力,他们来自微软.Pivotal.VMware.红帽 ...

  6. 干货 | 运维福音——Terraform自动化管理京东云

    干货 | 运维福音--Terraform自动化管理京东云 原创: 张宏伟 京东云开发者社区  昨天 Terraform是一个高度可扩展的IT基础架构自动化编排工具,主张基础设施即代码,可通过代码集中管 ...

  7. Writing Custom Providers

    转自:https://www.terraform.io/docs/extend/writing-custom-providers.html 很详细,做为一个记录 In Terraform, a Pro ...

  8. 云原生之旅 - 6)不能错过的一款 Kubernetes 应用编排管理神器 Kustomize

    前言 相信经过前一篇文章的学习,大家已经对Helm有所了解,本篇文章介绍另一款工具 Kustomize,为什么Helm如此流行,还会出现 Kustomize?而且 Kustomize 自 kubect ...

  9. Terraform 自定义provider 开发

    内容来自官方文档,主要是进行学习自定义provider 开发的流程 开发说明 我们需要开发的有provider 以及resource 对于resource 我们需要进行crud 的处理,同时还需要进行 ...

随机推荐

  1. linux下Mysql多实例实现

    什么是MySQL多实例 MySQL多实例就是在一台机器上开启多个不同的服务端口(如:3306,3307),运行多个MySQL服务进程,通过不同的socket监听不同的服务端口来提供各自的服务:: My ...

  2. Java语法基础学习DayEight

    一.异常处理 1.结构 java.lang.Object |-----java.lang.Throwable |-----java.lang.Error:错误,java程序对此无能为力,不显式处理 | ...

  3. css设置div高度与宽度相等的一种方法

    div.category{ width:33%; padding:33% 0 0; } 1.关键在padding:33% 0 0这句代码,通过设置padding-top与宽度相等(padding使用百 ...

  4. 阻止ARP欺骗

    利用Look N Stop防火墙,防止arp欺骗 阻止网络执法官控制 网络执法官是利用的ARp欺骗的来达到控制目的的. ARP协议用来解析IP与MAC的对应关系,所以用下列方法可以实现抗拒网络执法官的 ...

  5. 安装Cygwin,,以及遇到的问题

    实验需要用到Cygwin,于是去下了一个,安装过程比较顺利,参考:http://blog.csdn.net/chunleixiahe/article/details/55666792 但是发现  ma ...

  6. Spring Boot 揭秘与实战 源码分析 - 工作原理剖析

    文章目录 1. EnableAutoConfiguration 帮助我们做了什么 2. 配置参数类 – FreeMarkerProperties 3. 自动配置类 – FreeMarkerAutoCo ...

  7. JAVA多线程Thread与Runnable

    一.Runnable Runnable为一个之包含一个run方法的接口 public class MyRunnable implements Runnable{ @Override //表示:预示重写 ...

  8. libev

    libev是一个**事件驱动库**,它需要循环探测事件是否发生,在Linux上实际是封装了epoll等系统调用. 其循环过程由ev_loop( )函数设置,循环体是ev_loop结构. //创建事件循 ...

  9. DS18B20读数错误排除

    描述: 同时测试了好几个板子,都接了DS18B20传感器.但,有的板子读取的DS18B20温度值正确,有的读取错误. 原因查找: 以为是有的传感器坏了,但测试后发现并不是. 又以为是DS18B20需要 ...

  10. Refused to execute inline event handler because it violates the following Content Security Policy directive: "xxx". Either the 'unsafe-inline' keyword, a hash ('sha256-...'), or a nonce ('nonce-...')

    /********************************************************************************* * Refused to exec ...