Installation Guide for SOAP-2-REST Control Plane and Runtime

Overview

This guide provides a step-by-step process for an API publisher to deploy a running SOAP-2-REST (s2r) control plane and runtime from a clean cloud account. It covers the necessary prerequisites and outlines two primary installation topologies available at General Availability (GA): GCP-native and Kubernetes Helm chart. The estimated installation time ranges from 30–60 minutes for the GCP-native path and 20–40 minutes for the Helm path on an existing cluster. (source: docs/customer/install.md)

Key Capabilities and When to Use

The s2r platform supports the following installation topologies at GA:

• GCP-native (Cloud Run + Cloud SQL): Recommended for API publishers operating on Google Cloud Platform who prefer a low-touch, managed-service deployment.
• Kubernetes Helm chart: Suitable for API publishers who run Kubernetes in any cloud environment or on-premises, and prefer managing workloads within their clusters.

Other topologies, such as OVA/VMware/Hyper-V/Nutanix appliance images or AWS/Azure/Oracle native ports, are planned for post-GA releases and are tracked on the post-GA roadmap. (source: docs/customer/install.md)

How it Works

The installation process for s2r involves validating the environment, selecting a deployment topology, executing deployment steps, and configuring essential services and infrastructure.

Prerequisites and Preflight Checks

Before any deployment, a read-only preflight checker is run to validate all dependencies. This ensures the environment meets the minimum requirements, such as a cloud project, a controlled DNS hostname, an identity provider integration plan (Cloud IAP for GCP-native, OIDC for any topology), and optionally, an SMTP relay for operational alerts. Operator emails are also specified to become bootstrap administrators. (source: docs/customer/install.md)

Deployment Topologies

API publishers choose between a GCP-native deployment, which leverages Google Cloud's managed services like Cloud Run and Cloud SQL, or a Kubernetes Helm chart deployment, which allows for deployment on any Kubernetes cluster with PostgreSQL 15+. Each path involves specific scripts or Helm commands to build and deploy the core s2r services: admin-api, admin-ui, runtime, and worker. (source: docs/customer/install.md)

Infrastructure and Authentication Setup

For GCP-native deployments, a dedicated script provisions an external load balancer, Cloud IAP backend, and supporting infrastructure. For Kubernetes, an Ingress controller and cert-manager are required, with OIDC configured for cluster ingress. A critical security requirement is the "identity-header trust boundary," which mandates that the fronting load balancer or IAP must strip any client-supplied identity headers (X-Goog-Authenticated-User-Email, X-User-Email, X-Actor) on ingress to prevent spoofing. Additionally, services must only be reachable through the authenticated load balancer/ingress, never directly. (source: docs/customer/install.md)

First-Boot Behavior and Licensing

Upon first deployment, the platform starts in pristine authentication mode. The first authenticated user to access the /admin/ endpoint automatically becomes the bootstrap admin. Once this bootstrap process completes, the authentication mode automatically switches to protected, and subsequent users adhere to normal Role-Based Access Control (RBAC). The default install_profile is both (F5 modernisation + generic SOAP modernisation), which can be adjusted later in settings.

A 45-day Trial license is automatically issued on first boot, alongside a free Community Edition license (capped at a small number of services). The Trial license unlocks all features. After its expiration, the platform reverts to the Community Edition, where existing services continue to run, but new onboarding beyond the cap is blocked until an Enterprise renewal token is uploaded. (source: docs/customer/install.md)

GCP-native Installation Steps

This section details the steps for deploying s2r on Google Cloud Platform using native services. (source: docs/customer/install.md)

1. Prerequisites

Before proceeding, ensure you have:

• A Google Cloud project.
• A DNS hostname you control (e.g., s2r.your-domain.com).
• An identity provider integration plan, specifically Cloud IAP for the GCP-native path.
• An SMTP relay or transactional-email API for operational alerts (optional but recommended).
• Operator email(s) that will be designated as bootstrap administrators.
• The preflight checker has been run and any FAIL items addressed. (source: docs/customer/install.md)

2. Run the Preflight Checker

Execute the preflight checker script. This is a read-only operation that validates all dependencies. Refer to marketplace-preflight.md for detailed usage.

./scripts/preflight-marketplace.ps1 `
    -ProjectId your-project-id `
    -Region your-region `
    -AdminBootstrapEmails first.admin@your-org.com

The expected verdict is READY (exit 0) or READY WITH WARNINGS (exit 1). Do not proceed if the verdict is NOT READY. (source: docs/customer/install.md)

3. Set Authentication Credentials

Configure your Google Application Credentials. The service account used needs project-level deploy permissions. Consult marketplace-preflight.md §B for a list of required GCP APIs.

$env:GOOGLE_APPLICATION_CREDENTIALS = "C:\path\to\sa-key.json"

(source: docs/customer/install.md)

4. Build Service Images

This command builds and pushes the four s2r service images (admin-api, admin-ui, runtime, worker) to your Artifact Registry repository.

./scripts/build-images.ps1

(source: docs/customer/install.md)

5. Deploy Services

Execute the deployment script to provision services on Cloud Run.

./scripts/deploy-gcloud.ps1 `
    -ProjectId your-project-id `
    -Region your-region `
    -AdminBootstrapEmails first.admin@your-org.com

