SaaS Runtime overview

SaaS Runtime lets you store, host, manage, and monitor software as a service (SaaS) applications on Google Cloud. SaaS Runtime manages Terraform deployments at scale, allowing you to manage both your SaaS application and the infrastructure that it runs on.

SaaS Runtime can be used in many ways by a variety of stakeholders within the SaaS pipeline. If your work identifies with any of these roles, you may be interested in using SaaS Runtime:

  • Platform administrator
  • Application developer
  • Architect
  • Compliance administrator
  • Platform engineer
  • Finance operations

SaaS Runtime provides the following benefits:

  • Simplify your service management at scale by automating service management tasks (such as deployment, rollouts, and feature flag management) across your SaaS tenants.
  • Expand your observability and control by fine tuning your updates and releases across configurable units to manage your SaaS offering with precision at scale.
  • Build consistency across your Google Cloud ecosystem by managing services across various Google Cloud products including Google Cloud, Google Distributed Cloud, Billing, Observability, and Resource Manager.
  • Use flexible and templatizable architecture that promotes unit-based group updates and deployments for improved efficiency and reusability.

How does SaaS Runtime work?

SaaS Runtime deploys artifacts that define your SaaS offering. These artifacts must have a Terraform configuration. The deployment is organized into distinct units that can be updated with releases containing changes to your offering through a configurable rollout process.

For more information about SaaS Runtime nomenclature, see the Glossary.

Prepare your workload for SaaS Runtime

Before you deploy your SaaS offering, we recommend that you determine the ideal arrangement of your SaaS offering within the SaaS Runtime ecosystem.

Organize parts of your SaaS offering that should be updated or modified together into distinct Terraform configurations. As you plan your SaaS offering, use unit kinds for each grouping of your SaaS offering.

Once you've worked out the ideal structure for your workload on SaaS Runtime, you can create your SaaS offering, unit kinds, and then deploy your units using a rollout.

For an example of the setup for SaaS Runtime, see the quickstart.

SaaS Runtime service accounts

SaaS Runtime uses a combination of Google-managed and user-managed service accounts:

  • SaaS Runtime service account (Google-managed): This account is automatically created after creating the first SaaS offering resource. It is managed by Google. It performs actions on your behalf, such as interacting with other Google Cloud services during unit provisioning.

  • Actuation service account (User-managed): You create and manage this service account. SaaS Runtime (via Infrastructure Manager) uses this account to execute your Terraform configurations when provisioning or updating units. This account acts as the identity for creating and managing the resources defined in your Terraform. The actuation service account permissions are directly tied to the resources your Terraform configuration manages.

    You can have multiple actuation service accounts. We recommend that you should have one actuation service account for each tenant.

  • Optional: Artifact creation service account (User-managed): This service account is used for building and uploading your Terraform packaged into OCI artifacts. This is often a Cloud Build service account, but it can be any service account with appropriate permissions for your SaaS offering.

SaaS Runtime service account (Google-managed)

The SaaS Runtime service account is a Google-managed service agent used by SaaS Runtime to perform operations within your project.

This service account is automatically provisioned when you create your first SaaS Runtime resource. The SaaS Runtime service account is created using this format:

  service-PROJECT_NUMBER@gcp-sa-saasservicemgmt.iam.gserviceaccount.com

Replace:

  • PROJECT_NUMBER: Your project number.

Actuation service account (User-managed)

The actuation service account is a user-managed service account that you must create. SaaS Runtime (via Infra Manager) uses this service account to execute your Terraform configurations. It's the identity that creates, modifies, and deletes the resources defined in your Terraform.

You are responsible for creating this service account within your project, or within your tenant project.

Actuation service account input variables

When you create a unit, you must provide the actuation service account as an key-value pair input variable for the Terraform configuration:

  • Name: actuation_sa
  • Variable type: String

  • Variable value: Actuation service account email address:

    my-actuation-sa@my-identifier.iam.gserviceaccount.com

Required Permissions

The actuation service account requires sufficient permissions to manage the resources defined in your Terraform configuration. At a minimum, it needs:

  • roles/iam.serviceAccountTokenCreator: Allows the service account to generate tokens for authentication.
  • roles/config.admin: Grants full control over Infra Manager resources.
  • roles/storage.admin: Grants full control of Cloud Storage.

The actuation service account also needs permissions to create and manage the specific Google Cloud resources used by your application.

For example:

  • If your Terraform creates Google Kubernetes Engine (GKE) clusters, the service account needs appropriate GKE roles (roles/container.admin, for example).
  • If your Terraform creates Compute Engine instances, the service account needs the roles/compute.admin role.
  • If your Terraform creates Cloud SQL instances, the service account needs the appropriate Cloud SQL roles (roles/cloudsql.admin, for example).

Consult the documentation for each Google Cloud resource you use in your Terraform to determine the necessary permissions. Grant the least privilege necessary for your application to function.

Artifact creation service account (User-managed)

The artifact creation service account is a user-managed service account you create to use a build system (such as Cloud Build) to package and upload your Terraform artifacts to Artifact Registry.

This service account is separate from the SaaS Runtime and actuation service accounts, and builds your Terraform code and pushes the resulting artifact to Artifact Registry. Often, this is the Cloud Build service account.

Manual artifact creation

If you manually build and upload your Terraform artifacts (using Docker build and Docker push directly, for example), you don't need a separate artifact creation service account.

