diff --git a/Makefile b/Makefile index de4568ea..6f9d77b2 100644 --- a/Makefile +++ b/Makefile @@ -171,7 +171,7 @@ build-cache: # Add commands to populate the cache here \ export PM_PACKAGES_ROOT=${CACHE_DIR}; \ ${CURDIR}/repo.sh docs || true; \ - ${CURDIR}/tools/packman/python.sh -m pip install --no-cache-dir --no-deps -U -t ${CACHE_DIR}/chk/sphinx/4.5.0.2-py3.7-linux-x86_64/ Sphinx-Substitution-Extensions; \ + ${CURDIR}/tools/packman/python.sh -m pip install --no-cache-dir --no-deps -U -t ${CACHE_DIR}/chk/sphinx/4.5.0.2-py3.7-linux-x86_64/ Sphinx-Substitution-Extensions sphinxext-remoteliteralinclude; \ fi .PHONY: process-examples diff --git a/docs/nic-conf-operator/nic-configuration-operator.rst b/docs/nic-conf-operator/nic-configuration-operator.rst index 7761a915..29b13e7d 100644 --- a/docs/nic-conf-operator/nic-configuration-operator.rst +++ b/docs/nic-conf-operator/nic-configuration-operator.rst @@ -26,4 +26,5 @@ NIC Configuration Operator NIC Firmware Configuration Configuration Details + [TECH PREVIEW] Spectrum-X Configuration CRD API Reference diff --git a/docs/nic-conf-operator/nic-fw-configuration.rst b/docs/nic-conf-operator/nic-fw-configuration.rst index 8b0ceb04..9349196b 100644 --- a/docs/nic-conf-operator/nic-fw-configuration.rst +++ b/docs/nic-conf-operator/nic-fw-configuration.rst @@ -146,22 +146,9 @@ Configure and apply the NICFirmwareSource CR Deploy the NICFirmwareSource CR: -.. code-block:: yaml - - apiVersion: configuration.net.nvidia.com/v1alpha1 - kind: NicFirmwareSource - metadata: - name: connectx6-dx-firmware-22-44-1036 - namespace: nvidia-network-operator - finalizers: - - configuration.net.nvidia.com/nic-configuration-operator - spec: - # a list of firmware binaries zip archives from the Mellanox website, can point to any URL accessible from the cluster - binUrlSources: - - https://www.mellanox.com/downloads/firmware/fw-ConnectX6Dx-rel-22_44_1036-MCX623106AC-CDA_Ax-UEFI-14.37.14-FlexBoot-3.7.500.signed.bin.zip - # a URL to the BlueField Bundle (BFB) file, can point to any URL accessible from the cluster - bfbUrlSource: - - https://example.com/bf-fwbundle-3.1.0-77_25.07-prod.bfb +.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/docs/examples/example-nicfwsource-connectx6dx.yaml + :language: yaml + :lines: 18- .. note:: The ConnectX firmware binaries can be downloaded from the `NVIDIA Networking Firmware Downloads page `_. @@ -190,21 +177,9 @@ Configure and apply the NicFirmwareTemplate CR Configure and apply the NicFirmwareTemplate CR: -.. code-block:: yaml - - apiVersion: configuration.net.nvidia.com/v1alpha1 - kind: NicFirmwareTemplate - metadata: - name: connectx6dx-config - namespace: nvidia-network-operator - spec: - nodeSelector: - kubernetes.io/hostname: node1 - nicSelector: - nicType: "101d" - template: - nicFirmwareSourceRef: connectx6dx-firmware-22-44-1036 - updatePolicy: Update +.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/docs/examples/example-nicfirmwaretemplate-connectx6-dx.yaml + :language: yaml + :lines: 18- Spec of the NicDevice CR is updated in accordance with the NICFirmwareTemplate and NicConfigurationTemplate CRs matching the device @@ -267,40 +242,9 @@ Configure NIC Firmware using the NIC Configuration Operator Configure and apply the NicConfigurationTemplate CR --------------------------------------------------- -.. code-block:: yaml - - apiVersion: configuration.net.nvidia.com/v1alpha1 - kind: NicConfigurationTemplate - metadata: - name: connectx6-config - namespace: nvidia-network-operator - spec: - nodeSelector: - feature.node.kubernetes.io/network-sriov.capable: "true" - nicSelector: - # nicType selector is mandatory the rest are optional. Only a single type can be specified. - nicType: 101d - pciAddresses: - - "0000:03:00.0" - - “0000:04:00.0” - serialNumbers: - - "mt1952x03327" - resetToDefault: false # if set, template is ignored, device configuration should reset - template: - # numVfs and linkType fields are mandatory, the rest are optional - numVfs: 2 - linkType: Ethernet - pciPerformanceOptimized: - enabled: true - maxReadRequest: 4096 - roceOptimized: - enabled: true - qos: - trust: dscp - pfc: "0,0,0,1,0,0,0,0" - gpuDirectOptimized: - enabled: true - env: Baremetal +.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/docs/examples/example-nicconfigurationtemplate-connectx6dx.yaml + :language: yaml + :lines: 18- .. note:: It's not possible to apply more than one template of each kind (NICFirmwareTemplate or NICConfigurationTemplate) to a single device. In this case, no template will be applied and an error event will be emitted for the corresponding NicDevice CR. diff --git a/docs/nic-conf-operator/spectrum-x-configuration.rst b/docs/nic-conf-operator/spectrum-x-configuration.rst new file mode 100644 index 00000000..2b6ff5d8 --- /dev/null +++ b/docs/nic-conf-operator/spectrum-x-configuration.rst @@ -0,0 +1,83 @@ +.. license-header + SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +.. headings # #, * *, =, -, ^, " + +.. include:: ../common/vars.rst + +************************************************** +[TECH PREVIEW] NVIDIA Spectrum-X NIC Configuration +************************************************** + +.. contents:: On this page + :depth: 4 + :local: + :backlinks: none + + +`NVIDIA NIC Configuration Operator `_ offers NVIDIA Spectrum-X-specific NIC configuration for different versions of the Reference Architecture. + +.. note:: Currently, only ConnectX-8 (device ID 1023) and BlueField-3 SuperNIC (device ID a2dc) devices are supported for this configuration. + +.. warning:: Tech Preview feature. + +==================================================== +Install and configure the NIC Configuration Operator +==================================================== + +To install the operator and for more information about the CRDs follow the `NIC FW Configuration `_ and `Configuration Details `_ doc articles. + +============================================= +Provision the DOCA SPC-X CC algorithm package +============================================= + +To enable the DOCA SPC-X CC algorithm on NIC devices, the DOCA SPC-X CC .deb package for ubuntu 22.04 is required. This configuration step will be removed in the future, once the DOCA SPC-X CC algorithm will be publicly available. +To access the package, contact your NVIDIA CPM. +The package should be made available in the cluster and then its URL should be provided in the packageUrlSource field of the SpectrumXOperator CR. + +.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/docs/examples/spectrum-x/example-nicfirmwaresource-spectrum-x-cc-only.yaml + :language: yaml + :lines: 18- + +If firmware on the devices also needs to be updated, extend the NicFirmwareSource CR with fields for ConnectX and BlueField firmware. Please, use the correct firmware for your devices. + +.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/docs/examples/spectrum-x/example-nicfirmwaresource-spectrum-x-full.yaml + :language: yaml + :lines: 18- + +Configure and apply the NicFirmwareTemplate CR: + +.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/docs/examples/spectrum-x/example-nicfirmwaretemplate-spectrum-x.yaml + :language: yaml + :lines: 18- + +====================================== +Enable SPC-X optimizations for devices +====================================== + +.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/docs/examples/spectrum-x/example-nicconfigurationtemplate-spectrum-x.yaml + :language: yaml + :lines: 18- + +--------------------- +Configuration details +--------------------- + +Following configuration parameters are applied with spectrumXOptimized.enabled == true and spectrumXOptimized.version == "RA2.0": + +.. rli:: https://raw.githubusercontent.com/Mellanox/nic-configuration-operator/refs/tags/network-operator-|network-operator-version|/bindata/spectrum-x/RA2.0.yaml + :language: yaml + :lines: 17- \ No newline at end of file diff --git a/repo.sh b/repo.sh index 2297585d..20f59ab4 100755 --- a/repo.sh +++ b/repo.sh @@ -5,4 +5,37 @@ set -e SCRIPT_DIR=$(dirname ${BASH_SOURCE}) cd "$SCRIPT_DIR" -exec "tools/packman/python.sh" tools/repoman/repoman.py $@ +if [ "${1:-}" = "docs" ]; then + echo "Processing RST files for rli:: variable substitutions..." + # Forward substitutions script: |var| -> value (applies only to lines with 'rli::') + sed_file_f=/tmp/vars_rli.sed + grep -E '^\.\. \|.*\| replace::' docs/common/vars.rst | \ + sed 's/\.\. |\(.*\)| replace:: \(.*\)/\/rli::\/ s@|\1|@\2@g/' > "$sed_file_f" + # Apply in-place only to matching files (those that contain rli::) + grep -RIl --include="*.rst" --exclude-dir="_build" 'rli::' docs | while read -r file; do + echo "Processing $file" + sed -i -f "$sed_file_f" "$file" + done +fi + +# Run the documentation build (do not exec so we can run post-steps) +set +e +"tools/packman/python.sh" tools/repoman/repoman.py "$@" +rc=$? +set -e + +if [ "${1:-}" = "docs" ]; then + echo "Reverting rli:: substitutions in RST files..." + # Reverse substitutions script: value -> |var| (applies only to lines with 'rli::') + sed_file_r=/tmp/vars_rli_rev.sed + grep -E '^\.\. \|.*\| replace::' docs/common/vars.rst | \ + sed 's/\.\. |\(.*\)| replace:: \(.*\)/\/rli::\/ s@\2@|\1|@g/' > "$sed_file_r" + grep -RIl --include="*.rst" --exclude-dir="_build" 'rli::' docs | while read -r file; do + echo "Processing $file" + sed -i -f "$sed_file_r" "$file" + done + # Cleanup both scripts if present + rm -f /tmp/vars_rli.sed "$sed_file_r" +fi + +exit $rc \ No newline at end of file diff --git a/repo.toml b/repo.toml index cf957ce1..1a27d8db 100644 --- a/repo.toml +++ b/repo.toml @@ -13,7 +13,7 @@ social_media_set = [] social_media = [] favicon = "${root}/assets/favicon.ico" logo = "${root}/assets/nvidia-logo-white.png" -extensions_extra = ['sphinx_substitution_extensions'] +extensions_extra = ['sphinx_substitution_extensions', 'sphinxext.remoteliteralinclude'] [repo_docs.builds.linkcheck] build_by_default = false