A new platform for documentation and tutorials is launching soon.
We are migrating Consul documentation into HashiCorp Developer, our new developer experience.
»Network Infrastructure Automation Integration Program
HashiCorp's Network Infrastructure Automation (NIA) Integration Program allows partners to build integrations that allow customers to automate dynamic application workflows leveraging network and security infrastructure at runtime. Detailed below is the approach to integrate your networking technology along with the clearly defined steps, links to information sources, and checkpoints.
»Network Infrastructure Automation
Network Infrastructure Automation (NIA) relies on a declarative, workflow and service driven network automation architecture. NIA is carried out by
Consul-Terraform-Sync which leverages Terraform as the underlying automation tool and utilizes the Terraform provider ecosystem to drive relevant change to the network infrastructure. This usage of the Terraform provider in conjunction with Consul-Terraform-Sync allows for HashiCorp Consul to act as the core data source where it is updated with the state of the infrastructure.
Consul-Terraform-Sync executes one or more automation tasks with an appropriate value of service variables based on updates from the Consul service catalog. Each task consists of a runbook automation written as a compatible Terraform module using resources and data sources for the underlying network infrastructure. The Consul-Terraform-Sync daemon runs on the same node as a Consul agent.
Please note that the above indicated solution is a “push” based method and is not the only way to integrate network devices with Consul and drive Network Infrastructure Automation Integration. If your preferred method is to directly integrate with Consul without using Terraform, then please use Consul Integration Program.
»NIA Program Steps
The NIA Integration Program has six steps. By following these steps, Consul-Terraform-Sync compatible Terraform modules can be developed. They are then published as “verified” Consul-Terraform-Sync modules on the NIA page consul.io.
Note: A prerequisite to be eligible for NIA Integration program includes having a “verified” provider on Terraform registry for the appropriate technology. Please follow the guidelines to enroll in the Terraform Provider Development Program if you do not presently have a “verified” provider.
- Engage: Initial contact between Technology Partner and HashiCorp
- Enable: Documentation, code samples and best practices for developing the integration
- Develop & Test: Integration development and testing by Partner
- Review: HashiCorp code review and verification of integration (iterative process)
- Release: Module listed as Consul-Terraform-Sync compatible on Hashicorp Consul website and hosted on Terraform module registry
- Support: Ongoing maintenance and support of the module by the partner.
Please begin by providing the following details: NIA Integration Program.
Consul-Terraform-Sync compatible Terraform module development process is fairly straightforward and simple when technology partners have experience with building Terraform configuration files. Adopting Terraform best practices helps expedite the review and release cycles.
- Consul documentation
- Consul-Terraform-Sync documentation
- Writing Consul-Terraform-Sync compatible Terraform modules using our guide and tutorial
- Example Terraform Modules for reference: PAN-OS, Simple Print Module and a Template to structure your Terraform Modules
- Publishing to the Terraform Registry guidelines
»3. Develop & Test
Terraform modules are written in HashiCorp Configuration Language (HCL). Writing Terraform modules or a tutorial to build a module are good resources to begin writing a new module. Consul-Terraform-Sync compatible modules follow the standard module structure. Modules can use syntax supported by Terraform version 0.13, or higher. Consul-Terraform-Sync is designed to integrate with any module that satisfies these specifications. The guide will give you an introduction of the code structure and the basics of authoring a plugin that Terraform can interact with.
It is recommended that partners develop modules that cater to specific workflows on an individual platform in their product portfolio rather than having overarching modules that try to cover multiple workflows across different platforms. This is to keep the automation modular and adoptable by a broad set of users with varying network infrastructure topologies. Partners are encouraged to test the functionality of the modules against their supported platforms.
All Consul-Terraform-Sync compatible modules follow a naming convention:
terraform-<PROVIDER>-<NAME>-nia. Module repositories must use this four-part name format, where
<PROVIDER> is the Terraform Provider being used,
<NAME> reflects the type of infrastructure the module manages, and ends with the suffix
-nia to represent that this module is designed for NIA using Consul-Terraform-Sync.
Important: All Consul-Terraform-Sync compatible modules listed as Verified must contain one of the following open source licenses:
- CDDL 1.0, 2.0
- CPL 1.0
- Eclipse Public License (EPL) 1.0
- MPL 1.0, 1.1, 2.0
- 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"
- Microsoft Public License (MS-PL)
During the review process, HashiCorp will provide feedback on the newly developed Consul-Terraform-Sync compatible Terraform module. Please engage in the review process once one or two sample modules have been developed. Begin the process by emailing firstname.lastname@example.org with a URL to the public GitHub repo containing the code.
HashiCorp will then review the module, and the documentation. The documentation should clearly indicate the compatibility with Consul-Terraform-Sync software version(s) and partner platform's software version(s).
Once the module development has been completed another email should be sent to email@example.com along with a URL to the public GitHub repo containing the code requesting the final code review. HashiCorp will review the module and provide feedback about any changes that may be required. This is often an iterative process and can take some time to get done.
At this stage, it is expected that the module is fully developed, all tests and documentation are in place, and that HashiCorp has reviewed the module to be compatible with Consul-Terraform-Sync.
Once this is done, HashiCorp will get the new module listed as Consul-Terraform-Sync compatible on consul.io, and then the partner will be asked to publish the Terraform module to the Terraform Registry.
Many partners view the release step to be the end of the journey, while at HashiCorp we view it to be the start. Getting the Consul-Terraform-Sync compatible module 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 module and address any issues in a timely manner.
The expectation is to resolve all critical issues within 48 hours and all other issues within 5 business days. HashiCorp Consul and Terraform have 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.
Partners who choose to not follow the process of NIA Integration Program for their Consul-Terraform-Sync compatible Terraform modules will not have their modules listed on consul.io.
For any questions or feedback please contact us at firstname.lastname@example.org.