For details on how to use image, see Using OpenStack Image
The image high-level interface is available through the image
member of a
Connection
object. The image
member will
only be added if the service is detected.
Create an image and optionally upload data
Create a new image. If filename
or data
are provided, it will
also upload data to this image.
Note that uploading image data is actually quite a complicated procedure. There are three ways to upload an image:
Image upload
Image import
Image tasks
If the image tasks API is enabled, this must be used. However, this API is deprecated since the Image service’s Mitaka (12.0.0) release and is now admin-only. Assuming this API is not enabled, you may choose between image upload or image import. Image import is more powerful and allows you to upload data from multiple sources including other glance instances. It should be preferred on all services that support it.
name (str) – Name of the image to create. If it is a pathname of an image, the name will be constructed from the extensionless basename of the path.
filename (str) – The path to the file to upload, if needed. (optional, defaults to None)
data – Image data (string or file-like object). It is mutually exclusive with filename
container (str) – Name of the container in swift where images should be uploaded for import if the cloud requires such a thing. (optional, defaults to ‘images’)
md5 (str) – md5 sum of the image file. If not given, an md5 will be calculated.
sha256 (str) – sha256 sum of the image file. If not given, an md5 will be calculated.
disk_format (str) – The disk format the image is in. (optional, defaults to the os-client-config config value for this cloud)
container_format (str) – The container format the image is in. (optional, defaults to the os-client-config config value for this cloud)
tags (list) – List of tags for this image. Each tag is a string of at most 255 chars.
disable_vendor_agent (bool) – Whether or not to append metadata flags to the image to inform the cloud in question to not expect a vendor agent to be runing. (optional, defaults to True)
allow_duplicates – If true, skips checks that enforce unique image name. (optional, defaults to False)
meta – A dict of key/value pairs to use for metadata that bypasses automatic type conversion.
wait (bool) – If true, waits for image to be created. Defaults to true - however, be aware that one of the upload methods is always synchronous.
timeout – Seconds to wait for image creation. None is forever.
validate_checksum (bool) – If true and cloud returns checksum, compares return value with the one calculated or passed into this call. If value does not match - raises exception. Default is ‘false’
use_import (bool) – Use the ‘glance-direct’ method of the
interoperable image import mechanism to import the image. This
defaults to false because it is harder on the target cloud so
should only be used when needed, such as when the user needs the
cloud to transform image format. If the cloud has disabled direct
uploads, this will default to true. If you wish to use other import
methods, use the import_image
method instead.
stores – List of stores to be used when enabled_backends is
activated in glance. List values can be the id of a store or a
Store
instance.
Implies use_import
equals True
.
all_stores – Upload to all available stores. Mutually exclusive
with store
and stores
.
Implies use_import
equals True
.
all_stores_must_succeed – When set to True, if an error occurs
during the upload in at least one store, the worfklow fails, the
data is deleted from stores where copying is done (not staging),
and the state of the image is unchanged. When set to False, the
workflow will fail (data deleted from stores, …) only if the import
fails on all stores specified by the user. In case of a partial
success, the locations added to the image will be the stores where
the data has been correctly uploaded.
Default is True.
Implies use_import
equals True
.
Additional kwargs will be passed to the image creation as additional metadata for the image and will have all values converted to string except for min_disk, min_ram, size and virtual_size which will be converted to int.
If you are sure you have all of your data types correct or have an advanced need to be explicit, use meta. If you are just a normal consumer, using kwargs is likely the right choice.
If a value is in meta and kwargs, meta wins.
The results of image creation
SDKException if there are problems uploading
Import data to an existing image
Interoperable image import process are introduced in the Image API v2.6. It mainly allow image importing from an external url and let Image Service download it by itself without sending binary data at image creation.
image – The value can be the ID of a image or a
Image
instance.
method – Method to use for importing the image. Not all
deployments support all methods. One of: glance-direct
(default), web-download
, glance-download
, or
copy-image
. Use of glance-direct
requires the image be
first staged.
uri – Required only if using the web-download
import method.
This url is where the data is made available to the Image
service.
remote_region – The remote glance region to download the image from when using glance-download.
remote_image_id – The ID of the image to import from the remote glance when using glance-download.
remote_service_interface – The remote glance service interface to use when using glance-download.
store – Used when enabled_backends is activated in glance. The
value can be the id of a store or a.
Store
instance.
stores – List of stores to be used when enabled_backends is
activated in glance. List values can be the id of a store or a
Store
instance.
all_stores – Upload to all available stores. Mutually exclusive
with store
and stores
.
all_stores_must_succeed – When set to True, if an error occurs during the upload in at least one store, the worfklow fails, the data is deleted from stores where copying is done (not staging), and the state of the image is unchanged. When set to False, the workflow will fail (data deleted from stores, …) only if the import fails on all stores specified by the user. In case of a partial success, the locations added to the image will be the stores where the data has been correctly uploaded. Default is True.
The raw response from the request.
Stage binary image data
Create and upload a new image from attributes
container_format – Format of the container. A valid value is ami, ari, aki, bare, ovf, ova, or docker.
disk_format – The format of the disk. A valid value is ami, ari, aki, vhd, vmdk, raw, qcow2, vdi, or iso.
data – The data to be uploaded as an image.
attrs (dict) – Keyword arguments which will be used to create
a Image
, comprised of the
properties on the Image class.
The results of image creation
Download an image
This will download an image to memory when stream=False
, or allow
streaming downloads using an iterator when stream=True
.
For examples of working with streamed responses, see
Downloading an Image with stream=True.
image – The value can be either the ID of an image or a
Image
instance.
stream (bool) –
When True
, return a requests.Response
instance allowing you to iterate over the response data stream
instead of storing its entire contents in memory. See
requests.Response.iter_content()
for more details.
NOTE: If you do not consume the entirety of the response you must
explicitly call requests.Response.close()
or otherwise risk
inefficiencies with the requests
library’s handling of
connections.
When False
, return the entire contents of the response.
output – Either a file object or a path to store data into.
chunk_size (int) – size in bytes to read from the wire and buffer at one time. Defaults to 1024
When output is not given - the bytes comprising the given
Image when stream is False, otherwise a requests.Response
instance. When output is given - a
Image
instance.
Delete an image
image – The value can be either the ID of an image or a
Image
instance.
store – The value can be either the ID of a store or a
Store
instance that the
image is associated with. If specified, the image will only be
deleted from the specified store.
ignore_missing (bool) – When set to False
ResourceNotFound
will be
raised when the image does not exist.
When set to True
, no exception will be set when
attempting to delete a nonexistent image.
None
Find a single image
name_or_id – The name or ID of a image.
ignore_missing (bool) – When set to False
ResourceNotFound
will be
raised when the resource does not exist.
When set to True
, None will be returned when
attempting to find a nonexistent resource.
One Image
or None
Get a single image
Return a generator of images
query (kwargs) – Optional query parameters to be sent to limit the resources being returned.
A generator of image objects
Update a image
Deactivate an image
image – Either the ID of a image or a
Image
instance.
None
Reactivate an image
image – Either the ID of a image or a
Image
instance.
None
Add a tag to an image
image – The value can be the ID of a image or a
Image
instance
that the member will be created for.
tag (str) – The tag to be added
None
Remove a tag to an image
image – The value can be the ID of a image or a
Image
instance
that the member will be created for.
tag (str) – The tag to be removed
None
Create a new member from attributes
Delete a member
member – The value can be either the ID of a member or a
Member
instance.
image – The value can be either the ID of an image or a
Image
instance that the member
is part of. This is required if member
is an ID.
ignore_missing (bool) – When set to False
ResourceNotFound
will be raised when
the member does not exist. When set to True
, no exception will
be set when attempting to delete a nonexistent member.
None
Find a single member
name_or_id – The name or ID of a member.
image – This is the image that the member belongs to,
the value can be the ID of a image or a
Image
instance.
ignore_missing (bool) – When set to False
ResourceNotFound
will be
raised when the resource does not exist.
When set to True
, None will be returned when
attempting to find a nonexistent resource.
One Member
or None
Get a single member on an image
Return a generator of members
Update the member of an image
Return a generator of tasks
query (kwargs) – Optional query parameters to be sent to limit the resources being returned.
A generator of task objects
Get task details
Create a new task from attributes
Wait for a task to be in a particular status.
task – The resource to wait on to reach the specified status.
The resource must have a status
attribute.
status – Desired status.
failures (list
) – Statuses that would be interpreted as failures.
interval – Number of seconds to wait before to consecutive checks. Default to 2.
wait – Maximum number of seconds to wait before the change. Default to 120.
The resource is returned on success.
ResourceTimeout
if transition
to the desired status failed to occur in specified seconds.
ResourceFailure
if the resource
has transited to one of the failure statuses.
AttributeError
if the resource does not have a
status
attribute.
Get images schema
One Schema
ResourceNotFound
when no resource can be found.
Get single image schema
One Schema
ResourceNotFound
when no resource can be found.
Get image members schema
One Schema
ResourceNotFound
when no resource can be found.
Get image member schema
One Schema
ResourceNotFound
when no resource can be found.
Get image tasks schema
One Schema
ResourceNotFound
when no resource can be found.
Get image task schema
One Schema
ResourceNotFound
when no resource can be found.
Get metadata definition namespace schema
One MetadefSchema
ResourceNotFound
when no resource can be found.
Get metadata definition namespaces schema
One MetadefSchema
ResourceNotFound
when no resource can be found.
Get metadata definition resource type association schema
One MetadefSchema
ResourceNotFound
when no resource can be found.
Get metadata definition resource type associations schema
One MetadefSchema
ResourceNotFound
when no resource can be found.
Get metadata definition object schema
One MetadefSchema
ResourceNotFound
when no resource can be found.
Get metadata definition objects schema
One MetadefSchema
ResourceNotFound
when no resource can be found.
Get metadata definition property schema
One MetadefSchema
ResourceNotFound
when no resource can be found.
Get metadata definition properties schema
One MetadefSchema
ResourceNotFound
when no resource can be found.
Get metadata definition tag schema
One MetadefSchema
ResourceNotFound
when no resource can be found.
Get metadata definition tags schema
One MetadefSchema
ResourceNotFound
when no resource can be found.
Return a generator of supported image stores
A generator of store objects
Get a info about image constraints
One Import
ResourceNotFound
when no resource can be found.
Create a new metadef namespace from attributes
attrs (dict) – Keyword arguments which will be used to create
a MetadefNamespace
comprised of the properties on the MetadefNamespace class.
The results of metadef namespace creation
Delete a metadef namespace
metadef_namespace – The value can be either the name of a metadef
namespace or a
MetadefNamespace
instance.
ignore_missing (bool) – When set to False
,
ResourceNotFound
will be raised when
the metadef namespace does not exist.
None
Get a single metadef namespace
metadef_namespace – Either the name of a metadef namespace or an
MetadefNamespace
instance.
One
MetadefNamespace
ResourceNotFound
when no
resource can be found.
Return a generator of metadef namespaces
A generator object of metadef namespaces
ResourceNotFound
when no resource can be found.
Update a server
metadef_namespace – Either the name of a metadef namespace or an
MetadefNamespace
instance.
attrs – The attributes to update on the metadef namespace
represented by metadef_namespace
.
The updated metadef namespace
Return a generator of metadef resource types
A generator object of metadef resource types
ResourceNotFound
when no resource can be found.
and the resource type specified in the body of the request.
attrs (dict) – Keyword arguments which will be used to create a
MetadefResourceTypeAssociation
comprised of the properties on the
MetadefResourceTypeAssociation class.
The results of metadef resource type association creation
Removes a resource type association in a namespace.
metadef_resource_type – The value can be either the name of
a metadef resource type association or an
MetadefResourceTypeAssociation
instance.
metadef_namespace – The value can be either the name of metadef
namespace or an
MetadefNamespace
instance
ignore_missing (bool) – When set to False
,
ResourceNotFound
will be raised when
the metadef resource type association does not exist.
None
Return a generator of metadef resource type associations
metadef_namespace – The value can be either the name of metadef
namespace or an
MetadefNamespace
instance
A generator object of metadef resource type associations
ResourceNotFound
when no resource can be found.
Wait for a resource to be deleted.
res – The resource to wait on to be deleted.
interval – Number of seconds to wait before to consecutive checks. Default to 2.
wait – Maximum number of seconds to wait before the change. Default to 120.
The resource is returned on success.
ResourceTimeout
if transition
to delete failed to occur in the specified seconds.
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.