使用自訂 OS 映像檔

您可以為 TPU VM 使用自訂 OS 映像檔,預先載入軟體、使用特定 OS 發行版本,或套用自訂核心修改。建立自訂映像檔時,您必須在映像檔建立過程中進行特定系統修改,並設定映像檔,以處理 TPU 功能所需的開機時間工作。

如果將自訂 OS 映像檔與 TPU 搭配使用,請注意下列免責事項:

  • Google 提供預設的 TPU 最佳化 Ubuntu 長期支援 (LTS) 映像檔。本頁列出的 OS 變更僅適用於 Google 支援、經 TPU 最佳化的 Ubuntu LTS 映像檔。
  • 您必須自行推斷其他 OS 發行版本或自訂映像檔所需的 OS 變更。Google 不保證本頁列出的 Ubuntu 修改項目,能與其他 OS 發行版本或具有自訂核心的其他 Ubuntu 映像檔搭配運作。
  • 除了預設的 TPU 最佳化 Ubuntu LTS 映像檔外,Google 不會建構或提供任何 OS 映像檔的測試。您必須建構及測試自訂 OS 映像檔。

如要進一步瞭解預設的 TPU 最佳化 Ubuntu LTS 映像檔,請參閱「TPU OS 映像檔」。

必要條件

基本映像檔必須安裝下列元件:

  • Docker
  • ethtool,如果使用 TPU v6e 或 TPU7x,則為 6.7 以上版本
  • Python 3 搭配 PyYAML 和 requests 套件,在 Ubuntu 中以 python3-yaml 和 python3-requests 的形式提供
  • gcloud CLI

如果是 TPU7x VM,基本映像檔必須使用 6.8 以上版本的客體 OS Linux 核心版本。

在建立圖片時進行修改

建構自訂 Ubuntu 映像檔時,請套用下列修改。

停用自動升級

停用並移除 unattended-upgrades,以免背景套件更新保留 dpkg 鎖定或中斷 TPU 工作負載:

echo 'APT::Periodic::Unattended-Upgrade "0";' > /etc/apt/apt.conf.d/99cloudtpuconf
DEBIAN_FRONTEND=noninteractive apt-get -y purge unattended-upgrades

將 TPU 裝置繫結至 VFIO

