vllm-deploy-k8s

vLLM の Kubernetes デプロイ

YAML テンプレートを使用して vLLM を Kubernetes にデプロイするための Claude スキルです。GPU リソースとヘルスプローブを備えた ClusterIP Service 付きの Kubernetes Deployment として、vLLM の OpenAI 互換サーバーをデプロイします。

このスキルでできること

• NVIDIA GPU に対応した Kubernetes Deployment と Service として vLLM をデプロイします
• デプロイ前に、vLLM のデプロイがすでに存在するか確認します
• Hugging Face トークンのシークレットが存在するか確認し、存在しない場合はユーザーにトークンを求めます
• デフォルトで vllm/vllm-openai:latest イメージを使用します（ユーザーは別のバージョンを指定できます）
• ユーザーがカスタマイズできる、適切なデフォルト設定を提供します（モデル、レプリカ数、GPU 数、追加の vLLM フラグなど）

前提条件

• Kubernetes クラスターへのアクセス権を持つよう kubectl が設定されていること
• NVIDIA GPU Operator またはデバイスプラグインがクラスターのノードにインストールされていること
• Hugging Face トークン（Llama などのアクセス制限付きモデルでは必須、公開モデルでは任意）

デプロイ手順

ステップ 1：HF トークンのシークレットを確認する

デプロイ前に、対象の名前空間に hf-token Kubernetes シークレットが存在するか確認します。

kubectl get secret hf-token -n <namespace>

• シークレットが存在する場合：ステップ 2 に進みます。
• シークレットが存在しない場合：ユーザーに Hugging Face トークンの入力を求めてから、シークレットを作成します。

kubectl create secret generic hf-token --from-literal=HF_TOKEN="<user-provided-token>" -n <namespace>

アクセス制限付きモデル（例：meta-llama/Meta-Llama-3.1-8B）では、これが必須です。公開モデルではシークレットは任意ですが、レート制限を避けるために推奨されます。

ステップ 2：デプロイがすでに存在するか確認する

適用前に、vLLM のデプロイがすでに存在するか確認します。

kubectl get deployment vllm -n <namespace>

• デプロイが存在する場合：デプロイがすでに存在することをユーザーに伝えます。現在のイメージとステータスを表示し、更新するかスキップするかを尋ねます。
• デプロイが存在しない場合：デプロイに進みます。

ステップ 3：デプロイする

テンプレートの YAML ファイルを適用して vLLM をデプロイします。

kubectl apply -f templates/vllm-service.yaml -n <namespace>
kubectl apply -f templates/vllm-deployment.yaml -n <namespace>

ステップ 4：待機して確認する

デプロイのロールアウトが完了するまで待ちます。

kubectl rollout status deployment/vllm -n <namespace> --timeout=600s

Pod が実行中で準備完了になっていることを確認します。

kubectl get pods -n <namespace> -l app=vllm

Pod の状態が READY 1/1 および STATUS Running であることを確認します。Pod の準備がまだ完了していない場合は、しばらく待ってから再度確認します。CrashLoopBackOff または Error の場合は、kubectl logs -n <namespace> -l app=vllm でログを確認します。

ステップ 5：デプロイの概要を表示する

Pod の準備が完了したら、次の形式で概要メッセージをユーザーに表示します（プレースホルダーは実際の値に置き換えます）。

🎉 **vLLM Deployment Successful!**

| Resource | Name | Status |
|----------|------|--------|
| Deployment | <deployment-name> | <ready>/<total> Ready |
| Service | <service-name> | ClusterIP:<port> |
| Pod | <pod-name> | Running |
| Image | <image> | |
| Model | <model> | |

&nbsp;

**To test the API, run these two commands in your terminal:**

**1. Open a port-forward** (this connects your local port <port> to the vLLM service inside the cluster):

kubectl port-forward svc/vllm-svc <port>:<port> -n <namespace>

**2. In a separate terminal**, send a test request to the OpenAI-compatible API:

curl -s http://localhost:<port>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"<model>","messages":[{"role":"user","content":"Hello!"}],"max_tokens":50}' | python3 -m json.tool

If everything is working, you'll get a JSON response with the model's reply.

デフォルト設定

テンプレートでは、次のデフォルト値を使用します。

