ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #25789 from hashicorp/cgriggs01-pdp-docs 

[Website] Provider Dev Program Guide
This commit is contained in:
Chris Griggs 2020-08-10 13:32:56 -07:00 committed by GitHub
parent b9cf673bea 1b30656df4
commit 2fc26a9691
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 87 additions and 182 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

269
website/guides/terraform-provider-development-program.html.md
View File

@ -7,122 +7,82 @@ description: This guide is intended for vendors who're interested in having thei
# Terraform Provider Development Program # Terraform Provider Development Program
The Terraform Provider Development Program allows vendors to build The Terraform Provider Development Program facilitates vendors in creating and publishing Terraform providers that have been officially approved and verified by HashiCorp. Once verified, the provider published under your organization’s namespace will receive a distinct tier and badge that helps to distinguish it from community-sourced providers within the [Registry](https://registry.terraform.io).
Terraform providers that are officially approved and tested by HashiCorp and
listed on the official Terraform website. The program is intended to be largely The Verified badge helps users easily identify and discover integrations developed and maintained directly by an integration’s vendor, establishing a level of trust for our users. This program is intended to be largely self-serve, with links to information sources, clearly defined steps, and checkpoints detailed below.
self-serve, with links to information sources, clearly defined steps, and
checkpoints. ![Verified Provider Card](/assets/images/docs/verified-card.png)
-> **Building your own provider?** If you're building your own provider and aren't interested in having HashiCorp officially verify and regularly monitor your provider, please refer to the [Writing Custom Providers guide](https://www.terraform.io/docs/extend/writing-custom-providers.html) and the [Extending Terraform](https://www.terraform.io/docs/extend/index.html) section.
-> **Building your own provider?** If you're building your own provider and
aren't interested in having HashiCorp officially approve and regularly test the
provider, refer to the [Writing Custom Providers guide][writing] and the
[Extending Terraform][extending] section.
## What is a Terraform Provider? ## What is a Terraform Provider?
Terraform is used to create, manage, and manipulate infrastructure resources. Terraform is used to create, manage, and interact with infrastructure resources of any kind. Examples of resources include physical machines, VMs, network switches, containers, etc. Almost any infrastructure noun can be represented as a resource in Terraform.
Examples of resources include physical machines, VMs, network switches, containers, etc.
Almost any infrastructure noun can be represented as a resource in Terraform.
A provider is responsible for understanding API interactions with the underlying A Terraform Provider represents an integration that is responsible for understanding API interactions with the underlying infrastructure, such as a public cloud service (AWS, GCP, Azure), a PaaS service (Heroku), a SaaS service (DNSimple, CloudFlare), or on-prem resources (vSphere). The Provider then exposes these as resources that Terraform users can interface with, from within Terraform a configuration. Terraform presently supports more than 70 providers, a number that has more than doubled in the past 12 months.
infrastructure like a cloud (AWS, GCP, Azure), a PaaS service (Heroku), a SaaS
service (DNSimple, CloudFlare), or on-prem resources (vSphere). It then exposes
these as resources users can code to. Terraform presently supports more than
70 providers, a number that has more than doubled in the past 12 months.
All providers integrate into and operate with Terraform exactly the same way. All providers integrate into and operate with Terraform exactly the same way. The table below is intended to help users understand who develops, and maintains a particular provider.
The table below is intended to help users understand who develops, maintains
and tests a particular provider.
![Provider Engagement Table](/assets/images/docs/engage-table.png) <table border="0" style="border-collapse: collapse; width: 100%;">
<tbody>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><strong>Tier</strong></td>
<td style="width: 55.7271%; height: 21px;"><strong>Description</strong></td>
<td style="width: 31.7889%; height: 21px;"><strong>Namespace</strong></td>
</tr>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><img src="/docs/registry/providers/images/official-tier.png" alt="" /></td>
<td style="width: 55.7271%; height: 21px;"><i><span style="font-weight: 400;">Official providers are owned and maintained by HashiCorp </span></i></td>
<td style="width: 31.7889%; height: 21px;"><code><span style="font-weight: 400;">hashicorp</span></code></td>
</tr>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><img src="/docs/registry/providers/images/verified-tier.png" alt="" /></td>
<td style="width: 55.7271%; height: 21px;"><i><span style="font-weight: 400;">Verified providers are owned and maintained by third-party technology partners. Providers in this tier indicate HashiCorp has verified the authenticity of the Provider&rsquo;s publisher, and that the partner is a member of the </span></i><a href="https://www.hashicorp.com/ecosystem/become-a-partner/"><i><span style="font-weight: 400;">HashiCorp Technology Partner Program</span></i></a><i><span style="font-weight: 400;">.</span></i></td>
<td style="width: 31.7889%; height: 21px;"><span style="font-weight: 400;">Third-party organization, e.g. </span><code><span style="font-weight: 400;">mongodb/mongodbatlas</span></code></td>
</tr>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><img src="/docs/registry/providers/images/community-tier.png" alt="" /></td>
<td style="width: 55.7271%; height: 21px;">Community providers are published to the Terraform Registry by individual maintainers, groups of maintainers, or other members of the Terraform community.</td>
<td style="width: 31.7889%; height: 21px;"><br />Maintainer&rsquo;s individual or organization account, e.g. <code>DeviaVir/gsuite</code></td>
</tr>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><img src="/docs/registry/providers/images/archived-tier.png" alt="" /></td>
<td style="width: 55.7271%; height: 21px;">Archived Providers are Official or Verified Providers that are no longer maintained by HashiCorp or the community. This may occur if an API is deprecated or interest was low.</td>
<td style="width: 31.7889%; height: 21px;"><code>hashicorp</code> or third-party</td>
</tr>
</tbody>
</table>
<p></p>
-> **Note:** This document focuses on the "Verified" Tier in the table above. Community contributors interested in contributing to existing providers or building new providers should refer to the [Publishing a Provider](https://www.terraform.io/docs/registry/providers/publishing.html) section of our documentation.
-> **Note:** This document is primarily intended for the "HashiCorp/Vendors" row in
the table above. Community contributors who’re interested in contributing to
existing providers or building new providers should refer to the
[Writing Custom Providers guide][writing].
## Provider Development Process ## Provider Development Process
The provider development process is divided into six steps below. By following The provider development process is divided into five steps below. By following these steps, providers can be developed alongside HashiCorp to ensure new providers are able to be published in Terraform as quickly as possible.
these steps, providers can be developed alongside HashiCorp to ensure new
providers are able to be published in Terraform as quickly as possible.
![Provider Development Process](/assets/images/docs/process.png) ![Provider Development Process](/assets/images/docs/program-steps.png)
1. **Engage**: Initial contact between vendor and HashiCorp 1. **Apply**: Initial contact between vendor and HashiCorp
2. **Enable**: Information and articles to aid with the provider development 2. **Prepare**: Follow documentation while developing the provider
3. **Dev/Test**: Provider development and test process 3. **Verify**: Share public GPG key with HashiCorp
4. **Review**: HashiCorp code review and acceptance tests (iterative process) 4. **Publish**: Release the provider on the Registry
5. **Release**: Provider availability and listing on [terraform.io](https://www.terraform.io) 5. **Support**: Ongoing maintenance and support of the provider by the vendor.
6. **Support**: Ongoing maintenance and support of the provider by the vendor.
### 1. Engage ### 1. Apply
Please begin by providing some basic information about the provider that Please begin by completing our HashiCorp Technology Partner application: https://www.hashicorp.com/ecosystem/become-a-partner/#technology
is being built via a simple [webform](https://goo.gl/forms/iqfz6H9UK91X9LQp2).
This information is captured upfront and used by HashiCorp to track the Terraform has a large and active ecosystem of partners that may have already started working on the same provider. We'll do our best to connect similar parties to avoid duplicate efforts, and prepare for a successful and impactful launch of the integration. Once you have applied, a member of the HashiCorp Alliances team will be in touch, and will ask for your organization to sign our Technology Partner Agreement.
provider through various stages. The information is also used to notify the
provider developer of any overlapping work, perhaps coming from the community.
Terraform has a large and active community and ecosystem of partners that
may have already started working on the same provider. We'll do our best to
connect similar parties to avoid duplicate work.
### 2. Enable ### 2. Prepare
We’ve found the provider development process to be fairly straightforward and simple Detailed instructions for preparing a provider for publishing are available in our Registry documentation. Please see [Preparing your Provider](https://www.terraform.io/docs/registry/providers/publishing.html#preparing-your-provider). In order to provide a consistent and quality experience for users, please make sure detailed documentation for your provider is included. You can find more information on how to build and structure [provider documentation here](https://www.terraform.io/docs/registry/providers/docs.html).
when vendors pay close attention and follow to the resources below. Adopting
the same structure and coding patterns helps expedite the review and release cycles.
* [Writing custom providers guide][writing] We’ve found the provider development process to be fairly straightforward and simple when you pay close attention and follow the resources below. If you have not developed a provider before and are looking for some help in developing one, you may choose to leverage one of the following development agencies which have developed Terraform providers in the past and are familiar with the requirements and process:
* How-to build a provider [video](https://www.youtube.com/watch?v=2BvpqmFpchI)
* Sample provider developed by [partner](http://container-solutions.com/write-terraform-provider-part-1/)
* Example providers for reference: [AWS](https://github.com/terraform-providers/terraform-provider-aws), [OPC](https://github.com/terraform-providers/terraform-provider-opc)
* Contributing to Terraform [guidelines](https://github.com/hashicorp/terraform/blob/master/.github/CONTRIBUTING.md)
* Gitter HashiCorp-Terraform [room](https://gitter.im/hashicorp-terraform/Lobby).
### 3. Development & Test
Terraform providers are written in the [Go](https://golang.org/) programming
language. The
[Writing Custom Providers guide][writing]
is a good resource for developers to begin writing a new provider.
The best approach to building a new provider is to be familiar with both the
[Writing Custom Providers][writing] guide and [Extending Terraform][extending]
section. The guide will give you an introduction in code structure and the
basics of authoring a plugin that Terraform can interact with. The Extending
Terraform section contains guides, best practices, and API reference for
developers writing Terraform plugins. Additionally developers are encouraged to
use the [AWS
provider](https://github.com/terraform-providers/terraform-provider-aws) as an
implementation reference. Given the wide surface area of this provider, almost
all resource types and preferred code constructs are covered in it.
It is recommended for vendors to first develop support for one or two resources
and go through an initial review cycle before developing the code for the
remaining resources. This helps catch any issues early on in the process and
avoids errors from getting multiplied. In addition, it is advised to follow
existing conventions you see in the codebase, and ensure your code is formatted
with `go fmt`.
The provider code should include an acceptance test suite with tests for each
individual resource that holistically tests its behavior.
The Writing Acceptance Tests section in the
[Contributing to Terraform](https://github.com/hashicorp/terraform/blob/master/.github/CONTRIBUTING.md)
document explains how to approach these. It is recommended to randomize the
names of the tests as opposed to using unique static names, as that permits us
to parallelize the test execution.
Each provider has a section in the Terraform documentation. You'll want to add
new index file and individual pages for each resource supported by the provider.
All Terraform providers are required to contain a MPL-2.0 open source license.
While developing the provider code yourself is certainly possible, you can also
choose to leverage one of the following development agencies who’ve developed
Terraform providers in the past and are familiar with the requirements and process.
| Partner | Email | Website | | Partner | Email | Website |
|--------------------|:-----------------------------|:---------------------| |--------------------|:-----------------------------|:---------------------|
@ -131,108 +91,53 @@ Terraform providers in the past and are familiar with the requirements and proce
| Akava | bd@akava.io | www.akava.io | | Akava | bd@akava.io | www.akava.io |
| OpenCredo | hashicorp@opencredo.com | www.opencredo.com | | OpenCredo | hashicorp@opencredo.com | www.opencredo.com |
### 4. Review -> **Important:** All Terraform providers listed as Verified must contain one of the following open source licenses:
During the review process, HashiCorp will provide feedback on the newly - CDDL 1.0, 2.0
developed provider. **Please engage in the review process once one or two - CPL 1.0
sample resources have been developed.** Begin the process by emailing - Eclipse Public License (EPL) 1.0
<terraform-provider-dev@hashicorp.com> with a URL to the public GitHub repo - MPL 1.0, 1.1, 2.0
containing the code. - PSL 2.0
- Ruby's Licensing
- AFL 2.1, 3.0
- Apache License 2.0
- Artistic License 1.0, 2.0
- Apache Software License (ASL) 1.1
- Boost Software License
- BSD, BSD 3-clause, "BSD-new"
- CC-BY
- Microsoft Public License (MS-PL)
- MIT
HashiCorp will then review the resource code, acceptance tests, and the
documentation. When all the feedback has been addressed, support for the
remaining resources can continue to be developed, along with the corresponding
acceptance tests and documentation.
The vendor is encouraged to send HashiCorp ### 3. Verify
a rough list of resource names that are planned to be worked on along with the
mapping to the underlying APIs, if possible. This information can be provided
via the [webform](https://goo.gl/forms/iqfz6H9UK91X9LQp2). It is preferred that
the additional resources be developed and submitted as individual PRs in GitHub
as that simplifies the review process.
Once the provider has been completed another email should be sent to At this stage, it is expected that the provider is fully developed, all tests and documentation are in place, and your provider is ready for publishing. In this step, HashiCorp will verify the source and authenticity of the namespace being used to publish the provider by signing your GPG key with a trust signature.
<terraform-provider-dev@hashicorp.com> along with a URL to the public GitHub repo
containing the code requesting the final code review. HashiCorp will review the
code and provide feedback about any changes that may be required. This is often
an iterative process and can take some time to get done.
The vendor is also required to provide access credentials for the infrastructure -> **Important:** This step requires that you have signed and accepted our Technology Partner Agreement. If you have not received this, please see step #1 above.
(cloud or other) that is managed by the provider. Please encrypt the credentials
using our public GPG key published at keybase.io/terraform (you can use the form
at https://keybase.io/encrypt#terraform) and paste the encrypted message into
the [webform](https://goo.gl/forms/iqfz6H9UK91X9LQp2). Please do NOT enter
plain-text credentials. These credentials are used during the review phase,
as well as to test the provider as part of the regular testing HashiCorp conducts.
-> Please send your public key to terraform-registry@hashicorp.com, indicating you are a partner seeking verification, and a HashiCorp employee will be in touch to help verify, and add your key.
**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.
### 5. Release To export your public key in ASCII-armor format, use the following command:
At this stage, it is expected that the provider is fully developed, all tests ```
and documentation are in place,the acceptance tests are all passing, and that $ gpg --armor --export "{Key ID or email address}"
HashiCorp has reviewed the provider. ```
HashiCorp will create a new GitHub repo under the terraform-providers GitHub ### 4. Publish
organization for the new provider (example: `terraform-providers/terraform-provider-NAME`)
and grant the owner of the original provider code write access to the new repo.
A GitHub Pull Request should be created against this new repo with the provider
code that had been reviewed in step-4 above. Once this is done HashiCorp will
review and merge the PR, and get the new provider listed on
[terraform.io](https://www.terraform.io). This is also when the provider
acceptance tests are added to the HashiCorp test harness (TeamCity) and tested
at regular intervals.
Vendors whose providers are listed on terraform.io are permitted to use the Once the verification step is complete please follow the steps on [Publishing a Provider](https://www.terraform.io/docs/registry/providers/publishing.html). This step does not require additional involvement from HashiCorp as publishing is a fully self-service process in the [Terraform Registry](https://registry.terraform.io).
[HashiCorp Tested logo](/assets/images/docs/hashicorp-tested-icon.png) for their provider.
### 6. Support Once completed, your provider should be visible in the Terraform Registry and usable in Terraform. Please confirm that everything looks good, and that documentation is rendering properly.
Many vendors view the release step to be the end of the journey, while at ### 5. Maintain & Support
HashiCorp we view it to be the start. Getting the provider built is just the
first step in enabling users to use it against the infrastructure. Once this is
done on-going effort is required to maintain the provider and address any
issues in a timely manner.
The expectation is to resolve all critical issues within 48 hours and all other Getting a new provider built and published to the Terraform Registry is just the first step towards enabling your users with a quality Terraform integration. Once a `verified` provider has been published, on-going effort is required to maintain the provider. It is expected that all verified provider publishers will continue to maintain the provider and address any issues your users report in a timely manner. HashiCorp reserves the right to remove verified status from any provider this is no longer maintained.
issues within 5 business days. HashiCorp Terraform has as extremely wide
community of users and contributors and we encourage everyone to report issues
however small, as well as help resolve them when possible.
Vendors who choose to not support their provider and prefer to make it a The expectation is to resolve all critical issues within 48 hours and all other issues within 5 business days. HashiCorp Terraform has an extremely wide community of users and contributors and we encourage everyone to report issues however small, as well as help resolve them when possible.
community supported provider will not be listed on terraform.io.
## Checklist Vendors who choose to not support their provider and prefer to make it a community supported provider will no longer be listed as Verified.
Below is an ordered checklist of steps that should be followed during the
provider development process. This just reiterates the steps already documented
in the section above.
* Fill out provider development program engagement [webform](https://goo.gl/forms/iqfz6H9UK91X9LQp2)
* Refer to the example providers and model the new provider based on that
* Create the new provider with one or two sample resources along with acceptance tests and documentation
* Send email to <terraform-provider-dev@hashicorp.com> to schedule an initial review
* Address review feedback and develop support for the other resources
* Send email to <terraform-provider-dev@hashicorp.com> along with a pointer to the public GitHub repo containing the final code
* Provide HashiCorp with credentials for underlying infrastructure managed by the new provider via the [webform](https://goo.gl/forms/iqfz6H9UK91X9LQp2)
* Address all review feedback, ensure that each resource has a corresponding acceptance test, and the documentation is complete
* Plan to continue supporting the provider with additional functionality as well as addressing any open issues.
* All Terraform providers are required to contain a MPL-2.0 open source license.
## Contact Us ## Contact Us
For any questions or feedback please contact us at <terraform-provider-dev@hashicorp.com>. For any questions or feedback please contact us at <terraform-provider-dev@hashicorp.com>.
[writing]: /docs/extend/writing-custom-providers.html
[extending]: /docs/extend/index.html