Prasyarat Pilih pendekatan penerapan Anda Terapkan menggunakan volume Kubernetes (tanpa fallback)Terapkan menggunakan volume Kubernetes dengan fallback Terapkan menggunakan Amazon S3 dengan prefetch dan NVMe fallback Memahami model-bobot dan model-bobot-copy dengan prefetch Konfigurasikan akun layanan khusus Pramuat bobot model ke NVMe Nama volume yang dipesan Hal-hal yang perlu diingat Pemecahan masalah

Terapkan model dari penyimpanan NVMe lokal menggunakan kubectl

Topik ini menunjukkan cara menerapkan titik akhir inferensi di Amazon SageMaker HyperPod yang memuat bobot model dari penyimpanan NVMe lokal node alih-alih menariknya melalui jaringan dari Amazon S3 atau Amazon FSx. Bobot pembacaan secara lokal menghilangkan hop jaringan selama startup pod, yang mengurangi waktu mulai dingin pod inferensi dan berguna untuk peristiwa penskalaan otomatis, beban kerja skala dari nol, dan failover yang sensitif terhadap latensi. Untuk beban kerja di mana latensi start dingin tidak menjadi perhatian, gunakan modelSourceType: s3 atau fsx dan lewati topik ini.

NVMe lokal bersifat node-local dan fana: data pada NVMe hilang saat node diganti, misalnya selama gangguan spot, kegagalan perangkat keras, atau penyegaran AMI. Pendekatan dalam topik ini menangani hal ini secara berbeda — beberapa mengharuskan Anda untuk mengisi sebelumnya setiap node, yang lain kembali ke Amazon S3 secara otomatis ketika model tidak di-cache secara lokal. Penyimpanan instans NVMe lokal biasanya ditemukan di keluarga instans P, G, dan Trn. Lihat spesifikasi penyimpanan instans Amazon EC2 untuk memvalidasi ketersediaan jenis instans Anda.

Anda dapat memilih dari pendekatan berikut berdasarkan kebutuhan penyimpanan Anda:

Pendekatan penerapan NVMe
#	Pendekatan	Deskripsi
1	Volume Kubernetes (tidak ada fallback)	Gunakan saat bobot model ada di NVMe di setiap node. Penyiapan paling sederhana tanpa Amazon S3, Amazon FSx,, PV/PVC atau InitContainers yang diperlukan.
2	Volume Kubernetes dengan fallback	Gunakan saat model mungkin tidak ada di NVMe di setiap node. Anda memberikan kustom `initContainer` yang memeriksa NVMe terlebih dahulu dan mengunduh dari Amazon S3 menggunakan kredensyal IRSA jika modelnya hilang.
3	Amazon S3 dengan prefetch dan fallback	Gunakan saat Anda ingin mementaskan bobot model ke RAM untuk startup pod. Anda memberikan kustom `initContainer` yang memeriksa NVMe terlebih dahulu dan kembali menyalin dari mount Amazon S3 yang disediakan operator jika model tidak di-cache secara lokal.

Prasyarat

Sebelum Anda mulai, verifikasi bahwa Anda telah:

Siapkan kemampuan inferensi di SageMaker HyperPod kluster Amazon Anda. Untuk informasi selengkapnya, lihat Menyiapkan HyperPod cluster Anda untuk penerapan model.
Menginstal utilitas kubectl dan mengkonfigurasi jq di terminal Anda.
Pre-populated bobot model pada penyimpanan NVMe lokal dari node target Anda (lihat Pramuat bobot model ke NVMe instruksi).

Pilih pendekatan penerapan Anda

Gunakan alur keputusan berikut untuk menentukan pendekatan mana yang tepat untuk kasus penggunaan Anda.


                  ┌────────────────────────────┐
                  │ Want to use a volume of    │
                  │ your choice, e.g. NVMe?    │
                  └─────┬──────────────┬───────┘
                   YES  │              │ NO
                        ▼              ▼
        ┌──────────────────────┐   Use S3/FSx/HF
        │ Are you sure EVERY   │   as-is (no volume
        │ node has the model   │   override needed)
        │ on NVMe?             │
        └─────┬──────────┬─────┘
         YES  │          │ NO
              ▼          ▼
  ┌─────────────────┐  ┌───────────────────────────────┐
  │ Approach 1      │  │ Do you need the operator to   │
  │                 │  │ create S3/FSx PVCs as a       │
  │ Use k8sVolume   │  │ fallback when the model is    │
  │ field in CRD to │  │ missing on a node?            │
  │ read from NVMe  │  └──────┬────────────────┬───────┘
  │ directly.       │    YES  │                │ NO
  └─────────────────┘         ▼                ▼
                  ┌──────────────────┐  ┌──────────────────────┐
                  │ Approach 3       │  │ Approach 2           │
                  │                  │  │                      │
                  │ Use S3 with      │  │ Use k8sVolume with a │
                  │ prefetch enabled.│  │ custom initContainer │
                  │ Custom           │  │ you create that      │
                  │ initContainer    │  │ checks NVMe first    │
                  │ checks NVMe      │  │ and downloads from   │
                  │ first, falls     │  │ S3 via IRSA if the   │
                  │ back to S3, and  │  │ model is missing.    │
                  │ copies to RAM.   │  └──────────────────────┘
                  └──────────────────┘

