# roblox/nomad-driver-iis architecture

> Architecture diagram of the GitHub repository roblox/nomad-driver-iis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/roblox/nomad-driver-iis
- Repository: https://github.com/roblox/nomad-driver-iis

## Overview

##### Project Type and Purpose
- This is a Go-based Nomad task driver plugin named “nomad-driver-iis.”
- Its purpose is to let HashiCorp Nomad orchestrate Windows IIS websites, where each allocation results in a new IIS application pool and site named after the allocation GUID.

##### File Structure
Top-level directories and files:
- main.go – plugin entrypoint, registers the driver with Nomad.
- go.mod / go.sum – declares this as a Go module.
- iis/ – core Go package containing:
– driver.go – implements Nomad’s Driver interface.
– handle.go – logic to handle start/stop/task operations.
– state.go – in-memory tracking of allocation state.
– iis.go – wrappers around Windows IIS API calls.
– iis_test.go – unit tests for IIS interactions.
- examples/ – sample Nomad job specs (.nomad) illustrating driver usage.
- scripts/win_provision.ps1 – PowerShell script used to provision Windows VM for integration tests.
- test/ – sample cert, site and pool XML, HCL for integration tests.
- Vagrantfile – spins up Windows VM using VirtualBox & Vagrant for CI.
- .github/workflows – CI pipelines for tests and CLA checks.
- Makefile – build, test, clean, and converge targets.

##### README for Additional Insights
- Describes driver and task config options (stats_interval, path, bindings, SSL).
- Explains how it uses XML site/app pool config imports.
- Notes use of environment variables for IIS 10+ and meta-env vars for credentials.
- Provides build/test instructions leveraging Vagrant VM and Nomad CLI.
- Mentions CI via GitHub Actions.

