<commit_before><?xml version="1.0" encoding="UTF-8"?>
<section xml:id="vmware-vmdk-driver"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         version="5.0">
    <title>VMware VMDK driver</title>
    <para>VMware VMDK driver enables management of cinder volume on VMware
    vCenter Server or ESX managed datastore. Cinder volume is backed by VMDK
    files on the datastore.</para>
    <simplesect>
        <title>Configuration</title>
        <para>Two cinder drivers for VMware vCenter server and ESX are
        provided. Appropriate driver must be configured when using VMware
        server. For attach/detach operation to an instance, the driver works as
        expected only with the VMware driver for nova and it does not work
        with other nova drivers. Both nova and cinder drivers must be
        configured to the same server. The following table captures the
        configuration mapping:</para>
        <table rules="all">
            <caption>
                Cinder-Nova configuration mapping with VMware server
            </caption>
            <thead>
                <tr>
                    <td>VMware server</td>
                    <td>Nova driver</td>
                    <td>Cinder driver</td>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>vCenter server</td>
                    <td>vmwareapi.VMwareVCDriver</td>
                    <td>
                        cinder.volume.drivers.vmware.vmdk.VMwareVcVmdkDriver
                    </td>
                </tr>
                <tr>
                    <td>ESX/ESXi server</td>
                    <td>vmwareapi.VMwareESXDriver</td>
                    <td>
                        cinder.volume.drivers.vmware.vmdk.VMwareEsxVmdkDriver
                    </td>
                </tr>
            </tbody>
        </table>
        <para>The following table lists various options that the drivers support:</para>
        <xi:include href="../../../common/tables/cinder-vmware.xml"/>
    </simplesect>
    <simplesect>
        <title>VMDK disk type</title>
        <para>VMwareVcVmdkDriver and VMwareEsxVmdkDriver support creating
        VMDK disk file of types: <literal>thin</literal>,
        <literal>thick</literal> and <literal>eagerZeroedThick</literal>.
        VMDK disk file type can be specified via volume type extra specs. By
        using any volume type with appropriate extra spec for volume creation,
        the driver creates one of the above VMDK disk file type. The following
        captures extra spec entry to VMDK disk file type mapping:</para>
        <table rules="all">
            <caption>Extra spec entry to VMDK disk file type mapping</caption>
            <thead>
                <tr>
                    <td>Disk file type</td>
                    <td>Extra spec key</td>
                    <td>Extra spec value</td>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>thin</td>
                    <td>vmware:vmdk_type</td>
                    <td>thin</td>
                </tr>
                <tr>
                    <td>thick</td>
                    <td>vmware:vmdk_type</td>
                    <td>thick</td>
                </tr>
                <tr>
                    <td>eagerZeroedThick</td>
                    <td>vmware:vmdk_type</td>
                    <td>eagerZeroedThick</td>
                </tr>
            </tbody>
        </table>
        <para>When no volume type is used or if none of the above extra spec
        entry is found in the volume type, then the default disk file type
        used is <literal>thin</literal>.</para>
        <para>Example: creation of thick VMDK volume</para>
        <screen>
        <prompt>$</prompt> <userinput>cinder type-create thick_volume</userinput>
        <prompt>$</prompt> <userinput>cinder type-key thick_volume set vmware:vmdk_type=thick</userinput>
        <prompt>$</prompt> <userinput>cinder create --volume-type thick_volume --display-name volume1 1</userinput>
        </screen>
    </simplesect>
    <simplesect>
        <title>Clone type</title>
        <para>VMwareVcVmdkDriver supports clone types: <literal>full</literal>
        and <literal>linked/fast</literal> while creating volume from another
        source volume or from a snapshot point. Clone type can be specified via
        volume type extra specs. By using volume type with appropriate extra
        spec for creating volume from another source volume or from a snapshot
        point, the driver creates a <literal>full</literal> clone or a
        <literal>linked</literal> clone. The following captures extra spec
        entry to clone type mapping:</para>
        <table rules="all">
            <caption>Extra spec entry to clone type mapping</caption>
            <thead>
                <tr>
                    <td>Clone type</td>
                    <td>Extra spec key</td>
                    <td>Extra spec value</td>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>full</td>
                    <td>vmware:clone_type</td>
                    <td>full</td>
                </tr>
                <tr>
                    <td>linked/fast</td>
                    <td>vmware:clone_type</td>
                    <td>linked</td>
                </tr>
            </tbody>
        </table>
        <para>When no volume type is used or if none of the above extra spec
        entry is found in the volume type, then the default clone type is
        <literal>full</literal>.</para>
        <para>Example: linked cloning from another source volume</para>
        <screen>
        <prompt>$</prompt> <userinput>cinder type-create fast_clone</userinput>
        <prompt>$</prompt> <userinput>cinder type-key fast_clone set vmware:clone_type=linked</userinput>
        <prompt>$</prompt> <userinput>cinder create --volume-type fast_clone --source-volid 25743b9d-3605-462b-b9eb-71459fe2bb35 --display-name volume1 1</userinput>
        </screen>
        <para>Note: VMwareEsxVmdkDriver ignores the extra spec entry and always
        creates a <literal>full</literal> clone while creating volume from
        another source volume or from a snapshot point.</para>
    </simplesect>
    <simplesect>
        <title>Supported operations</title>
        <para>The following operations are supported by VMwareVcVmdkDriver and
        VMwareEsxVmdkDriver:</para>
        <itemizedlist>
            <listitem>
                <para>create volume</para>
            </listitem>
            <listitem>
                <para>create volume from another source volume: Supported only
                if source volume is not attached to an instance.</para>
            </listitem>
            <listitem>
                <para>create volume from snapshot</para>
            </listitem>
            <listitem>
                <para>create volume from glance image</para>
            </listitem>
            <listitem>
                <para>attach volume: When a volume is attached to an instance,
                a reconfigure operation is performed on the instance to add the
                volume's VMDK to it. The user must manually rescan and mount
                the device from within the guest operating system.</para>
            </listitem>
            <listitem>
                <para>detach volume</para>
            </listitem>
            <listitem>
                <para>create snapshot: Allowed only if volume is not attached
                to an instance.</para>
            </listitem>
            <listitem>
                <para>delete snapshot: Allowed only if volume is not attached
                to an instance.</para>
            </listitem>
            <listitem>
                <para>upload as image to glance: Allowed only if volume is not
                attached to an instance.</para>
            </listitem>
        </itemizedlist>
    </simplesect>
    <simplesect>
        <title>Datastore selection</title>
        <para>The driver chooses datastore that can accommodate for the volume
        space and has highest <literal>freespace/totalspace</literal> metric
        value.</para>
        <para>When the volume is being attached to an instance, the driver
        tries to place the volume under instance's ESX host on a datastore
        selected based on the above strategy.</para>
    </simplesect>
