Terraform Equinix Modules

Ths guide discusses how to contribute Terraform modules to the Equinix Labs GH Org.

Terraform modules should either be sourced from Template module template or closely following the format of this project.

Using the Terraform Equinix Modules Template

• Join the Equinix Labs GitHub org
• Choose a name for your repository
• Visit the Template module template
• Give the “terraform” group admin access to the repository
• Develop your module
• Tag your module
• Publish your module

Steps:

1. Join the Equinix Labs GitHub organization with your Equinix Single Sign-On:

• Equinix SSO
  • You may need to the verify networking settings
  • You may need to Enable Two Factor on your GitHub Profile
  • You may need to Enable SSO on your SSH key
• Make your membership public, if you like:
  • Equinix-Labs Org Members

1. Choose a name for your repository

• Module names must be of the form “terraform-{provider}-{something-concise}”. This ensures that the module can eventually be published. All Terraform configurations we share should strive to become a published, reusable, module.
• Names should begin with “terraform-equinix” for any project with Equinix or Equinix Metal providers, or “terraform-metal” when only the Equinix Metal provider is used. “terraform-equinix-foo” is a good prefix for any module.

1. Visit the Template module template:

• Click “Use this template”
• Use Equinix SSO, if prompted
• Choose the Equinix Labs org (if you do not see this, make sure you joined the org in step 1)
• Give the repository the name determined in the previous step.
• Set a meaningful description, for example “Terraform module for Equinix Things to do something desirable”
• Click the box to make it public
• Click “Create repository from template”

1. Give the “terraform” group admin access to the repository

• Click the “Settings” tab
• “Manage Access”
• “Invite Teams or People”
• “equinix-labs/terraform”
• Give the team “admin” access

1. Develop your module

• Look for “template” within the project and replace it with the appropriate repo name or advised content.
• Follow the standards provided in the Terraform Module Development Standards guide.
• GitHub run-pre-commit-hooks action should be preconfigured to verify that your PRs contain valid Terraform
• In your README.md and examples, avoid using any credentials that look like real credentials. Avoid IP addresses that are real public IP addresses. These credentials will be flagged and reviewed by the security team and will waste the time of everyone involved (I am writing this after receiving a phone call about a flagged phony credential :-) ).
• When working on changes, Branch Protection may be enabled which will prevent pushing directly to the main branch. Use branches and open PRs against those branches. With the approval of any other member of the “equinix-labs/terraform” team, your PR may be merged. It is also possible to disable branch protection.
• Follow the Conventional Commit Specification to properly format and submit commits. Other types are allowed, based on the Angular Convention types. Example commit message: fix: disabled log generation for system services. For more examples, see commit examples.
• Submit a PR when ready.

1. When your code has reached any level of stability (“it does what it says it does”), submit a PR following the format highlighted in the previous section 5. When you submit a PR, it should trigger a github workflow CI job: run-pre-commit-hooks. Once it is approved and merged, it will then trigger yet another gihub workflow CI job: generate-terraform-docs.

• The run-pre-commit-hooks github CI job will run checks on terraform, md, bash shell, python, yaml, and json files.
• The generate-terraform-docs github CI job will populate the main README.md, the modules README.md and the examples README.md file.
• The generate-release github CI job relies on the semantic release action
• This action is configured with 2 major plugins: commit-analyzer and release-notes-generator
  • commit-analyzer - This will examine the commits and look for keywords in the commit message, based on the Conventional Commit Specification, then update github release with the corresponding semantic change
  • release-notes-generator - This will update the CHANGELOG.md file with the relative info about each release and changes within.

• This is the reference semantic change table based on commit type:

  Type	Description	Semantic Increment
  feat	Features	minor
  fix	Bug Fixes	patch
  perf	Performance Improvements	patch
  revert	Reverts	patch
  breaking	Breaking Changes	major
  docs	Documentation	N/A
  style	Styles	N/A
  refactor	Code Refactoring	N/A
  build	Builds	N/A
  ci	Continuous Integrations	N/A
  chore	Chores	N/A

1. Publish the module

• Follow this link: Publish a Terraform module
• See HashiCorp Publishing Modules article for more details
• Any new releases will automatically be picked up
• You may update your README.md to reflect that the variables and outputs are defined in the registry documentation. You may also want to change your “git clone” instructions in favor of the “module “foo” {}” pattern.
• You should set the Terraform Registry URL in the repositories Settings / URL field. For example, https://registry.terraform.io/modules/equinix-labs/hybrid-gateway

Reviewing Equinix Terraform Modules

• Join the Equinix Labs GitHub org
• Review steps 5-7 above
• Join Equinix Terraform team
• Review then merge PR

Steps:

1. Join the Equinix Labs GitHub organization with your Equinix Single Sign-On:

• Equinix SSO
  • You may need to the verify networking settings
  • You may need to Enable SSO on your SSH key
• Make your membership public, if you like:
  • Equinix-Labs Org Members
• If the organization is not “equinix-labs”, “equinix”, etc, you may need to authorize the org first: Select an Organization

1. Review the guidelines offered above (Steps 5-7)

2. Join the Equinix-labs Terraform team

• Let an existing member of the team know that you’ve requested access so that they can approve your request.

1. Review then merge PRs