Improve discoverability and usability of examples/

[displague]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
• Please do not leave "+1" or "me too" comments, they generate extra noise for issue followers and do not help prioritize the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment.

Description

In #100, we moved the Fabric examples/ to their own GitHub repos. We've slid back from this position in recent updates. This can be seen in the project today with some inconsistent between resource families:

• Network Edge: examples/ directory contains a single README.md that refers to Terraform modules in the registry https://github.com/equinix/terraform-provider-equinix/tree/main/examples/edge-networking#readme
• Fabric: Documentation (Guide) includes a module example section that refers to Terraform modules in the registry https://registry.terraform.io/providers/equinix/equinix/latest/docs/guides/equinix_fabric_cloud_providers#terraform-modules---the-easiest-way
• Fabric: examples/ nested directory tree with per resource, use-case, examples. This pattern is evidenced in AzureRM, AWS, and (to a lesser-extent) Google providers maintained by Hashicorp. https://github.com/equinix/terraform-provider-equinix/tree/main/examples/fabric
• Metal: none (there are some guides that walk through use-cases, however there are few if any single resource example modules found in the two GitHub orgs that contain the most Equinix Metal modules (Equinix Labs, Equinix)

The main advantage of having the examples in the terraform-provider-equinix examples/ directory is that they are easier to maintain when making provider changes.

The main advantage of having examples included or referenced in the docs/ directory is that they are discoverable and alongside the primary reference for the resource.

The main advantage of having examples published in modules is that they can be consumed by Terraform directly. Their use can be measured. They can be modified to continue working even when the underlying resources have changed.

In order to make our examples more discoverable, usage measurable, reusable, and well maintained, the community would benefit from:

• [x] the examples/fabric/ paths being moved to distinct Terraform Modules (derived from the template: https://github.com/equinix-labs/terraform-equinix-template)
  • [x] Documentation for these projects will be autogenerated from the included actions (required vars.tf and outputs.tf following best practices)
  • [x] Validation and linting is performed from the included actions (E2E testing is possible but not enabled by default)
• [ ] the examples are covered in one of more docs/ guides related to the use-case or product family
  • [ ] the guide includes a the name of the module, a link to the Terraform module, and a link to the GitHub repo. This should be presented in table format when there are multiple examples listed (similar to the NE examples/ README.md)
• [x] the examples/ directory refers users to the published docs/ and does not harbor unvalidated TF code.
• [ ] Metal use-case and minimal resource modules are created and follow this pattern

Alternatives and evolved presentations to consider:

• https://deploy.equinix.com/labs/terraform/
• https://github.com/GoogleCloudPlatform/cloud-foundation-fabric/
• https://github.com/terraform-google-modules
• https://cloud.google.com/docs/terraform/blueprints/terraform-blueprints
• https://github.com/Azure/terraform-azure-modules
• https://github.com/terraform-aws-modules
  • https://registry.terraform.io/search/modules?namespace=terraform-aws-modules
• https://github.com/oracle-terraform-modules

[displague]

A counter argument is that the examples/ are tested, as evidenced in files like tests/connection_e2e_cloudRouter2serviceprofile_test.go

[thogarty]

A counter argument is that the examples/ are tested, as evidenced in files like tests/connection_e2e_cloudRouter2serviceprofile_test.go

This is actually a very good counter argument because Fabric will begin to use these integration tests for its Terraform additions for regression testing while we continue to meet parity with the available features available from the API.

[displague]

@thogarty There's some extra discussion around this in the upstream, wrt how modules are sourced. https://github.com/hashicorp/terraform/issues/31134#issuecomment-1741744663

My leaning for this issue, and with E2E testing and module discovery in mind, is that we move from:

equinix/terraform-provider-equinix /examples/fabric/v4/cloudRouterConnectivity/cloudRouter2aws to equinix-labs/terraform-equinix-fabric-cloudrouter-aws

This follows the pattern of the existing equinix-labs/terraform-equinix-fabric-connection-* modules.

Alternatively,

equinix-labs/terraform-equinix-fabric-cloudrouter/
   modules/{cloudrouter,aws,google,azure,...}
   examples/cloudrouter2{aws,google,azure}/

In either case, the E2E tests in this project would source the published version of those modules. This would help to prevent breaking changes from being introduced. If/when a breaking change is introduced, we'll have to be more deliberate in updating the E2E tests to refer to a branch of the published module repo updated with the breaking changes. Upon merge and release, change the branch reference to a tag reference. This should not be of immediate concerns since those tests are not run in this project's CI today.

The examples/ in this project would then follow the Network Edge examples/ne/README.md pattern, where we link out to external, published, reusable modules and their examples.

[displague]

The examples would benefit from a lint check:

• https://github.com/equinix/terraform-provider-equinix/issues/212#issuecomment-1921370253

[displague]

Fabric and NE examples are now located in:

https://github.com/equinix/terraform-equinix-fabric https://github.com/equinix/terraform-equinix-network-edge

https://github.com/equinix/terraform-provider-equinix/tree/main/examples is now using conventional paths.

There are some exceptions in examples/, guideposts to the modules. These should probably be moved out of the examples/ directory. Some possible homes for that content: the root README.md, Equinix Labs, Terraform Guides, or the provider index.md.