</section><commit_msg>Recommend vCenter VMDK driver and other edits<commit_after><?xml version="1.0" encoding="UTF-8"?>
<section xml:id="vmware-vmdk-driver"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         version="5.0">
    <title>VMware VMDK driver</title>
    <para>The VMware VMDK driver enables management of OpenStack Block Storage volumes on vCenter
        managed datastores. Volumes are backed by VMDK files on datastores using any VMware
        compatible storage technology. (e.g. NFS, iSCSI, FiberChannel, vSAN)</para>
    <simplesect>
        <title>Configuration</title>
        <para>The recommended OpenStack Block Storage volume driver is the VMware vCenter VMDK
            driver. An ESX VMDK driver is provided as well, but it has not been extensively tested.
            When configuring either driver, you must match it with the appropriate OpenStack Compute
            driver from VMware and both drivers must point to the same server. The following table
            captures this configuration mapping:</para>
        <table rules="all">
            <caption>
                Cinder-Nova configuration mapping with VMware server
            </caption>
            <thead>
                <tr>
                    <td>VMware Server</td>
                    <td>OpenStack Compute Driver</td>
                    <td>OpenStack Block Storage Driver</td>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>vCenter server</td>
                    <td>vmwareapi.VMwareVCDriver</td>
                    <td>
                        cinder.volume.drivers.vmware.vmdk.VMwareVcVmdkDriver
                    </td>
                </tr>
                <tr>
                    <td>ESX/ESXi server</td>
                    <td>vmwareapi.VMwareESXDriver</td>
                    <td>
                        cinder.volume.drivers.vmware.vmdk.VMwareEsxVmdkDriver
                    </td>
                </tr>
            </tbody>
        </table>
        <para>The following table lists various options that the drivers support:</para>
        <xi:include href="../../../common/tables/cinder-vmware.xml"/>
    </simplesect>
    <simplesect>
        <title>VMDK disk type</title>
        <para>The VMware VMDK drivers support creating VMDK disk files of type:
                <literal>thin</literal>, <literal>thick</literal> and
                <literal>eagerZeroedThick</literal>. The VMDK disk file type is specified using the
                <code>vmware:vmdk_type</code> extra spec key with the appropriate value. The
            following table captures the mapping between the extra spec entry and the VMDK disk file
            type:</para>
        <table rules="all">
            <caption>Extra spec entry to VMDK disk file type mapping</caption>
            <thead>
                <tr>
                    <td>Disk file type</td>
                    <td>Extra spec key</td>
                    <td>Extra spec value</td>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>thin</td>
                    <td>vmware:vmdk_type</td>
                    <td>thin</td>
                </tr>
                <tr>
                    <td>thick</td>
                    <td>vmware:vmdk_type</td>
                    <td>thick</td>
                </tr>
                <tr>
                    <td>eagerZeroedThick</td>
                    <td>vmware:vmdk_type</td>
                    <td>eagerZeroedThick</td>
                </tr>
            </tbody>
        </table>
        <para>If no <code>vmdk_type</code> extra spec entry is specified, the default disk file type is
                <literal>thin</literal>.</para>
        <para>The example below shows how to create a <code>thick</code> VMDK volume using the appropriate
            <code>vmdk_type</code>:</para>
        <screen>
        <prompt>$</prompt> <userinput>cinder type-create thick_volume</userinput>
        <prompt>$</prompt> <userinput>cinder type-key thick_volume set vmware:vmdk_type=thick</userinput>
        <prompt>$</prompt> <userinput>cinder create --volume-type thick_volume --display-name volume1 1</userinput>
        </screen>
    </simplesect>
    <simplesect>
        <title>Clone type</title>
        <para>With the VMware VMDK drivers, you can create a volume from another source volume or
            from a snapshot point. The VMware vCenter VMDK driver supports clone types
                <literal>full</literal> and <literal>linked/fast</literal>. The clone type is
            specified using the <code>vmware:clone_type</code> extra spec key with the appropriate value. The
            following table captures the mapping for clone types:</para>
        <table rules="all">
            <caption>Extra spec entry to clone type mapping</caption>
            <thead>
                <tr>
                    <td>Clone type</td>
                    <td>Extra spec key</td>
                    <td>Extra spec value</td>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>full</td>
                    <td>vmware:clone_type</td>
                    <td>full</td>
                </tr>
                <tr>
                    <td>linked/fast</td>
                    <td>vmware:clone_type</td>
                    <td>linked</td>
                </tr>
            </tbody>
        </table>
        <para>If not specified, the default clone type is <literal>full</literal>.</para>
        <para>The following is an example of linked cloning from another source volume:</para>
        <screen>
        <prompt>$</prompt> <userinput>cinder type-create fast_clone</userinput>
        <prompt>$</prompt> <userinput>cinder type-key fast_clone set vmware:clone_type=linked</userinput>
        <prompt>$</prompt> <userinput>cinder create --volume-type fast_clone --source-volid 25743b9d-3605-462b-b9eb-71459fe2bb35 --display-name volume1 1</userinput>
        </screen>
        <para>Note: The VMware ESX VMDK driver ignores the extra spec entry and always creates a
                <literal>full</literal> clone.</para>
    </simplesect>
    <simplesect>
        <title>Supported operations</title>
        <para>The following operations are supported by the VMware vCenter and ESX VMDK
            drivers:</para>
        <itemizedlist>
            <listitem>
                <para>create volume</para>
            </listitem>
            <listitem>
                <para>create volume from another source volume (Supported only if source volume is
                    not attached to an instance.)</para>
            </listitem>
            <listitem>
                <para>create volume from snapshot</para>
            </listitem>
            <listitem>
                <para>create volume from glance image</para>
            </listitem>
            <listitem>
                <para>attach volume (When a volume is attached to an instance, a reconfigure
                    operation is performed on the instance to add the volume's VMDK to it. The user
                    must manually rescan and mount the device from within the guest operating
                    system.)</para>
            </listitem>
            <listitem>
                <para>detach volume</para>
            </listitem>
            <listitem>
                <para>create snapshot (Allowed only if volume is not attached to an
                    instance.)</para>
            </listitem>
            <listitem>
                <para>delete snapshot (Allowed only if volume is not attached to an
                    instance.)</para>
            </listitem>
            <listitem>
                <para>upload as image to glance (Allowed only if volume is not attached to an
                    instance.)</para>
            </listitem>
        </itemizedlist>
        <para>Note: Although the VMware ESX VMDK driver supports these operations, it has not been
            extensively tested.</para>
    </simplesect>
    <simplesect>
        <title>Datastore selection</title>
        <para>When creating a volume, the driver chooses a datastore that has sufficient free space
            and has the highest <literal>freespace/totalspace</literal> metric value.</para>
        <para>When a volume is attached to an instance, the driver attempts to place the volume
            under the instance's ESX host on a datastore that is selected using the strategy
            above.</para>
    </simplesect>
</section>
{'fraction_non_alphanumeric': 0.09396361951106477, 'fraction_numerical': 0.004750318618931757, 'mean_word_length': 1.64364471669219, 'pattern_counts': {'":': 0, '<': 499, '<?xml version=': 2, '>': 499, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 12}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5936009', 'n_tokens_mistral': 4744, 'n_tokens_neox': 4475, 'n_words': 1388}