ironic.common.image_service module

class ironic.common.image_service.BaseImageService[source]

Bases: object

Provides retrieval of disk images.

abstract download(image_href, image_file)[source]

Downloads image to specified location.

Parameters:

  • image_href – Image reference.

  • image_file – File object to write data to.

Raises:

exception.ImageRefValidationFailed.

Raises:

exception.ImageDownloadFailed.

property is_auth_set_needed

Property to notify the caller if it needs to set authentication.

abstract show(image_href)[source]

Get dictionary of image properties.

Parameters:

image_href – Image reference.

Raises:

exception.ImageRefValidationFailed.

Returns:

dictionary of image properties. It has three of them: ‘size’, ‘updated_at’ and ‘properties’. ‘updated_at’ attribute is a naive UTC datetime object.

property transfer_verified_checksum

The transferred artifact checksum.

abstract validate_href(image_href)[source]

Validate image reference.

Parameters:

image_href – Image reference.

Raises:

exception.ImageRefValidationFailed.

Returns:

Information needed to further operate with an image.

class ironic.common.image_service.FileImageService[source]

Bases: BaseImageService

Provides retrieval of disk images available locally on the conductor.

download(image_href, image_file)[source]

Downloads image to specified location.

Parameters:

  • image_href – Image reference.

  • image_file – File object to write data to.

Raises:

exception.ImageRefValidationFailed if source image file doesn’t exist.

Raises:

exception.ImageDownloadFailed if exceptions were raised while writing to file or creating hard link.

show(image_href)[source]

Get dictionary of image properties.

Parameters:

image_href – Image reference.

Raises:

exception.ImageRefValidationFailed if image file specified doesn’t exist.

Returns:

dictionary of image properties. It has three of them: ‘size’, ‘updated_at’ and ‘properties’. ‘updated_at’ attribute is a naive UTC datetime object.

validate_href(image_href)[source]

Validate local image reference.

Parameters:

image_href – Image reference.

Raises:

exception.ImageRefValidationFailed if source image file doesn’t exist.

Returns:

Path to image file if it exists.

class ironic.common.image_service.HttpImageService[source]

Bases: BaseImageService

Provides retrieval of disk images using HTTP.

download(image_href, image_file)[source]

Downloads image to specified location.

Parameters:

  • image_href – Image reference.

  • image_file – File object to write data to.

Raises:

exception.ImageRefValidationFailed if GET request returned response code not equal to 200.

Raises:

exception.ImageDownloadFailed if: * IOError happened during file write; * GET request failed.

static gen_auth_from_conf_user_pass(image_href)[source]

This function is used to pass the credentials to the chosen

credential verifier and in case the verification is successful generate the compatible authentication object that will be used with the request(s). This function handles the authentication object generation for authentication strategies that are username+password based. Credentials are collected from the oslo.config framework.

Parameters:

image_href – href of the image that is being acted upon

Returns:

Authentication object used directly by the request library

Return type:

requests.auth.HTTPBasicAuth

static get(image_href)[source]

Downloads content and returns the response text.

Parameters:

image_href – Image reference.

Raises:

exception.ImageRefValidationFailed if GET request returned response code not equal to 200.

Raises:

exception.ImageDownloadFailed if: * IOError happened during file write; * GET request failed.

show(image_href)[source]

Get dictionary of image properties.

Parameters:

image_href – Image reference.

Raises:

exception.ImageRefValidationFailed if: * HEAD request failed; * HEAD request returned response code not equal to 200; * Content-Length header not found in response to HEAD request.

Returns:

dictionary of image properties. It has three of them: ‘size’, ‘updated_at’ and ‘properties’. ‘updated_at’ attribute is a naive UTC datetime object.

validate_href(image_href, secret=False)[source]

Validate HTTP image reference.

Parameters:

  • image_href – Image reference.

  • secret – Specify if image_href being validated should not be shown in exception message.

Raises:

exception.ImageRefValidationFailed if HEAD request failed or returned response code not equal to 200.

Raises:

exception.ImageRefIsARedirect if the supplied URL is a redirect to a different URL. The caller may be able to handle this.

Returns:

Response to HEAD request.

static verify_basic_auth_cred_format(image_href, user=None, password=None)[source]

Verify basic auth credentials used for image head request.

Parameters:

  • user – auth username

  • password – auth password

Raises:

exception.ImageRefValidationFailed if the credentials are not present

class ironic.common.image_service.OciImageService[source]

Bases: BaseImageService

Image Service class for accessing an OCI Container Registry.

download(image_href, image_file)[source]

Downloads image to specified location.

Parameters:

  • image_href – Image reference.

  • image_file – File object to write data to.

Raises:

exception.ImageRefValidationFailed.

Raises:

exception.ImageDownloadFailed.

Raises:

exception.OciImageNotSpecific.

identify_specific_image(image_href, image_download_source=None, cpu_arch=None)[source]

