# kalenarndt/terraform-vsphere-vcsa-deploy architecture

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

- Interactive diagram: https://gitdiagram.com/kalenarndt/terraform-vsphere-vcsa-deploy
- Repository: https://github.com/kalenarndt/terraform-vsphere-vcsa-deploy

## Overview

##### Project type and purpose
- This is an open-source Terraform module whose sole purpose is to automate the deployment of a VMware vCenter Server Appliance (VCSA) on either an ESXi host or inside an existing vCenter.
- It leverages Terraform’s provider/plugin architecture to interact with the VMware vSphere APIs (through the “vsphere” provider), and uses the “local” and “null” providers to manipulate local files and execute the VCSA installer binary.

##### File structure
- Top-level HCL files: main.tf, variables.tf, providers.tf, output.tf → define the module’s inputs, providers, resources and outputs.
- JSON templates in vcsa-esxi.json.tmpl and vcsa-vc.json.tmpl → used to feed the installer with a JSON config.
- examples/ directory → contains sample YAML maps and Terraform root modules that demonstrate how to invoke this module for ESXi or vCenter.
- No nested sub-modules; it is a single self-contained module.

##### Key insights from the README
- Describes how to consume the module (passing in a YAML file that is decoded to a Terraform map).
- Explains the required inputs (binaries_path, network settings, credentials, etc.).
- Shows that two null_resource blocks run either the Linux or Windows VCSA deployment binary using the JSON template.
- Outlines outputs that surface the deployed appliance’s IP, FQDN, root user, and SSO user credentials.

##### Components
a. User / Operator
- Interacts with Terraform CLI (init, plan, apply).
- Supplies:
- YAML deployment map (examples/…yaml)
- VCSA installer binaries (binaries_path).
b. Terraform Core
- HCL engine that parses .tf files, variables.tf, providers.tf.
- Providers invoked:
- vsphere provider → communicates with ESXi or vCenter API
- local provider → writes JSON template file (local_file.vcsa_template_to_json)
- null provider → executes the deployment binary (null_resource.vcsa_linux_deploy or vcsa_windows_deploy).
c. JSON Template Generator
- Takes HCL variables + decoded YAML → produces JSON config file for the VCSA installer.
d. VCSA Installer Binary
- Two paths: Linux binary (appliance installer) or Windows binary.
- Consumes JSON template, contacts target (ESXi host or vCenter) over API to push and configure the appliance VM.
e. VMware Infrastructure
- ESXi host or vCenter Server cluster/Datacenter.
- Network and datastore objects where the appliance VM gets deployed.
f. Outputs back into Terraform state
- module outputs (IP, FQDN, passwords).

##### Relationships & interactions
- Operator → Terraform CLI → Terraform Core
- Terraform Core → reads YAML map; passes variables into module
- Terraform Core(local provider) → writes JSON template → disk
- Terraform Core(null provider) → invokes installer binary → network → ESXi or vCenter API
- vSphere provider → API calls to create VM from template, customize OS, set networking
- Results flow back → Terraform state → outputs reported to user

##### Architectural patterns & design principles
- Infrastructure as Code module pattern
- Clear separation of concerns:
- HCL for config and orchestration
- JSON templating for installer config
- Null/local providers for external program execution and file I/O
- Idempotent resource model: Terraform tracks state, only re-runs deployment when needed.

##### Technologies & frameworks
- Terraform (HCL)
- VMware vSphere provider (Terraform plugin)
- HashiCorp local and null providers
- JSON template files
- YAML maps for input data
- VMware VCSA appliance binaries

##### Final advice
- Be exhaustive: capture each Terraform resource, the flow from input YAML to final VM.
- Do not overthink grouping; show every module, provider, resource and external interface as its own node.
- This level of detail will give stakeholders a crystal-clear view of how the module wires together to deploy VCSA.

