Run a full system upgrade (a ``yum upgrade`` or ``dnf upgrade``), or
    upgrade specified packages. If the packages aren't installed, they will
    not be installed.

    .. versionchanged:: 2014.7.0
    .. versionchanged:: 2015.8.12,2016.3.3,2016.11.0
        On minions running systemd>=205, `systemd-run(1)`_ is now used to
        isolate commands which modify installed packages from the
        ``salt-minion`` daemon's control group. This is done to keep systemd
        from killing any yum/dnf commands spawned by Salt when the
        ``salt-minion`` service is restarted. (see ``KillMode`` in the
        `systemd.kill(5)`_ manpage for more information). If desired, usage of
        `systemd-run(1)`_ can be suppressed by setting a :mod:`config option
        <salt.modules.config.get>` called ``systemd.scope``, with a value of
        ``False`` (no quotes).

    .. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html
    .. _`systemd.kill(5)`: https://www.freedesktop.org/software/systemd/man/systemd.kill.html

    .. versionchanged:: 2019.2.0
        Added ``obsoletes`` and ``minimal`` arguments

    Returns a dictionary containing the changes:

    .. code-block:: python

        {'<package>':  {'old': '<old-version>',
                        'new': '<new-version>'}}


    CLI Example:

    .. code-block:: bash

        salt '*' pkg.upgrade
        salt '*' pkg.upgrade name=openssl

    Repository Options:

    fromrepo
        Specify a package repository (or repositories) from which to install.
        (e.g., ``yum --disablerepo='*' --enablerepo='somerepo'``)

    enablerepo (ignored if ``fromrepo`` is specified)
        Specify a disabled package repository (or repositories) to enable.
        (e.g., ``yum --enablerepo='somerepo'``)

    disablerepo (ignored if ``fromrepo`` is specified)
        Specify an enabled package repository (or repositories) to disable.
        (e.g., ``yum --disablerepo='somerepo'``)

    disableexcludes
        Disable exclude from main, for a repo or for everything.
        (e.g., ``yum --disableexcludes='main'``)

        .. versionadded:: 2014.7

    name
        The name of the package to be upgraded. Note that this parameter is
        ignored if "pkgs" is passed.

        32-bit packages can be upgraded on 64-bit systems by appending the
        architecture designation (``.i686``, ``.i586``, etc.) to the end of the
        package name.

        Warning: if you forget 'name=' and run pkg.upgrade openssl, ALL packages
        are upgraded. This will be addressed in next releases.

        CLI Example:

        .. code-block:: bash

            salt '*' pkg.upgrade name=openssl

        .. versionadded:: 2016.3.0

    pkgs
        A list of packages to upgrade from a software repository. Must be
        passed as a python list. A specific version number can be specified
        by using a single-element dict representing the package and its
        version. If the package was not already installed on the system,
        it will not be installed.

        CLI Examples:

        .. code-block:: bash

            salt '*' pkg.upgrade pkgs='["foo", "bar"]'
            salt '*' pkg.upgrade pkgs='["foo", {"bar": "1.2.3-4.el5"}]'

        .. versionadded:: 2016.3.0

    normalize : True
        Normalize the package name by removing the architecture. This is useful
        for poorly created packages which might include the architecture as an
        actual part of the name such as kernel modules which match a specific
        kernel version.

        .. code-block:: bash

            salt -G role:nsd pkg.upgrade gpfs.gplbin-2.6.32-279.31.1.el6.x86_64 normalize=False

        .. versionadded:: 2016.3.0

    minimal : False
        Use upgrade-minimal instead of upgrade (e.g., ``yum upgrade-minimal``)
        Goes to the 'newest' package match which fixes a problem that affects your system.

        .. code-block:: bash

            salt '*' pkg.upgrade minimal=True

        .. versionadded:: 2019.2.0

    obsoletes : True
        Controls wether yum/dnf should take obsoletes into account and remove them.
        If set to ``False`` yum will use ``update`` instead of ``upgrade``
        and dnf will be run with ``--obsoletes=False``

        .. code-block:: bash

            salt '*' pkg.upgrade obsoletes=False

        .. versionadded:: 2019.2.0

    setopt
        A comma-separated or Python list of key=value options. This list will
        be expanded and ``--setopt`` prepended to each in the yum/dnf command
        that is run.

        .. versionadded:: 2019.2.0

    .. note::
        To add extra arguments to the ``yum upgrade`` command, pass them as key
        word arguments. For arguments without assignments, pass ``True``

    .. code-block:: bash

        salt '*' pkg.upgrade security=True exclude='kernel*'

