Aktifkan Connector di Kubernetes - Object Storage Service

Topik ini menjelaskan cara menginstal dan menggunakan OSS Connector untuk komponen AI/ML dalam penerapan Kubernetes guna memuat data model dari OSS untuk layanan inferensi.

Instal komponen Connector

Untuk menggunakan Connector dalam penerapan Kubernetes, Anda harus menginstal komponen Connector di kontainer aplikasi. Pilih salah satu metode instalasi berikut sesuai dengan kasus penggunaan Anda.

Metode 1: Init Container

Gunakan Init Container untuk mengunduh dan mengekstrak komponen Connector ke volume bersama sebelum kontainer aplikasi dimulai.

initContainers:
  # Init Container: dijalankan sebelum kontainer aplikasi untuk menyiapkan dependensi
  - name: install-connector
    image: busybox
    command:
      - sh
      - -c
      - |
        # Unduh paket DEB Connector
        wget -q https://gosspublic.alicdn.com/oss-connector/oss-connector-lib-1.2.0.x86_64.deb -O /tmp/connector.deb
        # Buat direktori sementara dan ekstrak paket DEB
        mkdir -p /tmp/extract && cd /tmp/extract
        ar x /tmp/connector.deb
        # Ekstrak hanya file .so yang diperlukan ke direktori bersama
        # Direktori /shared dipasang sebagai volume yang terlihat oleh kontainer utama
        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:
      # Pasang volume connector-lib di /shared
      # Kontainer utama juga memasang volume ini untuk berbagi file
      - name: connector-lib
        mountPath: /shared

containers:
  - name: vllm
    image: vllm/vllm-openai:latest
    volumeMounts:
      # Pasang volume connector-lib di /usr/local/lib dalam kontainer
      # Ini membuat file .so yang diekstrak oleh Init Container tersedia
      - name: connector-lib
        mountPath: /usr/local/lib
        subPath: usr/local/lib

volumes:
  # Volume bersama untuk meneruskan file antara Init Container dan kontainer utama
  - name: connector-lib
    emptyDir: {}

Metode 2: Instal saat startup

Unduh dan instal komponen Connector langsung dalam perintah startup kontainer.

containers:
  - name: vllm
    image: vllm/vllm-openai:latest
    command: ["/bin/bash", "-c"]
    args:
      - |
        # Unduh dan instal paket DEB Connector
        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
        # Mulai proses penyajian model
        ENABLE_CONNECTOR=1 python3 -m vllm.entrypoints.openai.api_server --model ${MODEL_DIR} ...

Metode 3: Custom Dockerfile

Buat gambar kustom dengan Connector yang telah dipra-instal, menggunakan gambar resmi vLLM vllm/vllm-openai sebagai dasar.

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

Buat dan dorong gambar tersebut:

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

Gunakan gambar dengan komponen Connector yang telah dipra-instal:

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

Perbandingan metode instalasi

Metode	Kasus penggunaan	Kelebihan	Kekurangan
Init Container / Instal saat startup	Pengujian cepat, validasi, pengembangan, ketika Anda tidak ingin memodifikasi gambar dasar	Tidak memerlukan gambar kustom, penerapan fleksibel, konfigurasi sederhana	Mengunduh dan mengekstrak setiap kali startup, waktu startup lebih lama, memerlukan akses jaringan eksternal
Custom Dockerfile	Lingkungan produksi, layanan berjalan lama, kluster berskala besar	Startup tercepat, gambar mandiri, stabilitas tinggi, dapat digunakan ulang	Memerlukan pemeliharaan gambar kustom, terkunci versi

Terapkan layanan inferensi model

Contoh berikut menggunakan gambar resmi vLLM vllm/vllm-openai dengan metode Init Container untuk menginstal komponen Connector dan menerapkan layanan inferensi yang memuat data model dari OSS.