Terapkan menggunakan volume Kubernetes (tanpa fallback)

Gunakan pendekatan ini ketika Anda memiliki bobot model pada NVMe di setiap node dan menginginkan pengaturan yang paling sederhana — tidak ada konfigurasi Amazon S3 atau Amazon FSx, tidak ada, dan tidak ada InitContainers. PV/PVC

Saat Anda menyetelmodelSourceType: kubernetesVolume, operator melewatkan PV/PVC pembuatan sepenuhnya. Tidak ada driver CSI, pemasangan sekering Amazon S3, atau dudukan Amazon FSx yang digunakan. model-weightsVolume yang disediakan pelanggan digunakan secara langsung dalam spesifikasi pod, dan pekerja membaca data model dari NVMe di. /opt/ml/model

penting

Saat menggunakanmodelSourceType: kubernetesVolume, operator mendapatkan nama volume yang diharapkan dari modelVolumeMount.name konfigurasi pekerja Anda. kubernetes.volumesharus berisi volume dengan nama yang sama. Operator memvalidasi ini dan menolak penerapan dengan KubernetesVolumeValidationFailed kondisi jika tidak ditemukan volume yang cocok. Dalam contoh berikut, keduanya menggunakanmodel-weights.

Buat file InferenceEndpointConfig YAMM. Ganti nilai placeholder dengan pengidentifikasi sumber daya Anda yang sebenarnya.


cat <<EOF> deploy_nvme_k8s_volume.yaml
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: nvme-k8s-volume
  namespace: default
spec:
  endpointName: nvme-k8s-volume
  modelName: Qwen2.5-VL-7B-Instruct
  invocationEndpoint: v1/chat/completions
  replicas: 1
  modelSourceConfig:
    modelSourceType: kubernetesVolume
  kubernetes:
    volumes:
      - name: model-weights
        hostPath:
          path: /opt/dlami/nvme/<YOUR_MODEL>
          type: Directory
  loadBalancer:
    healthCheckPath: /health
  worker:
    image: lmcache/vllm-openai:latest
    args:
      - /opt/ml/model
      - --max-model-len
      - "15000"
      - --tensor-parallel-size
      - "1"
    modelInvocationPort:
      containerPort: 8000
      name: http
    modelVolumeMount:
      name: model-weights
      mountPath: /opt/ml/model
    resources:
      limits:
        nvidia.com/gpu: "1"
      requests:
        cpu: "6"
        memory: 30Gi
        nvidia.com/gpu: "1"
    environmentVariables:
      - name: PYTHONHASHSEED
        value: "123"
      - name: VLLM_REQUEST_TIMEOUT
        value: "600"
EOF

Menyebarkan. InferenceEndpointConfig


kubectl apply -f deploy_nvme_k8s_volume.yaml

Verifikasi status penerapan.


kubectl describe InferenceEndpointConfig nvme-k8s-volume -n default

Terapkan menggunakan volume Kubernetes dengan fallback

Gunakan pendekatan ini ketika model mungkin atau mungkin tidak berada di NVMe pada node tertentu. hostPathVolume hanya berfungsi pada node di mana data ada — pod yang dijadwalkan pada node lain akan memasang jalur kosong atau tidak ada, menyebabkan server model gagal.

Dalam pendekatan ini, Anda mengatur modelSourceType: kubernetesVolume dan memberikan kustom initContainer yang memeriksa NVMe terlebih dahulu dan mengunduh dari Amazon S3 menggunakan kredensil IRSA jika modelnya hilang.

Mengatur IRSA