def upgrade(name=None,
            pkgs=None,
            refresh=True,
            skip_verify=False,
            normalize=True,
            minimal=False,
            obsoletes=True,
            **kwargs):
    '''
    Run a full system upgrade (a ``yum upgrade`` or ``dnf upgrade``), or
    upgrade specified packages. If the packages aren't installed, they will
    not be installed.

    .. versionchanged:: 2014.7.0
    .. versionchanged:: 2015.8.12,2016.3.3,2016.11.0
        On minions running systemd>=205, `systemd-run(1)`_ is now used to
        isolate commands which modify installed packages from the
        ``salt-minion`` daemon's control group. This is done to keep systemd
        from killing any yum/dnf commands spawned by Salt when the
        ``salt-minion`` service is restarted. (see ``KillMode`` in the
        `systemd.kill(5)`_ manpage for more information). If desired, usage of
        `systemd-run(1)`_ can be suppressed by setting a :mod:`config option
        <salt.modules.config.get>` called ``systemd.scope``, with a value of
        ``False`` (no quotes).

    .. _`systemd-run(1)`: https://www.freedesktop.org/software/systemd/man/systemd-run.html
    .. _`systemd.kill(5)`: https://www.freedesktop.org/software/systemd/man/systemd.kill.html

    .. versionchanged:: 2019.2.0
        Added ``obsoletes`` and ``minimal`` arguments

    Returns a dictionary containing the changes:

    .. code-block:: python

        {'<package>':  {'old': '<old-version>',
                        'new': '<new-version>'}}


    CLI Example:

    .. code-block:: bash

        salt '*' pkg.upgrade
        salt '*' pkg.upgrade name=openssl

    Repository Options:

    fromrepo
        Specify a package repository (or repositories) from which to install.
        (e.g., ``yum --disablerepo='*' --enablerepo='somerepo'``)

    enablerepo (ignored if ``fromrepo`` is specified)
        Specify a disabled package repository (or repositories) to enable.
        (e.g., ``yum --enablerepo='somerepo'``)

    disablerepo (ignored if ``fromrepo`` is specified)
        Specify an enabled package repository (or repositories) to disable.
        (e.g., ``yum --disablerepo='somerepo'``)

    disableexcludes
        Disable exclude from main, for a repo or for everything.
        (e.g., ``yum --disableexcludes='main'``)

        .. versionadded:: 2014.7

    name
        The name of the package to be upgraded. Note that this parameter is
        ignored if "pkgs" is passed.

        32-bit packages can be upgraded on 64-bit systems by appending the
        architecture designation (``.i686``, ``.i586``, etc.) to the end of the
        package name.

        Warning: if you forget 'name=' and run pkg.upgrade openssl, ALL packages
        are upgraded. This will be addressed in next releases.

        CLI Example:

        .. code-block:: bash

            salt '*' pkg.upgrade name=openssl

        .. versionadded:: 2016.3.0

    pkgs
        A list of packages to upgrade from a software repository. Must be
        passed as a python list. A specific version number can be specified
        by using a single-element dict representing the package and its
        version. If the package was not already installed on the system,
        it will not be installed.

        CLI Examples:

        .. code-block:: bash

            salt '*' pkg.upgrade pkgs='["foo", "bar"]'
            salt '*' pkg.upgrade pkgs='["foo", {"bar": "1.2.3-4.el5"}]'

        .. versionadded:: 2016.3.0

    normalize : True
        Normalize the package name by removing the architecture. This is useful
        for poorly created packages which might include the architecture as an
        actual part of the name such as kernel modules which match a specific
        kernel version.

        .. code-block:: bash

            salt -G role:nsd pkg.upgrade gpfs.gplbin-2.6.32-279.31.1.el6.x86_64 normalize=False

        .. versionadded:: 2016.3.0

    minimal : False
        Use upgrade-minimal instead of upgrade (e.g., ``yum upgrade-minimal``)
        Goes to the 'newest' package match which fixes a problem that affects your system.

        .. code-block:: bash

            salt '*' pkg.upgrade minimal=True

        .. versionadded:: 2019.2.0

    obsoletes : True
        Controls wether yum/dnf should take obsoletes into account and remove them.
        If set to ``False`` yum will use ``update`` instead of ``upgrade``
        and dnf will be run with ``--obsoletes=False``

        .. code-block:: bash

            salt '*' pkg.upgrade obsoletes=False

        .. versionadded:: 2019.2.0

    setopt
        A comma-separated or Python list of key=value options. This list will
        be expanded and ``--setopt`` prepended to each in the yum/dnf command
        that is run.

        .. versionadded:: 2019.2.0

    .. note::
        To add extra arguments to the ``yum upgrade`` command, pass them as key
        word arguments. For arguments without assignments, pass ``True``

    .. code-block:: bash

        salt '*' pkg.upgrade security=True exclude='kernel*'
    '''
    options = _get_options(get_extra_options=True, **kwargs)

    if salt.utils.data.is_true(refresh):
        refresh_db(**kwargs)

    old = list_pkgs()

    targets = []
    if name or pkgs:
        try:
            pkg_params = __salt__['pkg_resource.parse_targets'](
                name=name,
                pkgs=pkgs,
                sources=None,
                normalize=normalize,
                **kwargs)[0]
        except MinionError as exc:
            raise CommandExecutionError(exc)

        if pkg_params:
            # Calling list.extend() on a dict will extend it using the
            # dictionary's keys.
            targets.extend(pkg_params)

    cmd = ['--quiet', '-y']
    cmd.extend(options)
    if skip_verify:
        cmd.append('--nogpgcheck')
    if obsoletes:
        cmd.append('upgrade' if not minimal else 'upgrade-minimal')
    else:
        # do not force the removal of obsolete packages
        if _yum() == 'dnf':
            # for dnf we can just disable obsoletes
            cmd.append('--obsoletes=False')
            cmd.append('upgrade' if not minimal else 'upgrade-minimal')
        else:
            # for yum we have to use update instead of upgrade
            cmd.append('update' if not minimal else 'update-minimal')
    cmd.extend(targets)
    result = _call_yum(cmd)
    __context__.pop('pkg.list_pkgs', None)
    new = list_pkgs()
    ret = salt.utils.data.compare_dicts(old, new)

    if result['retcode'] != 0:
        raise CommandExecutionError(
            'Problem encountered upgrading packages',
            info={'changes': ret, 'result': result}
        )

    return ret