# vmware/packer-examples-for-vsphere architecture

> Architecture diagram of the GitHub repository vmware/packer-examples-for-vsphere, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vmware/packer-examples-for-vsphere
- Repository: https://github.com/vmware/packer-examples-for-vsphere

## Overview

##### Project type and purpose
- This is an **open-source example repository** (“Packer Examples for VMware vSphere”) showcasing how to use HashiCorp Packer (with the `vsphere-iso` builder plugin) together with Ansible and Terraform to automate VM image creation and consumption in a VMware vSphere environment.
- It provides:
- A catalog of HCL-based Packer templates for various Linux and Windows guest OSes under `builds/` and `builds/windows/`
- Ansible roles (`ansible/roles/`) for post-install configuration and cleanup
- Terraform modules (`terraform/vsphere-*`) to publish and consume images in vSphere Content Libraries
- CI/CD pipelines (`.github/workflows/`) to lint, test, build images, and publish documentation
- Automated tests (`tests/`) for network and storage configuration

##### File structure
- Top-level directories:
- `.github/` – CI/CD workflows and issue/PR templates
- `ansible/` – Ansible roles: base, clean, configure, users
- `builds/` & `builds/windows/` – Packer templates per OS/version
- `terraform/` – Two modules
– `vsphere-role`: manages vSphere permission/role assignment
– `vsphere-virtual-machine`: subfolders for content-library creations & VM deployments
- `tests/` – Golden-image tests for network/storage scenarios
- `docs/` – MkDocs configuration and markdown assets
- Config and build orchestration:
- `Makefile`, `build.sh`, `download.sh`, `set-envvars.sh`
- Terraform variables/examples under each module
- Ansible inventory via playbooks (`ansible/linux-playbook.yml`, `ansible/windows-playbook.yml`)

##### Extract additional insights from README
- Purpose: help developers, SREs to streamline image builds for vSphere.
- Target: multiple Linux distros & Windows versions.
- All examples are in HCL.
- Docs are auto-published via MkDocs.
- CI triggers lint, test and release pipelines.

a. Main components to include:
1. **Developer Machine / Local Environment**
- Docker‐based devcontainer ( `.devcontainer/` )
- Shell scripts (`build.sh`, `set-envvars.sh`)
2. **Source Repository** (GitHub)
- Code, templates, Ansible roles, Terraform modules, docs
3. **CI/CD Platform** (GitHub Actions)
- Lint jobs (`lint.yml`), build/test jobs (`release.yml`), docs publish (`docs.yml`)
4. **Packer Engine**
- Reads HCL templates (from `builds/`)
- Invokes `vsphere-iso` builder + Ansible provisioner
5. **Ansible Provisioner**
- Executes roles under `ansible/roles/*`
6. **Terraform Engine**
- Uses modules under `terraform/vsphere-role` and `terraform/vsphere-virtual-machine`
- Publishes images to vSphere Content Library and deploys VMs
7. **VMware vSphere Infrastructure**
- ESXi hosts, vCenter, Content Library, Networks, Storage
8. **Test Harness**
- Packer testing with golden images (`tests/network/`, `tests/storage/`)
9. **Documentation Site**
- MkDocs site built from `docs/` and published to GitHub Pages

b. Relationships & interactions:
- **Developer** commits changes → **GitHub** → triggers **CI/CD**
- **CI** runs:
- **Lint** (HCL, markdown, YAML)
- **Test** (Packer test suite on `tests/`)
- **Build**: Packer → Ansible → creates VM images → Terraform → push to vSphere Content Library
- **Docs**: MkDocs → publishes to Docs site
- **Terraform** modules consumed by end users to spin up VMs from published images

c. Architectural patterns & design principles:
- **Infrastructure as Code (IaC)**: Packer + Terraform + Ansible
- **Modularity**:
- Separate templates per OS/version
- Reusable Ansible roles
- Standalone Terraform modules
- **Test-Driven IaC**: Golden image testing before publishing
- **CI/CD** for automated validation, building, and publishing

