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)¶

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=True, **kwargs)¶

Upload an image.

Parameters:

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) 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’

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)
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’

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

import_image(image, method='glance-direct', uri=None, store=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:

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.
Returns:	None

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.

Returns:

None

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:	`Image`

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 when stream=True. For examples of working with streamed responses, see Downloading an Image with stream=True.

Parameters:

Parameters:	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
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 - a `Image` instance.

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

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 - a Image instance.

update_image(image, **attrs)¶

Update a image

Parameters:	image – Either the ID of a image or a `Image` instance.
Attrs kwargs:	The attributes to update on the image represented by `value`.
Returns:	The updated image
Return type:	`Image`

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 to `True`, no exception will be set when attempting to delete a nonexistent image.
Returns:	`None`

get_image(image)¶

Get a single image

Parameters:	image – The value can be the ID of a image or a `Image` instance.
Returns:	One `Image`
Raises:	`ResourceNotFound` when no resource can be found.

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 to `True`, None will be returned when attempting to find a nonexistent resource.
Returns:	One `Image` or None

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:	`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

stage_image(image, filename=None, data=None)¶

Stage binary image data

Parameters:	image – The value can be the ID of a image or a `Image` instance. filename – Optional name of the file to read data from. data – Optional data to be uploaded as an image.
Returns:	The results of image creation
Return type:	`Image`

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

Member Operations¶

add_member(image, **attrs)¶

Create a new member from attributes

Parameters:	image – The value can be the ID of a image or a `Image` instance that the member will be created for. attrs (dict) – Keyword arguments which will be used to create a `Member`, comprised of the properties on the Member class.
Returns:	The results of member creation
Return type:	`Member`

remove_member(member, image, ignore_missing=True)¶

Delete a member

Parameters:	member – The value can be either the ID of a member or a `Member` instance. 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.
Returns:	`None`

update_member(member, image, **attrs)¶

Update the member of an image

Parameters:	member – Either the ID of a member or a `Member` instance. image – This is the image that the member belongs to. The value can be the ID of a image or a `Image` instance.
Attrs kwargs:	The attributes to update on the member represented by `value`.
Returns:	The updated member
Return type:	`Member`

get_member(member, image)¶

Get a single member on an image

Parameters:	member – The value can be the ID of a member or a `Member` instance. image – This is the image that the member belongs to. The value can be the ID of a image or a `Image` instance.
Returns:	One `Member`
Raises:	`ResourceNotFound` when no resource can be found.

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 to `True`, None will be returned when attempting to find a nonexistent resource.
Returns:	One `Member` or None

members(image)¶

Return a generator of members

Parameters:	image – This is the image that the member belongs to, the value can be the ID of a image or a `Image` instance.
Returns:	A generator of member objects
Return type:	`Member`

Task Operations¶

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:	`Task`

create_task(**attrs)¶

Create a new task from attributes

Parameters:	attrs (dict) – Keyword arguments which will be used to create a `Task`, comprised of the properties on the Task class.
Returns:	The results of task creation
Return type:	`Task`

get_task(task)¶

Get task details

Parameters:	task – The value can be the ID of a task or a `Task` instance.
Returns:	One `Task`
Raises:	`ResourceNotFound` when no resource can be found.

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 a `status` attribute.

Schema Operations¶

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¶

stores(**query)¶

Return a generator of supported image stores

Returns:	A generator of store objects
Return type:	`Store`

get_import_info()¶

Get a info about image constraints

Returns:	One `Import`
Raises:	`ResourceNotFound` when no resource can be found.

Image API v2

Image API v2¶

The Image v2 Class¶

Image Operations¶

Member Operations¶

Task Operations¶

Schema Operations¶

Service Info Discovery Operations¶

openstacksdk

Page Contents