This script performs the following actions:

1. Verifies prerequisites.
2. Deploys all four services to Cloud Run, configuring them with the correct service accounts, secrets, and environment variable bindings.
3. Runs Flyway database migrations during the initial deployment.
4. Verifies that each service revision is Ready=True before proceeding to the next service.

The expected runtime for this step is 8–15 minutes. (source: docs/customer/install.md)

6. Apply Infrastructure (Load Balancer, IAP, DNS)

Provision the external load balancer, IAP backend, and other supporting infrastructure using Terraform.

./scripts/deploy-terraform.ps1

After this step, configure your DNS provider to point your chosen hostname (e.g., s2r.your-domain.com) to the Load Balancer IP address output by Terraform.

Security Requirement — Identity-Header Trust Boundary (Mandatory)

The admin control plane relies on request headers set by the fronting IAP / load balancer (X-Goog-Authenticated-User-Email, X-User-Email, X-Actor) to derive the caller's identity. To prevent identity spoofing:

1. The fronting LB/IAP MUST strip any client-supplied copies of these headers on ingress. The provided Terraform configuration handles this for the GCP IAP path. If you use a custom load balancer or proxy, or the Kubernetes ingress (as described in the Helm section), you MUST implement an equivalent header-sanitization rule.
2. The services MUST only be reachable through the LB and never exposed directly. The GCP deployment configures Cloud Run ingress to internal-and-cloud-load-balancing; this setting must be preserved. For Kubernetes, services should remain ClusterIP and route solely through the authenticated ingress.

Failure to follow either of these steps allows identity spoofing of the admin plane and is a hard prerequisite for any production deployment. (source: docs/customer/install.md)

7. Verify Installation

Perform a health check and access the Admin UI to confirm successful deployment.

# Health check (server-side)
gcloud run services list --region=your-region --filter='metadata.name~"^s2r-"'

# Browser (after DNS propagates)
# Visit https://s2r.your-domain.com/ → log in via your IdP → land on Dashboard

(source: docs/customer/install.md)

Kubernetes Helm Installation Steps

This section outlines the process for deploying s2r using a Helm chart on a Kubernetes cluster. (source: docs/customer/install.md)

1. Prerequisites

Before proceeding, ensure your environment meets the following:

• A Kubernetes cluster version 1.28 or newer, equipped with an Ingress controller and cert-manager.
• A PostgreSQL database (version 15 or newer) that is reachable from the cluster pods. This can be an in-cluster operator-managed instance or a managed service.
• A dedicated namespace for SOAP-2-REST (e.g., s2r).
• An OIDC identity provider configured for cluster ingress. (source: docs/customer/install.md)

2. Helm Chart Installation

The s2r Helm chart is located under deploy/helm/s2r/ within the release artifact bundle. You can add it to your local Helm repository or install it directly.

helm install s2r ./deploy/helm/s2r \
    --namespace s2r --create-namespace \
    --values my-values.yaml

(source: docs/customer/install.md)

3. my-values.yaml Example Configuration

Below is an example of a my-values.yaml file, which defines the configuration for the Helm chart.

global:
  domain: s2r.your-domain.com
  adminBootstrapEmails:
    - first.admin@your-org.com
  installProfile: both          # 'f5_modernization' | 'generic' | 'both'

postgres:
  host: postgres.your-db-host
  port: 5432
  database: soap_to_rest
  user: s2r_app
  passwordSecretRef: s2r-db-password   # k8s Secret name, key 'password'

envelopeKey:
  secretRef: s2r-credential-key        # k8s Secret name, key 'envelope-key'

oidc:
  issuerUrl: https://idp.your-domain.com/auth/realms/your-realm
  clientId: s2r-admin-ui
  clientSecretRef: s2r-oidc-client-secret

resources:
  adminApi:    { cpu: 1,   memory: 2Gi }
  adminUi:     { cpu: 0.5, memory: 512Mi }
  runtime:     { cpu: 2,   memory: 2Gi }
  worker:      { cpu: 1,   memory: 1Gi }

ingress:
  className: nginx
  tlsSecretName: s2r-tls
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt

(source: docs/customer/install.md)

4. Apply and Verify

Use Helm to install or upgrade the chart and then verify the deployment status of the s2r services.

helm upgrade --install s2r ./deploy/helm/s2r \
    --namespace s2r --create-namespace \
    --values my-values.yaml

kubectl -n s2r rollout status deployment/admin-api
kubectl -n s2r rollout status deployment/admin-ui
kubectl -n s2r rollout status deployment/runtime
kubectl -n s2r rollout status deployment/worker

After successful deployment, browse to https://s2r.your-domain.com/ and log in. (source: docs/customer/install.md)

Helm Chart Configuration Reference

The following table details the configurable parameters for the s2r Helm chart, as shown in the my-values.yaml example. (source: docs/customer/install.md)

Name	Type	Default	Description

---

All SOAP-to-REST docs