.. versionadded:: 2015.5.0

    Create a simple zpool, a mirrored zpool, a zpool having nested VDEVs, a hybrid zpool with cache, spare and log drives or a zpool with RAIDZ-1, RAIDZ-2 or RAIDZ-3

    zpool : string
        Name of storage pool

    vdevs : string
        One or move devices

    force : boolean
        Forces use of vdevs, even if they appear in use or specify a
        conflicting replication level.

    mountpoint : string
        Sets the mount point for the root dataset

    altroot : string
        Equivalent to "-o cachefile=none,altroot=root"

    properties : dict
        Additional pool properties

    filesystem_properties : dict
        Additional filesystem properties

    createboot : boolean
        create a boot partition

        .. versionadded:: 2018.3.0

        .. warning:
          This is only available on illumos and Solaris

    CLI Examples:

    .. code-block:: bash

        salt '*' zpool.create myzpool /path/to/vdev1 [...] [force=True|False]
        salt '*' zpool.create myzpool mirror /path/to/vdev1 /path/to/vdev2 [...] [force=True|False]
        salt '*' zpool.create myzpool raidz1 /path/to/vdev1 /path/to/vdev2 raidz2 /path/to/vdev3 /path/to/vdev4 /path/to/vdev5 [...] [force=True|False]
        salt '*' zpool.create myzpool mirror /path/to/vdev1 [...] mirror /path/to/vdev2 /path/to/vdev3 [...] [force=True|False]
        salt '*' zpool.create myhybridzpool mirror /tmp/file1 [...] log mirror /path/to/vdev1 [...] cache /path/to/vdev2 [...] spare /path/to/vdev3 [...] [force=True|False]

    .. note::

        Zpool properties can be specified at the time of creation of the pool
        by passing an additional argument called "properties" and specifying
        the properties with their respective values in the form of a python
        dictionary:

        .. code-block:: text

            properties="{'property1': 'value1', 'property2': 'value2'}"

        Filesystem properties can be specified at the time of creation of the
        pool by passing an additional argument called "filesystem_properties"
        and specifying the properties with their respective values in the form
        of a python dictionary:

        .. code-block:: text

            filesystem_properties="{'property1': 'value1', 'property2': 'value2'}"

        Example:

        .. code-block:: bash

            salt '*' zpool.create myzpool /path/to/vdev1 [...] properties="{'property1': 'value1', 'property2': 'value2'}"

    CLI Example:

    .. code-block:: bash

        salt '*' zpool.create myzpool /path/to/vdev1 [...] [force=True|False]
        salt '*' zpool.create myzpool mirror /path/to/vdev1 /path/to/vdev2 [...] [force=True|False]
        salt '*' zpool.create myzpool raidz1 /path/to/vdev1 /path/to/vdev2 raidz2 /path/to/vdev3 /path/to/vdev4 /path/to/vdev5 [...] [force=True|False]
        salt '*' zpool.create myzpool mirror /path/to/vdev1 [...] mirror /path/to/vdev2 /path/to/vdev3 [...] [force=True|False]
        salt '*' zpool.create myhybridzpool mirror /tmp/file1 [...] log mirror /path/to/vdev1 [...] cache /path/to/vdev2 [...] spare /path/to/vdev3 [...] [force=True|False]