如要允許訪客 OS 存取 TPU 硬體,您必須將 TPU 裝置繫結至 vfio-pci 驅動程式。

  1. 在 /etc/udev/rules.d/ 中建立名為 99-tpu-vfiopci.rules 的 udev 規則檔案:

    # Rules for binding vfio-enabled TPU devices to vfio-pci.
    
    # v5p
    SUBSYSTEM=="pci", ACTION=="add", ATTRS{vendor}=="0x1ae0", ATTRS{device}=="0x0062", ATTRS{subsystem_vendor}=="0x1ae0", ATTRS{subsystem_device}=="0x00ad", DRIVER!="vfio-pci", TAG+="bind_to_vfio_pci"
    
    # v6e
    SUBSYSTEM=="pci", ACTION=="add", ATTRS{vendor}=="0x1ae0", ATTRS{device}=="0x006f", ATTRS{subsystem_vendor}=="0x1ae0", ATTRS{subsystem_device}=="0x00d1", DRIVER!="vfio-pci", TAG+="bind_to_vfio_pci"
    
    # TPU7x
    SUBSYSTEM=="pci", ACTION=="add", ATTRS{vendor}=="0x1ae0", ATTRS{device}=="0x0076", ATTRS{subsystem_vendor}=="0x1ae0", ATTRS{subsystem_device}=="0x00f2", DRIVER!="vfio-pci", TAG+="bind_to_vfio_pci"
    
    # Bind all 'bind_to_vfio_pci' tagged devices to vfio-pci.
    TAG=="bind_to_vfio_pci", RUN+="/lib/udev/bind_to_vfio_pci.sh $kernel"
    
  2. 在 /lib/udev/ 中建立名為 bind_to_vfio_pci.sh 的指令碼:

    #!/bin/bash
    
    # Run ./bind_to_vfio_pci.sh <DBDF>
    # Binds the device at <DBDF> to vfio-pci.
    # If the device is already bound to a driver, unbinds it first.
    
    # Load the vfio-pci module into the kernel. No-op if already loaded.
    modprobe vfio-pci
    
    DBDF_REGEX="^[[:xdigit:]]{4}:[[:xdigit:]]{2}:[[:xdigit:]]{2}.[[:xdigit:]]$"
    
    unset BDF
    if [[ $1 =~ $DBDF_REGEX ]]; then
        BDF=$1
    else
        echo "Error: BDF arg ($1) is not in form dddd:bb:dd.f"
        exit 1
    fi
    
    PCI_PATH="/sys/bus/pci/devices/$BDF"
    
    echo "vfio-pci" > "$PCI_PATH/driver_override"
    
    PCI_DRIVER_PATH="$PCI_PATH/driver"
    if [[ -d "$PCI_DRIVER_PATH" ]]; then
        curr_driver=$(readlink "$PCI_DRIVER_PATH")
        curr_driver=${curr_driver##*/}
        if [[ $curr_driver == "vfio-pci" ]]; then
            echo "$BDF already bound to vfio-pci"
            exit 0
        else
            echo "$BDF" > "$PCI_DRIVER_PATH/unbind"
            if [[ -d "$PCI_DRIVER_PATH" ]]; then
                echo "Error: Unable to unbind $PCI_DRIVER_PATH"
                exit 1
            fi
            echo "Unbound $BDF from driver $curr_driver"
        fi
    fi
    echo "$BDF" > /sys/bus/pci/drivers_probe
    echo "Bound $BDF to vfio-pci"
    
    # Grant read/write access on VFIO device to all users
    IOMMU_GROUP=$(readlink "$PCI_PATH/iommu_group" | xargs basename)
    VFIO_DEV="/dev/vfio/$IOMMU_GROUP"
    if [[ -c "$VFIO_DEV" ]]; then
        chmod 0666 "$VFIO_DEV"
    else
        echo "$VFIO_DEV not found"
        exit 1
    fi
    
    # Set allow_unsafe_interrupts for x86 platforms.
    (uname -a | grep -q x86_64) && echo 1 > /sys/module/vfio_iommu_type1/parameters/allow_unsafe_interrupts
    
    # This is only needed to avoid non-zero exit code from previous command.
    echo "All Done!"
    
  3. 將指令碼設定為可執行:

    chmod +x /lib/udev/bind_to_vfio_pci.sh
    
  4. 授予系統上所有使用者存取 TPU 裝置的權限:

    echo 'KERNEL=="accel*" MODE="0666"' >> /etc/udev/rules.d/99-tpu.rules
    

修改圖片以提升成效

為確保最佳效能,請調整下列系統限制和參數。

記憶體上限

更新 /etc/security/limits.conf,允許單一程序鎖定不限量的記憶體:

echo '*  hard  memlock  unlimited' >> /etc/security/limits.conf
echo '*  soft  memlock  unlimited' >> /etc/security/limits.conf

檔案限制

更新 /etc/security/limits.conf,增加開啟檔案數量:

echo "*    soft    nofile       100000" >> /etc/security/limits.conf
echo "*    hard    nofile       100000" >> /etc/security/limits.conf
echo "root soft    nofile       100000" >> /etc/security/limits.conf
echo "root hard    nofile       100000" >> /etc/security/limits.conf

核心參數

更新 GRUB 設定 (通常位於 /etc/default/grub),在 GRUB_CMDLINE_LINUX 中加入下列參數:

  • idle=poll:防止 CPU 進入低耗電閒置狀態。
  • transparent_hugepage=always:啟用 Transparent Huge Pages (THP)。
  • iommu.passthrough=0:停用輸入/輸出記憶體管理單元 (IOMMU) 直通模式。
  • panic=-1:設定核心,在核心錯誤時立即重新啟動。
  • intel_iommu=on,sm_on:以可擴充模式啟用 Intel IOMMU。TPU7x 和 v5p 架構必須設定這個值。

以下步驟說明如何更新這些核心參數:

  1. 使用通用參數設定核心指令列變數:

    kernel_cmdline="idle=poll transparent_hugepage=always iommu.passthrough=0 panic=-1"
    
  2. 如果您要為 TPU7x 或 TPU v5p 建構映像檔,請附加 Intel IOMMU 參數:

    kernel_cmdline="${kernel_cmdline} intel_iommu=on,sm_on"
    
  3. 更新 /etc/default/grub 中的 GRUB_CMDLINE_LINUX,並重新產生 GRUB 設定:

    sed -i "s/^GRUB_CMDLINE_LINUX=\".*\"/GRUB_CMDLINE_LINUX=\"${kernel_cmdline}\"/" /etc/default/grub
    echo "Status: New kernel cmdline: $(grep -e '^GRUB_CMDLINE_LINUX=' /etc/default/grub)"
    
    update-grub
    

安裝 vBar 代理程式

必須有 vBar 代理程式,晶片間互連 (ICI) 網路才能運作。

如要在建立映像檔時提取 vBar 代理程式容器映像檔,請執行下列指令:

  1. 使用 gcr.io 驗證 Docker:

    gcloud auth configure-docker gcr.io
    
  2. 提取 vBar 代理程式 Docker 映像檔:

    docker pull gcr.io/cloud-tpu-v2-images/vbar_control_agent:0.0.3
    

如要瞭解如何設定映像檔,以便在開機時啟動 vBar 代理程式容器,請參閱「啟動 vBar 代理程式」。

選用:安裝並執行 AI Telemetry Collector

AI Telemetry Collector 會在 TPU VM 中執行,可讓您透過 Cloud Monitoring 或自己的 Prometheus 監控管道,存取執行階段和基礎架構指標。您可以使用 ai-telemetry-collector Docker 映像檔,搭配自訂 OS 使用 AI Telemetry Collector。您可以將映像檔安裝到自訂 OS,並使用 config.yaml 檔案指定收集間隔、啟用或停用特定指標,或變更匯出目的地。

如要安裝並執行 AI Telemetry Collector,請執行下列指令:

  1. 使用 gcr.io 驗證 Docker:

    gcloud auth configure-docker gcr.io
    
  2. 提取 AI Telemetry Collector Docker 映像檔:

    docker pull gcr.io/cloud-tpu-v2-images/ai-telemetry-collector:latest
    
  3. 使用 AI Telemetry Collector 映像檔執行容器,並採用預設設定:

    docker run -d --restart=always --privileged --net=host gcr.io/cloud-tpu-v2-images/ai-telemetry-collector:latest
    

    如要瞭解如何使用自訂設定檔或新增其他設定檔,請參閱「AI Telemetry Collector」。

修改啟動時間

設定映像檔,以便在每次 VM 啟動時執行下列各節中的工作。您可以使用 cloud-init 工具,將中繼資料傳遞至執行個體,藉此設定開機時工作。下列各節中的設定會使用 write_files 和 runcmd 等模組。定義要寫入檔案的程式碼片段應包含在 write_files: 鍵下,而應在啟動時執行的指令應包含在 cloud-init 設定中的 runcmd: 鍵下。

以下定義檔案的程式碼片段都以 write_files: 鍵開頭,方便您查看其所屬位置。將程式碼片段合併為一個 cloud-init 設定時,請使用單一 write_files: 鍵,並列出其下的所有檔案項目。如果設定包含多個 write_files: 鍵,系統只會使用最後一個鍵,不會建立其他鍵定義的指令碼。

啟動 vBar 代理

在開機時啟動 vBar 控制代理程式容器:

docker run -d --restart=always --privileged --net=host \
  -e HOME=/home/tpu-runtime --name=vbar_control_agent \
  gcr.io/cloud-tpu-v2-images/vbar_control_agent:0.0.3 \
  vbar_control_agent_files/bin/vbar_control_agent --logtostderr

設定環境變數

為確保環境已正確初始化,可處理 TPU 工作負載,您必須在系統啟動程序中,從 Compute Engine 中繼資料伺服器擷取執行階段設定變數。方法是在 cloud-init 設定的 write_files: 區段中加入下列程式碼片段,建立名為 /var/scripts/configure-env-vars.sh 的指令碼。這個指令碼會自動從 tpu-env 中繼資料金鑰擷取屬性,並儲存至 /home/tpu-runtime/tpu-env,供 TPU 軟體堆疊使用。

write_files:
  - path: /var/scripts/configure-env-vars.sh
    permissions: '0755'
    owner: root
    content: |
      #!/bin/bash
      grep -q CLOUDSDK_PYTHON /etc/environment || echo "CLOUDSDK_PYTHON=/usr/bin/python3" >> /etc/environment
      export HOME=/home/tpu-runtime
      mkdir -p "${HOME}"
      curl -s 'http://metadata.google.internal/computeMetadata/v1/instance/attributes/tpu-env' -H 'Metadata-Flavor: Google' > /tmp/tpu-env.yaml
      python3 -c '
      import yaml
      with open("/tmp/tpu-env.yaml", "r") as stream_in:
        for k, v in (yaml.safe_load(stream_in) or {}).items():
          print("{var}={value}".format(var=k, value=str(v)))
      ' > "${HOME}/tpu-env"
      rm -f /tmp/tpu-env.yaml
      set -a
      source "${HOME}/tpu-env"
      set +a

取得 VM 中繼資料

下列程式碼片段會建立名為 /var/scripts/get-vm-metadata.py 的指令碼,這是一項 Python 公用程式,可透過程式輔助方式查詢中繼資料伺服器,取得特定執行個體屬性和自訂中繼資料標記。在 cloud-init 設定的 write_files: 區塊中加入下列內容:

write_files:
  - path: /var/scripts/get-vm-metadata.py
    permissions: '0755'
    owner: root
    content: |
      #!/usr/bin/env python3
      import os
      import sys
      import requests

      if len(sys.argv) < 2:
        sys.stderr.write('Must provide key')
        os._exit(1)

      key = sys.argv[1]
      default = None
      if len(sys.argv) > 2:
        default = sys.argv[2]

      attribute_type = 'attributes'
      if len(sys.argv) > 3:
        attribute_type = sys.argv[3]

      request = requests.get(
          'http://metadata.google.internal/computeMetadata/v1/instance/{}/{}'.format(
              attribute_type, key
          ),
          headers={'Metadata-Flavor': 'Google'},
      )
      if request.status_code == 200:
        print(request.text)
      elif request.status_code in (403, 404):
        sys.stderr.write('Metadata key: {} does not exist\n'.format(key))
        if default:
          print(default)
      else:
        sys.stderr.write('Lookup failed with: {}'.format(request))

增加 Cloud Storage 逾時時間

如果工作負載會與 Cloud Storage 互動,請在 /etc/environment 中新增逾時值,延長逾時時間。方法是在 cloud-init 設定的 write_files: 區段中加入下列程式碼片段,建立名為 /var/scripts/configure-gcs-timeouts.sh 的指令碼。

write_files:
  - path: /var/scripts/configure-gcs-timeouts.sh
    permissions: '0755'
    owner: root
    content: |
      #!/bin/bash
      echo "GCS_RESOLVE_REFRESH_SECS=60" >> /etc/environment
      echo "GCS_REQUEST_CONNECTION_TIMEOUT_SECS=300" >> /etc/environment
      echo "GCS_METADATA_REQUEST_TIMEOUT_SECS=300" >> /etc/environment
      echo "GCS_READ_REQUEST_TIMEOUT_SECS=300" >> /etc/environment
      echo "GCS_WRITE_REQUEST_TIMEOUT_SECS=600" >> /etc/environment

調整網路設定

如要最佳化 TPU VM 的網路處理量和延遲時間,請將下列指令碼新增至 cloud-init 設定的 write_files: 區段。在 TPU v6e 和 TPU7x VM 上,這些指令碼也會啟用 TCP 資料分割、提高 TCP 接收緩衝區限制,以及將 NIC 中斷分散到 NUMA 核心。這些指令碼需要「取得 VM 中繼資料」一節中的 /var/scripts/get-vm-metadata.py 指令碼。

write_files:
  - path: /var/scripts/configure-networking.sh
    permissions: '0755'
    owner: root
    content: |
      #!/bin/bash
      ACCELERATOR_TYPE=$(/usr/bin/python3 /var/scripts/get-vm-metadata.py accelerator-type)
      if [[ "$ACCELERATOR_TYPE" =~ ^v6e ]] || [[ "$ACCELERATOR_TYPE" =~ ^tpu7 ]]; then
        echo "Enabling max rx buffer size for v6e, tpu7x & tpu7"
        for port in $(ls /sys/class/net | grep ens); do
          dhclient -r "$port"
          if ethtool -h | grep -q tcp-data-split; then
            if ethtool -G "$port" tcp-data-split on; then
              echo "Max RX buffer size and TCP data split enabled for $port"
            else
              echo "Unable to enable max RX buffer size and TCP data split for $port"
            fi
          else
            if ethtool --set-priv-flags "$port" enable-max-rx-buffer-size on; then
              echo "Max RX buffer size enabled for $port"
            else
              echo "Unable to enable max RX buffer size for $port"
            fi
          fi
          dhclient "$port"
        done
      else
        echo "Skipping max rx buffer size for TPU generation $ACCELERATOR_TYPE before v6e"
      fi

  - path: /var/scripts/set_tcp_config.sh
    permissions: '0755'
    owner: root
    content: |
      #!/bin/bash
      echo "Setting TCP config"

      # Disable metrics cache
      sysctl -w net.ipv4.tcp_no_metrics_save=1

      # Disable slow start after idle
      sysctl -w net.ipv4.tcp_slow_start_after_idle=0

      # Set rto_min 5ms and enable quickack
      sysctl_rto_min_exists=$(sysctl -a | grep tcp_rto_min_us)
      if [[ -z "$sysctl_rto_min_exists" ]]; then
        ip route show | while IFS= read -r route; do
          if ! echo "$route" | grep -q "linkdown"; then
            ip route change ${route/lock/} rto_min 5ms quickack 1
          fi
        done
      else
        sysctl -w net.ipv4.tcp_rto_min_us=5000
        ip route show | while IFS= read -r route; do
          if ! echo "$route" | grep -q "linkdown"; then
            ip route change ${route/lock/} quickack 1
          fi
        done
      fi

      # Increase TCP zerocopy control memory
      sysctl -w net.core.optmem_max=131072

      # Disable Cubic Hystart Ack-Train
      echo 2 > /sys/module/tcp_cubic/parameters/hystart_detect

      ACCELERATOR_TYPE=$(/usr/bin/python3 /var/scripts/get-vm-metadata.py accelerator-type)
      if [[ "$ACCELERATOR_TYPE" =~ ^v6e ]] || [[ "$ACCELERATOR_TYPE" =~ ^tpu7 ]]; then
        # Increase TCP receive buffer limits
        echo "4096 41943040 314572800" > /proc/sys/net/ipv4/tcp_rmem
      fi

  - path: /var/scripts/spread-nic-irqs.sh
    permissions: '0755'
    owner: root
    content: |
      #!/bin/bash
      ACCELERATOR_TYPE=$(/usr/bin/python3 /var/scripts/get-vm-metadata.py accelerator-type)
      if [[ "$ACCELERATOR_TYPE" == v6e* ]] || [[ "$ACCELERATOR_TYPE" == tpu7* ]]; then
        node0_cores=$(echo /sys/devices/system/node/node0/cpu[0-9]* | wc -w)
        ht_buddies=$(cat /sys/devices/system/cpu/cpu0/topology/core_cpus_list | tr ',' ' ' | wc -w)
        total_schedulable_cores=$((node0_cores / ht_buddies))
        second_numa_starting_core=${total_schedulable_cores}

        first_numa_core=0
        second_numa_core=${second_numa_starting_core}
        for nic in $(ls -1 /sys/class/net); do
          if [[ -d "/sys/class/net/$nic/device" ]]; then
            NUM_QUEUES=$(echo /sys/class/net/"$nic"/queues/tx* | wc -w)
            base_ntfy_block=$(ls -1 /sys/class/net/"${nic}"/device/msi_irqs | sort -n | head -n 1)
            num_ntfy_blocks=$(ls /sys/class/net/"${nic}"/device/msi_irqs/ | wc -w)
            tx_irq_base_directory=$((base_ntfy_block))
            rx_irq_base_directory=$((base_ntfy_block + (num_ntfy_blocks / 2)))

            core=0
            max_core=${total_schedulable_cores}
            nic_numa=$(cat /sys/class/net/"${nic}"/device/numa_node)
            if [[ "${nic_numa}" -eq "1" ]]; then
              core=${second_numa_core}
              max_core=$((second_numa_starting_core + total_schedulable_cores))
            else
              core=${first_numa_core}
            fi

            for ((queue = 0; queue < $NUM_QUEUES; queue++)); do
              echo $core > /proc/irq/$((tx_irq_base_directory + $queue))/smp_affinity_list
              echo $core > /proc/irq/$((rx_irq_base_directory + $queue))/smp_affinity_list
              cp /proc/irq/$((tx_irq_base_directory + $queue))/smp_affinity /sys/class/net/"$nic"/queues/tx-"$queue"/xps_cpus
              core=$((core + 1))
              if [[ $core -ge $max_core ]]; then
                if [[ "${nic_numa}" -eq "1" ]]; then
                  core=${second_numa_starting_core}
                else
                  core=0
                fi
              fi
            done

            if [[ "${nic_numa}" -eq "1" ]]; then
              second_numa_core=${core}
            else
              first_numa_core=${core}
            fi
          fi
        done
      else
        echo "Skipping NIC IRQ spreading for TPU generation $ACCELERATOR_TYPE before v6e"
      fi

執行啟動指令碼

如要在 VM 啟動時自動執行設定指令碼,請在 cloud-init 設定中新增 runcmd: 區段:

runcmd:
  - /var/scripts/configure-env-vars.sh
  - /var/scripts/configure-gcs-timeouts.sh
  - /var/scripts/configure-networking.sh
  - /var/scripts/set_tcp_config.sh
  - /var/scripts/spread-nic-irqs.sh

後續步驟