We’ve recently shipped one of the most requested features in Replicated: the ability for Replicated to self-update! This isn’t enabled by default; read more about how the feature works and how to use it.
Replicated Release Schedule
Before jumping into how to implement this feature, we should discuss the planned and expected Replicated release schedule. Replicated supports the standard semver specification. We ship a minor version monthly. Our minor versions contain new functionality, but does not break backward compatibility. For example, in November, we shipped Replicated 2.3.0. In December, we are planning to ship 2.4.0. All of the Replicated components (replicated, replicated-ui, replicated-operator) use the same version numbers. If we ship a bugfix version in the middle of a month, it will be a patch version. In early December, we shipped Replicated 2.3.1 and 2.3.2 with some minor fixes.
If your application works with 2.x.0, you should be confident that we will not break it in 2.x.1 or 2.x.2, etc. Our patch releases do not contain any new functionality and are designed to be interim updates that you should be comfortable with. When choosing a release it is recommend you always use the latest patch release for that release.
Design
To start, Replicated will only auto-update itself when the installed application is being updated. Replicated cannot update itself outside of the application release cycle. This helps ensure that your customer’s installations are stable and don’t unexpectedly change to a new version.
Second, Replicated will not auto update to the latest version (unless that’s what you want and explicitly enable it with a very wide semver range). We allow you to specify which version or versions of Replicated you’d like to support with each release. We implemented this using a syntax similar to the npm syntax. We support the most common operators, for a full reference, check out our docs.
Opting In
To opt in and start using the upgrade feature, you simply ship a release that contains a new preflight check, specifying the Replicated version range that is required for this release of your application. During app update, Replicated will find the highest version that matches the range you specified, and update itself to that version.
For example:
[.pre]host_requirements:replicated_version: ">=2.3.0 <2.4.0"[.pre]
When your customer updates to this release of your application, Replicated will seek out the best available version and update it. The above example assumes you want your customer running the latest 2.3 release of Replicated.
How it works
Starting with Replicated 2.2.0, we have been laying the groundwork to release this feature. Regardless of which version or which release channel you install Replicated from, if you use the easy install script, Replicated will download the correct Replicated images, and tag them locally with the current tag. Replicated always runs the replicated:current image. When an update is required, Replicated will pull the new tag from the remote repository, retag it as current and then allow itself to be restarted. We do this so that there are no caches with systems or any init system to update. While this is happening, there is a process to ensure that all of the images are pulled and tagged before restarting to prevent leaving the system in a partially-upgraded state.
There is no UI visible to your customer during this process. Replicated will update itself and all components (including replicated-operator containers running on remote nodes) before applying your application update. We did this so that you can reliably ensure that the version of Replicated running has the features your code expects.
Initial Installations
There’s still a challenge during initial installation time. If your application contains YAML that pins the Replicated version to 2.3.x, but the current release of Replicated is 2.5.1, we want to ensure your customer gets the correct initial version so they don’t have to immediately downgrade.
Today, you are familiar with the easy installation script hosted at https://get.replicated.com/docker. You’ve possibly used our instructions to install known versions of Replicated by specifying the component versions in the URL. We wanted something better; something that you didn’t have to continue to update as you shipped new versions.
The installation script now supports passing in your app slug and channel name, and it will create a dynamic script that uses the current YAML at the top of your channel and the current Replicated releases to determine the best version of Replicated to install. We encourage you to use these new scripts now, and update your proxy if you are proxying behind your own server.
You now have a unique custom URL for each release channel in your application, and it can be built using the following format:
https://get.replicated.com/docker/:appSlug/:channelName. If you click on one of your release channels in vendor.replicated.com, it will show you the install path for that channel at the top of the page.
If you have multiple channels with the same name, you will have to rename a channel in order to use this feature. We will enforce unique channel names in the future, but ambiguity in channel names will result in undefined behavior today.
Older Installations
For customers running Replicated versions lower than 2.3.0, those installations will not respect the new replicated_version YAML tag. It’s safe to add this and older versions of Replicated will ignore it, but they won’t get updated automatically until they are manually updated to at least 2.3.0.
Airgap
Replicated updater will not work with airgap installs. For customers running airgap installations, they will have to manually download and update.