Install on GCP with Cloud Run and Cloud SQL

Overview

This document describes the recommended topology for deploying the SOAP-2-REST platform to Google Cloud Platform (GCP). This approach uses managed services to provide the lowest-touch operational path on GCP. The deployment is configured for internal-only ingress, with no public endpoints exposed by the services.

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

The core components of this deployment are:

• Compute: Four distinct services (admin-api, admin-ui, runtime, worker) run as separate Cloud Run services.
• Database: A Cloud SQL for PostgreSQL instance, accessed over private connectivity using IAM database authentication.
• Storage: A Cloud Storage bucket serves as the archive for raw traffic.
• Identity and Access: Cloud IAP secures the admin-api and admin-ui services, acting as the identity-aware front door.
• Networking: A regional internal HTTP(S) load balancer provides a single entry point, and services use Direct VPC egress to communicate with the database and other VPC resources without a Serverless VPC connector.

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

Deployed Components

The deployment process provisions the following GCP resources:

| Component | GCP Resource | admin-api, admin-ui, runtime, worker | Cloud Run services (s2r-admin-api, s2r-admin-ui, s2r-runtime, s2r-worker) | | Database | Cloud SQL for PostgreSQL, reached over private connectivity with IAM DB auth | | Raw traffic archive | Cloud Storage bucket | | Front-door identity | Cloud IAP on the admin UI / admin API backend services | | Edge | Regional internal HTTP(S) load balancer | | Egress to backends | Cloud Run Direct VPC egress (no Serverless VPC connector required) |

The runtime, admin-api, and worker service accounts are granted cloudsql.client and cloudsql.instanceUser IAM roles to authenticate with the database. The runtime service account also has read access to Secret Manager for resolving backend credentials.

Prerequisites

Before deployment, ensure the following resources are provisioned in your GCP environment:

• A GCP project and a designated region.
• A VPC and subnet for the Cloud Run services to connect to using Direct VPC egress.
• A Cloud SQL for PostgreSQL instance with a dedicated application database created. The instance must be configured for private-IP only access.
• IAM database users must exist for the application service accounts.
• An IAP access group or a list of principals who will be granted the roles/iap.httpsResourceAccessor role to access the admin services.
• A service account JSON key with cross-project deployment permissions, with its path set in the GOOGLE_APPLICATION_CREDENTIALS environment variable. The deployment scripts use this key and do not require an interactive gcloud auth login.

These prerequisites are typically provisioned automatically by the Specaria portal's Bring-Your-Own-Cloud (BYOC) self-service deployment process.

Deployment Process

The deployment is orchestrated by a series of scripts, which are typically executed on your behalf by the Specaria portal's self-service BYOC process (portal.specaria.io). You do not need a local source checkout or build toolchain.

The deployment follows a specific order to ensure dependencies are met:

1. Build Images (scripts/build-images.ps1): Each service's container image is built using Cloud Build.
2. Configure IAM (scripts/configure-iam.ps1): Service accounts are created and IAM role bindings are applied.
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 reach a Ready=True state before proceeding.
4. Apply Infrastructure (scripts/deploy-terraform.ps1): Terraform is used to provision supporting infrastructure, including the internal load balancer and Cloud IAP backend configuration.

This "gcloud first, Terraform second" approach ensures that the application services and their database schema are ready before the networking and access control infrastructure is layered on top.

Single-Service Deployments

To redeploy a single service, use the -Service filter with the deployment script. This preserves the centralized secret and provenance bindings that are critical for operation.

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

Caution: Do not use gcloud run deploy directly for single-service updates. Doing so will drop critical secret bindings required by the application.

How It Works: Internal-Only Ingress

The platform is designed for secure, internal-only access. The Cloud Run services are configured with ingress set to internal-and-cloud-load-balancing. This means the services cannot be reached directly via their public *.run.app URLs.

All access is routed through the regional internal HTTP(S) load balancer, which is fronted by Cloud IAP for the admin-ui and admin-api services. IAP enforces authentication and authorization before allowing traffic to reach the backend services.

Installation Verification

After deployment, verify the installation by performing the following checks.

1. Confirm services are running and internal:

   gcloud run services list --region=<region> --filter='metadata.name~"^s2r-"'
   

2. Check deployment provenance: Verify the running code version by inspecting the S2R_DEPLOY environment variable on a service revision.

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

3. Verify IAP configuration:

   • Confirm each Cloud Run service is set to internal ingress only.
   • Ensure IAP is enabled on the s2r-admin-ui and s2r-admin-api backend services.
   • Verify your IAP access group has the roles/iap.httpsResourceAccessor role on both services.
   • Check that the Google-managed IAP service identity has the roles/run.invoker role on s2r-admin-ui and s2r-admin-api.
   • Ensure no stale allUsers invoker bindings remain on any service.

4. Test access: Browse to the IAP-gated hostname for the admin UI, log in with your identity provider, and confirm that the application dashboard loads successfully.

For a complete list of post-deployment checks, see the Deployment Runbook.

Multi-Cloud and Alternative Topologies

The platform isolates cloud-specific components (such as object storage, secret management, and compute provisioning) behind a cloud-adapter layer. The active provider is selected at boot time via the s2r.cloud.provider configuration property, which defaults to gcp.

The product provides sample Terraform environments as starting points for other deployment topologies.

Directory	Cloud	Purpose
customer-mot-gcp	GCP	Reference GCP-native env (Cloud Run + Cloud SQL + GCS + IAP)
customer-test-aws	AWS	Sample AWS-host env
customer-test-azure	Azure	Sample Azure-host env
customer-vmware-relay-only	vSphere	F5 relay VM on vSphere

Currently, the GCP-native and Helm-based Kubernetes installation paths are the generally available options.

See Also

• Configuration Reference
• Deployment Runbook
• Authentication
• Network & Data Residency

---

All SOAP-to-REST docs