d. Key technologies & frameworks:
- HashiCorp Packer (`vsphere-iso` builder plugin)
- Ansible (provisioner roles)
- Terraform (vSphere provider)
- GitHub Actions CI
- MkDocs for documentation
- Docker (devcontainer)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer & Repository
    subgraph "Developer & Repo"
        direction TB
        DeveloperMachine["Developer Machine / Local Environment"]:::external
        BuildScript["build.sh"]:::code
        SetEnv["set-envvars.sh"]:::code
        DockerDev[".devcontainer/"]:::code
        SourceRepo["Source Repository (GitHub)"]:::external
        MakefileNode["Makefile"]:::code
        Download["download.sh"]:::code
        Config["config.sh"]:::code
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        CIPlatform["GitHub Actions CI/CD"]:::external
        Lint["Lint Job"]:::process
        Release["Release/Build Job"]:::process
        DocsWF["Docs Publish Job"]:::process
    end

    %% Core IaC Engines
    PackerEngine["Packer Engine"]:::process
    AnsibleProv["Ansible Provisioner"]:::process
    TerraformEngine["Terraform Engine"]:::process
    TestHarness["Test Harness (Golden-Image Tests)"]:::process
    MkDocsSite["MkDocs Documentation Build"]:::process

    %% vSphere Infrastructure
    subgraph "vSphere Infrastructure" 
        direction TB
        vSphereInfra["vSphere ESXi / vCenter / Content Library"]:::external
    end

    %% Documentation Site
    DocumentationSite["Documentation Site (GitHub Pages)"]:::external

    %% Relationships
    DeveloperMachine -->|commits code| SourceRepo
    BuildScript -->|configures env| DeveloperMachine
    SetEnv -->|configures env| DeveloperMachine
    DockerDev --> DeveloperMachine
    MakefileNode --> SourceRepo
    Download --> SourceRepo
    Config --> SourceRepo

    SourceRepo -->|push triggers| CIPlatform
    CIPlatform -->|runs| Lint
    CIPlatform -->|runs| TestHarness
    CIPlatform -->|runs| Release
    CIPlatform -->|runs| DocsWF

    TestHarness -->|tests templates| PackerEngine
    Release -->|build images| PackerEngine
    PackerEngine -->|provision| AnsibleProv
    AnsibleProv -->|generates image| TerraformEngine
    TerraformEngine -->|publishes image| vSphereInfra
    DocsWF -->|build docs| MkDocsSite
    MkDocsSite -->|publish| DocumentationSite

    %% Click Events
    click DeveloperMachine "https://github.com/vmware/packer-examples-for-vsphere/tree/develop/.devcontainer/"
    click BuildScript "https://github.com/vmware/packer-examples-for-vsphere/blob/develop/build.sh"
    click SetEnv "https://github.com/vmware/packer-examples-for-vsphere/blob/develop/set-envvars.sh"
    click DockerDev "https://github.com/vmware/packer-examples-for-vsphere/tree/develop/.devcontainer/"
    click Lint "https://github.com/vmware/packer-examples-for-vsphere/blob/develop/.github/workflows/lint.yml"
    click Release "https://github.com/vmware/packer-examples-for-vsphere/blob/develop/.github/workflows/release.yml"
    click DocsWF "https://github.com/vmware/packer-examples-for-vsphere/blob/develop/.github/workflows/docs.yml"
    click PackerEngine "https://github.com/vmware/packer-examples-for-vsphere/tree/develop/builds/"
    click AnsibleProv "https://github.com/vmware/packer-examples-for-vsphere/tree/develop/ansible/roles/"
    click LinuxPlaybook "https://github.com/vmware/packer-examples-for-vsphere/blob/develop/ansible/linux-playbook.yml"
    click WindowsPlaybook "https://github.com/vmware/packer-examples-for-vsphere/blob/develop/ansible/windows-playbook.yml"
    click TerraformEngine "https://github.com/vmware/packer-examples-for-vsphere/tree/develop/terraform/vsphere-role/"
    click TFVM "https://github.com/vmware/packer-examples-for-vsphere/tree/develop/terraform/vsphere-virtual-machine/"
    click TestsNetwork "https://github.com/vmware/packer-examples-for-vsphere/tree/develop/tests/network/"
    click TestsStorage "https://github.com/vmware/packer-examples-for-vsphere/tree/develop/tests/storage/"
    click MkDocsSite "https://github.com/vmware/packer-examples-for-vsphere/blob/develop/mkdocs.yml"
    click DocumentationSite "https://github.com/vmware/packer-examples-for-vsphere/tree/develop/docs/"
    click MakefileNode "https://github.com/vmware/packer-examples-for-vsphere/tree/develop/Makefile"
    click Download "https://github.com/vmware/packer-examples-for-vsphere/blob/develop/download.sh"
    click Config "https://github.com/vmware/packer-examples-for-vsphere/blob/develop/config.sh"

    %% Styles
    classDef code fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef process fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef external fill:#FFE0B2,stroke:#F57C00,color:#000
```