Sebelum menerapkan, konfigurasikan Peran IAM untuk Akun Layanan (IRSA) untuk memberikan kredensi pod Anda untuk diunduh dari Amazon S3.

Dapatkan ID penyedia OIDC untuk klaster Anda.


aws eks describe-cluster --name <CLUSTER_NAME> --region <REGION> \
  --query "cluster.identity.oidc.issuer" --output text

Buat kebijakan kepercayaan IAM. Simpan yang berikut ini sebagaitrust-policy.json, ganti nilai placeholder.


{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/oidc.eks.<REGION>.amazonaws.com/id/<OIDC_ID>"
    },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "oidc.eks.<REGION>.amazonaws.com/id/<OIDC_ID>:sub": "system:serviceaccount:<NAMESPACE>:<SA_NAME>",
        "oidc.eks.<REGION>.amazonaws.com/id/<OIDC_ID>:aud": "sts.amazonaws.com"
      }
    }
  }]
}

Awas

Selalu lingkup kebijakan kepercayaan ke namespace dan ServiceAccount nama tertentu. Jangan pernah menggunakan wildcard dalam kondisi subjek (misalnya,system:serviceaccount:*:*), karena ini akan memungkinkan siapa pun ServiceAccount di namespace mana pun untuk mengambil peran.

Buat peran IAM dan lampirkan kebijakan baca Amazon S3 tercakup untuk bucket model Anda.


aws iam create-role --role-name <ROLE_NAME> \
  --assume-role-policy-document file://trust-policy.json

aws iam put-role-policy --role-name <ROLE_NAME> \
  --policy-name S3ModelReadAccess \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::<YOUR_BUCKET>",
        "arn:aws:s3:::<YOUR_BUCKET>/<YOUR_MODEL_PREFIX>/*"
      ]
    }]
  }'

Buat akun layanan Kubernetes dengan anotasi IRSA.


kubectl create sa <SA_NAME> -n <NAMESPACE>
kubectl annotate sa <SA_NAME> -n <NAMESPACE> \
  eks.amazonaws.com/role-arn=arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>

Menyebarkan model

Buat file InferenceEndpointConfig YAMM. Ganti nilai placeholder dengan pengidentifikasi sumber daya Anda yang sebenarnya.


cat <<EOF> deploy_nvme_k8s_volume_fallback.yaml
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: nvme-k8s-volume-fallback
  namespace: default
spec:
  endpointName: nvme-k8s-volume-fallback
  modelName: Qwen2.5-VL-7B-Instruct
  invocationEndpoint: v1/chat/completions
  replicas: 1
  modelSourceConfig:
    modelSourceType: kubernetesVolume
  kubernetes:
    serviceAccountName: <YOUR_SERVICE_ACCOUNT>
    initContainers:
      - name: smart-loader
        image: public.ecr.aws/aws-cli/aws-cli:latest
        command: ["/bin/bash", "-c"]
        args:
          - |
            if [ "$(ls -A /model)" ]; then
              echo "NVMe hit — model already present ($(du -sh /model | cut -f1))"
            else
              echo "NVMe miss — downloading from S3"
              aws s3 sync s3://<YOUR_BUCKET>/<YOUR_MODEL>/ /model/
            fi
        volumeMounts:
          - name: model-weights
            mountPath: /model
    volumes:
      - name: model-weights
        hostPath:
          path: /opt/dlami/nvme/<YOUR_MODEL>
          type: DirectoryOrCreate
  loadBalancer:
    healthCheckPath: /health
  worker:
    image: lmcache/vllm-openai:latest
    args:
      - /opt/ml/model
      - --max-model-len
      - "15000"
      - --tensor-parallel-size
      - "1"
    modelInvocationPort:
      containerPort: 8000
      name: http
    modelVolumeMount:
      name: model-weights
      mountPath: /opt/ml/model
    resources:
      limits:
        nvidia.com/gpu: "1"
      requests:
        cpu: "6"
        memory: 30Gi
        nvidia.com/gpu: "1"
    environmentVariables:
      - name: PYTHONHASHSEED
        value: "123"
EOF

Menyebarkan. InferenceEndpointConfig


kubectl apply -f deploy_nvme_k8s_volume_fallback.yaml

Verifikasi status penerapan.


kubectl describe InferenceEndpointConfig nvme-k8s-volume-fallback -n default

Terapkan menggunakan Amazon S3 dengan prefetch dan NVMe fallback

Gunakan pendekatan ini saat Anda menginginkan kinerja inferensi dengan mementaskan bobot model ke RAM, dengan fallback otomatis ke Amazon S3 jika model tidak di-cache secara lokal di NVMe.

