Rollout a release

This document describes how to roll out a release using SaaS Runtime.

SaaS Runtime enables updates across multiple provisioned units using rollouts. Rollouts target units based on their UnitKind and can optionally apply filters (unit_filter) to target a specific subset of units using the Google Cloud CLI . This allows for managed updates across your deployed base. A rollback can be performed by upgrading units to a previous release.

For operations on a single, specific unit, use the controls available on the Unit details page.

Before you begin

Before you update your SaaS offering, you should:

Create a release

Before you can update your SaaS offering, you must create a release. A release represents a specific version of your SaaS application that is defined by a blueprint package and its associated configurations. Essentially, a release contains the update you roll out to your units.

Console

  1. Go to SaaS Runtime.

    Go to SaaS Runtime

  2. Click Releases.

  3. On the Releases page, click Create.

  4. On the Create Release page:

    1. In the Release name box, enter a unique name for your release.
    2. In the Unit kind box, select the unit kind this release is associated with.
    3. In the Only upgradeable from (optional) section, you can optionally select releases that units can be upgraded from to this release. This lets you control upgrade paths.
    4. In the Create Blueprint and Store Blueprint steps, select or create your blueprint. Refer to Blueprints documentation for detailed information on blueprints creation options.

    5. In the Variables (optional) section, you can optionally set input variables for this release. Refer to Variables documentation for more information on setting variables.

  5. Click Create.

  6. You have created a release. You can view the release details on the Release details page. You will be able to reference this release when creating a rollout.

gcloud

To create a release using Google Cloud console:

gcloud beta saas-runtime releases create RELEASE_NAME --blueprint-package=BLUEPRINT_PACKAGE_URI --unit-kind=UNIT_KIND [--location=LOCATION] [--labels=[KEY=VALUE,...]] [--upgradeable-from-releases=[RELEASE_NAME,...]] [--input-variable-defaults=[variable=VARIABLE,value=VALUE,type=TYPE,...]]

Replace:

  • RELEASE_NAME: The ID of the release you want to create. This will be part of the full resource name for the release.
  • BLUEPRINT_PACKAGE_URI: The URI of the blueprint package to use for this release. Blueprints are OCI images hosted in Artifact Registry, or another OCI registry.
    • The blueprint package contains the artifacts required for you to provision a unit, and includes metadata about the engine used (Terraform), as well as the version.
    • If you omit the hostname in the URI, it defaults to the regional Artifact Registry path (us-east1-docker.pkg.dev, for example).
    • See Blueprints documentation for more information on creating blueprints.
  • UNIT_KIND: The ID or fully qualified identifier for the unit kind this release corresponds to. UNIT_KIND is immutable after you create a release.
  • LOCATION: The location where you want to create the release. This flag provides a fallback value for the release location if the full URI path is not provided. Defaults to the location configured in your Google Cloud CLI environment.
  • LABELS: (Optional) Labels to apply to the release for categorization. Labels are key-value pairs.
    • Keys must start with a lowercase character and contain only hyphens, underscores, lowercase characters, and numbers.
    • Values must contain only hyphens, underscores, lowercase characters, and numbers.
    • For example: --labels=environment=staging,team=saas-runtime
  • UPGRADEABLE_FROM_RELEASES: (Optional) A comma-separated list of release names that specifies which existing releases can be updated with the new release you create.
    • If you leave this flag empty, there are no constraints on which releases can be updated to this release.
    • When provided, unit update requests to this release will enforce this constraint.
  • INPUT_VARIABLE_DEFAULTS: (Optional) Default values for input variables required by the blueprint.
    • You can specify variable defaults inline or by referencing a YAML or JSON file.
    • Variables defined here can be overridden during rollout creation.

For more information on setting variables, see Variables documentation. For more information about releases, see Release Google Cloud CLI reference.

Create a rollout kind

Before you can create a rollout, you need to create a rollout kind that serves as a template for how your release is deployed to your units.

