# equinix-labs/terraform-equinix-kubernetes-cluster architecture

> Architecture diagram of the GitHub repository equinix-labs/terraform-equinix-kubernetes-cluster, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/equinix-labs/terraform-equinix-kubernetes-cluster
- Repository: https://github.com/equinix-labs/terraform-equinix-kubernetes-cluster

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    User["User / Terraform CLI"]:::user

    %% Terraform Module
    subgraph "Terraform Root Module"
        TFModule["Root Module"]:::terraform
        Providers["Providers:\nequinix, local, null, tls"]:::terraform
        subgraph "Resources"
            Devices["equinix_metal_device"]:::resource
            Ports["equinix_metal_port"]:::resource
            IPBlock["equinix_metal_reserved_ip_block"]:::resource
            BGP["equinix_metal_bgp_session"]:::resource
            Keys["tls_private_key / local_sensitive_file"]:::resource
            WaitCI["null_resource.wait_for_cloud_init"]:::resource
            KubeCfg["null_resource.kubeconfig"]:::resource
        end
    end

    %% Equinix API
    API["Equinix Metal API"]:::api

    %% Hardware and Templates
    subgraph "Physical Metal Devices"
        Hardware["Hardware"]:::hardware
        subgraph "Control Plane Nodes"
            CPInit["cloud-config-cp-init.tftpl"]:::template
            CPJoin["cloud-config-cp-join.tftpl"]:::template
        end
        subgraph "Worker Nodes"
            WorkerTpl["cloud-config-worker.tftpl"]:::template
        end
    end

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        CP["Control Plane"]:::k8s
        WK["Workers"]:::k8s
    end

    %% Optional CNI Plugin
    CNI["Examples: cluster-with-cni"]:::example

    %% Outputs
    Kubefile["kubeconfig file"]:::output
    SSHKey["SSH keypair"]:::output

    %% Connections
    User -->|"init/plan/apply"| TFModule
    TFModule --> Providers
    TFModule --> Devices
    TFModule --> Ports
    TFModule --> IPBlock
    TFModule --> BGP
    TFModule --> Keys
    TFModule --> WaitCI
    TFModule --> KubeCfg

    Providers -->|"API calls"| API
    Devices -->|"create"| API
    Ports -->|"create"| API
    IPBlock -->|"reserve VIP"| API
    BGP -->|"announce VIP"| API

    API --> Hardware
    Hardware --> CPInit & CPJoin & WorkerTpl
    CPInit -->|"bootstrap via kubeadm"| CP
    CPJoin -->|"join via kubeadm"| CP
    WorkerTpl -->|"join via kubeadm"| WK

    CNI -.->|"deploy addon"| CP
    CNI -.->|"deploy addon"| WK

    KubeCfg -->|"writes"| Kubefile
    Keys -->|"writes"| SSHKey

    %% Click Events
    click TFModule "https://github.com/equinix-labs/terraform-equinix-kubernetes-cluster/blob/main/main.tf"
    click CPInit "https://github.com/equinix-labs/terraform-equinix-kubernetes-cluster/blob/main/templates/cloud-config-cp-init.tftpl"
    click CPJoin "https://github.com/equinix-labs/terraform-equinix-kubernetes-cluster/blob/main/templates/cloud-config-cp-join.tftpl"
    click WorkerTpl "https://github.com/equinix-labs/terraform-equinix-kubernetes-cluster/blob/main/templates/cloud-config-worker.tftpl"
    click CNI "https://github.com/equinix-labs/terraform-equinix-kubernetes-cluster/tree/main/examples/cluster-with-cni/"
    click API "https://github.com/equinix-labs/terraform-equinix-kubernetes-cluster/blob/main/.github/workflows/documentation.yaml"
    click Kubefile "https://github.com/equinix-labs/terraform-equinix-kubernetes-cluster/blob/main/outputs.tf"
    click Keys "https://github.com/equinix-labs/terraform-equinix-kubernetes-cluster/blob/main/versions.tf"

    %% Styles
    classDef user fill:#a2f497,stroke:#333,stroke-width:1px;
    classDef terraform fill:#7afcff,stroke:#333,stroke-width:1px;
    classDef resource fill:#b3e6ff,stroke:#333,stroke-width:1px;
    classDef api fill:#87ceeb,stroke:#333,stroke-width:2px;
    classDef hardware fill:#d3d3d3,stroke:#333,stroke-width:1px;
    classDef template fill:#fff2b3,stroke:#333,stroke-width:1px;
    classDef k8s fill:#e6ccff,stroke:#333,stroke-width:1px;
    classDef example fill:#f0a3ff,stroke:#333,stroke-width:1px,stroke-dasharray:5 5;
    classDef output fill:#ffddb3,stroke:#333,stroke-width:1px;
```