Instead, you should authenticate using your own credentials or a service account with the necessary Artifact Registry permissions.

Required Permissions

If you are using Cloud Build, the Cloud Build service account typically needs the following roles:

  • roles/artifactregistry.writer: To push artifacts to Artifact Registry.
  • roles/artifactregistry.repoAdmin: To manage the Artifact Registry repository.
  • roles/storage.admin: To manage the Cloud Storage buckets.
  • roles/developerconnect.admin: Permissions to use Developer Connect.
  • roles/developerconnect.readTokenAccessor: Permissions to get Developer Connect read token.
  • roles/logging.logWriter: Permissions to write logs.
  • If you are deploying your Terraform configuration using Developer Connect: roles/cloudbuild.builds.builder: To execute builds.
  • Any other permissions required by your build process (for example, access to source code repositories).

Rollout strategies

SaaS Runtime employs several rollout strategies to manage how units in your SaaS offering are updated. These rollout strategies follow Google Cloud's approach to change by applying consistent approaches to the deployment of changes across your SaaS offering.

Use rollout strategies to minimize negative customer impacts and isolate issues to individual logical and physical failure domains. Define your rollout strategies by creating a rollout kind specifying one of the following rollout strategies:

  • One location at a time (simple): One location rolls out at a time, with no wait in-between locations. Units are selected arbitrarily within a location, with a maximum of 20% of the location's units updated at a given time.

    This strategy is recommended for development environments and emergency scenarios.

  • All at once (simple): All locations begin rolling out at the same time.

    This strategy is recommended for development environments and emergency scenarios.

  • Progressive (gradual): Within each location, units are rolled out in static percentage-based batches (for example, 1%, 10%, 20%, 30%, ~40%) with soak times between batches. Across locations, the rollout progresses with an exponential increase in the number of concurrent locations (for example, one location, then two, then four) with soak times (18 hours, for example) between waves. Units within a location are selected randomly.

    This strategy is designed for safe and predictable rollouts across multiple locations. It starts with a small footprint and gradually expands as confidence grows. This strategy is recommended in production environments with more than one location.

  • Progressive (single location): Units are updated in static percentage-based batches (for example, 1%, 10%, 20%, 30%, ~40%) with longer soak times (18 hours, for example) between batches to allow ample time for issue detection and to limit the adverse impact of rollout changes.

    This strategy is tailored for SaaS offerings operating in a single location, prioritizing safety and caution. We recommend this strategy in production environments with one location.

For more information about creating rollout kinds, see Create a rollout kind.

SaaS Runtime regionalization

SaaS offering resources define where your SaaS Runtime units can reside, and how your rollouts are managed. When you create a SaaS offering, the regions you select serve as a single source of truth for the supported regions of your SaaS offering. The regions you select are the available regions you've defined for your SaaS offering.

When you use SaaS Runtime through Google Cloud console, SaaS Runtime automates the replication of the resources you define in your SaaS offering across regions. This ensures consistency and availability of your SaaS Runtime resources across all of the available regions you've defined in your SaaS offering.

SaaS Runtime replicates these resources:

  • SaaS offering (Saas)
  • Unit kind (UnitKind)
  • Release (Release)

Using global as a region

Including global as a region within your SaaS offering is generally not recommended for deployment targets. SaaS Runtime uses the global region to propagate regional rollouts. Regional rollouts cannot run in the global region.

Rollout regionalization

Supported locations for rollouts are determined by the top-level regions defined in your SaaS offering's available regions.

Rollouts read the list of available regions from the associated SaaS offering.

Resource replication

SaaS Runtime handles the creation and updates of resources to all of your SaaS offering's available regions.

When you update your SaaS offering's available regions, the SaaS Runtime handles the replication:

  • Locations added: Resources are replicated to the newly added locations.
  • Locations with old copies: The content is updated.

Artifact Registry and Developer Connect locations

The locations of your Artifact Registry repository and Developer Connect instance have specific requirements:

  • The region of your Artifact Registry repository and Developer Connect instance can be any valid Google Cloud region. They don't need to be included in your SaaS offering's available regions.

  • The region of your Artifact Registry repository must match the region of your Developer Connect instance.

    This necessitates the presence of SaaS offering, release, and unit kind resources in all regions defined in your SaaS offering, even though the Artifact Registry and Developer Connect reside in a single (potentially different) region.

  • Units can only be created in regions specified in your SaaS offering.

SaaS Runtime regions configuration example

We have provided this example to demonstrate how regionalization works when using SaaS Runtime with managed resource replication.

For example, if you wanted to deploy your SaaS offering in us-central1 and europe-west4, while hosting your Artifact Registry repository and Developer Connect instance in us-east1, your SaaS Runtime regions infrastructure would be something like:

  • SaaS offering available regions: ['us-central1', 'europe-west4']
  • Artifact Registry repository region: us-east1
  • Developer Connect instance region: us-east1
  • Unit kind, and release resources: SaaS Runtime manages the creation and updates of these resources across global, us-central1, and europe-west4 regions
  • Units: Units could be created in either us-central1, or europe-west4

This configuration lets you manage your deployments across two regions while keeping your artifact management centralized in a third, distinct region with automated resource replication. You should consider your latency, compliance, and data residency requirements carefully when selecting your regions.

What's next