Overview¶
Snapshots and Images¶
When you have created a custom workflow or configuration, you can create a snapshot for your own use. In OpenStack, an instance snapshot is an image. The only difference between an image that has been uploaded directly to the image data service: glance and an image you create by snapshot is that an image created by snapshot has additional properties in the Glance database and defaults to being private.
Info
Glance is a central image repository which provides discovering, registering, retrieving for disk and server images.
CAUTION: Avoid snapshotting running instances
You can create a snapshot from a running server instance, but if you want to preserve data, you must shut down the source VM and verify the instance status is SHUTOFF before creating the snapshot.
CAUTION: cloud-init & qemu-guest-agent
Before creating the snapshot and/or image, you’ll want to make sure that cloud-init is installed on your instance as well as qemu-guest-agent
- If your instance was based on one of the Featured images, both cloud-init and qemu-guest-agent should be present unless you explicitly removed them.
To create the snapshot from the command line ¶
openstack server image create --name snapshot-image-name instance-name
# (e.g. openstack server image create --name MyCustomImage-Feb-7-2022 my-custom-instance)
The snapshot will also be available in Horizon and Exosphere both in the image list and will be avaible as a starting image for a new instance.
Snapshots can be downloaded locally in raw format with:
openstack image save --file whatever_file_name_you_like.raw UID
# (e.g. openstack image save --file my-custom-image.raw 569677d8-c7b0-4606-86d8-7673a5ecd5cf)
Uploading a snapshot or new image into Glance:¶
You can upload a snapshot or image into Glance using:
openstack image create \
--disk-format raw \
--container-format bare \
--property visibility=private \
--property hw_disk_bus=scsi \
--property hw_scsi_model=virtio-scsi \
--property hw_qemu_guest_agent=yes \
--property os_require_quiesce=yes \
--file my-custom-image.raw \
My-Custom-Image-Name
CAUTION: metadata tags and visibility
There are a lot of metadata tags in the example, but those are important to insure that your instances will create properly from the stored image. You definitely want to make sure you get them all.
You can also set the visibility property during creation, but see Sharing an Image for limits.
Boot & Test¶
- Boot the new image.
- Test it.
- Make sure it works.
- Do this before deleting. Please. Once it’s gone, it’s really gone. Be sure.
Delete unused snapshot ¶
Delete your snapshot if you no longer need it. For example:
openstack image delete 569677d8-c7b0-4606-86d8-7673a5ecd5cf
Sharing an Image ¶
When you upload an image to Openstack, you can set the visibility of your image. Our documentation for uploading an image from the CLI sets visibility to private, which makes the image accessible only to users in the same project.
In order to make an image or snapshot available to users in other projects you need to set visibility either to shared or to community.
When an image is set to community with:
openstack image set --community ${image-uuid-or-name}
Placeholder ${variables} on this page
This page uses shell variable syntax to represent placeholders in commands that you should substitute with your own input. For example, if your image’s name is my-awesome-js2-image, this command becomes:
openstack image set --community my-awesome-js2-image
users in ALL projects have access to it and they are displayed in Horizon and Exosphere.
CAUTION: Use --community, not --visibility community
openstack image set --visibility community does not work. --visibility is an Image v1 option that is no longer supported by the Image v2 API, and the command fails with ERROR: --visibility was given, which is an Image v1 option that is no longer supported in Image v2. Use the dedicated --community flag (or --shared, --private, --public) instead.
In order to request community images via the CLI (similar for the API) we need to add --community to the command:
openstack image list --community
Because by default, when you run:
openstack image list
Only the following images are returned:
publicimages- All images which you created (including any with visibility of
privateandshared) - All
sharedimages created by other projects, but which you have explicitly accepted membership of (see below)
To return only public, only private, or only shared images, you can run one of the following:
openstack image list --public
openstack image list --private
openstack image list --shared
Note: In the last case it will return all shared images for images you created, as well as images created by other projects which you have explicitly accepted membership of (see below).
A community image from another project is bootable even if it does not appear in your default image list
A community image owned by a different project may not show up in the default openstack image list output, because that command only returns public images plus the ones you own or have membership in. The image is still fully bootable. Use openstack image list --community to find it, and you can create instances from it directly (e.g. openstack server create --image <image-uuid-or-name> ...).
When an image is set to shared with:
openstack image set --shared ${image-uuid-or-name}
CAUTION: Setting shared visibility alone does NOT grant access
openstack image set --shared only marks the image as shareable. It does not by itself give any other project access to the image. To actually share it with another project you must add that project as a member with openstack image add project (below), and the receiving project must then accept the membership. Until both of those steps happen, users in the other project will get No Image found for ${image-uuid-or-name} (HTTP 404).
To share it explicitly with another project, add that project as a member:
openstack image add project ${image-uuid-or-name} ${project-uuid}
Where ${project-uuid} is the OpenStack UUID of the project you want to share it with.
Use the receiving project’s UUID, not its name.
You may experience difficulty accepting the share action from the receiving project (No Image found for ${image-uuid-here}) if you run openstack image add project with a project name/number (e.g. ABC260001). Instead, use an OpenStack UUID.
You can find your current project’s UUID by running:
openstack project show -c name -f value $(openstack application credential show -c project_id -f value ${OS_APPLICATION_CREDENTIAL_ID})
Adding the member places the membership in a pending state. Only the receiving project can complete it; the owner cannot accept on their behalf (the owner gets a 403 Forbidden: You are not authorized to complete modify_member action). Someone from the other project you’re sharing it with would then need to do
openstack image set --accept ${image-uuid-or-name}
to accept the image, which flips the membership from pending to accepted. After that the image shows up in the receiving project’s openstack image list and can be used to boot instances.
You can check the current visibility setting of an image with:
openstack image show ${image-uuid-or-name} -c name -c id -c visibility
You can list which projects you’ve shared an image with an their status with:
openstack image member list ${image-uuid-or-name}
The status column shows the lifecycle of each member: pending after openstack image add project, flipping to accepted once the receiving project runs openstack image set --accept.
To stop sharing the image with a specific project, remove the member:
openstack image remove project ${image-uuid-or-name} ${project-uuid}
CAUTION: VISIBILITY
You can set the visibility property to shared (only users in your project or projects you specifically shared with you can see and boot) or private (only your allocation can see and boot). Only in VERY special cases will Jetstream2 allow public visibility, such as staff-featured images. Limiting the number of fully public images in the catalog improves Jetstream2 reliability and performance.
Currently, visibility can only be modified in the Horizon and CLI interfaces.