diff --git a/doc/source/_includes/intel-driver-version-c6e3fa384ff7.rest b/doc/source/_includes/intel-driver-version-c6e3fa384ff7.rest new file mode 100644 index 000000000..4972a4851 --- /dev/null +++ b/doc/source/_includes/intel-driver-version-c6e3fa384ff7.rest @@ -0,0 +1,2 @@ +.. intel-driver-version-begin +.. intel-driver-version-end \ No newline at end of file diff --git a/doc/source/system_configuration/kubernetes/index-sysconf-kub-78f0e1e9ca5a.rst b/doc/source/system_configuration/kubernetes/index-sysconf-kub-78f0e1e9ca5a.rst index d3031a5b4..29afe24c9 100644 --- a/doc/source/system_configuration/kubernetes/index-sysconf-kub-78f0e1e9ca5a.rst +++ b/doc/source/system_configuration/kubernetes/index-sysconf-kub-78f0e1e9ca5a.rst @@ -109,6 +109,15 @@ Change Intel Multi-Driver Version intel-multi-driver-version-5e23e989daf5 +---------------------------- +Switch Intel Driver Versions +---------------------------- + +.. toctree:: + :maxdepth: 1 + + intel-driver-version-c6e3fa384ff7 + ---------------------- Application Management ---------------------- diff --git a/doc/source/system_configuration/kubernetes/intel-driver-version-c6e3fa384ff7.rst b/doc/source/system_configuration/kubernetes/intel-driver-version-c6e3fa384ff7.rst new file mode 100644 index 000000000..c02de7f00 --- /dev/null +++ b/doc/source/system_configuration/kubernetes/intel-driver-version-c6e3fa384ff7.rst @@ -0,0 +1,170 @@ +.. WARNING: Add no lines of text between the label immediately following +.. and the title. + +.. _intel-driver-version-c6e3fa384ff7: + +============================ +Switch Intel Driver Versions +============================ + +.. contents:: |minitoc| + :local: + :depth: 2 + +------------ +Introduction +------------ + +The system supports both in-tree and out-of-tree versions of the Intel ``ice``, ``i40e``, +and ``iavf`` drivers. On initial installation, the system uses the default out-of-tree +driver version. This sections describes how to switch between the in-tree and +out-of-tree driver versions. + +.. warning:: + + The |NIC| firmware (NVM) has to align with one of the selected driver + listed below. + +- Out-of-tree drivers (default) + - ice: 1.14.9.2 / Required NVM/firmware: 4.20 (Intel E810) + - i40e: 2.25.7 / Required NVM/firmware: 9.00 + - iavf: 4.11.1 + +- In-tree drivers + - ice: Same as 6.6.7 kernel in-tree driver / Required NVM/firmware: 4.20 + - i40e: Same as 6.6.7 kernel in-tree driver / Required NVM/firmware: 9.00 + - iavf: Same as 6.6.7 kernel in-tree driver + +---------------------------------------------------------- +Switch between the In-tree and Out-of-tree Driver Versions +---------------------------------------------------------- + +The ``out_of_tree_drivers`` service parameter can be used to switch between the +in-tree and out-of-tree versions of a given driver. + +Switch to In-tree Driver Versions +--------------------------------- + +The system can be switched to the in-tree versions of ``ice``, ``i40e``, and ``iavf`` +drivers using any of the following two mechanisms. + +- Before installation, specify the ``out_of_tree_drivers`` service parameter + to none in the deployment config file. + + .. code-block:: none + + serviceParameters: + - service: platform + section: kernel + paramname: out_of_tree_drivers + paramvalue: "none" + +- After installation, modify the ``out_of_tree_drivers`` service parameter to + none and apply the configuration using the steps mentioned in :ref:`apply-driver-configuration-0342c0220631`. + + .. code-block:: none + + ~(keystone_admin)$ system service-parameter-modify platform kernel out_of_tree_drivers=none + + +Switch to Out-of-tree Driver Versions +------------------------------------- + +To use the out-of-tree drivers, set the out-of-tree drivers you want to load in +the ``out_of_tree_drivers`` service parameter and apply the configuration using +the steps mentioned in :ref:`apply-driver-configuration-0342c0220631`. You can set all +the supported drivers, or only specific ones. + +- Set all out-of-tree drivers: + + .. code-block:: none + + ~(keystone_admin)$ system service-parameter-modify platform kernel out_of_tree_drivers=ice,i40e,iavf + +- Set specified out-of-tree drivers: + + To set only ``ice`` and ``i40e``, but not ``iavf`` (in this case, the iavf is in the in-tree driver): + + .. code-block:: none + + ~(keystone_admin)$ system service-parameter-modify platform kernel out_of_tree_drivers=ice,i40e + + To set ``iavf`` and ``ice``, but not ``i40e``: + + .. code-block:: none + + ~(keystone_admin)$ system service-parameter-modify platform kernel out_of_tree_drivers=ice,iavf + + You can set any permutation or combination of ``ice``, ``i40e``, and ``iavf`` + in the ``out_of_tree_drivers`` service parameter. Any driver not explicitly set + using the ``out_of_tree_drivers`` service parameter will use its in-tree version. + +.. _apply-driver-configuration-0342c0220631: + +Apply Driver Configuration +-------------------------- + +To apply the service parameter change, all the hosts need to be locked and unlocked. +Use the following commands for each host depending on the deployed configuration: + +For |AIO-SX| deployments: + +.. code-block:: none + + ~(keystone_admin)$ system host-lock controller-0 + ~(keystone_admin)$ system host-unlock controller-0 + +For |AIO-DX| and standards deployments, after ``controller-1`` is locked/unlocked, +swact ``controller-0`` to make ``controller-1`` the active node. The next set of +commands are executed on the ``controller-0`` node: + +.. code-block:: none + + ~(keystone_admin)$ system host-lock controller-1 + ~(keystone_admin)$ system host-unlock controller-1 + ~(keystone_admin)$ system host-swact controller-0 + +On ``controller-1``, after ``controller-0`` is locked/unlocked swact ``controller-1`` to go +back to ``controller-0`` as the active node. The next set of commands are executed +on the ``controller-1`` node: + +.. code-block:: none + + ~(keystone_admin)$ system host-lock controller-0 + ~(keystone_admin)$ system host-unlock controller-0 + ~(keystone_admin)$ system host-swact controller-1 + +All the remaining nodes in the deployment need to be locked/unlocked, one at a time. +Use the following commands (replace ``worker-0`` with the name of the node being +locked/unlocked): + +.. code-block:: none + + ~(keystone_admin)$ system host-lock worker-0 + ~(keystone_admin)$ system host-unlock worker-0 + +.. note:: + + You must wait for the node to enter the locked state prior to unlocking. + +To verify the current Intel driver version use ``ethtool -i`` on the desired +Intel network interface. For example: + +.. code-block:: none + + ~(keystone_admin)$ ethtool -i ens785f0 | egrep '^(driver|version):' + driver: i40e + version: 6.6.40-stx.3 + + +Backup and Restore +------------------ + +If a backup and restore is performed, after unlocking the host during a restore +operation, the system is configured to the driver version at the time of the backup. + +.. only:: partner + + .. include:: /_includes/intel-driver-version-c6e3fa384ff7.rest + :start-after: intel-driver-version-begin + :end-before: intel-driver-version-end