Saat Anda mengatur modelSourceType: s3 denganprefetchEnabled: true, operator membuat dua volume secara otomatis:

Volume yang dinamai menurut nama Anda modelVolumeMount.name (biasanyamodel-weights) — dudukan sekering Amazon S3 CSI yang berisi model Anda
model-weights-copy— RAM-backed emptyDir tempat pekerja membaca dari

Anda menambahkan nvme-cache volume kustom yang menunjuk ke penyimpanan NVMe lokal node, dan kustom yang: initContainer

Jika model ada di NVMe — salinan dari NVMe ke RAM (model-weights-copy), lewati jaringan sepenuhnya.
Jika model tidak ada — kembali menyalin dari Amazon S3 mount model-weights () ke RAM model-weights-copy (). Secara opsional menyalin ke NVMe sehingga startup pod berikutnya pada node yang sama menggunakan jalur lokal yang cepat.

penting

Jangan mengesampingkan model-weights kubernetes.volumes saat menggunakan pendekatan ini. Operator membuat model-weights menunjuk ke volume Amazon S3 CSI. Menggantinya akan menghapus volume yang disediakan operator yang dibutuhkan InitContainer Anda untuk fallback. Gunakan nama volume terpisah (misalnya,nvme-cache) untuk HostPath NVMe Anda.

penting

Jangan termasuk model-weights-copy dalamkubernetes.volumes. Ini adalah nama cadangan yang dibuat secara otomatis oleh operator. InitContainer Anda dapat mereferensikannya volumeMounts tetapi tidak boleh mendeklarasikannya sebagai volume.

Buat file InferenceEndpointConfig YAMM. Ganti nilai placeholder dengan pengidentifikasi sumber daya Anda yang sebenarnya.


cat <<EOF> deploy_nvme_s3_prefetch_fallback.yaml
apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: nvme-s3-prefetch-fallback
  namespace: default