Console

  1. Go to SaaS Runtime.

    Go to SaaS Runtime

  2. Click Rollout kinds.

  3. On the Rollout Kinds page, click Create.

  4. On the Create a rollout kind page:

    1. In the Rollout kind name box, enter a name for your rollout kind.
    2. In the Unit kind box, select the unit kind detailing the type of unit you want the release to rollout.
    3. In the Rollout strategy drop-down, select the strategy you would like to use to deploy the release to your units:
      • One location at a time (simple): Deploy to all units of the specified unit kind by each location with provisioned units in sequence.
      • All at once (simple): Deploy to all units of the specified unit kind in all locations with provisioned units.

  5. Click Create.

  6. You have created a rollout kind. On the Rollout Kind details page, you can view and edit the parameters for your rollout kind.

gcloud

To create a rollout kind using Google Cloud console:

  gcloud beta saas-runtime rollout-kinds create ROLLOUT_KIND_NAME --unit-kind=UNIT_KIND --location=LOCATION --rollout_strategy=ROLLOUT_STRATEGY --error_budget=ERROR_BUDGET --unit_filter=UNIT_FILTER --update_unit_kind_default=UPDATE_UNIT_KIND_DEFAULT

Replace:

  • ROLLOUT_KIND_NAME: The name of rollout kind.
  • UNIT_KIND: Defines which units you want to apply releases to. Releases are applied to all units of the selected unit kind.
  • LOCATION: The location where you want to create your rollout kind.
  • ROLLOUT_STRATEGY: Defines the rollout strategy for your rollout kind. Possible values include:
    • Google.Cloud.Simple.AllAtOnce: Deploy to all units of the specified unit kind by each location with provisioned units in sequence.
    • Google.Cloud.Simple.OneLocationAtATime: Deploy to all units of the specified unit kind in all locations with provisioned units.
  • ERROR_BUDGET: The configuration for error budget. If the number of failed units exceeds your error_budget max (defined by allowed_count, allowed_ratio * total_units), the rollout will be paused. If error_budget isn't set, SaaS Runtime will attempt to update all units regardless of the number of failures encountered.
  • UNIT_FILTER: CEL formatted filter string used against units. The filter will be applied to determine the eligible unit population. This filter can only reduce the scope of the rollout. It cannot expand the rollout's scope.
  • UPDATE_UNIT_KIND_DEFAULT: The configuration for updating the unit kind. By default, the unit kind will be updated on the rollout start. Possible values include:
    • UPDATE_UNIT_KIND_STRATEGY_UNSPECIFIED: Unit kind update strategy is unspecified.
    • UPDATE_UNIT_KIND_STRATEGY_ON_START: Update the unit kind strategy on the rollout start.
    • UPDATE_UNIT_KIND_STRATEGY_NEVER: Never update the unit kind strategy.

For more information, see RolloutKind Google Cloud CLI reference.

Error budget feature

SaaS Runtime includes an error budget feature (ErrorBudget in RolloutKind) as a safeguard. This can automatically pause a rollout if the number or percentage of unit update failures (during infrastructure application, for example) exceeds a configured threshold, helping to limit the impact of potential issues during an update.

Create a rollout

After you've created a rollout kind, you can create a rollout that specifies the release you want to update your units with.

Once the rollout is created, SaaS Runtime updates your units according to the strategy defined in the unit kind.

Console

  1. Go to SaaS Runtime.

    Go to SaaS Runtime

  2. Click Rollouts.

  3. On the Rollout List page, click Create.

  4. On the Create a rollout page:

    1. In the Rollout Kind box, select the rollout kind detailing how to rollout your release to the specified units.
    2. In the Release box, specify the release to update the units with.
    3. In the Rollout Name box, enter a name for your rollout.

  5. Click Create.

  6. Your rollout has been created.

    On the Global Rollout Detail page, you can monitor rollout details including the rollout state, rollout progress (by unit count), and rollout failures.

gcloud

To create a rollout using Google Cloud console:

  gcloud beta saas-runtime rollouts create ROLLOUT_NAME --rollout-kind=ROLLOUT_KIND_NAME --release=RELEASE_NAME --location=LOCATION

Replace:

  • ROLLOUT_NAME: The name of the rollout.
  • ROLLOUT_KIND_NAME: Defines which rollout kind you want to use to apply releases to your units. Releases are applied to all units of the unit kind defined in the rollout kind.
  • RELEASE_NAME: Defines the release binary you want to deploy to your units.
  • LOCATION: The location where you want to create your rollout.

For more information, see Rollout Google Cloud CLI reference.

What's next