Save an instance as an image

Save Image saves a running instance’s container as a Docker image in a Container Registry namespace of your project, with the packages you installed. Launch new instances from it, put it back on this instance after a restart or a plan change, or pull it with Docker. Save an image before a change you would want to undo, such as an image update, a plan change, or a framework upgrade. An image also gives your project one environment that everyone launches from. TIR saves the image while the instance keeps running.

What the image keeps

In the saved image	Left out of the saved image
Files outside the workspace	The workspace at /home/jovyan: your files, notebooks, and checkpoints
Packages installed with apt	Packages installed with pip install --user
Packages installed with a system-wide pip install	Packages in a virtual environment under /home/jovyan
Edits to /root/.bashrc	Data on mounted datasets, SFS, and PFS

To carry a package in a saved image, install it with apt or with a system-wide pip install. A new instance launched from the saved image starts with an empty workspace. Restoring the image on this instance instead keeps its workspace as it is. For what each part of an instance keeps, see Where your files live on an instance.

Before you begin

• An instance that is Running. Save Image is available only in that status.
• A registry namespace in the project’s Container Registry, in the side menu under Storage. If you need one, a link in the save form creates it right from the form. The link shows when you have permission to create a Container Registry.
• Permission to update instances in the project. Every project role except MEMBER has it, and a MEMBER needs a policy that allows updates.

The saved image is billed as Container Registry storage for as long as it stays in the registry, even after you stop or delete the instance. A namespace is charged for its peak size in each calendar month, and deleting the image ends its charge. See pricing.

Save the image

The saved image leaves out the workspace at /home/jovyan. Before you save, copy any files and checkpoints you need to mounted storage or to your own machine. See Copy files to and from an instance and Mount datasets and file systems on an instance.

1. In the instance’s actions menu, or on its Images tab, select Save Image.
2. In Image Name, enter a name, such as pytorch-env-v1. Use lowercase letters and digits, and separate parts with dots, underscores, or hyphens, up to two of these characters in a row. The name starts and ends with a letter or digit and is three to 120 characters long.
3. (Optional) In Image Tag (Optional), enter a version label, such as v1.0. A tag uses letters, digits, dots, underscores, and hyphens, and starts with a letter, a digit, or an underscore. Left blank, the tag is latest.
4. In Container Registry, choose the namespace to save the image in, and select Create.
5. Select Save. TIR builds the image and pushes it to your registry, where its storage charges apply. Until then, the instance’s app and actions are on hold.

While the image is saving

The instance is Saving Image while TIR builds the image. Once the save finishes, you can open the app again and stop, restart, update, or delete the instance. One instance runs one save at a time, and a namespace builds one image with the same name and tag at a time.

When the build finishes, the instance shows Running again on its own. TIR emails the person who started the save when it succeeds or fails, with the team owner and admins in copy.

Find the saved image

Every image saved from the instance is on its Images tab. While TIR works, the image goes from Building to Pushing, and it ends as Succeeded or Failed. Not Found means the image has been removed from the registry.

You also find the image in Container Registry, on the Images tab of the namespace you chose.

Use the saved image

An image is ready to use once its status is Succeeded.

Launch a new instance from the image

Select Create Instance, choose the Custom Images tab, set Image Type to Private, pick the Registry Namespace, and select the image under Available Images. Complete the form as described in Create an instance from your own image. To copy another instance’s settings as well, pick the saved image in the clone form. See Clone an instance.

Restore the image on this instance

On the instance’s Images tab, select Restore Image on the image. The instance restarts with the saved image and keeps its workspace at /home/jovyan. If the image has been removed from the registry, the restore is refused and its status changes to Not Found.

Pull the image with Docker

To use the image outside TIR, log in with the namespace’s own registry username and password, which are separate from your TIR sign-in, then pull it. Find them under Container Registry, in the side menu under Storage. The namespace’s row has its Username, and its terminal button under Commands gives a ready Docker Login Command. If Docker refuses the login, copy the command again from there. Replace <username> with the namespace’s registry username, <namespace> with the registry namespace, <image-name> with the image name, and <tag> with its tag.

For an image saved in Delhi:

docker login registry.e2enetworks.net -u <username>
docker pull registry.e2enetworks.net/<namespace>/<image-name>:<tag>

For an image saved in Chennai:

docker login in-south1-registry.e2enetworks.net -u <username>
docker pull in-south1-registry.e2enetworks.net/<namespace>/<image-name>:<tag>

Docker asks for your Container Registry password after the login command. For example, to pull the image pytorch-env-v1 with the tag latest from the namespace my-project-images in Delhi:

docker pull registry.e2enetworks.net/my-project-images/pytorch-env-v1:latest

Name and test your images

Give each image a name and a version tag that say what it is, such as pytorch-finetune tagged v2, rather than reusing latest every time. You can then tell versions apart and launch the one you want. Launch an instance from a new image and check that it behaves as expected before you rely on it elsewhere.

Delete a saved image

Delete an image once you are done with it, so you stop paying for it in the registry. Deleting a saved image also removes it from the registry, and the deletion is permanent.

1. On the instance’s Images tab, select Delete Image on the image. It is available once the image is past Building and Pushing. You need permission to delete images in Container Registry.
2. Confirm the deletion.

TIR keeps an image that a resource is still using and refuses to delete it. Deleting the instance itself leaves its saved images in the Container Registry, still billed until you delete them.

If the instance stays on Saving Image, or an instance launched from the image does not start, see Troubleshooting TIR Instances.