Upgrade an app with containers

The topic describes how to upgrade a Snowflake Native App with Snowpark Container Services.

About upgrading an app with containers

The process of upgrading an app with containers has two main stages:

  • Upgrade the services in the containers managed by the app.

    Like other Snowpark Continer Services, container apps use the ALTER SERVICE command to modify a service based on a service specification file for the new version. This command runs asynchronously.

  • Upgrade other objects in the app.

    After the services are successfully upgraded, other object within the app are upgraded. This is similar to the normal Snowflake Native App upgrade process. See About upgrades for more information.

The challenge when upgrading an app with containers is that the ALTER SERVICE command runs asynchronously. If a provider adds this command directly to the setup script, the setup script continues to run while the service upgrade is in progress. Providers need to write the code for the service upgrade so that the services are upgraded correctly before continuing the upgrade for other objects in the app.

To handle service upgrades correctly, the Snowflake Native App Framework provides features that allow the app to:

  • Pause the execution of the setup script until the services upgrade successfully or fail. Providers should ensure that the setup script can handle possible situations. See Pause setup script execution for more information.

  • Use a callback function to rollback previously upgraded services to a previous version if the upgrade fails. See Coordinate service upgrades for more information.

Pause setup script execution

To allow services to upgrade correctly, providers can pause the setup script using the SYSTEM$WAIT_FOR_SERVICES system function within the setup script. The following example shows how to use this system function:

SELECT SYSTEM$WAIT_FOR_SERVICES(600, 'services.web_ui', 'services.worker, 'services.aggregation');
Copy

This command causes the setup script to pause until one of the following occurs:

  • All named services passed to the system function have READY status.

  • Any of the named services has the FAILED status.

  • 600 seconds has passed.

Coordinate service upgrades

The Snowflake Native App Framework provides a callback function that allows providers to synchronize upgrading services with the rest of the upgrade procedure.

Possible conflicts when upgrading services

During the upgrade of a core Snowflake Native App, the setup script upgrades to the new version of the app by modifying objects within a versioned schema. If an error occurs during upgrade, the objects within the versioned schema revert back to the previous version of the app.

In the case of an app with containers, services are modified by running the ALTER SERVICE command in the setup script based on a service specification file applicable to the new version. Because services are not created within versioned schemas, a service is upgraded as soon as the ALTER SERVICE runs successfully. If there is a failure later in the setup script, for example, the objects in versioned schemas are reverted back to the previous version, but the modified services are those of the new version.

Use a version initializer callback function to manage service upgrades

The Snowflake Native App Framework provides a version initializer used to start or upgrade services or other related processes, for example tasks. The version initializer is a callback stored procedure that is specified in the manifest file.

The version initializer callback function is invoked in the following contexts:

  • During installation, the version initializer is called as soon as the setup script of the app finishes without errors.

  • During upgrade, the version initializer there are two possible scenarios:

    • If the setup script of the new version succeeds, then the new version of the version initializer is called.

    • If the setup script or the version initializer of the new version fails, then the version initializer of the previous version is called. This allows the version initializer of the previous version to use the ALTER SERVICE to revert the services to the previous version.

Specify the version initializer

To specify the stored procedure used as the version initializer, add the following to the manifest.yml file:

lifecycle_callbacks:
  version_initializer: callbacks.version_init
Copy

In this example, the version_initializer property is set to a stored procedure named version_init within a schema named callbacks.

Within the setup script, a provider can define this procedure within a versioned schema as shown in the following example:

CREATE OR ALTER VERSIONED SCHEMA callbacks;

CREATE OR REPLACE PROCEDURE callbacks.version_init()
  ...
  -- body of the version_init() procedure
  ...
Copy

Best practices when upgrading apps with containers

  • Take care when setting the timeout value for the SYSTEM$WAIT_FOR_SERVICES() system function.

  • Snowflake recommends creating the stored procedure used as the version initializer within a versioned schema. If this stored procedure is not created within a version schema, the version initializer may not exist.

  • If an app specifies a version initializer, then the app must not attempt to start or upgrade services within the setup script.

  • The version initializer does not require being granted an application roles.

Language: English