GCP-Native Installation with Cloud Run and Cloud SQL

Overview

This document describes the recommended topology for deploying the platform on Google Cloud Platform (GCP) using native, managed services. This approach uses Cloud Run for the core services, Cloud SQL for PostgreSQL as the database, Cloud Storage for the raw traffic archive, and Cloud IAP (Identity-Aware Proxy) for securing administrative access.

This deployment model is designed for minimal operational overhead and creates an internal-only environment with no public endpoints. All ingress is handled by a regional internal HTTP(S) load balancer. The platform's core services (admin-api, admin-ui, runtime, worker) are deployed as distinct Cloud Run services, each with its own least-privilege IAM service account.

This GCP-native topology has been generally available since v1.0 and is the same architecture used by the GCP Marketplace offering.

How it works

Architecture

The platform is deployed as a set of interconnected GCP services. The following table maps the platform's logical components to the specific GCP resources created during installation.

The following diagram illustrates the request flow for an administrative user accessing the platform.

flowchart TD
    subgraph "Your GCP Project"
        subgraph "Your VPC"
            User(["<br/><b>API Publisher</b><br/>(via peered network)"])
            IAP[("Cloud IAP")]
            LB["Regional Internal<br>HTTP(S) Load Balancer"]
            
            subgraph "Cloud Run Services"
                AdminUI["s2r-admin-ui"]
                AdminAPI["s2r-admin-api"]
                Runtime["s2r-runtime"]
                Worker["s2r-worker"]
            end

            subgraph "Data Plane"
                SQL[("Cloud SQL<br>for PostgreSQL")]
                GCS[("Cloud Storage<br>Bucket")]
            end
        end
    end

    User --> LB
    LB -- Authenticates via --> IAP
    IAP -- Authorizes & Forwards --> LB
    LB --> AdminUI
    LB --> AdminAPI
    
    AdminUI -- Interacts with --> AdminAPI
    AdminAPI -- Reads/Writes --> SQL
    Runtime -- Reads/Writes --> SQL
    Worker -- Reads/Writes --> SQL
    Runtime -- Archives traffic to --> GCS

Each service runs with a dedicated, least-privilege IAM service account.

• The runtime, admin-api, and worker service accounts are granted the roles/cloudsql.client and roles/cloudsql.instanceUser roles to enable IAM database authentication with the Cloud SQL instance.
• The runtime service account is additionally granted read access to Secret Manager for resolving backend credentials at runtime.

Deployment Process

The deployment is executed by a series of scripts in a specific order. This process is automated when using the BYOC deployment from the Specaria portal.

1. Build Images (scripts/build-images.ps1): Container images for each service are built using Cloud Build.
2. Configure IAM (scripts/configure-iam.ps1): IAM service accounts are created and permissions are bound.
3. Deploy Services (scripts/deploy-gcloud.ps1): The four Cloud Run services are deployed. The admin-api is deployed first, which triggers the Flyway database migrations on its initial startup. The script waits for each service revision to report Ready=True before proceeding.
4. Apply Infrastructure (scripts/deploy-terraform.ps1): Terraform is used to provision the supporting infrastructure, including the internal load balancer and the Cloud IAP configuration.

Prerequisites

Before deployment, the following resources must exist in your GCP project:

• A GCP project and a designated region.
• A VPC and subnet to be used for Direct VPC egress from the Cloud Run services.
• A Cloud SQL for PostgreSQL instance with a database created for the application.
• IAM database users configured for the service accounts that will run the platform services.
• An IAP access group or a list of principals who will be granted the roles/iap.httpsResourceAccessor role for the admin-ui and admin-api services.
• The GOOGLE_APPLICATION_CREDENTIALS environment variable must be set, pointing to a service account JSON key with permissions to deploy resources. The deployment scripts use this credential and do not require an interactive gcloud auth login.

Example: Single-Service Redeployment

While the initial deployment provisions all services, you can redeploy a single service using the -Service parameter with the deployment script. This is the correct method for updating a service without losing its configuration bindings.

./scripts/deploy-gcloud.ps1 -Service admin-api

Verification and Troubleshooting

After a deployment, verify that the installation is correctly configured and secure.

Internal-Only Ingress

Confirm that access is properly restricted. The raw *.run.app URLs for the Cloud Run services should not be accessible from the public internet. Access should only be possible through the internal load balancer's IAP-protected hostname.

Check the following:

• Each Cloud Run service's ingress setting is internal-and-cloud-load-balancing.
• Cloud IAP is enabled on the backend services for the s2r-admin-ui and s2r-admin-api.
• Your designated IAP access group has the roles/iap.httpsResourceAccessor role on both admin services.
• The Google-managed IAP service identity has the roles/run.invoker role on s2r-admin-ui and s2r-admin-api.
• No public allUsers invoker bindings exist on any of the services.

Service Status and Provenance

You can use gcloud commands to check the status of the deployed services and verify the source code provenance of a running revision.

1. List running services:

   # Replace <region> with your deployment region
   gcloud run services list --region=<region> --filter='metadata.name~"^s2r-"'
   

   This command should list the s2r-admin-api, s2r-admin-ui, s2r-runtime, and s2r-worker services.

2. Check deployment provenance:

   # Replace <revision> and <region> with your service revision and region
   gcloud run revisions describe <revision> \
       --region=<region> \
       --format='value(spec.containers[0].env)' | grep S2R_DEPLOY
   

   The output should display environment variables that indicate the source commit and build details, confirming which version of the code is running.

Finally, navigate to your IAP-gated hostname in a browser, authenticate through your identity provider, and confirm that the administration dashboard loads successfully.

Multi-Cloud and Alternative Topologies

The platform is designed with a cloud-adapter layer to abstract cloud-specific implementations for services like object storage and secret management. The active provider is selected at boot time via the s2r.cloud.provider and s2r.relay-vm.provider configuration settings, which default to gcp.

The following sample Terraform environments are provided as starting points for other deployment topologies:

See Also

• Configuration Reference
• Deployment Runbook
• Authentication
• Network & Data Residency
• Kubernetes (Helm) Installation

All SOAP-to-REST docs