diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index cdd3ebabe2..b1836287be 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -230,6 +230,7 @@ export default [ name: 'Integrations', content: [ 'partnerships', + 'nia-integration', { title: 'Vault Integration', href: '/docs/connect/ca/vault', diff --git a/website/pages/docs/integrate/nia-integration.mdx b/website/pages/docs/integrate/nia-integration.mdx new file mode 100644 index 0000000000..7cab83137a --- /dev/null +++ b/website/pages/docs/integrate/nia-integration.mdx @@ -0,0 +1,102 @@ +--- +layout: docs +page_title: Network Infrastructure Automation Integration Program +sidebar_title: NIA Integration Program +description: Guide to partnership integrations for Consul NIA +--- + +# 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 leverages an agent, `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-Tasks allows for HashiCorp Consul to act as the core data source where it is updated with the state of the infrastructure. + +The Consul-Terraform-Sync agent 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 agent runs on the same node as a Consul agent. + +[![NIA Architecture](/img/nia-highlevel-diagram.png)](/img/nia-highlevel-diagram.png) + +-> 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](/docs/integrate/partnerships). + +## 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](/use-cases/network-infrastructure-automation). + +-> **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. + +[![NIA Integration Program Steps](/img/nia-integration-program.png)](/img/nia-integration-program.png) + +1. **Engage**: Initial contact between Technology Partner and HashiCorp +2. **Enable**: Documentation, code samples and best practices for developing the integration +3. **Develop & Test**: Integration development and testing by Partner +4. **Review**: HashiCorp code review and verification of integration (iterative process) +5. **Release**: Module listed as Consul-Terraform-Sync compatible on Hashicorp Consul website and hosted on Terraform module registry +6. **Support**: Ongoing maintenance and support of the module by the partner. + +### 1. Engage + +Please begin by providing the following details: [NIA Integration Program](https://docs.google.com/forms/d/1HtJXYQ36n83lFXEX-F_uIB7abUEMj95prSi5TSDMCXc/viewform?gxids=7757&edit_requested=true). + +### 2. Enable + +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](/docs) +- Consul-Terraform-Sync use case [documentation](/use-cases/network-infrastructure-automation) +- Writing Consul-Terraform-Sync compatible Terraform modules [guide](/docs/nia/installation/requirements#how-to-create-a-compatible-terraform-module) +- Example [module](https://registry.terraform.io/modules/findkim/ngfw/panos/0.0.1-beta3) for reference +- Contributing to Terraform module registry [guidelines](https://www.terraform.io/docs/registry/modules/publish.html) + +### 3. Develop & Test + +Terraform modules are written in HashiCorp Configuration Language (HCL). Writing [Terraform modules](https://www.terraform.io/docs/modules/index.html) or a [tutorial to build a module](https://learn.hashicorp.com/tutorials/terraform/module-create) are good resources to begin writing a new module. +Consul-Terraform-Sync compatible modules follow the [standard module structure](https://www.terraform.io/docs/modules/index.html#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](/docs/nia/installation/requirements#how-to-create-a-compatible-terraform-module). The guide will give you an introduction of the code structure and the basics of authoring a module for Terraform. Additionally developers are encouraged to use the [PAN-OS NGFW](https://github.com/devarshishah3/terraform-panos-dag-nia) module as an implementation reference. + +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 elegant and modular. Partners are encouraged to the functionality of the modules against their supported platforms. + +All Consul-Terraform-Sync compatible modules follow a naming convention: `terraform---nia`. Module repositories must use this four-part name format, where `` is the Terraform Provider being used, `` 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" +- CC-BY +- Microsoft Public License (MS-PL) +- MIT + +### 4. Review + +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 nia-integration-dev@hashicorp.com 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 nia-integration-dev@hashicorp.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. + +### 5. Release + +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](/use-cases/network-infrastructure-automation), and on [Terraform module registry](https://registry.terraform.io/browse/modules). + +### 6. Support + +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](/use-cases/network-infrastructure-automation). In addition, the modules will be considered community supported. + +### Contact Us + +For any questions or feedback please contact us at nia-integration-dev@hashicorp.com. diff --git a/website/public/img/nia-highlevel-diagram.png b/website/public/img/nia-highlevel-diagram.png new file mode 100644 index 0000000000..ddcb9f076d Binary files /dev/null and b/website/public/img/nia-highlevel-diagram.png differ diff --git a/website/public/img/nia-integration-program.png b/website/public/img/nia-integration-program.png new file mode 100644 index 0000000000..52ea697fe8 Binary files /dev/null and b/website/public/img/nia-integration-program.png differ