Image API v2¶
For details on how to use image, see Using OpenStack Image
The Image v2 Class¶
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.
Image Operations¶
- class openstack.image.v2._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
- import_image(image, method='glance-direct', uri=None, store=None, stores=None, all_stores=None, all_stores_must_succeed=None)
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.
- Parameters
image – The value can be the ID of a image or a
Image
instance.method – Method to use for importing the image. A valid value is glance-direct or web-download.
uri – Required only if using the web-download import method. This url is where the data is made available to the Image service.
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
andstores
.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.
- Returns
None
- stage_image(image, filename=None, data=None)
Stage binary image data
- upload_image(container_format=None, disk_format=None, data=None, **attrs)
Create and upload a new image from attributes
- Parameters
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.
- Returns
The results of image creation
- Return type
- download_image(image, stream=False, output=None, chunk_size=1024)
Download an image
This will download an image to memory when
stream=False
, or allow streaming downloads using an iterator whenstream=True
. For examples of working with streamed responses, see Downloading an Image with stream=True.- Parameters
image – The value can be either the ID of an image or a
Image
instance.stream (bool) –
When
True
, return arequests.Response
instance allowing you to iterate over the response data stream instead of storing its entire contents in memory. Seerequests.Response.iter_content()
for more details. NOTE: If you do not consume the entirety of the response you must explicitly callrequests.Response.close()
or otherwise risk inefficiencies with therequests
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
- Returns
When output is not given - the bytes comprising the given Image when stream is False, otherwise a
requests.Response
instance. When output is given - aImage
instance.
- delete_image(image, ignore_missing=True)
Delete an image
- Parameters
image – The value can be either the ID of an image or a
Image
instance.ignore_missing (bool) – When set to
False
ResourceNotFound
will be raised when the image does not exist. When set toTrue
, no exception will be set when attempting to delete a nonexistent image.
- Returns
None
- find_image(name_or_id, ignore_missing=True)
Find a single image
- Parameters
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 toTrue
, None will be returned when attempting to find a nonexistent resource.
- Returns
One
Image
or None
- get_image(image)
Get a single image
- images(**query)
Return a generator of images
- Parameters
query (kwargs) – Optional query parameters to be sent to limit the resources being returned.
- Returns
A generator of image objects
- Return type
- update_image(image, **attrs)
Update a image
- deactivate_image(image)
Deactivate an image
- Parameters
image – Either the ID of a image or a
Image
instance.- Returns
None
- reactivate_image(image)
Deactivate an image
- Parameters
image – Either the ID of a image or a
Image
instance.- Returns
None
- add_tag(image, tag)
Add a tag to an image
- Parameters
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
- Returns
None
- remove_tag(image, tag)
Remove a tag to an image
- Parameters
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
- Returns
None
- create_image(name, filename=None, container=None, md5=None, sha256=None, disk_format=None, container_format=None, disable_vendor_agent=True, allow_duplicates=False, meta=None, wait=False, timeout=3600, data=None, validate_checksum=False, use_import=False, stores=None, tags=None, all_stores=None, all_stores_must_succeed=None, **kwargs)
Upload an image.
- Parameters
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 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.
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. Impliesuse_import
equalsTrue
.all_stores – Upload to all available stores. Mutually exclusive with
store
andstores
. Impliesuse_import
equalsTrue
.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
equalsTrue
.
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.
- Returns
A
munch.Munch
of the Image object- Raises
SDKException if there are problems uploading
Member Operations¶
- class openstack.image.v2._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
- add_member(image, **attrs)
Create a new member from attributes
- remove_member(member, image=None, ignore_missing=True)
Delete a member
- Parameters
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 ifmember
is an ID.ignore_missing (bool) – When set to
False
ResourceNotFound
will be raised when the member does not exist. When set toTrue
, no exception will be set when attempting to delete a nonexistent member.
- Returns
None
- find_member(name_or_id, image, ignore_missing=True)
Find a single member
- Parameters
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 toTrue
, None will be returned when attempting to find a nonexistent resource.
- Returns
One
Member
or None
- get_member(member, image)
Get a single member on an image
- members(image, **query)
Return a generator of members
- update_member(member, image, **attrs)
Update the member of an image
Task Operations¶
- class openstack.image.v2._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
- tasks(**query)
Return a generator of tasks
- Parameters
query (kwargs) – Optional query parameters to be sent to limit the resources being returned.
- Returns
A generator of task objects
- Return type
- get_task(task)
Get task details
- create_task(**attrs)
Create a new task from attributes
- wait_for_task(task, status='success', failures=None, interval=2, wait=120)
Wait for a task to be in a particular status.
- Parameters
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.
- Returns
The resource is returned on success.
- Raises
ResourceTimeout
if transition to the desired status failed to occur in specified seconds.- Raises
ResourceFailure
if the resource has transited to one of the failure statuses.- Raises
AttributeError
if the resource does not have astatus
attribute.
Schema Operations¶
- class openstack.image.v2._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
- get_images_schema()
Get images schema
- Returns
One
Schema
- Raises
ResourceNotFound
when no resource can be found.
- get_image_schema()
Get single image schema
- Returns
One
Schema
- Raises
ResourceNotFound
when no resource can be found.
- get_members_schema()
Get image members schema
- Returns
One
Schema
- Raises
ResourceNotFound
when no resource can be found.
- get_member_schema()
Get image member schema
- Returns
One
Schema
- Raises
ResourceNotFound
when no resource can be found.
- get_tasks_schema()
Get image tasks schema
- Returns
One
Schema
- Raises
ResourceNotFound
when no resource can be found.
- get_task_schema()
Get image task schema
- Returns
One
Schema
- Raises
ResourceNotFound
when no resource can be found.
Service Info Discovery Operations¶
- class openstack.image.v2._proxy.Proxy(session, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None, *args, **kwargs)
- stores(**query)
Return a generator of supported image stores
- Returns
A generator of store objects
- Return type
- get_import_info()
Get a info about image constraints
- Returns
One
Import
- Raises
ResourceNotFound
when no resource can be found.