Kubernetes でのコネクタの有効化 - Object Storage Service - Alibaba Cloud ドキュメントセンター

このトピックでは、Kubernetes デプロイメントで AI/ML 用 OSS コネクタコンポーネントをインストールして使用し、OSS からモデルデータをロードして推論サービスに利用する方法について説明します。

コネクタコンポーネントのインストール

Kubernetes デプロイメントでコネクタを使用するには、アプリケーションコンテナにコネクタコンポーネントをインストールする必要があります。ユースケースに応じて、以下のいずれかのインストール方法を選択してください。

方法1：Init コンテナ

Init コンテナを使用して、アプリケーションコンテナが起動する前に、コネクタコンポーネントをダウンロードして共有ボリュームに展開します。

initContainers:
  # Init コンテナ：アプリケーションコンテナの起動前に依存関係を準備するために実行されます
  - name: install-connector
    image: busybox
    command:
      - sh
      - -c
      - |
        # コネクタの DEB パッケージをダウンロードします
        wget -q https://gosspublic.alicdn.com/oss-connector/oss-connector-lib-1.2.0.x86_64.deb -O /tmp/connector.deb
        # 一時ディレクトリを作成し、DEB パッケージを展開します
        mkdir -p /tmp/extract && cd /tmp/extract
        ar x /tmp/connector.deb
        # 必要な .so ファイルのみを共有ディレクトリに展開します
        # /shared ディレクトリは、メインコンテナから見えるボリュームとしてマウントされます
        mkdir -p /shared/usr/local/lib
        tar -xf data.tar.gz -O ./usr/local/lib/libossc_preload.so > /shared/usr/local/lib/libossc_preload.so
    volumeMounts:
      # connector-lib ボリュームを /shared にマウントします
      # メインコンテナもファイル共有のためにこのボリュームをマウントします
      - name: connector-lib
        mountPath: /shared

containers:
  - name: vllm
    image: vllm/vllm-openai:latest
    volumeMounts:
      # connector-lib ボリュームをコンテナ内の /usr/local/lib にマウントします
      # これにより、Init コンテナによって展開された .so ファイルが利用可能になります
      - name: connector-lib
        mountPath: /usr/local/lib
        subPath: usr/local/lib

volumes:
  # Init コンテナとメインコンテナ間でファイルを渡すための共有ボリューム
  - name: connector-lib
    emptyDir: {}

方法2：起動時のインストール

コンテナの起動コマンドでコネクタコンポーネントを直接ダウンロードしてインストールします。

containers:
  - name: vllm
    image: vllm/vllm-openai:latest
    command: ["/bin/bash", "-c"]
    args:
      - |
        # コネクタの DEB パッケージをダウンロードしてインストールします
        wget https://gosspublic.alicdn.com/oss-connector/oss-connector-lib-1.2.0.x86_64.deb
        dpkg -i oss-connector-lib-1.2.0.x86_64.deb
        # モデルサービングプロセスを開始します
        ENABLE_CONNECTOR=1 python3 -m vllm.entrypoints.openai.api_server --model ${MODEL_DIR} ...

方法3：カスタム Dockerfile

公式の vLLM イメージ vllm/vllm-openai をベースイメージとして使用し、コネクタがプリインストールされたカスタムイメージをビルドします。

FROM vllm/vllm-openai:latest
RUN wget https://gosspublic.alicdn.com/oss-connector/oss-connector-lib-1.2.0.x86_64.deb && \
    dpkg -i oss-connector-lib-1.2.0.x86_64.deb

イメージをビルドしてプッシュします。

docker build -t myregistry/vllm-with-connector:latest .
docker push myregistry/vllm-with-connector:latest

コネクタコンポーネントがプリインストールされたイメージを使用します。

containers:
  - name: vllm
    image: myregistry/vllm-with-connector:latest

インストール方法の比較

方法	ユースケース	メリット	デメリット
Init コンテナ / 起動時のインストール	ベースイメージを変更したくない場合の、迅速なテスト、検証、開発	カスタムイメージ不要、柔軟なデプロイメント、シンプルな構成	起動ごとにダウンロードと展開が発生し、起動時間が長くなる、外部ネットワークへのアクセスが必要
カスタム Dockerfile	本番環境、長時間実行サービス、大規模クラスター	最速の起動、自己完結型イメージ、高い安定性、再利用可能	カスタムイメージのメンテナンスが必要、バージョンがロックされる

モデル推論サービスのデプロイ

以下の例では、公式の vLLM イメージ vllm/vllm-openai と Init コンテナ方式を使用してコネクタコンポーネントをインストールし、OSS からモデルデータをロードする推論サービスをデプロイします。

# ConfigMap：コネクタの設定ファイルを保存します
# 目的：コネクタの設定をコンテナ内のファイルとしてマウントします
# マウントパス：/etc/oss-connector/config.json
apiVersion: v1
kind: ConfigMap
metadata:
  name: connector-config