パラメーター	デフォルト値
イメージ	vllm/vllm-openai:latest
モデル	Qwen/Qwen2.5-1.5B-Instruct
ポート	8000
レプリカ数	1
GPU 数	1
GPU メモリ使用率	0.85
テンソル並列サイズ	1
CPU リクエスト／上限	12 ／ 128
メモリリクエスト／上限	100Gi ／ 400Gi
共有メモリ（dshm）	80Gi

カスタマイズ

ユーザーから変更を依頼された場合は、適用する前にテンプレート YAML ファイルを変更してください。以下をカスタマイズできます。

• イメージのバージョン：templates/vllm-deployment.yaml の image: vllm/vllm-openai:<version> を変更します（デフォルト：latest）。ユーザーから指定された場合は、v0.17.1 のような特定のバージョンタグを使用してください。
• モデル：Deployment の args 内にある vllm serve コマンドのモデル名を変更します。
• 追加の vLLM フラグ：Deployment の args 内にある vllm serve コマンドに追加のフラグを追記します（例：--max-model-len 4096、--kv-cache-dtype fp8、--enforce-eager、--generation-config vllm）。
• レプリカ数：Deployment 仕様の replicas: を変更します。
• GPU 数：リソースの requests と limits の両方で nvidia.com/gpu を変更します。
• テンソル並列サイズ：GPU 数に合わせて --tensor-parallel-size フラグを変更します。
• CPU／メモリリソース：requests と limits の cpu および memory の値を変更します。
• ポート：Deployment の containerPort、Service の port／targetPort、すべてのヘルスプローブ（liveness、readiness、startup）の port を変更し、さらに args 内の vllm serve コマンドに --port <port> を追加します。4 か所すべてを一致させてください。
• Namespace：-n <namespace> を使用して、特定の Namespace に適用します。
• 共有メモリサイズ：dshm emptyDir ボリュームの sizeLimit を変更します。

Edit ツールを使用してテンプレートファイルを編集し、変更したテンプレートを適用してください。

ステータスの確認

kubectl get deployment,svc,pods -n <namespace> -l app=vllm

クリーンアップ

ユーザーから vLLM デプロイメントのクリーンアップまたは削除を依頼された場合は、次の手順を実行してください。

1. Deployment と Service を削除します。

kubectl delete -f templates/vllm-deployment.yaml -n <namespace>
kubectl delete -f templates/vllm-service.yaml -n <namespace>

2. HF トークンシークレットも削除するかユーザーに確認します。削除する場合：

kubectl delete secret hf-token -n <namespace>

3. すべてがクリーンアップされたことを確認します。

kubectl get deployment,svc,pods -n <namespace> -l app=vllm

4. ユーザーに概要メッセージを表示します。

vLLM deployment has been cleaned up from namespace <namespace>.
Deleted: Deployment/vllm, Service/vllm-svc
HF token secret: <kept/deleted>

トラブルシューティング

• Pod が Pending のままになる：GPU ノードがありません。スケジューリングエラーを確認するには、kubectl describe pod <pod-name> を実行します。NVIDIA GPU Operator またはデバイスプラグインがインストールされていることを確認してください。
• Pod が OOMKilled になる：Deployment の memory 制限を増やすか、より小さなモデルを使用します。
• ImagePullBackOff：イメージ名とタグを確認します。ノードから Docker Hub／コンテナレジストリにアクセスできることを確認してください。
• Startup probe の失敗（CrashLoopBackOff）：モデルのダウンロードに時間がかかっている可能性があります。kubectl logs <pod-name> でログを確認します。アクセス制限付きモデルの場合は、hf-token シークレットが存在することを確認してください。必要に応じて、startup probe の failureThreshold を増やします。
• HF_TOKEN が機能しない：シークレットが存在することを確認します：kubectl get secret hf-token -n <namespace>。トークンが有効であることを確認してください。
• コンテナ内で GPU が検出されない：nvidia.com/gpu リソースが要求されており、NVIDIA デバイスプラグインがノード上で実行されていることを確認してください。

参考資料

• vLLM ドキュメント
• vLLM Docker イメージ
• NVIDIA GPU Operator
• Kubernetes GPU スケジューリング