terraform-provider-openapi

README

Terraform Provider OpenAPI

This terraform provider aims to minimise as much as possible the efforts needed from service providers to create and maintain custom terraform providers. This provider uses terraform as the engine that will orchestrate and manage the cycle of the resources and depends on a swagger file (hosted on a remote endpoint) to successfully configure itself dynamically at runtime.

Powered by https://www.terraform.io	Following The OpenAPI Specification

What are the main pain points that this terraform provider tries to tackle?

• As as service provider, you can focus on improving the service itself rather than the tooling around it.
• Due to the dynamic nature of this terraform provider, the service provider can continue expanding the functionality of the different APIs by introducing new versions, and this terraform provider will be able to discover the new resource versions automatically without the need to add support for those as you would when mantining your own custom Terraform provider.
• Find consistency across APIs provided by different teams encouraging the adoption of OpenAPI specification for describing, producing, consuming, and visualizing RESTful Web services.

Overview

API terraform provider is a powerful full-fledged terraform provider that is able to configure itself at runtime based on a Swagger specification file containing the definitions of the APIs exposed. The dynamic nature of this provider is what makes it very flexible and convenient for service providers as subsequent upgrades to their APIs will not require new compilations of this provider. The service provider APIs are discovered on the fly and therefore the service providers can focus on their services rather than the tooling around it.

Pre-requirements

• The service provider hosts APIs compliant with OpenApi and swagger spec file is available via a discovery endpoint.

Requirements

• Terraform v0.12.0 (to execute the terraform provider plugin)
• Go 1.12.4 (to build the provider plugin)
  • This project uses go modules for dependency management
• Docker 17.09.0-ce (to run service provider example)
• Docker-compose 1.16.1 (to run service provider example)

How to use Terraform Provider OpenAPI

Things to know regarding custom terraform providers

• Terraform expects third party providers to be manually installed in the '.terraform.d/plugins' sub-path in your user's home directory.
• Terraform expects terraform provider names to follow a specific naming scheme. The naming scheme for plugins is terraform-<type>-NAME_vX.Y.Z, where type is either provider or provisioner.

More information about how terraform discovers third party terraform providers and naming conventions here.

OpenAPI Terraform provider installation

There are multiple ways how the OpenAPI Terraform provider can be installed. Please refer to the OpenAPI Terraform provider installation document to learn more about it.

OpenAPI Terraform provider in action

After having provisioned your environment with the OpenAPI Terraform provider you can now write Terraform configuration files using resources provided by the OpenAPI service. Refer to Using the OpenAPI Terraform Provider doc for more details.

Terraform provider documentation

You can generate the Terraform documentation automatically given an already Terraform compatible OpenAPI document using the The OpenAPI Terraform Documentation Renderer library. The OpenAPI document is the source of truth for both the OpenAPI Terraform provider as well as the user facing documentation.

References

Additionally, the following documents provide deep insight regarding OpenAPI and Terraform as well as frequently asked questions:

• How to document contains information about how to define a swagger file following good practises that make it work seamlessly with this terraform provider. Additionally, learn more about what is currently supported.
• Migrating to Terraform 0.12. This document describes how to update configuration created using Terraform v0.11 to v0.12.
• FAQ document answers for the most frequently asked questions.

Contributing

Please follow the guidelines from:

• Contributor Guidelines
• How to set up the local environment?

References

• go-swagger: Api terraform provider makes extensive use of this library which offers a very convenient implementation to serialize and deserialize swagger specifications.
• JsonPath: Json path is used in the plugin external configuration file to define values for provider schema properties that are coming from external files.

Authors

• Daniel I. Khan Ramiro

See also the list of contributors who participated in this project.