# terraform-google-modules/terraform-google-network architecture

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

- Interactive diagram: https://gitdiagram.com/terraform-google-modules/terraform-google-network
- Repository: https://github.com/terraform-google-modules/terraform-google-network

## Overview

##### Project Type and Purpose
- This is an open-source Terraform module (“terraform-google-network”) for provisioning and managing GCP VPC networks (and related resources) in a modular, reusable fashion.
- It defines a “root” module (main.tf + variables.tf + outputs.tf) which delegates to a number of sub-modules (vpc, subnets, routes, firewall-rules, etc.).
- It also includes examples, tests (unit-style fixtures and Go-based integration tests), CI/CD configuration (GitHub Actions, Cloud Build), and documentation.

##### Top-Level Components
a. Core Module
- main.tf, variables.tf, outputs.tf, metadata.yaml – orchestrates creation of a VPC and its subcomponents
- helpers/ (e.g. migrate.py) – scripts supporting module lifecycle or migrations
b. Sub-Modules (modules/)
- vpc
- subnets & subnets-beta
- routes & routes-beta
- firewall-rules
- network-firewall-policy
- hierarchical-firewall-policy
- private-service-connect
- vpc-serverless-connector-beta
- network-connectivity-center
Each encapsulates one logical resource group, with its own inputs, outputs, versions, metadata.
c. Examples (examples/)
- A series of folders demonstrating different use cases (basic_auto_mode, basic_custom_mode, firewall_logging, multi_vpc, etc.).
- Each contains its own Terraform configs: main.tf, variables.tf, outputs.tf, versions.tf.
d. Testing
- test/fixtures – Terraform snippets and expected outputs for unit-style validation.
- test/integration – Go test suites invoking Terraform to spin up real infrastructure in GCP.
- test/setup – supporting Terraform stack for integration harness (IAM, service account, etc.).
e. CI/CD
- .github/workflows/*.yaml – lint, stale-issue automation, release automation, renovate config.
- build/*.cloudbuild.yaml & Makefile – Cloud Build pipelines for linting, validation, release.
f. Documentation & Governance
- README.md, docs/, CHANGELOG.md, CONTRIBUTING.md, CODEOWNERS, LICENSE.

##### External Dependencies & Data Flows
- Terraform CLI interacts with the Google Cloud Terraform Provider to make GCP API calls (Compute Engine, VPC, IAM).
- CI pipelines (GitHub Actions / Cloud Build) run Terraform commands and tests, report back to GitHub.
- Tests (Go) invoke Terraform, read outputs, verify expectations.
- Examples demonstrate consumption of the published module (registry source).

##### Key Architectural Patterns
- Modular decomposition: each sub-module encapsulates one GCP resource.
- Layered abstraction: root module composes sub-modules; examples consume root module.
- Test-as-code: fixtures for unit tests; integration tests in Go.
- GitOps/CI-as-code: YAML pipelines for linting, testing, release management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Terraform Code Components
    subgraph "Terraform Code" 
        direction TB
        subgraph "Core Module"
            direction TB
            CM_main["main.tf"] 
            CM_vars["variables.tf"] 
            CM_out["outputs.tf"] 
            CM_meta["metadata.yaml"] 
            CM_migrate["migrate.py"] 
        end
        subgraph "Sub-Modules"
            direction TB
            VPC["vpc"]
            Subnets["subnets"]
            Routes["routes"]
            Firewall["firewall-rules"]
        end
        Examples["Examples"]
    end

    %% Testing
    subgraph "Testing" 
        direction TB
        Fixtures["Test Fixtures"]
        Integration["Integration Tests"]
        Setup["Integration Setup"]
    end

    %% CI/CD
    subgraph "CI/CD Pipelines"
        direction TB
        GHActions["GitHub Actions"]
        CloudBuild["Cloud Build"]
        Makefile["Makefile"]
    end

    %% External
    subgraph "External"
        direction TB
        TerraformCLI["Terraform CLI"]
        GProvider["Google Terraform Provider"]
        GCP["GCP APIs"]
    end

    %% Relationships
    CM_main -->|calls| VPC
    CM_main -->|calls| Subnets
    CM_main -->|calls| Routes
    CM_main -->|calls| Firewall
    CM_main -->|uses| Examples

    Fixtures -->|validates via terraform plan| CM_main
    Integration -->|executes apply/destroy via Terraform CLI| TerraformCLI
    TerraformCLI -->|uses provider| GProvider
    GProvider -->|calls APIs| GCP

    GHActions -->|runs| Fixtures
    GHActions -->|runs| Integration
    GHActions -->|runs| Examples
    GHActions -->|reports to| GHActions

    CloudBuild -->|runs| Fixtures
    CloudBuild -->|runs| Integration
    CloudBuild -->|runs| Examples
    CloudBuild -->|reports to| GHActions

    Makefile -->|invokes| CloudBuild
    Makefile -->|invokes| GHActions

    %% Click Events
    click CM_main "https://github.com/terraform-google-modules/terraform-google-network/blob/main//main.tf"
    click CM_vars "https://github.com/terraform-google-modules/terraform-google-network/blob/main//variables.tf"
    click CM_out "https://github.com/terraform-google-modules/terraform-google-network/blob/main//outputs.tf"
    click CM_meta "https://github.com/terraform-google-modules/terraform-google-network/blob/main//metadata.yaml"
    click CM_migrate "https://github.com/terraform-google-modules/terraform-google-network/blob/main//helpers/migrate.py"

    click VPC "https://github.com/terraform-google-modules/terraform-google-network/tree/main//modules/vpc/"
    click Subnets "https://github.com/terraform-google-modules/terraform-google-network/tree/main//modules/subnets/"
    click Routes "https://github.com/terraform-google-modules/terraform-google-network/tree/main//modules/routes/"
    click Firewall "https://github.com/terraform-google-modules/terraform-google-network/tree/main//modules/firewall-rules/"

    click Examples "https://github.com/terraform-google-modules/terraform-google-network/tree/main//examples/"

    click Fixtures "https://github.com/terraform-google-modules/terraform-google-network/tree/main//test/fixtures/"
    click Integration "https://github.com/terraform-google-modules/terraform-google-network/tree/main//test/integration/"
    click Setup "https://github.com/terraform-google-modules/terraform-google-network/tree/main//test/setup/"

    click GHActions "https://github.com/terraform-google-modules/terraform-google-network/tree/main//.github/workflows/"
    click CloudBuild "https://github.com/terraform-google-modules/terraform-google-network/tree/main//build/"
    click Makefile "https://github.com/terraform-google-modules/terraform-google-network/tree/main//Makefile"

    %% Styles
    classDef tf fill:#aed6f1,stroke:#1f618d,color:#1f618d
    classDef testing fill:#a9dfbf,stroke:#196f3d,color:#196f3d
    classDef ci fill:#f5b041,stroke:#b9770e,color:#b9770e
    classDef external fill:#d7dbdd,stroke:#909497,color:#909497
    class CM_main,CM_vars,CM_out,CM_meta,CM_migrate,VPC,Subnets,Routes,Firewall,Examples tf
    class Fixtures,Integration,Setup testing
    class GHActions,CloudBuild,Makefile ci
    class TerraformCLI,GProvider,GCP external
```