##### Detail
- Layer: Nomad scheduler, client agent, driver code packages, OS interface, IIS service.
- Explicitly show how configs and secrets flow into the driver.
- Don’t hesitate to break the IIS block into subcomponents (AppHost, Binding Manager, Certificate store).
- Call out test automation paths separately but clearly.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Nomad Components
    subgraph "Nomad Infrastructure" 
        direction TB
        NS["Nomad Server & Scheduler"]:::core
        NC["Nomad Windows Client (Agent)"]:::core
    end

    %% Plugin Executable and Code
    subgraph "nomad-driver-iis Plugin" 
        direction TB
        ME["Plugin Entrypoint\nmain.go"]:::core
        GM["Go Module Files\ngo.mod, go.sum"]:::config
        subgraph "Core IIS Package"
            direction TB
            DI["Driver Interface\nimplementation\niis/driver.go"]:::core
            HA["Task Orchestration Logic\niis/handle.go"]:::core
            ST["In-Memory State Management\niis/state.go"]:::core
            IW["Windows IIS API Wrappers\niis/iis.go"]:::core
            UT["IIS Unit Tests\niis/iis_test.go"]:::test
        end
    end

    %% Windows Host and IIS
    subgraph "Windows Host Environment" 
        direction TB
        OS["Windows Operating System"]:::infra
        IIS["IIS Service\nApplicationHost"]:::core
        FS["File System\nSite & AppPool XML"]:::infra
        SEC["Environment & Secrets\n(Meta-env, Vault/Consul)"]:::config
    end

    %% Configuration Artifacts
    subgraph "Configuration Artifacts" 
        direction TB
        EX1["Example Job Spec\niis-test.nomad"]:::config
        EX2["Example Job Spec\niis-test-classic.nomad"]:::config
    end

    %% CI Workflow
    subgraph "CI & Testing" 
        direction TB
        GH1["CLA Bot Check\n.github/workflows/clabot.yml"]:::infra
        GH2["Driver Test Pipeline\n.github/workflows/test-driver.yml"]:::infra
        VA["Vagrant VM\nVagrantfile"]:::infra
        PS["VM Provisioning Script\nscripts/win_provision.ps1"]:::infra
        TA["Integration Test Artifacts"]:::test
        subgraph "Test Artifacts" 
            direction TB
            TF1["Certificate\ntest/test.pfx"]:::test
            TF2["AppPool XML\ntest/testapppool.xml"]:::test
            TF3["Site XML\ntest/testsite.xml"]:::test
            TF4["Nomad Client HCL\ntest/win_client.hcl"]:::config
        end
    end

    %% Build & Docs
    Make["Makefile"]:::infra
    RD["Project Documentation\nREADME.md"]:::infra
    LI["License File\nLICENSE"]:::infra

    %% Relationships
    NS -->|"allocation request"| NC
    NC -->|"RPC Start/Stop/Stats"| ME
    ME --> DI
    DI --> HA
    HA --> IW
    HA --> ST
    DI --> FS
    DI --> SEC
    IW --> IIS
    IIS --> OS
    DI -->|"PowerShell / COM API"| OS
    DI --> FS
    EX1 --> ME
    EX2 --> ME

    %% CI flows
    GH1 --> VA
    GH2 --> VA
    VA --> PS
    PS --> TA
    TA --> IIS

    %% Build & Docs relations
    Make --> ME
    Make --> UT
    Make --> TA
    RD --> GM
    RD --> EX1
    RD --> EX2

    %% Click Events
    click ME "https://github.com/roblox/nomad-driver-iis/blob/master/main.go"
    click GM "https://github.com/roblox/nomad-driver-iis/blob/master/go.mod"
    click GM "https://github.com/roblox/nomad-driver-iis/blob/master/go.sum"
    click DI "https://github.com/roblox/nomad-driver-iis/blob/master/iis/driver.go"
    click HA "https://github.com/roblox/nomad-driver-iis/blob/master/iis/handle.go"
    click ST "https://github.com/roblox/nomad-driver-iis/blob/master/iis/state.go"
    click IW "https://github.com/roblox/nomad-driver-iis/blob/master/iis/iis.go"
    click UT "https://github.com/roblox/nomad-driver-iis/blob/master/iis/iis_test.go"
    click EX1 "https://github.com/roblox/nomad-driver-iis/blob/master/examples/iis-test.nomad"
    click EX2 "https://github.com/roblox/nomad-driver-iis/blob/master/examples/iis-test-classic.nomad"
    click PS "https://github.com/roblox/nomad-driver-iis/blob/master/scripts/win_provision.ps1"
    click TF1 "https://github.com/roblox/nomad-driver-iis/blob/master/test/test.pfx"
    click TF2 "https://github.com/roblox/nomad-driver-iis/blob/master/test/testapppool.xml"
    click TF3 "https://github.com/roblox/nomad-driver-iis/blob/master/test/testsite.xml"
    click TF4 "https://github.com/roblox/nomad-driver-iis/blob/master/test/win_client.hcl"
    click VA "https://github.com/roblox/nomad-driver-iis/tree/master/Vagrantfile"
    click GH1 "https://github.com/roblox/nomad-driver-iis/blob/master/.github/workflows/clabot.yml"
    click GH2 "https://github.com/roblox/nomad-driver-iis/blob/master/.github/workflows/test-driver.yml"
    click Make "https://github.com/roblox/nomad-driver-iis/tree/master/Makefile"
    click RD "https://github.com/roblox/nomad-driver-iis/blob/master/README.md"
    click LI "https://github.com/roblox/nomad-driver-iis/tree/master/LICENSE"

    %% Styles
    classDef core fill:#2196f3,color:#fff,stroke:#1e88e5,stroke-width:1px;
    classDef config fill:#4caf50,color:#fff,stroke:#388e3c,stroke-width:1px;
    classDef infra fill:#ff9800,color:#fff,stroke:#f57c00,stroke-width:1px;
    classDef test fill:#9c27b0,color:#fff,stroke:#7b1fa2,stroke-width:1px;
```
