How templatemechanics/pulumi-gcp works
Project Type and Purpose
• This is an open-source, YAML-driven Infrastructure-as-Code (IaC) tool built on Pulumi for Google Cloud Platform (GCP).
• It reads a user’s config.yaml (aka Pulumi.yaml) and dynamically maps definitions into Pulumi GCP resource calls, handling naming conventions, secret resolution, and cross-resource references.
File Structure Analysis
• __main__.py
– Entry point. Parses the YAML file, invokes core orchestration.
• config.py
– Defines dataclasses, loads/parses YAML, and maps entries to Pulumi resource constructors.
• gcpclassic.py
– Encapsulates GCP naming conventions, secret resolution, region-abbr logic, and helper functions for referencing existing resources.
• Pulumi.yaml (aka config.yaml)
– User-supplied YAML describing team, service, environment, labels, and a list of gcp_resources.
• config.py / requirements.txt / Pulumi.yaml / Pulumi state
– Configuration, dependencies, and project metadata for Pulumi.
Key Architectural Insights from README
• Dynamic resource mapping via introspection of pulumi_gcp.
• Use of ref:<resource>.<attribute> syntax for linking resources.
• Custom name-override and secret resolution via Pulumi config.
• Extensible design aimed at adding new resource types or multi-environment support.
Components
a. Front-End:
• User-defined YAML config (Pulumi.yaml)
b. Orchestration Layer:
• __main__.py (CLI entrypoint)
• config.py (Parser & mapper)
• gcpclassic.py (Naming & helper logic)
c. Pulumi Engine:
• Pulumi Python SDK (pulumi, pulumi_gcp modules)
• State management (local or remote backend)
d. External System / Cloud Provider:
• GCP APIs (Compute, SQL, Networking, etc.)
• Secret store via Pulumi config
e. Optional Metadata:
• Dependency resolution graph (auto-generated by Pulumi)
Relationships and Data Flow
1. User runs pulumi up → triggers __main__.py
2. __main__.py loads Pulumi config (secrets, region)
3. config.py parses YAML into internal dataclasses
4. gcpclassic.py applies naming conventions & resolves ref: and secret: tokens
5. For each resource entry, invoke Pulumi GCP SDK to create or fetch resources
6. Pulumi Engine communicates with GCP APIs, records state in backend
7. Pulumi outputs resource attributes back to the user/CLI
Architectural Patterns and Principles
• Modular separation: parsing (config.py), business logic (gcpclassic.py), orchestration (__main__.py)
• Dependency injection: dataclasses decouple YAML schema from Pulumi calls
• Dynamic introspection: uses Pulumi’s provider metadata rather than hard-coding resources
• Convention-over-configuration: naming conventions reduce boilerplate
• Extensibility points: new YAML templates, additional helper functions in gcpclassic.py
Coverage of Essential Elements
• YAML config source, code modules, Pulumi engine, and external GCP services.
• Secret resolution path (YAML secret token → Pulumi config → runtime injection).