skip to Main Content

Tintri Blog

For Developers: Finding Synthetic VMs and Non-Clone VMs

August 6, 2015

How do I clone a synthetic VM?

First, let’s discuss what a synthetic VM is. From the VMStore System Admin Manual:

A synthetic VM is a VM that is not in inventory but the storage system knows about it from snapshot information, cached data, or other sources, then VMstore will synthesize a Synthetic VM from such data. A replica that has been copied to a destination VMstore is a synthetic VM that is synthesized from replica snapshot information.

To find synthetic VMs, use the GET /v310/vm API with a filter live == FALSE. Here is a snippet of code.

# Filter to look for synthetic clones
q_filter = {'queryType' : 'TOP_DOCS_BY_TIME',
            'live'      : 'FALSE'}

    url = "/v310/vm/"
    r = tintri.api_get_query(server_name, url, q_filter, session_id)
    if r.status_code != 200:
        message = "The HTTP response for get VM call to the server is not 200."
        raise tintri.TintriApiException(message, r.status_code, url, q_filter, r.text)

This lets the VMstore’s database do the the search for you. If you prefer client side checking, you will have to check each VM for 'live' equal to FALSE.

Speaking of client side checking, this is the technique for finding non-clones. A non-clone will not contain the 'snapshot.bases' field. Unfortunately, there is no query parameter for this, so the client must do the work. In the code snippet below, the 'snapshot.bases' field existence is checked for each VM.

page_size = 100

# Get a list of VMs a page size at a time
    get_vm_url = "/v310/vm"
    count = 1
    vm_paginated_result = {'next' : "offset=0&limit=" + str(page_size)}

    # While there are more VMs, go get them
    while 'next' in vm_paginated_result:
        url = get_vm_url + "?" + vm_paginated_result['next']

        # Get a page of VMs
        r = tintri.api_get(server_name, url, session_id)
        if r.status_code != 200:
            raise tintri.TintriApiException(message, r.status_code, url, None, r.text)

        # For each VM in the page, print the VM name and UUID.
        vm_paginated_result = r.json()

        # Check for the first time through the loop and
        # print the total number of VMs.
        if count == 1:
            num_vms = vm_paginated_result["filteredTotal"]
            if num_vms == 0:
                raise tintri.TintriRequestsException("No  VMs present")

            print_info(str(num_vms) + " VMs present")

        # print the non-clone VM names
        items = vm_paginated_result["items"]
        for vm in items:
            vm_name = vm["vmware"]["name"]
            vm_uuid = vm["uuid"]["uuid"]
            snapshot = vm["snapshot"]

            # Check the 'bases' field non-existence to indicate that the VM is a non-clone.
            if not 'bases' in snapshot:
                print(str(count) + ": " + vm_name)
                count += 1

        print_info(str(count) + "non-clone VMs present")

except tintri.TintriRequestsException as tre:
    tintri.api_logout(server_name, session_id)
except tintri.TintriApiException as tae:

This code snippet uses pagination and gets 100 VMs at a time. This puts less of a burden on the VMstore. Note how the 'next' field is used to obtain the next page and is formatted to be appended to the API URI. If the 'next' field exists then there are more items to obtain. The 'next' field is initialized before the loop with the zeroth offset and the page size.

Back To Top
This site is registered on as a development site.