spec:
  endpointName: nvme-s3-prefetch-fallback
  modelName: Qwen2.5-VL-7B-Instruct
  invocationEndpoint: v1/chat/completions
  replicas: 1
  modelSourceConfig:
    modelSourceType: s3
    s3Storage:
      bucketName: <YOUR_BUCKET>
      region: <YOUR_REGION>
    prefetchEnabled: true
  kubernetes:
    serviceAccountName: <YOUR_SERVICE_ACCOUNT>
    initContainers:
      - name: smart-loader
        image: public.ecr.aws/aws-cli/aws-cli:latest
        command: ["/bin/bash", "-c"]
        args:
          - |
            # Check NVMe first, fall back to S3 mount, then copy to RAM
            if [ "$(ls -A /nvme)" ]; then
              echo "NVMe hit ($(du -sh /nvme | cut -f1))"
              echo "Copying model from NVMe to RAM..."
              cp -r /nvme/* /model/
            else
              echo "NVMe miss — copying from S3 mount to NVMe, then NVMe to RAM"
              cp -r /s3-model/* /nvme/
              cp -r /nvme/* /model/
            fi
            echo "Done. $(du -sh /model | cut -f1) in RAM."
        volumeMounts:
          - name: model-weights
            mountPath: /s3-model
          - name: nvme-cache
            mountPath: /nvme
          - name: model-weights-copy
            mountPath: /model
    volumes:
      - name: nvme-cache
        hostPath:
          path: /opt/dlami/nvme/<YOUR_MODEL>
          type: DirectoryOrCreate
  loadBalancer:
    healthCheckPath: /health
  worker:
    image: lmcache/vllm-openai:latest
    args:
      - /opt/ml/model
      - --max-model-len
      - "15000"
      - --tensor-parallel-size
      - "1"
    modelInvocationPort:
      containerPort: 8000
      name: http
    modelVolumeMount:
      name: model-weights
      mountPath: /opt/ml/model
    resources:
      limits:
        nvidia.com/gpu: "1"
      requests:
        cpu: "6"
        memory: 30Gi
        nvidia.com/gpu: "1"
    environmentVariables:
      - name: PYTHONHASHSEED
        value: "123"
      - name: VLLM_REQUEST_TIMEOUT
        value: "600"
EOF

Menyebarkan. InferenceEndpointConfig


kubectl apply -f deploy_nvme_s3_prefetch_fallback.yaml

Verifikasi status penerapan.


kubectl describe InferenceEndpointConfig nvme-s3-prefetch-fallback -n default

Memahami model-bobot dan model-bobot-copy dengan prefetch

Saat menggunakan prefetch, operator membuat dua volume terkait model:

Volume yang dinamai menurut nama Anda modelVolumeMount.name (biasanyamodel-weights) — dudukan sekering Amazon S3 CSI yang berisi model Anda
model-weights-copy— sebuah RAM-backed emptyDir tempat pekerja benar-benar membaca

Dalam AndaInferenceEndpointConfig, Anda mendefinisikan:


modelVolumeMount:
    name: model-weights
    mountPath: /opt/ml/model

Saat Anda mereferensikan model-weightsprefetchEnabled: true, kapan, sebenarnya model-weights-copy yang dipasang /opt/ml/model di dalam wadah pekerja. Saat menggunakan initContainer kustom, pastikan Anda menyalin data ke dalam volume yang dipanggil model-weights-copy — di situlah pekerja mengharapkan untuk menemukannya.

KetikaprefetchEnabled: false, hanya ada satu volume (dinamai menurut nama AndamodelVolumeMount.name) dan itu dipasang langsung di/opt/ml/model.

Konfigurasikan akun layanan khusus

Anda dapat menetapkan Kubernetes kustom ServiceAccount ke pod titik akhir inferensi Anda menggunakan bidang di. spec.kubernetes.serviceAccountName InferenceEndpointConfig Ini berguna untuk memberikan AWS kredensil melalui IRSA (IAM Roles for Service Accounts) ke container pekerja atau kontainer init Anda — misalnya, untuk mengunduh bobot model dari Amazon S3 dalam skenario fallback.

penting

Dukungan akun layanan kustom dinonaktifkan secara default dan harus diaktifkan secara eksplisit oleh administrator klaster sebelum digunakan. Lihat Aktifkan akun layanan khusus untuk instruksi.

Jika Anda tidak menentukan ServiceAccount, default namespace ServiceAccount digunakan.

Aktifkan akun layanan khusus

Dukungan akun layanan kustom dinonaktifkan secara default. Administrator klaster harus mengaktifkannya dalam konfigurasi Helm operator sebelum pengguna dapat mereferensikan kustom ServiceAccounts di dalamnya. InferenceEndpointConfig

Perbarui nilai Helm operator untuk mengaktifkan fitur. Jika Anda menerapkan operator melalui Helm, tingkatkan dengan tanda:
```
helm upgrade hyperpod-inference-operator <CHART_PATH> \
  --set enableCustomServiceAccounts=true \
  --reuse-values
```
Jika Anda menggunakan operator sebagai add-on Amazon EKS, perbarui konfigurasi add-on untuk disertakan enableCustomServiceAccounts: true dalam pengaturan konfigurasi lanjutan.

Verifikasi bahwa pod operator memiliki variabel lingkungan yang disetel:


kubectl get deployment hyperpod-inference-operator-controller-manager \
  -n hyperpod-inference-system \
  -o jsonpath='{.spec.template.spec.containers[0].env}' | jq '.[] | select(.name=="ENABLE_CUSTOM_SERVICE_ACCOUNTS")'

Anda harus melihat:


{
  "name": "ENABLE_CUSTOM_SERVICE_ACCOUNTS",
  "value": "true"
}

penting

Jika fitur ini tidak diaktifkan, semua InferenceEndpointConfig yang menentukan kubernetes.serviceAccountName ditolak dengan DeploymentFailed status dan pesan:kubernetes.serviceAccountName is not enabled. Requires addon configuration (enableCustomServiceAccounts: true).

Beri label pada akun layanan

Sebelum Anda dapat mereferensikan kustom ServiceAccount, administrator cluster harus memberi label sebagai user-assignable:


kubectl label serviceaccount <your-service-account> \
  sagemaker.amazonaws.com/user-assignable=true \
  -n <namespace>

Hanya ServiceAccounts dengan label ini dapat direferensikan dengan titik akhir inferensi. Ini adalah kontrol keamanan untuk mencegah eskalasi hak istimewa yang tidak sah.

Tentukan akun layanan dalam konfigurasi Anda

Tambahkan serviceAccountName bidang di bawah spec.kubernetes diInferenceEndpointConfig:


apiVersion: inference.sagemaker.aws.amazon.com/v1
kind: InferenceEndpointConfig
metadata:
  name: my-inference-endpoint
  namespace: my-namespace
spec:
  kubernetes:
    serviceAccountName: my-inference-sa
  # ... rest of your config

Aturan validasi

Operator memvalidasi serviceAccountName bidang pada operasi membuat dan memperbarui. Penerapan Anda akan ditolak dengan DeploymentFailed status jika salah satu dari kondisi berikut terpenuhi:

ServiceAccount Tidak ada di namespace — serviceAccountName "X" not found in namespace "Y"
Tidak ServiceAccount ada label yang diperlukan - serviceAccountName "X" is not labeled as user-assignable (requires label sagemaker.amazonaws.com/user-assignable=true)
ServiceAccount Ini adalah sistem operator ServiceAccount - serviceAccountName must not reference the operator's service account

catatan

Semua kontainer dalam pod inferensi (worker, init container, dan sidecars) mewarisi izin yang ditentukan. ServiceAccount Jika ServiceAccount dianotasi denganeks.amazonaws.com/role-arn, pod akan menerima AWS kredensyal sementara untuk peran IAM tersebut. Administrator klaster hanya boleh memberi label ServiceAccounts sebagai dapat ditetapkan pengguna setelah meninjau peran RBAC terkait dan izin IAM.

catatan

Jika a ServiceAccount dihapus saat an InferenceEndpointConfig sudah berjalan, Pod yang ada terus berjalan dengan kredensialnya saat ini hingga dimulai ulang. Namun, pembuatan pod baru (misalnya, selama penskalaan atau penjadwalan ulang) akan gagal karena sudah ServiceAccount tidak ada lagi. Operator memvalidasi ServiceAccount kapan penerapan pertama kali dibuat dan ketika spesifikasi IEC diperbarui - itu tidak terus memantau. ServiceAccount Memperbarui spesifikasi IEC setelah SA dihapus akan menghasilkan status. DeploymentFailed

Praktik terbaik keamanan untuk akun layanan kustom

Saat Anda menggunakan kustom ServiceAccount dengan titik akhir inferensi, operator HyperPod inferensi membuat Deployment atas nama Anda. Semua kontainer dalam pod inferensi — termasuk pekerja, kontainer init, dan sidecars — mewarisi izin yang ditentukan. ServiceAccount Ikuti praktik terbaik ini untuk mengamankan klaster Anda.

Kunci izin RBAC

Buat yang didedikasikan ServiceAccount untuk setiap beban kerja inferensi. Jangan gunakan kembali ServiceAccounts di seluruh beban kerja yang tidak terkait.

Ikat hanya izin RBAC minimum yang diperlukan. Misalnya, jika container init Anda hanya perlu membaca dari Amazon S3, container tersebut ServiceAccount seharusnya tidak memiliki izin untuk membuat daftar atau memodifikasi resource Kubernetes.


# Example: minimal Role for an inference workload that only needs S3 access via IRSA
# No Kubernetes API permissions needed — IRSA provides AWS credentials directly
apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-inference-sa
  namespace: my-namespace
  labels:
    sagemaker.amazonaws.com/user-assignable: "true"
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::<ACCOUNT_ID>:role/<SCOPED_ROLE_NAME>

Hindari pemberian izin (ClusterRoleBindings) di seluruh cluster untuk ServiceAccounts digunakan oleh pod inferensi.

Lingkup peran IAM IRSA

Saat membuat anotasi ServiceAccount denganeks.amazonaws.com/role-arn, pastikan peran IAM mengikuti prinsip hak istimewa paling sedikit.

Cakupan izin Amazon S3 ke bucket dan awalan tertentu yang berisi bobot model Anda.


{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["s3:GetObject", "s3:ListBucket"],
    "Resource": [
      "arn:aws:s3:::<YOUR_BUCKET>",
      "arn:aws:s3:::<YOUR_BUCKET>/<YOUR_MODEL_PREFIX>/*"
    ]
  }]
}

Jangan gunakan kebijakan yang dikelola secara luas seperti AmazonS3FullAccess dalam produksi. Penggunaan AmazonS3ReadOnlyAccess atau kebijakan khusus yang dicakup ke bucket model Anda.

Lindungi label yang dapat ditetapkan pengguna

Hanya administrator klaster yang harus menambah atau menghapus sagemaker.amazonaws.com/user-assignable=true label. Gunakan Kubernetes RBAC untuk membatasi siapa yang dapat memodifikasi label di namespace Anda. ServiceAccount
Tinjau peran RBAC dan izin IAM yang terkait dengan a ServiceAccount sebelum memberi label sebagai dapat ditetapkan pengguna.

Audit berkala yang ServiceAccounts membawa user-assignable label.


kubectl get serviceaccounts -n <NAMESPACE> -l sagemaker.amazonaws.com/user-assignable=true

Pastikan peran non-admin tidak menyertakanpatch,update, atau create kata kerja pada ServiceAccount sumber daya. Operator memvalidasi user-assignable label pada waktu penerapan, tetapi tidak mencegah pengguna yang tidak sah menambahkan label ke file. ServiceAccount Membatasi siapa yang dapat memodifikasi ServiceAccounts melalui RBAC adalah kontrol utama untuk melindungi label ini. Non-admin pengguna seharusnya hanya memiliki get dan list mengakses:
```
# Example: RBAC Role for non-admin users — read-only access to ServiceAccounts
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: sa-read-only
  namespace: <NAMESPACE>
rules:
  - apiGroups: [""]
    resources: ["serviceaccounts"]
    verbs: ["get", "list"]
```

penting

Operator HyperPod inferensi bertindak sebagai perantara yang membuat Deployment atas nama pengguna. Tidak seperti beban kerja Kubernetes standar di mana pemanggil langsung membuat pod, operator menetapkan yang ditentukan ke pod yang dibuatnya. ServiceAccount Ini berarti bahwa setiap izin yang diberikan kepada pengguna yang dapat ditetapkan secara efektif ServiceAccount tersedia bagi siapa saja yang dapat membuat di namespace tersebut. InferenceEndpointConfig Pastikan RBAC tingkat ruang nama mengontrol siapa yang dapat membuat dan memperbarui sumber daya. InferenceEndpointConfig

Pramuat bobot model ke NVMe

Jika Anda perlu mengisi NVMe sebelumnya pada node tertentu sebelum menerapkan, Anda dapat menggunakan pod satu kali untuk menyinkronkan dari Amazon S3.

catatan

Pendekatan ini menargetkan node tertentu melalui nodeName dan tidak bekerja dengan penskalaan otomatis. Untuk skenario penskalaan otomatis, gunakan volume Kubernetes dengan fallback atau Amazon S3 dengan pendekatan prefetch, yang menangani model yang hilang secara otomatis melalui logika fallback InitContainer.

Buat file YAMM pod preload. Ganti nilai placeholder dengan pengidentifikasi sumber daya Anda yang sebenarnya.


cat <<EOF> nvme-s3-copy.yaml
apiVersion: v1
kind: Pod
metadata:
  name: nvme-s3-copy
  namespace: default
spec:
  nodeName: <TARGET_NODE>
  restartPolicy: Never
  containers:
    - name: s3-copy
      image: public.ecr.aws/aws-cli/aws-cli:latest
      command: ["/bin/bash", "-c"]
      args:
        - |
          echo "=== Starting S3 sync to NVMe ==="
          aws s3 sync s3://<YOUR_BUCKET>/<YOUR_MODEL>/ /nvme/<YOUR_MODEL>/ --region <YOUR_REGION>
          echo "=== Sync complete ==="
          ls -la /nvme/<YOUR_MODEL>/
          du -sh /nvme/<YOUR_MODEL>/
          echo "=== Done ==="
      volumeMounts:
        - name: nvme-storage
          mountPath: /nvme
  serviceAccountName: default
  volumes:
    - name: nvme-storage
      hostPath:
        path: /opt/dlami/nvme
        type: Directory
EOF

Terapkan pod dan pantau kemajuan sinkronisasi.


kubectl apply -f nvme-s3-copy.yaml
kubectl get pod nvme-s3-copy -w
kubectl logs nvme-s3-copy -f

Bersihkan pod setelah sinkronisasi selesai.
```
kubectl delete pod nvme-s3-copy
```

Nama volume yang dipesan

Operator mengelola beberapa volume internal yang tidak dapat diganti melalui. kubernetes.volumes Menggunakan salah satu dari nama-nama ini menghasilkan suatu KubernetesVolumeValidationFailed kondisi.

Nama volume yang dipesan
#	Nama	Tujuan
1	`shm`	Memori bersama (`/dev/shm`) untuk komunikasi antar-proses
2	`model-weights-copy`	RAM-backed EmptyDir digunakan saat `prefetchEnabled: true`
3	`parallel-copy-configmap`	ConfigMap untuk skrip salinan paralel (prefetch)
4	`lmcache-config`	Volume konfigurasi LMcache
5	`gated-model-downloader-configmap`	ConfigMap untuk skrip unduhan model yang terjaga keamanannya

Hal-hal yang perlu diingat

Jangan gunakan nama volume yang dicadangkan. Operator mengelola beberapa volume internal (lihatNama volume yang dipesan). Menggunakan salah satu dari nama-nama ini kubernetes.volumes menghasilkan suatu KubernetesVolumeValidationFailed kondisi.
Nama volume harus cocok. Operator mendapatkan nama volume darimodelVolumeMount.name. Saat menggunakanmodelSourceType: kubernetesVolume, kubernetes.volumes harus berisi volume dengan nama yang sama.
Pasang volume ke lokasi yang benar di InitContainer Anda. Pastikan volume apa pun yang Anda buat dipasang ke jalur yang benar di InitContainer Anda.
Tidak diperlukan akun layanan khusus untuk S3/FSx. Jika Anda tidak dapat membuat akun layanan khusus atau memilih untuk tidak, Anda dapat menggunakan modelSourceType: s3 ataufsx. Operator menyediakan S3/FSx volume secara otomatis. Anda masih dapat menambahkan volume kustom initContainers dan override di atas penyimpanan yang dikelola operator.
Kredensyal IRSA disuntikkan ke semua wadah. Saat Anda menyetel kubernetes.serviceAccountName ke akun layanan dengan anotasi IRSA, Amazon EKS menyuntikkan AWS kredensil (aws-iam-tokenvolume,,AWS_WEB_IDENTITY_TOKEN_FILE) ke semua kontainerAWS_ROLE_ARN, termasuk InitContainers kustom Anda.
Jangan atur modelLocation saat menggunakankubernetesVolume. Jalur volume dikendalikan olehkubernetes.volumes. Pengaturan modelLocation kapan modelSourceType kubernetesVolume menghasilkan kesalahan validasi.
Pahami cara model-weights-copy kerja model-weights vs dengan prefetch. SaatprefetchEnabled: true, operator membuat dua volume terkait model:
- model-weights— volume sumber (dari Amazon S3/Amazon FSx PVC atau penggantian Anda)
- model-weights-copy— sebuah RAM-backed emptyDir tempat pekerja benar-benar membaca
Saat Anda mereferensikan model-weights konfigurasi AndaprefetchEnabled: true, kapan, sebenarnya model-weights-copy yang dipasang /opt/ml/model di wadah pekerja. Saat menggunakan initContainer kustom, pastikan Anda menyalin data ke dalam volume yang dipanggil model-weights-copy — di situlah pekerja mengharapkan untuk menemukannya. KetikaprefetchEnabled: false, hanya ada satu volume (dinamai menurut nama AndamodelVolumeMount.name) dan itu dipasang langsung di/opt/ml/model.

Pemecahan masalah

Gunakan perintah debugging ini jika penerapan Anda tidak berfungsi seperti yang diharapkan.

Periksa InferenceEndpointConfig status untuk melihat status penerapan tingkat tinggi dan masalah konfigurasi apa pun.
```
kubectl describe InferenceEndpointConfig <ENDPOINT_NAME> -n <NAMESPACE>
```

Periksa status penerapan Kubernetes.


kubectl describe deployment <ENDPOINT_NAME> -n <NAMESPACE>

Periksa status semua objek Kubernetes di namespace Anda.


kubectl get pods,svc,deployment,InferenceEndpointConfig,sagemakerendpointregistration -n <NAMESPACE>

Periksa log initContainer jika langkah pemuatan model gagal.
```
kubectl logs <POD_NAME> -c smart-loader -n <NAMESPACE>
```
Jika penerapan gagal dengan “tidak ditemukan di namespace”, verifikasi yang ada: ServiceAccount
```
kubectl get serviceaccount <name> -n <namespace>
```
Jika penerapan gagal dengan “tidak diberi label sebagai dapat ditetapkan pengguna”, minta administrator klaster Anda untuk menambahkan label yang diperlukan:
```
kubectl label serviceaccount <name> sagemaker.amazonaws.com/user-assignable=true -n <namespace>
```
Jika penerapan gagal dengan “tidak harus mereferensikan akun layanan operator”, buat terpisah ServiceAccount untuk beban kerja Anda. Anda tidak dapat menggunakan operator HyperPod inferensi itu sendiri ServiceAccount.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Menerapkan model dari Amazon S3, Amazon FSx, atau Hugging Face Hub menggunakan kubectl

Sertifikat kustom dan Route 53 DNS