# googlecloudplatform/terraform-google-cloud-run architecture

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

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/terraform-google-cloud-run
- Repository: https://github.com/googlecloudplatform/terraform-google-cloud-run

## Overview

##### Project type and purpose
- This is an open-source Terraform module (Infrastructure-as-Code) for provisioning Cloud Run services on GCP.
- Its core responsibilities are:
- Configure domain mappings
- Apply IAM policies (Cloud Run Invoker)
- Optionally wire in VPC Connectors, Cloud SQL, Secret Manager, CMEK, Org-Policies

##### File-structure analysis
- Top-level:
- main.tf, variables.tf, outputs.tf – the “root” Terraform entrypoint
- modules/… – submodules packaging distinct chunks of functionality:
– secure-cloud-run-core
– secure-cloud-run-security
– secure-serverless-harness
– secure-serverless-net
– job-exec
– service-project-factory
– v2 (parallel versioning)
- examples/… – usage examples invoking the root module with different configurations
- test/… – fixture and integration tests validating module behavior
- build/, docs/, Makefile, CI workflows for linting/testing/releases

##### README insights
- Enumerates resources created: Cloud Run service, Domain mapping, IAM role bindings
- Highlights optional integrations: VPC Access, Cloud SQL, Secret Manager, CMEK, Custom Domains
- Declares dependencies: Terraform v1.3+, GCP provider, optional beta provider

a. Main components
– Terraform CLI/Workflow (Terraform binary, state, plan/apply)
– Root module (entrypoint)
– Submodules (each implements a slice of functionality)
– GCP APIs/Services:
- Cloud Run
- IAM
- Serverless VPC Access
- Cloud SQL
- Secret Manager
- Cloud DNS / Cloud Domains (for custom-domain mapping)
– Example harness (gcloud/Inspec tests)
b. Relationships & interactions
1. Operator runs `terraform init/plan/apply` → Terraform CLI reads root module → loads submodules
2. Each submodule issues Terraform blocks → GCP provider calls respective REST APIs
3. Cloud Run submodule provisions service → revision / container image deploy
4. Domain-map submodule provisions custom-domain mapping → DNS verification step
5. IAM submodule binds `roles/run.invoker` to service account or members list
6. Optional modules: VPC connector attached to revision, Cloud SQL connection annotation, CMEK key referencing KMS
7. Test harness invokes gcloud & Inspec to verify end-state
c. Architectural patterns & design principles
– Module composition: root module delegates to small, focused submodules
– Optionality via variables & count/for-each meta-arguments
– Separation of concerns: security, networking, compute, project-factory each isolated
– Versioning patterns: parallel “v2” modules for incremental API version support
d. Key technologies / frameworks
– Terraform core, GCP Terraform Provider, GCP Beta Provider
– Google Cloud Run, Serverless VPC Access, Cloud SQL, Secret Manager, Cloud DNS, KMS, IAM

## Diagram (Mermaid)

