github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/website/guides/terraform-provider-development-program.html.md (about) 1 --- 2 layout: "extend" 3 page_title: "Terraform Provider Development Program" 4 sidebar_current: "guides-terraform-provider-development-program" 5 description: This guide is intended for vendors who're interested in having their platform supported by Teraform. The guide walks vendors through the steps involved in creating a provider and applying for it to be included with Terraform. 6 --- 7 8 # Terraform Provider Development Program 9 10 The Terraform Provider Development Program allows vendors to build 11 Terraform providers that are officially approved and tested by HashiCorp and 12 listed on the official Terraform website. The program is intended to be largely 13 self-serve, with links to information sources, clearly defined steps, and 14 checkpoints. 15 16 -> **Building your own provider?** If you're building your own provider and 17 aren't interested in having HashiCorp officially approve and regularly test the 18 provider, refer to the [Writing Custom Providers guide][writing] and the 19 [Extending Terraform][extending] section. 20 21 ## What is a Terraform Provider? 22 23 Terraform is used to create, manage, and manipulate infrastructure resources. 24 Examples of resources include physical machines, VMs, network switches, containers, etc. 25 Almost any infrastructure noun can be represented as a resource in Terraform. 26 27 A provider is responsible for understanding API interactions with the underlying 28 infrastructure like a cloud (AWS, GCP, Azure), a PaaS service (Heroku), a SaaS 29 service (DNSimple, CloudFlare), or on-prem resources (vSphere). It then exposes 30 these as resources users can code to. Terraform presently supports more than 31 70 providers, a number that has more than doubled in the past 12 months. 32 33 All providers integrate into and operate with Terraform exactly the same way. 34 The table below is intended to help users understand who develops, maintains 35 and tests a particular provider. 36 37  38 39 -> **Note:** This document is primarily intended for the "HashiCorp/Vendors" row in 40 the table above. Community contributors who’re interested in contributing to 41 existing providers or building new providers should refer to the 42 [Writing Custom Providers guide][writing]. 43 44 ## Provider Development Process 45 46 The provider development process is divided into six steps below. By following 47 these steps, providers can be developed alongside HashiCorp to ensure new 48 providers are able to be published in Terraform as quickly as possible. 49 50  51 52 1. **Engage**: Initial contact between vendor and HashiCorp 53 2. **Enable**: Information and articles to aid with the provider development 54 3. **Dev/Test**: Provider development and test process 55 4. **Review**: HashiCorp code review and acceptance tests (iterative process) 56 5. **Release**: Provider availability and listing on [terraform.io](https://www.terraform.io) 57 6. **Support**: Ongoing maintenance and support of the provider by the vendor. 58 59 ### 1. Engage 60 61 Please begin by providing some basic information about the provider that 62 is being built via a simple [webform](https://goo.gl/forms/iqfz6H9UK91X9LQp2). 63 64 This information is captured upfront and used by HashiCorp to track the 65 provider through various stages. The information is also used to notify the 66 provider developer of any overlapping work, perhaps coming from the community. 67 68 Terraform has a large and active community and ecosystem of partners that 69 may have already started working on the same provider. We'll do our best to 70 connect similar parties to avoid duplicate work. 71 72 ### 2. Enable 73 74 We’ve found the provider development process to be fairly straightforward and simple 75 when vendors pay close attention and follow to the resources below. Adopting 76 the same structure and coding patterns helps expedite the review and release cycles. 77 78 * [Writing custom providers guide][writing] 79 * How-to build a provider [video](https://www.youtube.com/watch?v=2BvpqmFpchI) 80 * Sample provider developed by [partner](http://container-solutions.com/write-terraform-provider-part-1/) 81 * Example providers for reference: [AWS](https://github.com/terraform-providers/terraform-provider-aws), [OPC](https://github.com/terraform-providers/terraform-provider-opc) 82 * Contributing to Terraform [guidelines](https://github.com/hashicorp/terraform/blob/master/.github/CONTRIBUTING.md) 83 * Gitter HashiCorp-Terraform [room](https://gitter.im/hashicorp-terraform/Lobby). 84 85 ### 3. Development & Test 86 87 Terraform providers are written in the [Go](https://golang.org/) programming 88 language. The 89 [Writing Custom Providers guide][writing] 90 is a good resource for developers to begin writing a new provider. 91 92 The best approach to building a new provider is to be familiar with both the 93 [Writing Custom Providers][writing] guide and [Extending Terraform][extending] 94 section. The guide will give you an introduction in code structure and the 95 basics of authoring a plugin that Terraform can interact with. The Extending 96 Terraform section contains guides, best practices, and API reference for 97 developers writing Terraform plugins. Additionally developers are encouraged to 98 use the [AWS 99 provider](https://github.com/terraform-providers/terraform-provider-aws) as an 100 implementation reference. Given the wide surface area of this provider, almost 101 all resource types and preferred code constructs are covered in it. 102 103 It is recommended for vendors to first develop support for one or two resources 104 and go through an initial review cycle before developing the code for the 105 remaining resources. This helps catch any issues early on in the process and 106 avoids errors from getting multiplied. In addition, it is advised to follow 107 existing conventions you see in the codebase, and ensure your code is formatted 108 with `go fmt`. 109 110 The provider code should include an acceptance test suite with tests for each 111 individual resource that holistically tests its behavior. 112 The Writing Acceptance Tests section in the 113 [Contributing to Terraform](https://github.com/hashicorp/terraform/blob/master/.github/CONTRIBUTING.md) 114 document explains how to approach these. It is recommended to randomize the 115 names of the tests as opposed to using unique static names, as that permits us 116 to parallelize the test execution. 117 118 Each provider has a section in the Terraform documentation. You'll want to add 119 new index file and individual pages for each resource supported by the provider. 120 121 All Terraform providers are required to contain a MPL-2.0 open source license. 122 123 While developing the provider code yourself is certainly possible, you can also 124 choose to leverage one of the following development agencies who’ve developed 125 Terraform providers in the past and are familiar with the requirements and process. 126 127 | Partner | Email | Website | 128 |--------------------|:-----------------------------|:---------------------| 129 | Crest Data Systems | malhar@crestdatasys.com | www.crestdatasys.com | 130 | DigitalOnUs | hashicorp@digitalonus.com | www.digitalonus.com | 131 | Akava | bd@akava.io | www.akava.io | 132 | OpenCredo | hashicorp@opencredo.com | www.opencredo.com | 133 134 ### 4. Review 135 136 During the review process, HashiCorp will provide feedback on the newly 137 developed provider. **Please engage in the review process once one or two 138 sample resources have been developed.** Begin the process by emailing 139 <terraform-provider-dev@hashicorp.com> with a URL to the public GitHub repo 140 containing the code. 141 142 HashiCorp will then review the resource code, acceptance tests, and the 143 documentation. When all the feedback has been addressed, support for the 144 remaining resources can continue to be developed, along with the corresponding 145 acceptance tests and documentation. 146 147 The vendor is encouraged to send HashiCorp 148 a rough list of resource names that are planned to be worked on along with the 149 mapping to the underlying APIs, if possible. This information can be provided 150 via the [webform](https://goo.gl/forms/iqfz6H9UK91X9LQp2). It is preferred that 151 the additional resources be developed and submitted as individual PRs in GitHub 152 as that simplifies the review process. 153 154 Once the provider has been completed another email should be sent to 155 <terraform-provider-dev@hashicorp.com> along with a URL to the public GitHub repo 156 containing the code requesting the final code review. HashiCorp will review the 157 code and provide feedback about any changes that may be required. This is often 158 an iterative process and can take some time to get done. 159 160 The vendor is also required to provide access credentials for the infrastructure 161 (cloud or other) that is managed by the provider. Please encrypt the credentials 162 using our public GPG key published at keybase.io/terraform (you can use the form 163 at https://keybase.io/encrypt#terraform) and paste the encrypted message into 164 the [webform](https://goo.gl/forms/iqfz6H9UK91X9LQp2). Please do NOT enter 165 plain-text credentials. These credentials are used during the review phase, 166 as well as to test the provider as part of the regular testing HashiCorp conducts. 167 168 -> 169 **NOTE:** It is strongly recommended to develop support for just one or two resources first and go through the review cycle before developing support for all the remaining resources. This approach helps catch any code construct issues early, and avoids the problem from multiplying across other resources. In addition, one of the common gaps is often the lack of a complete set of acceptance tests, which results in wasted time. It is recommended that you make an extra pass through the provider code and ensure that each resource has an acceptance test associated with it. 170 171 ### 5. Release 172 173 At this stage, it is expected that the provider is fully developed, all tests 174 and documentation are in place,the acceptance tests are all passing, and that 175 HashiCorp has reviewed the provider. 176 177 HashiCorp will create a new GitHub repo under the terraform-providers GitHub 178 organization for the new provider (example: `terraform-providers/terraform-provider-NAME`) 179 and grant the owner of the original provider code write access to the new repo. 180 A GitHub Pull Request should be created against this new repo with the provider 181 code that had been reviewed in step-4 above. Once this is done HashiCorp will 182 review and merge the PR, and get the new provider listed on 183 [terraform.io](https://www.terraform.io). This is also when the provider 184 acceptance tests are added to the HashiCorp test harness (TeamCity) and tested 185 at regular intervals. 186 187 Vendors whose providers are listed on terraform.io are permitted to use the 188 [HashiCorp Tested logo](/assets/images/docs/hashicorp-tested-icon.png) for their provider. 189 190 ### 6. Support 191 192 Many vendors view the release step to be the end of the journey, while at 193 HashiCorp we view it to be the start. Getting the provider built is just the 194 first step in enabling users to use it against the infrastructure. Once this is 195 done on-going effort is required to maintain the provider and address any 196 issues in a timely manner. 197 198 The expectation is to resolve all critical issues within 48 hours and all other 199 issues within 5 business days. HashiCorp Terraform has as extremely wide 200 community of users and contributors and we encourage everyone to report issues 201 however small, as well as help resolve them when possible. 202 203 Vendors who choose to not support their provider and prefer to make it a 204 community supported provider will not be listed on terraform.io. 205 206 ## Checklist 207 208 Below is an ordered checklist of steps that should be followed during the 209 provider development process. This just reiterates the steps already documented 210 in the section above. 211 212 * Fill out provider development program engagement [webform](https://goo.gl/forms/iqfz6H9UK91X9LQp2) 213 214 * Refer to the example providers and model the new provider based on that 215 216 * Create the new provider with one or two sample resources along with acceptance tests and documentation 217 218 * Send email to <terraform-provider-dev@hashicorp.com> to schedule an initial review 219 220 * Address review feedback and develop support for the other resources 221 222 * Send email to <terraform-provider-dev@hashicorp.com> along with a pointer to the public GitHub repo containing the final code 223 224 * Provide HashiCorp with credentials for underlying infrastructure managed by the new provider via the [webform](https://goo.gl/forms/iqfz6H9UK91X9LQp2) 225 226 * Address all review feedback, ensure that each resource has a corresponding acceptance test, and the documentation is complete 227 228 * Plan to continue supporting the provider with additional functionality as well as addressing any open issues. 229 230 * All Terraform providers are required to contain a MPL-2.0 open source license. 231 232 ## Contact Us 233 234 For any questions or feedback please contact us at <terraform-provider-dev@hashicorp.com>. 235 236 [writing]: /docs/extend/writing-custom-providers.html 237 [extending]: /docs/extend/index.html 238