Update the image of an instance

Update the image of an instance to move it to another framework, a newer version of its image, or your own custom image, and keep the same instance. Its workspace at /home/jovyan, its plan, its workspace size, and its other settings stay as they are. Only the image and its app change.

Before you begin

• An instance in any status except Saving Image or Expired. You can update it while it runs.
• Permission to update instances in the project. Every project role except MEMBER has it, and a MEMBER needs a policy that allows updates.
• SSH turned on for the instance, if the new image has no app. A Base OS image, a public image, and a custom image without JupyterLab Support are reached over SSH only. SSH needs at least one SSH key and a security group that allows port 22. See Connect to an instance over SSH.
• For a custom image: the image in a registry namespace of the project’s Container Registry, in the same region. See Create an instance from your own image.

Updating the image of a running instance restarts it and stops every running process. Files in /home/jovyan, on mounted datasets and file systems, and in /mnt/local are kept, so save your work there first. To keep the packages you installed on the current image, save the instance as an image before you update it.

Choose the new image

1. In the instance’s actions menu, select Update Image. The image the instance uses now is under Current Image Details.
2. Choose the new image on one of the tabs:
   • TIR Pre-built: images that E2E maintains, each with a framework and an app such as JupyterLab.
   • Base OS: operating-system images with no app, reached over SSH.
   • Custom Images: an image from your project’s Container Registry, or a public image that you name with its tag. TIR checks a public image when you submit it, and refuses one that fails the check.
3. Select Update Image.
4. Select Update to confirm.

What happens after the update

On a running instance, the update restarts the instance with the new image, and it is back to Running once the new container starts. Open the app with Launch App, or connect over SSH, to work with the new image.

A stopped instance stays stopped, and uses the new image the next time you start it.

After the update:

• Files in /home/jovyan, on mounted datasets and file systems, and in /mnt/local are kept.
• Files elsewhere in the container and packages you installed yourself are gone.
• Programs you were running have stopped. Start them again, or let a start script start them each time the instance starts.
• The plan, the workspace size, and the instance’s other settings stay as they were.

To go back to an image you saved from this instance, use Restore Image on its Images tab. A restore works like an image update and keeps the workspace. See Save an instance as an image.

To give the instance a different amount of CPU, GPU, or memory, see Change the plan of an instance. If it stays on Waiting after the update, for example because TIR fails to download a custom image from its registry, see Troubleshooting TIR Instances.