```mermaid
flowchart TD
    TerraformCLI["Terraform CLI\n(init, plan, apply)"]:::terraform
    StateStore["Terraform State\n(GCS backend)"]:::terraform

    RootModule["Root Module\n(main.tf, variables.tf, outputs.tf)"]:::terraform
    click RootModule "https://github.com/googlecloudplatform/terraform-google-cloud-run/blob/main//main.tf"

    subgraph "Compute (Cloud Run)"
        SCRCore["secure-cloud-run-core\n(main.tf, loadbalancer.tf)"]:::compute
        click SCRCore "https://github.com/googlecloudplatform/terraform-google-cloud-run/blob/main//modules/secure-cloud-run-core/main.tf"
    end

    subgraph "Security"
        SCRSec["secure-cloud-run-security\n(iam.tf, kms.tf, org_policies.tf)"]:::security
        click SCRSec "https://github.com/googlecloudplatform/terraform-google-cloud-run/blob/main//modules/secure-cloud-run-security/iam.tf"
    end

    subgraph "Networking"
        SSNet["secure-serverless-net\n(network.tf, firewall.tf, iam.tf)"]:::network
        click SSNet "https://github.com/googlecloudplatform/terraform-google-cloud-run/blob/main//modules/secure-serverless-net/network.tf"
    end

    subgraph "Test Harness"
        SSHarness["secure-serverless-harness\n(main.tf, network.tf, private_service_connect.tf, service_perimeter.tf)"]:::terraform
        click SSHarness "https://github.com/googlecloudplatform/terraform-google-cloud-run/blob/main//modules/secure-serverless-harness/main.tf"
    end

    subgraph "Batch/Job Execution"
        JobExec["job-exec\n(main.tf)"]:::terraform
        click JobExec "https://github.com/googlecloudplatform/terraform-google-cloud-run/blob/main//modules/job-exec/main.tf"
    end

    subgraph "Project Factory"
        ProjFact["service-project-factory\n(main.tf)"]:::terraform
        click ProjFact "https://github.com/googlecloudplatform/terraform-google-cloud-run/blob/main//modules/service-project-factory/main.tf"
    end

    subgraph "v2 Versioning"
        V2["v2\n(main.tf)"]:::terraform
        click V2 "https://github.com/googlecloudplatform/terraform-google-cloud-run/blob/main//modules/v2/main.tf"
    end

    Examples["Examples\n(/examples/*)"]:::terraform
    click Examples "https://github.com/googlecloudplatform/terraform-google-cloud-run/blob/main//examples/secure_cloud_run/main.tf"

    IntTests["Integration Tests\n(/test/integration)"]:::terraform
    click IntTests "https://github.com/googlecloudplatform/terraform-google-cloud-run/blob/main//test/integration/simple_cloud_run/controls/gcloud.rb"

    FixtureTests["Fixture Tests\n(/test/fixtures)"]:::terraform
    click FixtureTests "https://github.com/googlecloudplatform/terraform-google-cloud-run/blob/main//test/fixtures/simple_cloud_run/main.tf"

    CI["CI & Build\n(/build/*, /.github/workflows)"]:::terraform
    click CI "https://github.com/googlecloudplatform/terraform-google-cloud-run/blob/main//build/int.cloudbuild.yaml"

    CloudRun["Cloud Run API"]:::compute
    IAMAPI["IAM API"]:::security
    VPCAccess["Serverless VPC Access API"]:::network
    CloudSQL["Cloud SQL"]:::optional
    SecretMgr["Secret Manager"]:::optional
    DNS["Cloud DNS / Domains"]:::network
    KMS["Cloud KMS"]:::security

    TerraformCLI --> RootModule
    TerraformCLI --> StateStore

    RootModule --> SCRCore
    RootModule --> SCRSec
    RootModule --> SSNet
    RootModule --> SSHarness
    RootModule --> JobExec
    RootModule --> ProjFact
    RootModule --> V2
    RootModule -.-> CloudSQL
    RootModule -.-> SecretMgr

    SCRCore -->|"deploy service"| CloudRun
    SCRSec -->|"bind roles/run.invoker"| IAMAPI
    SCRSec -->|"reference key"| KMS
    SSNet -->|"attach connector"| VPCAccess
    SSNet -->|"DNS config"| DNS
    SSNet -->|"network IAM"| IAMAPI
    SSHarness -->|"validate network"| VPCAccess
    JobExec -->|"execute jobs"| CloudRun
    ProjFact -->|"provision project"| CloudRun
    V2 -->|"v2 deploy"| CloudRun
    DNS -->|"verify domain"| CloudRun

    Examples --> TerraformCLI
    IntTests --> TerraformCLI
    IntTests --> CloudRun
    CI --> TerraformCLI

    classDef terraform fill:#D6EAF8,stroke:#1B4F72,color:#000
    classDef compute fill:#D5F5E3,stroke:#1D8348,color:#000
    classDef network fill:#FCF3CF,stroke:#B7950B,color:#000
    classDef security fill:#FADBD8,stroke:#C0392B,color:#000
    classDef optional fill:#E5E8E8,stroke:#566573,color:#000
```
