How equinix-labs/terraform-equinix-kubernetes-cluster works
Project type and purpose
• This is a Terraform Infrastructure-as-Code (IaC) module (“terraform-equinix-kubernetes-cluster”) whose purpose is to provision and bootstrap a Kubernetes cluster on Equinix Metal.
• It’s not an application codebase but a declarative blueprint that uses Terraform providers (equinix, local, null, tls) to allocate physical machines, configure them with cloud-init, and run kubeadm.
File structure
• Top-level files:
• main.tf, variables.tf, outputs.tf, versions.tf, terraform.tfvars.example → root Terraform module
• templates/*.tftpl → cloud-init templates for control-plane init/join and worker nodes
• examples/* → runnable examples (e.g., with CNI plugin)
• .github/workflows/*.yml → CI/CD (documentation generation, integration tests, releases)
• pre-commit configuration, linting, changelog, CONTRIBUTING, LICENSE, README
• Patterns:
• Single Terraform module (no nested submodules)
• Resources for Equinix Metal (devices, ports, reserved IPs, BGP sessions)
• Local and null providers used to manage SSH keys, wait for cloud-init, copy kubeconfig
• Build/deploy scripts: Terraform CLI is the entrypoint.
Key README insights
• Requires Terraform ≥1.0.0 and Equinix Metal API token/project/SSH key.
• Boots control plane nodes via kubeadm, optionally installs a CNI plugin (example).
• Outputs VIP, kubeconfig, SSH keypair, and cloud-init completion.
• Emphasizes cloud-init usage and null_resource dependencies to sequence bootstrap.
Main components and relationships
a. Terraform CLI (User)
→ invokes Terraform init/plan/apply using root module
b. Terraform Root Module
→ providers: equinix (Metal API), local (writes files), null (provisioner triggers), tls (SSH keys)
→ resources:
• equinix_metal_device (control-plane nodes & workers)
• equinix_metal_port (network ports)
• equinix_metal_reserved_ip_block (VIP block)
• equinix_metal_bgp_session (BGP for VIP announcement)
• tls_private_key / local_sensitive_file (SSH keypair)
• null_resource.wait_for_cloud_init → polls nodes until cloud-init finishes
• null_resource.kubeconfig → pulls kubeconfig to local machine
c. Equinix Metal API
← called by equinix provider to create devices and network resources
d. Physical Metal Devices
→ cloud-init templates applied:
• control-plane init (kubeadm init + kube-vip for HA)
• control-plane join (if HA >1)
• worker join via kubeadm
→ Kubernetes cluster forms (CP nodes advertise BGP VIP, workers join)
e. Optional CNI plugin
• Deployed by example module: flannel, calico, etc.
f. Local machine artifacts
• kubeconfig file written by null_resource.kubeconfig
• SSH key pair output
Architectural patterns and principles
• Declarative IaC: Terraform manages full lifecycle.
• Immutable provisioning: cloud-init to bootstrap OS and Kubernetes.
• Sequence enforcement via null_resource dependencies.
• Logical separation of concerns: networking (BGP, reserved IP), compute (devices), control-plane vs workers, bootstrap logic.
Final advice
• Be exhaustive: include all providers, major resource types, bootstrap steps.
• Arrowheads show the direction of calls or data flow.
• Connection with the Terraform resource name or action for clarity.
• Avoid clutter: group related resources (all equinix_metal_* under a “Network & Devices” block).