Snap-ins upgrades

The platform supports upgrading snap-in versions and corresponding snap-ins that haven't been published to the marketplace.

Upgrades can be performed using the upgrade subcommand of snap_in_version.

For example:

1 $ devrev snap_in_version upgrade -h
2 Upgrades a snap-in version.
3 
4 Usage:
5   devrev snap_in_version upgrade [flags]
6 
7 Flags:
8       --archive string    Archive path
9       --force             Force upgrade of snap-in version even if it isn't compatible for upgrade with existing version
10   -h, --help              help for upgrade
11       --manifest string   Manifest path
12       --path string       Path to the directory containing the manifest file and source code for snap-in functions
13       --version string    snap-in version ID
14 
Show more

You can pass only the manifest if that's the only thing that has changed. If you have changed the source code of the snap-in functions, you can pass the path to the directory containing the manifest file and the source code. The path to the archive file containing the functions can also be passed if you have already created it.Only one path, either directory containing the manifest file or archive should be passed.

The actual snap-in version to be upgraded is specified using the --version flag.

Upgrade behavior

The upgrade command checks if the updated version is compatible with the existing version. If it isn't compatible, the upgrade fails. If you want to force an upgrade, you can use the --force flag.

If the upgrade is compatible, the upgrade command does the following:

1. Create a new snap-in version with the new manifest and source code. If either of them isn't provided, the existing manifest or source code is used.
2. Upgrade the snap-in to use the updated version.
3. Delete the old snap-in version.

If the upgrade isn't compatible, the upgrade command does the following:

1. Fail if the --force flag isn't used.
2. Delete the existing snap-in if the --force flag is used.

Version compatibility

The following table shows compatibility between snap-in versions:

Example scenarios

The following are some examples of when you might need to run these upgrades:

• Changing the source code of a function used in the snap-in
• Adding a new automation
• Adding a new command
• Changing the description of a snap-in
• Changing the identity of a snap-in (changing the service account)

Idempotency

If you run the upgrade command for the same snap-in version multiple times, the command does the following:

1. Returns an already existing error if an upgrade is currently in progress or completed for the same snap-in version.
2. When the previous upgrade failed, starts another upgrade if :
   • the manifest is different.
   • the --archive or --path parameter is passed to the upgrade command.

Checking status of the upgrade

When you run devrev snap_in_version list for the same package after the upgrade succeeds, you should see the updated snap-in version. In the list, you might see the old snap-in version and the updated snap-in version while the upgrade is in progress. In the case of a failure, you will only see the old snap-in version.