Skip to content

real_deployment_architecture.md

Latest commit

 

History

History
100 lines (78 loc) · 5.19 KB

real_deployment_architecture.md

File metadata and controls

100 lines (78 loc) · 5.19 KB
Raw

Real Deployment Architecture (Terraform-Aligned)

Purpose

This document defines the real deployment architecture for the FinOps Assessment Platform based on the current Terraform baseline in infra/terraform/.

1. Runtime Architecture

Cloud Run runtime

  • Implemented: Terraform provisions one Cloud Run v2 service (google_cloud_run_v2_service.runtime) using a prebuilt container image (container_image).
  • Implemented: Runtime sizing and execution controls are configurable (container_concurrency, container_timeout_seconds, container_cpu, container_memory).
  • Planned: Real deployment validation in a non-placeholder GCP project using environment tfvars.

Artifact Registry and container flow

  • Implemented boundary: Terraform expects an image URI and deploys it to Cloud Run.
  • Not yet implemented in Terraform: Artifact Registry repository creation, image build, and image push pipeline.
  • Operational flow (current model): build image externally -> push to Artifact Registry externally -> pass tagged container_image into Terraform -> Cloud Run pulls image at deploy time.

2. IAM Architecture

Service accounts and identity split

  • Implemented: Dedicated runtime service account (google_service_account.runtime) attached to Cloud Run.
  • Implemented: Optional dedicated scheduler invoker service account (google_service_account.scheduler_invoker) when scheduler is enabled.
  • Implemented: Scheduler invoker receives only roles/run.invoker on the Cloud Run service.

Read-only scanning model

  • Implemented: Project-scoped read-only scanner roles are granted to runtime identity for explicit target_projects:
    • roles/compute.viewer
    • roles/monitoring.viewer
    • roles/container.viewer
    • roles/cloudsql.viewer
    • roles/storage.viewer
  • Implemented: Org mode adds discovery-only role roles/resourcemanager.projectViewer at org level.
  • Implemented limitation: Org mode does not auto-propagate scanner roles to discovered projects.

Runtime vs deploy permissions

  • Implemented separation: Runtime identity is distinct from the human/operator identity running Terraform.
  • Planned operational requirement: Operator/deployer permissions remain outside this Terraform module and must be managed separately.

3. Configuration Contract

Terraform input model

  • Implemented: variables.tf defines validated inputs for project, region, runtime behavior, IAM scope, scheduler, and optional secret wiring.
  • Implemented: env/dev.tfvars, env/staging.tfvars, and env/prod.tfvars provide per-environment values and defaults.
  • Implemented: Contract checks enforce scope consistency:
    • target_scope_mode=project requires non-empty target_projects
    • target_scope_mode=org requires target_org_id

Variable-to-runtime environment mapping

Implemented in google_cloud_run_v2_service.runtime:

  • environment -> ENVIRONMENT
  • execution_mode -> EXECUTION_MODE
  • target_scope_mode -> TARGET_SCOPE_MODE
  • target_projects -> TARGET_PROJECTS (comma-separated)
  • target_org_id -> TARGET_ORG_ID
  • log_level -> LOG_LEVEL
  • enable_artifact_storage -> ENABLE_ARTIFACT_STORAGE
  • enable_scheduler -> ENABLE_SCHEDULER
  • runtime_secret_env (optional) -> dynamic secret-backed env vars from Secret Manager

4. Execution Architecture

Triggering model

  • Implemented: Operator-driven execution is primary (manual Terraform run + runtime endpoint invocation).
  • Implemented: Cloud Run endpoint is deploy-time output and supports on-demand execution.
  • Implemented optional extension: Cloud Scheduler can trigger the same Cloud Run path when enable_scheduler=true.
  • Not yet implemented: CI/CD-triggered deployment/execution orchestration.

Scheduler positioning

  • Implemented as optional infrastructure branch only.
  • Environment intent currently encoded in tfvars:
    • dev: scheduler disabled
    • staging: scheduler disabled
    • prod: scheduler enabled

5. Outputs and Consumption

Terraform outputs

Implemented in outputs.tf:

  • cloud_run_service_name
  • cloud_run_service_uri
  • runtime_service_account_email

Expected consumption

  • Implemented usage: Operators use outputs for endpoint invocation and identity verification after apply.
  • Planned/operational: Runtime logs and run diagnostics are consumed from GCP logging during deployment validation.

6. Separation of Concerns

Platform runtime infrastructure

  • Implemented: Cloud Run runtime, runtime IAM, optional scheduler wiring, optional Secret Manager access wiring.

Demo validation resources

  • Not yet implemented in current Terraform baseline: Demo waste resources (for example stopped VM, unattached disk, unused IP) are not provisioned in infra/terraform.
  • Planned for Phase 7 scope: Demo validation environment should be handled explicitly and separately from runtime deployment resources.

7. Current State Summary

  • Implemented now: Core deployment baseline for running the platform on Cloud Run with read-only scanning IAM.
  • Planned next: Replace placeholders, apply in real project(s), and perform Phase 7 real deployment validation.
  • Not yet implemented: Artifact Registry provisioning/build pipeline, demo validation infra resources, CI/CD automation, and multi-region topology.