## Diagram (Mermaid)

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

    %% Core Layer
    TerraformCLI -->|"init, plan, apply"| TerraformCore["Terraform Core (HCL Engine)"]:::core

    subgraph "Terraform Module Core"
        direction TB
        MainTF["main.tf"]:::coreFile
        VariablesTF["variables.tf"]:::coreFile
        ProvidersTF["providers.tf"]:::coreFile
        OutputTF["output.tf"]:::coreFile
    end

    TerraformCore -->|"parses .tf files"| MainTF
    TerraformCore --> VariablesTF
    TerraformCore --> ProvidersTF
    TerraformCore --> OutputTF

    click MainTF "https://github.com/kalenarndt/terraform-vsphere-vcsa-deploy/blob/master/main.tf"
    click VariablesTF "https://github.com/kalenarndt/terraform-vsphere-vcsa-deploy/blob/master/variables.tf"
    click ProvidersTF "https://github.com/kalenarndt/terraform-vsphere-vcsa-deploy/blob/master/providers.tf"
    click OutputTF "https://github.com/kalenarndt/terraform-vsphere-vcsa-deploy/blob/master/output.tf"

    %% Providers
    ProvidersTF --> VsphereProv["vsphere provider"]:::provider
    ProvidersTF --> LocalProv["local provider"]:::provider
    ProvidersTF --> NullProv["null provider"]:::provider

    %% Artifacts & Generators
    subgraph "JSON Template Generator"
        direction TB
        VCSEsiTmpl["vcsa-esxi.json.tmpl"]:::artifact
        VCSVcTmpl["vcsa-vc.json.tmpl"]:::artifact
    end

    click VCSEsiTmpl "https://github.com/kalenarndt/terraform-vsphere-vcsa-deploy/blob/master/vcsa-esxi.json.tmpl"
    click VCSVcTmpl "https://github.com/kalenarndt/terraform-vsphere-vcsa-deploy/blob/master/vcsa-vc.json.tmpl"

    LocalProv -->|"writes JSON"| JSONGen["JSON Template Generator"]:::artifact
    JSONGen --> VCSEsiTmpl
    JSONGen --> VCSVcTmpl

    ArtifactYAML["YAML Deployment Map"]:::artifact
    Operator -->|"supplies YAML"| ArtifactYAML

    %% Installer Binary
    InstallerBin["VCSA Installer Binary"]:::artifact
    ArtifactYAML --> TerraformCore
    NullProv -->|"executes binary"| InstallerBin

    %% VMware Infrastructure
    subgraph "VMware Infrastructure"
        direction TB
        VSAPI["vSphere API\n(ESXi or vCenter)"]:::infra
    end

    InstallerBin -->|"API calls"| VSAPI
    VsphereProv -->|"API calls"| VSAPI

    VSAPI -->|"returns VM info"| TerraformCore
    TerraformCore -->|"updates state"| TFState["Terraform State & Outputs"]:::core

    TFState -->|"outputs IP, FQDN, credentials"| Operator

    %% Examples
    subgraph "Examples"
        direction TB
        ExMapESXi["examples/deploy-vcsa-on-esxi-map/"]:::examples
        ExModESXi["examples/deploy-vcsa-on-esxi/"]:::examples
        ExMapVC["examples/deploy-vcsa-on-vcenter-map/"]:::examples
        ExModVC["examples/deploy-vcsa-on-vcenter/"]:::examples
    end

    click ExMapESXi "https://github.com/kalenarndt/terraform-vsphere-vcsa-deploy/tree/master/examples/deploy-vcsa-on-esxi-map/"
    click ExModESXi "https://github.com/kalenarndt/terraform-vsphere-vcsa-deploy/tree/master/examples/deploy-vcsa-on-esxi/"
    click ExMapVC "https://github.com/kalenarndt/terraform-vsphere-vcsa-deploy/tree/master/examples/deploy-vcsa-on-vcenter-map/"
    click ExModVC "https://github.com/kalenarndt/terraform-vsphere-vcsa-deploy/tree/master/examples/deploy-vcsa-on-vcenter/"

    Operator -->|"references examples"| ExMapESXi
    Operator --> ExModESXi
    Operator --> ExMapVC
    Operator --> ExModVC

    %% Styles
    classDef user fill:#c2f0c2,stroke:#2d662d;
    classDef core fill:#cce5ff,stroke:#33527a;
    classDef provider fill:#99ccff,stroke:#336699;
    classDef artifact fill:#ffe0b3,stroke:#cc8400;
    classDef infra fill:#e5ccff,stroke:#744e9e;
    classDef coreFile fill:#e6f2ff,stroke:#4d88ff;
    classDef examples fill:#f2f2f2,stroke:#999999;
```
