# templatemechanics/pulumi-azure architecture

> Architecture diagram of the GitHub repository templatemechanics/pulumi-azure, 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/templatemechanics/pulumi-azure
- Repository: https://github.com/templatemechanics/pulumi-azure

## Overview

##### Project Type and Purpose
- This is a CLI‐driven, open-source infrastructure-as-code tool built on Pulumi for provisioning Azure resources via a YAML configuration. It dynamically maps YAML entries to Pulumi Azure Native resource classes, applies naming conventions, resolves secrets, and orchestrates resource creation or import.

##### File Structure
- __main__.py: Entry point invoked by the Pulumi CLI (`pulumi up`).
- config.py: Dataclasses for YAML parsing and dynamic mapping to Pulumi resource classes.
- azurenative.py: Azure-specific logic—naming standards, abbreviations, secret resolution, and helpers for existing vs. new resources.
- config.yaml (user-supplied): Defines team, service, environment, location, tags, and a list of Azure resources with attributes.
- Pulumi.*.yaml & requirements.txt: Pulumi stack config and Python dependencies.
- LICENSE, README.MD, .gitignore: Project metadata.

##### README Insights
- Describes features: YAML-defined infra, dynamic resource mapping, naming conventions, region abbreviations, resource referencing, secret resolution.
- Shows usage flow: `pulumi login` → `stack init` → `config set` → `pulumi up`.
- Emphasizes extensibility and possible enhancements.

##### Main Components
a. User / CLI Layer
- Pulumi CLI (invokes __main__.py).
- YAML configuration files & Pulumi stack config.
b. Application Layer
- Entry Point (__main__.py): orchestrates parse → validation → resource instantiation.
- Config Module (config.py):
- Parses YAML → dataclasses
- Maps each resource spec to the appropriate Pulumi Azure Native class via reflection.
- Azure Logic Module (azurenative.py):
- Applies naming conventions
- Resolves secrets (`secret:<key>`) from Pulumi config
- Handles existing vs. new resource logic.
c. Pulumi Engine
- Pulumi Python SDK: translates code into resource operations (create, import).
- Pulumi Core: plans and applies to targeted cloud provider.
d. Cloud Provider
- Azure Resource Manager (REST API): receives ARM calls for resource provisioning.
- Azure Resources: ResourceGroup, VirtualNetwork, Subnet, SqlServer, etc.
e. External Systems
- Pulumi Service/Backend (state storage, optional).
- Secret Store (Pulumi’s encrypted config).

##### Relationships and Interactions
- CLI → __main__.py (start of Python app)
- __main__.py → config.py (YAML parse & mapping)
- __main__.py → azurenative.py (apply naming, secret resolution)
- Application → Pulumi SDK (generate resource definitions)
- Pulumi SDK → Azure Resource Manager (deploy/import resources)
- Azure RM → Azure Resources (actual provisioning)
- Pulumi Core → Pulumi Service (state management)

##### Architectural Patterns & Principles
- Separation of Concerns: parsing, mapping, naming, SDK interaction each in its own module.
- Plugin-style Reflection: dynamic discovery of Pulumi resource classes.
- Declarative Configuration: YAML as the single source of truth.
- Extensible Core: new resources automatically supported via the Azure Native SDK.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Local Machine"
        User["User"]:::external
        PulumiCLI["Pulumi CLI"]:::platform
        subgraph "Configuration Files"
            ConfigYAML["config-start.yaml"]:::file
            PulumiDev["Pulumi.dev.yaml"]:::file
            PulumiProj["Pulumi.yaml"]:::file
        end
        subgraph "Project Code"
            Entry["__main__.py"]:::code
            ConfigMod["config.py"]:::code
            AzureLogic["azurenative.py"]:::code
            Req["requirements.txt"]:::file
            Readme["README.MD"]:::file
            License["LICENSE"]:::file
            Gitignore[".gitignore"]:::file
        end
    end

    subgraph "Pulumi Layer"
        PulumiSDK["Pulumi Python SDK"]:::platform
        PulumiCore["Pulumi Core"]:::platform
        PulumiService["Pulumi Service"]:::platform
    end

    subgraph "Cloud Provider"
        AzureRM["Azure Resource Manager (ARM API)"]:::platform
        subgraph "Azure Resources"
            Resources["ResourceGroup, VNet, Subnet, SqlServer, etc"]:::cloud
        end
    end

    %% Connections
    User -->|"invokes"| PulumiCLI
    PulumiCLI -->|"runs entry point"| Entry
    Entry -->|"parse & mapping"| ConfigMod
    Entry -->|"apply naming & secrets"| AzureLogic
    Entry -->|"generate resource defs"| PulumiSDK
    PulumiSDK -->|"deploy/import"| AzureRM
    AzureRM -->|"provision"| Resources
    PulumiCore <-->|"state management"| PulumiService

    %% Click Events
    click Entry "https://github.com/templatemechanics/pulumi-azure/blob/main/__main__.py"
    click ConfigMod "https://github.com/templatemechanics/pulumi-azure/blob/main/config.py"
    click AzureLogic "https://github.com/templatemechanics/pulumi-azure/blob/main/azurenative.py"
    click ConfigYAML "https://github.com/templatemechanics/pulumi-azure/blob/main/config-start.yaml"
    click PulumiDev "https://github.com/templatemechanics/pulumi-azure/blob/main/Pulumi.dev.yaml"
    click PulumiProj "https://github.com/templatemechanics/pulumi-azure/blob/main/Pulumi.yaml"
    click Req "https://github.com/templatemechanics/pulumi-azure/blob/main/requirements.txt"
    click Readme "https://github.com/templatemechanics/pulumi-azure/blob/main/README.MD"
    click License "https://github.com/templatemechanics/pulumi-azure/tree/main/LICENSE"
    click Gitignore "https://github.com/templatemechanics/pulumi-azure/blob/main/.gitignore"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef platform fill:#DFFFE0,stroke:#333,stroke-width:1px
    classDef file fill:#FFF4D0,stroke:#333,stroke-width:1px
    classDef cloud fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCFF,stroke:#333,stroke-width:1px
```