data:
  config.json: |
    {
        "logLevel": 1,
        "logPath": "/var/log/oss-connector/connector.log",
        "auditPath": "/var/log/oss-connector/audit.log",
        "expireTimeSec": 120,
        "prefetch": {
            "vcpus": 16,
            "workers": 16
        }
    }
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: model-connector-deployment
spec:
  selector:
    matchLabels:
      app: model-connector
  template:
    metadata:
      labels:
        app: model-connector
    spec:
      # Init コンテナ：アプリケーションコンテナの起動前に依存関係を準備するために実行されます
      initContainers:
        - name: install-connector
          image: busybox
          command: ["/bin/sh", "-c"]
          args:
            - |
              # コネクタの DEB パッケージをダウンロードします
              wget -q https://gosspublic.alicdn.com/oss-connector/oss-connector-lib-1.2.0.x86_64.deb -O /tmp/connector.deb

              # 一時ディレクトリを作成し、DEB パッケージを展開します
              mkdir -p /tmp/extract && cd /tmp/extract
              ar x /tmp/connector.deb

              # 必要な .so ファイルのみを共有ディレクトリに展開します
              # /shared ディレクトリは、メインコンテナから見えるボリュームとしてマウントされます
              mkdir -p /shared/usr/local/lib
              tar -xf data.tar.gz -O ./usr/local/lib/libossc_preload.so > /shared/usr/local/lib/libossc_preload.so

          volumeMounts:
            # connector-lib ボリュームを /shared にマウントします
            # メインコンテナもファイル共有のためにこのボリュームをマウントします
            - name: connector-lib
              mountPath: /shared
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        imagePullPolicy: IfNotPresent
        resources:
          requests:
            cpu: "16"
            memory: "70Gi"
          limits:
            cpu: "20"
            memory: "80Gi"
        command: ["/bin/bash", "-c"]
        args:
          - |
            # ファイルシステムコールをインターセプトするために、コネクタライブラリを LD_PRELOAD に追加します
            export LD_PRELOAD="/usr/local/lib/libossc_preload.so${LD_PRELOAD:+:$LD_PRELOAD}"
            # vLLM サーバーを起動します
            # ENABLE_CONNECTOR=1 は、モデルの高速ロードのために OSS コネクタを有効にします
            # モデルパス ${MODEL_DIR}/qwen/Qwen3-8B/ は OSS パスを指しており、
            # コネクタによってインターセプトされ、リダイレクトされます
            ENABLE_CONNECTOR=1 python3 -m vllm.entrypoints.openai.api_server \
              --model ${MODEL_DIR}/qwen/Qwen3-8B/ \
              --trust-remote-code \
              --tensor-parallel-size 1 \
              --disable-custom-all-reduce
        env:
        # OSS アクセス構成：内部エンドポイントとリージョンを指定します
        - name: OSS_ENDPOINT
          value: "oss-cn-beijing-internal.aliyuncs.com"
        - name: OSS_REGION
          value: "cn-beijing"

        # OSS 上のルートパス。コネクタはローカルパスをこの OSS パスにマッピングします
        - name: OSS_PATH
          value: "oss://examplebucket/"

        # ローカルマウントディレクトリ (コネクタによってインターセプトされ、データは OSS からロードされます)
        - name: MODEL_DIR
          value: "/var/model"

        # Secret (oss-access-key-connector) から OSS アクセス認証情報を読み取ります
        # 事前に Secret を作成します：
        #   kubectl create secret generic oss-access-key-connector \
        #     --from-literal=key=<OSS_ACCESS_KEY_ID> \
        #     --from-literal=secret=<OSS_ACCESS_KEY_SECRET>
        - name: OSS_ACCESS_KEY_ID
          valueFrom:
            secretKeyRef:
              name: oss-access-key-connector
              key: key
        - name: OSS_ACCESS_KEY_SECRET
          valueFrom:
            secretKeyRef:
              name: oss-access-key-connector
              key: secret
        volumeMounts:
          # コネクタ設定ファイルをマウントします
          - name: connector-config
            mountPath:  /etc/oss-connector/
          # connector-lib ボリュームをコンテナ内の /usr/local/lib にマウントします
          # これにより、Init コンテナによって展開された .so ファイルが利用可能になります
          - name: connector-lib
            mountPath: /usr/local/lib
            subPath: usr/local/lib
      terminationGracePeriodSeconds: 10
      volumes:
      # コネクタ設定の ConfigMap
      - name: connector-config
        configMap:
          name: connector-config
      # Init コンテナとメインコンテナ間でファイルを渡すための共有ボリューム
      - name: connector-lib
        emptyDir: {}

複数インスタンスのモデルブロードキャストサービスのデプロイ

以下の例では、コネクタがプリインストールされたイメージ (myregistry/vllm-with-connector) を使用して、複数のレプリカ間でモデルブロードキャストを有効にします。モデルブロードキャストの詳細については、「モデルブロードキャスト」をご参照ください。

# ConfigMap：コネクタ設定テンプレートを保存します
# 目的：init コンテナがレンダリングしてメインコンテナ用の最終的な設定ファイルを作成するためのテンプレート (config.json.tmpl) を提供します
# テンプレートのマウントパス (init コンテナ)：/tmpl/config.json.tmpl
# レンダリングされた出力パス (メインコンテナ)：/etc/oss-connector/config.json
apiVersion: v1
kind: ConfigMap
metadata:
  name: connector-config
