Skip to content

Latest commit

 

History

History
134 lines (104 loc) · 7.85 KB

terraform-modules.md

File metadata and controls

134 lines (104 loc) · 7.85 KB
Raw

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

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:
  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

  • 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

Steps:

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

  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