def create(zpool, *vdevs, **kwargs):
    '''
    .. versionadded:: 2015.5.0

    Create a simple zpool, a mirrored zpool, a zpool having nested VDEVs, a hybrid zpool with cache, spare and log drives or a zpool with RAIDZ-1, RAIDZ-2 or RAIDZ-3

    zpool : string
        Name of storage pool

    vdevs : string
        One or move devices

    force : boolean
        Forces use of vdevs, even if they appear in use or specify a
        conflicting replication level.

    mountpoint : string
        Sets the mount point for the root dataset

    altroot : string
        Equivalent to "-o cachefile=none,altroot=root"

    properties : dict
        Additional pool properties

    filesystem_properties : dict
        Additional filesystem properties

    createboot : boolean
        create a boot partition

        .. versionadded:: 2018.3.0

        .. warning:
          This is only available on illumos and Solaris

    CLI Examples:

    .. code-block:: bash

        salt '*' zpool.create myzpool /path/to/vdev1 [...] [force=True|False]
        salt '*' zpool.create myzpool mirror /path/to/vdev1 /path/to/vdev2 [...] [force=True|False]
        salt '*' zpool.create myzpool raidz1 /path/to/vdev1 /path/to/vdev2 raidz2 /path/to/vdev3 /path/to/vdev4 /path/to/vdev5 [...] [force=True|False]
        salt '*' zpool.create myzpool mirror /path/to/vdev1 [...] mirror /path/to/vdev2 /path/to/vdev3 [...] [force=True|False]
        salt '*' zpool.create myhybridzpool mirror /tmp/file1 [...] log mirror /path/to/vdev1 [...] cache /path/to/vdev2 [...] spare /path/to/vdev3 [...] [force=True|False]

    .. note::

        Zpool properties can be specified at the time of creation of the pool
        by passing an additional argument called "properties" and specifying
        the properties with their respective values in the form of a python
        dictionary:

        .. code-block:: text

            properties="{'property1': 'value1', 'property2': 'value2'}"

        Filesystem properties can be specified at the time of creation of the
        pool by passing an additional argument called "filesystem_properties"
        and specifying the properties with their respective values in the form
        of a python dictionary:

        .. code-block:: text

            filesystem_properties="{'property1': 'value1', 'property2': 'value2'}"

        Example:

        .. code-block:: bash

            salt '*' zpool.create myzpool /path/to/vdev1 [...] properties="{'property1': 'value1', 'property2': 'value2'}"

    CLI Example:

    .. code-block:: bash

        salt '*' zpool.create myzpool /path/to/vdev1 [...] [force=True|False]
        salt '*' zpool.create myzpool mirror /path/to/vdev1 /path/to/vdev2 [...] [force=True|False]
        salt '*' zpool.create myzpool raidz1 /path/to/vdev1 /path/to/vdev2 raidz2 /path/to/vdev3 /path/to/vdev4 /path/to/vdev5 [...] [force=True|False]
        salt '*' zpool.create myzpool mirror /path/to/vdev1 [...] mirror /path/to/vdev2 /path/to/vdev3 [...] [force=True|False]
        salt '*' zpool.create myhybridzpool mirror /tmp/file1 [...] log mirror /path/to/vdev1 [...] cache /path/to/vdev2 [...] spare /path/to/vdev3 [...] [force=True|False]

    '''
    ## Configure pool
    # NOTE: initialize the defaults
    flags = []
    opts = {}
    target = []

    # NOTE: push pool and filesystem properties
    pool_properties = kwargs.get('properties', {})
    filesystem_properties = kwargs.get('filesystem_properties', {})

    # NOTE: set extra config based on kwargs
    if kwargs.get('force', False):
        flags.append('-f')
    if kwargs.get('createboot', False) or 'bootsize' in pool_properties:
        flags.append('-B')
    if kwargs.get('altroot', False):
        opts['-R'] = kwargs.get('altroot')
    if kwargs.get('mountpoint', False):
        opts['-m'] = kwargs.get('mountpoint')

    # NOTE: append the pool name and specifications
    target.append(zpool)
    target.extend(vdevs)

    ## Create storage pool
    res = __salt__['cmd.run_all'](
        __utils__['zfs.zpool_command'](
            command='create',
            flags=flags,
            opts=opts,
            pool_properties=pool_properties,
            filesystem_properties=filesystem_properties,
            target=target,
        ),
        python_shell=False,
    )

    ret = __utils__['zfs.parse_command_result'](res, 'created')
    if ret['created']:
        ## NOTE: lookup zpool status for vdev config
        ret['vdevs'] = _clean_vdev_config(
            __salt__['zpool.status'](zpool=zpool)[zpool]['config'][zpool],
        )

    return ret