data:
  config.json.tmpl: |
    {
        "logLevel": 1,
        "logPath": "/var/log/oss-connector/connector.log",
        "auditPath": "/var/log/oss-connector/audit.log",
        "expireTimeSec": 120,
        "prefetch": {
            "vcpus": 16,
            "workers": 16
        },
        "broadcast": {
            "enableBroadcast": true,
            "tenant": "${REDIS_TENANT}",
            "db": {
                "host": "${REDIS_HOST}",
                "port": 6379,
                "username": "${REDIS_USERNAME}",
                "password": "${REDIS_PASSWORD}"
            }
        },
        "bindPort": 19989
    }
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: model-connector-deployment
spec:
  replicas: 2
  selector:
    matchLabels:
      app: model-connector
  template:
    metadata:
      labels:
        app: model-connector
    spec:
      # Init コンテナ：メインコンテナが起動する前に、設定テンプレートを最終的な config.json にレンダリングします
      initContainers:
      - name: render-config
        image: busybox
        command: ["/bin/sh", "-c"]
        args:
          # sed を使用して、テンプレートのプレースホルダーを実際の環境変数の値に置き換えます
          - |
            sed -e "s|\${REDIS_HOST}|$REDIS_HOST|g" \
                -e "s|\${REDIS_USERNAME}|$REDIS_USERNAME|g" \
                -e "s|\${REDIS_PASSWORD}|$REDIS_PASSWORD|g" \
                -e "s|\${REDIS_TENANT}|$REDIS_TENANT|g" \
                /tmpl/config.json.tmpl > /etc/oss-connector/config.json
        env:
        # Secret (redis-secret) から Redis 接続の詳細を読み取ります
        # 事前に Secret を作成します：
        #   kubectl create secret generic redis-secret \
        #     --from-literal=host=<host> \
        #     --from-literal=username=<username> \
        #     --from-literal=password=<password>
        - name: REDIS_HOST
          valueFrom:
            secretKeyRef:
              name: redis-secret
              key: host
        - name: REDIS_USERNAME
          valueFrom:
            secretKeyRef:
              name: redis-secret
              key: username
        - name: REDIS_PASSWORD
          valueFrom:
            secretKeyRef:
              name: redis-secret
              key: password
        - name: REDIS_TENANT
          value: "broadcast-demo"
        volumeMounts:
          # sed の入力として ConfigMap テンプレートをマウントします
          - name: connector-config
            mountPath: /tmpl
          # レンダリングされた設定をメインコンテナ用に書き込むために、共有の emptyDir をマウントします
          - name: rendered-config
            mountPath: /etc/oss-connector
      containers:
      - name: vllm
        image: myregistry/vllm-with-connector:latest
        imagePullPolicy: IfNotPresent
        resources:
          requests:
            cpu: "16"
            memory: "70Gi"
          limits:
            cpu: "20"
            memory: "80Gi"
        command: ["/bin/bash", "-c"]
        args:
          - |
            # ファイルシステムコールをインターセプトするために、コネクタライブラリを LD_PRELOAD に追加します
            export LD_PRELOAD="/usr/local/lib/libossc_preload.so${LD_PRELOAD:+:$LD_PRELOAD}"
            # vLLM サーバーを起動します
            # ENABLE_CONNECTOR=1 は、モデルの高速ロードのために OSS コネクタを有効にします
            ENABLE_CONNECTOR=1 python3 -m vllm.entrypoints.openai.api_server \
              --model ${MODEL_DIR}/qwen/Qwen3-8B/ \
              --trust-remote-code \
              --tensor-parallel-size 1 \
              --disable-custom-all-reduce
        env:
        # OSS アクセス構成：内部エンドポイントとリージョンを指定します
        - name: OSS_ENDPOINT
          value: "oss-cn-beijing-internal.aliyuncs.com"
        - name: OSS_REGION
          value: "cn-beijing"

        # OSS 上のルートパス。コネクタはローカルパスをこの OSS パスにマッピングします
        - name: OSS_PATH
          value: "oss://examplebucket/"

        # ローカルマウントディレクトリ (コネクタによってインターセプトされ、データは OSS からロードされます)
        - name: MODEL_DIR
          value: "/var/model"

        # Secret (oss-access-key-connector) から OSS アクセス認証情報を読み取ります
        - name: OSS_ACCESS_KEY_ID
          valueFrom:
            secretKeyRef:
              name: oss-access-key-connector
              key: key
        - name: OSS_ACCESS_KEY_SECRET
          valueFrom:
            secretKeyRef:
              name: oss-access-key-connector
              key: secret
        volumeMounts:
          # コネクタ設定 (init コンテナによってレンダリング)
          - name: rendered-config
            mountPath: /etc/oss-connector/
      terminationGracePeriodSeconds: 10
      volumes:
      # コネクタ設定テンプレートの ConfigMap (init コンテナにマウント)
      - name: connector-config
        configMap:
          name: connector-config
      # レンダリングされた設定 (init コンテナからメインコンテナへ共有)
      - name: rendered-config
        emptyDir: {}