Identify a specific OCI Registry Artifact.

This method supports the caller, but is located in the image service code to provide it access to the Container Registry client code which holds the lower level methods.

The purpose of this method is to take the user requested image_href and identify the best matching artifact attached to a container registry’s entry. This is because the container registry can contain many artifacts which can be distributed and allocated by different types. To achieve this goal, this method utilizes the image_download_source to weight the preference of type of file to look for, and the CPU architecture to enable support for mutli-arch container registries.

In order to inform the caller about the url, as well as related data, such as the manifest which points to the artifact, artifact digest, known original filename of the artifact, this method returns a dictionary with several fields which may be useful to aid in understanding of what artifact was chosen.

Parameters:

  • image_href – The image URL as supplied by the Ironic user.

  • image_download_source – The Ironic image_download_source value, defaults to None. When a value of ‘local’ is provided, this method prefers selection of qcow images over raw images. Otherwise, raw images are the preference.

  • cpu_arch – The Bare Metal node’s defined CPU architecture, if any. Defaults to None. When used, a direct match is sought in the remote container registry. If ‘x86_64’ or ‘amd64’ is used, the code searches for the values in the remote registry interchangeably due to OCI data model standardizing on amd64 as the default value for 64bit x86 Architectures.

Returns:

A dictionary with multiple values to the caller to aid in returning the required HTTP URL, but also metadata about the selected artifact including size, filename, blob digest, related manifest digest, the remote recorded mediaType value, if the file appears compressed, if the file appears to be a raw disk image, any HTTP Authorization secret, if applicable, and the OCI image manifest URL. As needs could be different based upon different selection algorithms and evolving standards/approaches in use of OCI registries, the dictionary can also be empty, or contain different values and any caller should defensively use information as needed. If a record is not found, a empty dictionary is the result set. Under normal circumstances, the result looks something like this example. { ‘image_url’: ‘https://fqdn/path’, ‘image_size’: 1234567, ‘image_filename’: ‘filename.raw.zstd’, ‘image_checksum’: ‘f00f…’, ‘image_container_blob_digest’: ‘sha256:f00f…’, ‘image_media_type’: ‘application/zstd, ‘image_compression_type’: ‘zstd’, ‘image_disk_format’: ‘raw’, ‘image_request_authorization_secret’: None, ‘oci_image_manifest_url’: ‘https://fqdn/path@sha256:123f…’, }

property is_auth_set_needed

Property to notify the caller if it needs to set authentication.

set_image_auth(image_url, auth_data)[source]

Sets the supplied auth_data dictionary on the class for use later.

Provides a mechanism to inform the image service of specific credentials without wiring this in as a first class citizen in all image service interfaces.

Parameters:

auth_data – The authentication data dictionary holding username, password, or other authentication data which may be used by this client class.

Returns:

None

Raises:

AssertionError should this method be called twice in the same workflow.

show(image_href)[source]

Get dictionary of image properties.

Parameters:

image_href – Image reference.

Raises:

exception.ImageRefValidationFailed.

Raises:

exception.OciImageNotSpecific.

Returns:

dictionary of image properties. It has three of them: ‘size’, ‘checksum’, and ‘digest’

property transfer_verified_checksum

Property to notify the caller if it needs to set authentication.

validate_href(image_href, secret=None)[source]

Validate OCI image reference.

This method is an alias of the show method on this class, which exists only for API compatibility reasons. Ultimately, the show method performs all of the same validation required.

Parameters:

  • image_href – Image reference.

  • secret – Unused setting.

Raises:

exception.ImageRefValidationFailed

Raises:

exception.OciImageNotSpecific

Returns:

Identical output to the show method on this class as this method is an alias of the show.

ironic.common.image_service.get_image_service(image_href, client=None, context=None)[source]

Get image service instance to download the image.

Parameters:

  • image_href – String containing href to get image service for.

  • client – Glance client to be used for download, used only if image_href is Glance href.

  • context – request context, used only if image_href is Glance href.

Raises:

exception.ImageRefValidationFailed if no image service can handle specified href.

Returns:

Instance of an image service class that is able to download specified image.

ironic.common.image_service.get_image_service_auth_override(node, permit_user_auth=True)[source]

Collect image service authentication overrides

This method is intended to collect authentication credentials together for submission to remote image services which may have authentication requirements which are not presently available, or where specific authentication details are required.

Parameters:

  • task – A Node object instance.

  • permit_user_auth – Option to allow the caller to indicate if user provided authentication should be permitted.

Returns:

A dictionary with username and password keys containing credential to utilize or None if no value found.

ironic.common.image_service.is_container_registry_url(image_href)[source]

Determine if the supplied reference string is an OCI registry URL.

Parameters:

image_href – A string containing a url, sourced from the original user request.

Returns:

True if the URL appears to be an OCI image registry URL. Otherwise, False.