org.ovirt.engine.sdk4.services

Interface ImageTransferService

All Superinterfaces:

Service

All Known Implementing Classes:

ImageTransferServiceImpl

public interface ImageTransferService
extends Service

This service provides a mechanism to control an image transfer. The client will have to create a transfer by using add of the [services/image_transfers] service, stating the image to transfer data to/from.

After doing that, the transfer is managed by this service.

E.g., for uploading to the disk image with id 52cb593f-837c-4633-a444-35a0a0383706, the client can use oVirt’s Python’s SDK as follows:

transfers_service = system_service.image_transfers_service()
transfer = transfers_service.add(
   types.ImageTransfer(
      image=types.Image(
         id='52cb593f-837c-4633-a444-35a0a0383706'
      )
   )
)

Transfers have phases, which govern the flow of the upload/download. A client implementing such a flow should poll/check the transfer’s phase and act accordingly. All the possible phases can be found in ImageTransferPhase.

After adding a new transfer, its phase will be initializing. The client will have to poll on the transfer’s phase until it changes. When the phase becomes transferring, the session is ready to start the transfer.

For example:

transfer_service = transfers_service.image_transfer_service(transfer.id)
while transfer.phase == types.ImageTransferPhase.INITIALIZING:
   time.sleep(3)
   transfer = transfer_service.get()

At that stage, if the transfer’s phase is paused_system, then the session was not successfully established. One possible reason for that is that the ovirt-imageio-daemon is not running in the host that was selected for transfer. The transfer can be resumed by calling resume of the service that manages it.

If the session was successfully established - the returned transfer entity will contain the proxy_url and signed_ticket attributes, which the client needs to use in order to transfer the required data. The client can choose whatever technique and tool for sending the HTTPS request with the image’s data.

• proxy_url is the address of a proxy server to the image, to do I/O to.

• signed_ticket is the content that needs to be added to the Authentication header in the HTTPS request, in order to perform a trusted communication.

For example, Python’s HTTPSConnection can be used in order to perform an upload, so an upload_headers dict is set for the upcoming upload:

upload_headers = {
   'Authorization' :  transfer.signed_ticket,
}

Using Python’s HTTPSConnection, a new connection is established:

# Extract the URI, port, and path from the transfer's proxy_url.
url = urlparse(transfer.proxy_url)

# Create a new instance of the connection.
proxy_connection = HTTPSConnection(
   url.hostname,
   url.port,
   context=ssl.SSLContext(ssl.PROTOCOL_SSLv23)
)

The specific content range being sent must be noted in the Content-Range HTTPS header. This can be used in order to split the transfer into several requests for a more flexible process.

For doing that, the client will have to repeatedly extend the transfer session to keep the channel open. Otherwise, the session will terminate and the transfer will get into paused_system phase, and HTTPS requests to the server will be rejected.

E.g., the client can iterate on chunks of the file, and send them to the proxy server while asking the service to extend the session:

path = "/path/to/image"
MB_per_request = 32
with open(path, "rb") as disk:
   size = os.path.getsize(path)
   chunk_size = 1024*1024*MB_per_request
   pos = 0
   while (pos < size):
      transfer_service.extend()
      upload_headers['Content-Range'] = "bytes %d-%d/%d" % (pos, min(pos + chunk_size, size)-1, size)
      proxy_connection.request(
         'PUT',
         url.path,
         disk.read(chunk_size),
         headers=upload_headers
      )
      r = proxy_connection.getresponse()
      print r.status, r.reason, "Completed", "{:.0%}".format(pos/ float(size))
      pos += chunk_size

When finishing the transfer, the user should call finalize. This will make the final adjustments and verifications for finishing the transfer process.

For example:

transfer_service.finalize()

In case of an error, the transfer’s phase will be changed to finished_failure, and the disk’s status will be changed to Illegal. Otherwise it will be changed to finished_success, and the disk will be ready to be used. In both cases, the transfer entity will be removed shortly after.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ImageTransferService.ExtendRequest Extend the image transfer session.
static interface	ImageTransferService.ExtendResponse Extend the image transfer session.
static interface	ImageTransferService.FinalizeRequest After finishing to transfer the data, finalize the transfer.
static interface	ImageTransferService.FinalizeResponse After finishing to transfer the data, finalize the transfer.
static interface	ImageTransferService.GetRequest Get the image transfer entity.
static interface	ImageTransferService.GetResponse Get the image transfer entity.
static interface	ImageTransferService.PauseRequest Pause the image transfer session.
static interface	ImageTransferService.PauseResponse Pause the image transfer session.
static interface	ImageTransferService.ResumeRequest Resume the image transfer session.
static interface	ImageTransferService.ResumeResponse Resume the image transfer session.

Method Summary

Modifier and Type	Method and Description
ImageTransferService.ExtendRequest	extend() Extend the image transfer session.
ImageTransferService.FinalizeRequest	finalize_() After finishing to transfer the data, finalize the transfer.
ImageTransferService.GetRequest	get() Get the image transfer entity.
ImageTransferService.PauseRequest	pause() Pause the image transfer session.
ImageTransferService.ResumeRequest	resume() Resume the image transfer session.
Service	service(String path) Service locator method, returns individual service on which the URI is dispatched.

Method Detail

extend

ImageTransferService.ExtendRequest extend()

Extend the image transfer session.

finalize_

ImageTransferService.FinalizeRequest finalize_()

After finishing to transfer the data, finalize the transfer.

This will make sure that the data being transferred is valid and fits the image entity that was targeted in the transfer. Specifically, will verify that if the image entity is a QCOW disk, the data uploaded is indeed a QCOW file, and that the image doesn’t have a backing file.

get

ImageTransferService.GetRequest get()

Get the image transfer entity.

pause

ImageTransferService.PauseRequest pause()

Pause the image transfer session.

resume

ImageTransferService.ResumeRequest resume()

Resume the image transfer session. The client will need to poll the transfer’s phase until it is different than resuming. For example:

transfer_service = transfers_service.image_transfer_service(transfer.id)
transfer_service.resume()
transfer = transfer_service.get()

while transfer.phase == types.ImageTransferPhase.RESUMING:
   time.sleep(1)
   transfer = transfer_service.get()

service

Service service(String path)

Service locator method, returns individual service on which the URI is dispatched.