# ConfigMap: menyimpan file konfigurasi Connector
# Tujuan: memasang konfigurasi Connector sebagai file di dalam kontainer
# Jalur pemasangan: /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 Container: dijalankan sebelum kontainer aplikasi untuk menyiapkan dependensi
      initContainers:
        - name: install-connector
          image: busybox
          command: ["/bin/sh", "-c"]
          args:
            - |
              # Unduh paket DEB Connector
              wget -q https://gosspublic.alicdn.com/oss-connector/oss-connector-lib-1.2.0.x86_64.deb -O /tmp/connector.deb

              # Buat direktori sementara dan ekstrak paket DEB
              mkdir -p /tmp/extract && cd /tmp/extract
              ar x /tmp/connector.deb

              # Ekstrak hanya file .so yang diperlukan ke direktori bersama
              # Direktori /shared dipasang sebagai volume yang terlihat oleh kontainer utama
              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:
            # Pasang volume connector-lib di /shared
            # Kontainer utama juga memasang volume ini untuk berbagi file
            - 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:
          - |
            # Tambahkan pustaka Connector ke LD_PRELOAD untuk mengintersepsi panggilan sistem file
            export LD_PRELOAD="/usr/local/lib/libossc_preload.so${LD_PRELOAD:+:$LD_PRELOAD}"
            # Mulai server vLLM
            # ENABLE_CONNECTOR=1 mengaktifkan OSS Connector untuk pemuatan model yang dipercepat
            # Jalur model ${MODEL_DIR}/qwen/Qwen3-8B/ mengarah ke jalur OSS,
            # diintersepsi dan dialihkan oleh Connector
            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:
        # Konfigurasi akses OSS: tentukan titik akhir internal dan wilayah
        - name: OSS_ENDPOINT
          value: "oss-cn-beijing-internal.aliyuncs.com"
        - name: OSS_REGION
          value: "cn-beijing"

        # Jalur root di OSS. Connector memetakan jalur lokal ke jalur OSS ini
        - name: OSS_PATH
          value: "oss://examplebucket/"

        # Direktori pemasangan lokal (diintersepsi oleh Connector, data dimuat dari OSS)
        - name: MODEL_DIR
          value: "/var/model"

        # Baca kredensial akses OSS dari Secret (oss-access-key-connector)
        # Buat Secret terlebih dahulu:
        #   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:
          # Pasang file konfigurasi Connector
          - name: connector-config
            mountPath:  /etc/oss-connector/
          # Pasang volume connector-lib di /usr/local/lib dalam kontainer
          # Ini membuat file .so yang diekstrak oleh Init Container tersedia
          - name: connector-lib
            mountPath: /usr/local/lib
            subPath: usr/local/lib
      terminationGracePeriodSeconds: 10
      volumes:
      # ConfigMap konfigurasi Connector
      - name: connector-config
        configMap:
          name: connector-config
      # Volume bersama untuk meneruskan file antara Init Container dan kontainer utama
      - name: connector-lib
        emptyDir: {}

Terapkan layanan broadcast model multi-instans

Contoh berikut menggunakan gambar dengan Connector yang telah dipra-instal (myregistry/vllm-with-connector) untuk mengaktifkan broadcast model di beberapa replika. Untuk informasi selengkapnya tentang broadcast model, lihat Model Broadcast.

# ConfigMap: menyimpan templat konfigurasi Connector
# Tujuan: menyediakan templat (config.json.tmpl) yang dirender oleh init container
#          menjadi file konfigurasi akhir untuk kontainer utama
# Jalur pemasangan templat (init container): /tmpl/config.json.tmpl
# Jalur output hasil render (kontainer utama): /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 container: merender templat konfigurasi menjadi config.json akhir
      #                  sebelum kontainer utama dimulai
      initContainers:
      - name: render-config
        image: busybox
        command: ["/bin/sh", "-c"]
        args:
          # Gunakan sed untuk mengganti placeholder templat dengan nilai variabel lingkungan aktual
          - |
            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:
        # Baca detail koneksi Redis dari Secret (redis-secret)
        # Buat Secret terlebih dahulu:
        #   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:
          # Pasang templat ConfigMap sebagai input untuk sed
          - name: connector-config
            mountPath: /tmpl
          # Pasang emptyDir bersama untuk menulis konfigurasi hasil render bagi kontainer utama
          - 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:
          - |
            # Tambahkan pustaka Connector ke LD_PRELOAD untuk mengintersepsi panggilan sistem file
            export LD_PRELOAD="/usr/local/lib/libossc_preload.so${LD_PRELOAD:+:$LD_PRELOAD}"
            # Mulai server vLLM
            # ENABLE_CONNECTOR=1 mengaktifkan OSS Connector untuk pemuatan model yang dipercepat
            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:
        # Konfigurasi akses OSS: tentukan titik akhir internal dan wilayah
        - name: OSS_ENDPOINT
          value: "oss-cn-beijing-internal.aliyuncs.com"
        - name: OSS_REGION
          value: "cn-beijing"

        # Jalur root di OSS. Connector memetakan jalur lokal ke jalur OSS ini
        - name: OSS_PATH
          value: "oss://examplebucket/"

        # Direktori pemasangan lokal (diintersepsi oleh Connector, data dimuat dari OSS)
        - name: MODEL_DIR
          value: "/var/model"

        # Baca kredensial akses OSS dari Secret (oss-access-key-connector)
        - 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:
          # Konfigurasi Connector (dirender oleh init container)
          - name: rendered-config
            mountPath: /etc/oss-connector/
      terminationGracePeriodSeconds: 10
      volumes:
      # ConfigMap templat konfigurasi Connector (dipasang di init container)
      - name: connector-config
        configMap:
          name: connector-config
      # Konfigurasi hasil render (dibagikan dari init container ke kontainer utama)
      - name: rendered-config
        emptyDir: {}