> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/dev/miniprem/kubernetes-overview/kubernetes-eks.md).

# AWS EKS

## AWS EKS 本番デプロイ

> NVIDIA A10G GPU アクセラレーションを活用し、AWS EKS 上に Renny デジタルヒューマンをデプロイします

{% hint style="info" %}
本ページの内容はデジタルヒューマン株式会社の正式サポート対象外です。参考情報としてご利用ください。
{% endhint %}

{% hint style="info" %}
**マルチクラウド対応:** 本ガイドは AWS EKS 専用です。その他のクラウドプロバイダーについては以下を参照してください。\
\
・[マルチクラウド概要](/dev/miniprem/kubernetes-overview.md) - すべてのクラウドプロバイダーの比較\
・[Azure AKS デプロイ](/dev/miniprem/kubernetes-overview/kubernetes-aks.md) - Azure 上へのデプロイ\
・[マルチクラウドガイド](/dev/miniprem/kubernetes-overview/kubernetes-multi-cloud.md) - コスト比較と移行
{% endhint %}

### 目次

* [概要](#overview)
* [アーキテクチャ](#architecture)
* [前提条件](#prerequisites)
* [クイックスタート](#quick-start)
* [構成](#configuration)
* [運用](#operations)
* [モニタリング](#monitoring)
* [トラブルシューティング](#troubleshooting)
* [コスト管理](#cost-management)
* [ライセンス](#license)
* [著作権](#copyright)

### 概要

本 Kubernetes デプロイメントは、NVIDIA GPU をサポートする AWS EKS 上に Renny デジタルヒューマン向けの **本番運用に耐える自動スケーリング基盤** を提供します。以下のようなユースケースに最適です。

* 高可用性を求められる **本番ワークロード**
* 10〜20 体以上のデジタルヒューマンを同時稼働させる **エンタープライズデプロイ**
* 需要に応じた **自動スケーリング**
* NVIDIA A10G GPU による **GPU アクセラレーションレンダリング**
* インフラをコードで管理する **マルチリージョンデプロイ**

#### 主な特長

* ✅ **ワンクリックデプロイ**（約 30〜45 分）
* ✅ **自動スケーリング**（10〜20 体の Renny インスタンス）
* ✅ コスト最適化のための **GPU タイムスライシング**
* ✅ Vulkan / Unreal Engine 互換のための **Ubuntu 22.04 EKS AMI**
* ✅ NVIDIA GPU Operator による **GPU ドライバーの自動インストール**
* ✅ 一元的なロギングを実現する **CloudWatch 連携**
* ✅ 3 つのアベイラビリティーゾーンにまたがる **高可用性**
* ✅ Terraform による **Infrastructure as Code**

#### アーキテクチャ比較

| 項目           | Docker（ローカル）   | Kubernetes（本番）     |
| ------------ | -------------- | ------------------ |
| **デプロイ**     | 単一マシン          | マルチノードクラスター        |
| **スケーラビリティ** | 1〜5 インスタンス     | 10〜20 体以上          |
| **高可用性**     | なし             | あり（マルチ AZ）         |
| **自動スケーリング** | 手動             | 自動                 |
| **GPU サポート** | 単一 GPU         | タイムスライシングによる複数 GPU |
| **コスト**      | 約 100〜500 ドル/月 | 約 10,000 ドル/月      |
| **セットアップ時間** | 5〜10 分         | 30〜45 分            |
| **ユースケース**   | 開発／デモ          | 本番／エンタープライズ        |

### アーキテクチャ

#### インフラ概要

```mermaid
flowchart TD
    subgraph aws["AWS Cloud (us-east-2)"]
        subgraph vpc["VPC (10.0.0.0/16)"]
            subgraph pub["Public Subnets (3 AZs)"]
                nat1["NAT Gateway 1"]
                nat2["NAT Gateway 2"]
                nat3["NAT Gateway 3"]
            end
            subgraph priv["Private Subnets (3 AZs)"]
                subgraph eks["EKS Cluster (renny-production)"]
                    cp["Control Plane (Managed by AWS)"]
                    subgraph cng["Control Node Group"]
                        ctl["2x t3.large instances"]
                    end
                    subgraph gng["Renny GPU Node Group"]
                        g5["10-20x g5.4xlarge instances"] --> a10g["NVIDIA A10G GPUs (24GB VRAM each)"]
                    end
                end
            end
        end
        cw["CloudWatch Logs (centralized monitoring)"]
    end
```

#### GPU タイムスライシング

GPU タイムスライシングによって、複数の Renny ポッドが 1 枚の物理 GPU を共有できます。

```mermaid
flowchart LR
    subgraph node["g5.4xlarge Node (NVIDIA A10G 24GB)"]
        vgpu1["Virtual GPU 1"] --> pod1["Renny Pod 1 (~30% utilization)"]
        vgpu2["Virtual GPU 2"] --> pod2["Renny Pod 2 (~30% utilization)"]
    end
    total["Total GPU Utilization: ~60% (optimal cost/performance)"]
```

#### ネットワークアーキテクチャ

* **WebRTC / UDP**: ポート 22000〜23000（PixelStreaming）
* **TURN / STUN**: ポート 3478（TCP / UDP）
* **HTTPS**: ポート 443（`*.uneeq.io` への送信）
* **プライベートサブネット**: セキュリティのため、すべての GPU ノードを配置
* **NAT ゲートウェイ**: 高可用な外向き接続を提供

### 前提条件

#### 必要なツール

1. 適切な権限を持つ **AWS アカウント**
2. 認証情報を設定した **AWS CLI**（2.3.0 以上）
3. **Terraform**（1.0 以上）
4. **kubectl**（Kubernetes CLI）
5. **Helm**（3.0 以上、Kubernetes パッケージマネージャー）
6. [サポート窓口](https://support.digitalhumans.jp/)から発行する **Harbor** アカウント
7. **Renny Helm チャート**（`renny-chart.tgz` ファイル）

#### macOS 固有の要件

```bash
# Install coreutils for deployment timeouts
brew install coreutils
```

#### インストールコマンド

**Terraform:**

```bash
# macOS
brew tap hashicorp/tap
brew install hashicorp/tap/terraform

# Linux (Ubuntu/Debian)
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform
```

**その他のツール:**

```bash
# AWS CLI
# macOS: brew install awscli
# Linux: pip install awscli

# kubectl
# macOS: brew install kubectl
# Linux: sudo snap install kubectl --classic

# Helm
# macOS: brew install helm
# Linux: sudo snap install helm --classic
```

#### インストールの確認

```bash
terraform version  # Should show v1.6.6 or higher
aws --version      # AWS CLI version
kubectl version    # Kubernetes CLI
helm version       # Helm package manager
gtimeout --version # macOS only - GNU coreutils
```

### クイックスタート

#### ステップ 1: AWS 認証情報のセットアップ

デプロイスクリプトは **プロファイル対応** で、AWS 設定を自動的に検出します。

**オプション 1: AWS SSO（推奨）**

```bash
# Login to your SSO profile
aws sso login --profile your-org-profile

# Run deployment with profile
cd kubernetes/
./scripts/deploy.sh --profile your-org-profile
```

**オプション 2: IAM ユーザー**

```bash
aws configure
# Enter Access Key ID and Secret Access Key
# Region: us-east-2 (or your preferred region)
```

**AWS 設定の確認:**

```bash
./scripts/check-aws-prerequisites.sh
```

**VPC の空き状況を確認:**

```bash
./scripts/check-vpc-usage.sh
# AWS has a default limit of 5 VPCs per region
# This script helps identify unused VPCs
```

#### ステップ 2: 認証情報の設定

`kubernetes/terraform/terraform.tfvars` を作成します。

```hcl
# Required credentials
dhop_tenant_id  = "your-tenant-id"
dhop_api_key    = "your-api-key"  # Plain text API key

# Harbor registry credentials (contact help@uneeq.com for robot account)
harbor_username = "robot$your-customer-name"
harbor_password = "your-harbor-robot-password"

# Optional: Override defaults
aws_region = "us-east-2"  # Change to your preferred region
```

#### ステップ 3: Helm チャートの配置

`renny-chart.tgz` ファイルを `kubernetes/` ディレクトリに配置してください。

#### ステップ 4: デプロイ

ワンクリックデプロイを実行します。

```bash
cd kubernetes
chmod +x scripts/*.sh

# Basic deployment
./scripts/deploy.sh

# With specific AWS profile
./scripts/deploy.sh --profile your-profile-name

# Get help
./scripts/deploy.sh --help
```

#### デプロイ手順

デプロイスクリプトは以下の処理を行います。

1. ✅ **前提条件の確認**（AWS 認証情報、各種ツール）
2. 🏗️ Terraform による **VPC と EKS クラスターのデプロイ**（約 15〜20 分）
3. 🚀 Ubuntu ノードの **高速クラスタージョイン**（約 3〜5 分）
4. 🎮 **NVIDIA GPU Operator のインストール**（約 5〜10 分）
5. 🤖 内部音声処理を伴う **Renny のデプロイ**（約 5〜10 分）
6. ⚖️ **オートスケーリングの設定**（10〜20 インスタンス）

**デプロイ全体の所要時間: 約 30〜45 分**

### 構成

#### GPU タイムスライシングの設定

GPU タイムスライシングの設定はすべて `kubernetes/values/renny-values.yaml` で管理します。

```yaml
# GPU time-slicing configuration
gpuTimeSlicing:
  enabled: true
  replicasPerGpu: 2  # How many pods share one GPU

deployment:
  nodeType: renny
  totalReplicas: 4   # Total number of Renny pods
  # Note: totalReplicas must be a multiple of replicasPerGpu

resources:
  limits:
    nvidia.com/gpu: 1  # Each pod requests 1 GPU share
    memory: "7Gi"       # Per-pod memory
    cpu: "3600m"        # Per-pod CPU (3.6 cores)
```

**変更手順:**

1. `kubernetes/values/renny-values.yaml` を編集します。
2. `./scripts/deploy.sh` を実行して変更を反映します。

#### NVIDIA ドライバーの選定

ドライバーはすべて **NVIDIA 公式のプロプライエタリドライバー** を使用してください。オープンソースの nouveau ドライバーはミニプレム（MiniPrem）と互換性がなく、GPU アクセラレーション、NVENC エンコード、Vulkan サポートのいずれも利用できません。

デプロイ時には以下のいずれかを選択します。

**ドライバー 575 以上（本番運用実績あり）**

* ✅ 本番運用可能、広範な検証済み
* ✅ Unreal Engine 5.6 以上との互換性
* ✅ 完全なグラフィックス機能
* ✅ CUDA 12.6 以上のサポート

**ドライバー 580 以上（最新版）**

* ✅ NVIDIA Ada Lovelace（40xx シリーズ）および Blackwell（50xx シリーズ）GPU には必須 — Vulkan と NVENC の完全サポートを得るには 580 以上が必要です
* ✅ 最新の機能および最適化を提供
* ✅ CUDA 12.8 以上のサポート
* ⚠️ 最新リリースのため、慎重に動作確認をしてください

#### TTS（音声合成）の設定

TTS（音声合成）プロバイダーは `kubernetes/values/renny-values.yaml` で設定します。

```yaml
# Azure Speech Services
tts:
  azureRegion: "eastus"
  azureSpeechKey: "your-azure-api-key"  # Plain text

# ElevenLabs
tts:
  elevenlabsApiKey: "sk_your-elevenlabs-api-key"

# Google Cloud TTS
tts:
  gcpCredentials: "{\"type\": \"service_account\", ...}"
```

**変更の反映:**

```bash
helm upgrade renny ./renny-chart.tgz -n uneeq-renderer -f values/renny-values.yaml
```

### 運用

#### Renny インスタンスのスケーリング

10〜20 インスタンスの範囲でスケーリングします。

```bash
./scripts/scale.sh 15  # Scale to 15 instances
```

#### デプロイ状況の確認

包括的なステータスレポートを取得します。

```bash
./scripts/status.sh
```

#### GPU ドライバーの確認

```bash
# Check GPU operator pods
kubectl get pods -n gpu-operator

# Verify GPU drivers on nodes
kubectl get nodes -l nvidia.com/gpu.present=true

# Test GPU functionality
kubectl run gpu-test --image=nvidia/cuda:12.4-runtime-ubuntu22.04 --rm -it --restart=Never \
  --overrides='{"spec":{"nodeSelector":{"uneeq.io/node-type":"renny"},"tolerations":[{"key":"nvidia.com/gpu","operator":"Equal","value":"true","effect":"NoSchedule"}]}}' \
  -- nvidia-smi
```

#### kubectl コンテキストの確認

デプロイ後、kubectl は自動的に EKS クラスターに接続されます。

```bash
# Verify connection
kubectl config current-context

# Reconnect if needed
aws eks update-kubeconfig --region us-east-2 --name renny-production
```

### モニタリング

#### ポッドのヘルスモニタリング

```bash
# Check all pods
kubectl get pods -A

# Check Renny pods
kubectl get pods -n uneeq-renderer

# Watch pods in real-time
kubectl get pods -n uneeq-renderer -w

# Check pod details
kubectl describe pod <pod-name> -n uneeq-renderer

# View logs
kubectl logs <pod-name> -n uneeq-renderer -f
```

#### ノードリソースのモニタリング

```bash
# Check node status
kubectl get nodes -o wide

# Check GPU availability
kubectl get nodes -L nvidia.com/gpu,uneeq.io/node-type

# Check node resources
kubectl describe nodes | grep -A10 "Allocated resources"
```

#### CloudWatch Logs

Renny のログはすべて自動的に CloudWatch に送信され、一元的に管理できます。

**ロググループの場所:**

* EKS クラスターログ: `/aws/eks/[cluster-name]/cluster`
* アプリケーションログ: `/aws/containerinsights/[cluster-name]/application`

**CloudWatch Insights クエリの例:**

最近のエラーを検索:

```sql
fields @timestamp, service, renderer_id, message
| filter service = "renderer"
| filter log_level = "error"
| sort @timestamp desc
| limit 50
```

音声処理を監視:

```sql
fields @timestamp, message, client_session_id
| filter service = "renderer"
| filter message like /speech.*failed|USE_V2_COORDINATOR/
| sort @timestamp desc
```

### トラブルシューティング

#### よくある問題

**ポッドが Pending のまま:**

```bash
# Check why pod isn't scheduled
kubectl describe pod <pod-name> -n uneeq-renderer

# Common causes:
# - "Insufficient nvidia.com/gpu" = No GPU nodes available
# - "Insufficient cpu/memory" = Resource limits exceeded
```

**イメージプルの失敗:**

```bash
# Check Docker registry secret
kubectl get secret docker-config -n uneeq-renderer

# Recreate if needed (run deploy script again)
```

**GPU ドライバーの問題:**

```bash
# Check GPU operator installation
kubectl get pods -n gpu-operator

# Check driver installation logs
kubectl logs -n gpu-operator -l app=nvidia-driver-daemonset --tail=100

# Verify GPU resources
kubectl get nodes -L nvidia.com/gpu
```

**kubectl 接続の問題:**

```bash
# Verify context
kubectl config current-context

# Test connectivity
kubectl get nodes

# Reconnect to EKS
aws eks update-kubeconfig --region us-east-2 --name renny-production
```

#### デバッグコマンド

```bash
# Check all events
kubectl get events -n uneeq-renderer --sort-by='.lastTimestamp'

# Interactive pod debugging
kubectl exec -it <pod-name> -n uneeq-renderer -- /bin/bash

# Check GPU utilization
kubectl exec -n gpu-operator $(kubectl get pods -n gpu-operator -l app=nvidia-dcgm-exporter -o name | head -1) -- nvidia-smi
```

#### クリーンアップ

すべてのリソースを破棄するには（約 15〜20 分）以下を実行します。

```bash
./scripts/destroy.sh
```

確認なしで緊急クリーンアップする場合:

```bash
./scripts/cleanup.sh  # USE WITH CAUTION
```

### コスト管理

#### 月額コストの目安（us-east-1）

* **EKS コントロールプレーン**: 約 73 ドル/月
* **NAT ゲートウェイ**（3 台）: 約 135 ドル/月
* **コントロールノード**（t3.large × 2）: 約 120 ドル/月
* **Renny ノード**（g5.4xlarge × 10）: 約 8,760 ドル/月
* **基本料金合計**: 約 9,088 ドル/月

*コストは Renny インスタンス数（10〜20）に応じて増減します。*

#### コスト削減のヒント

1. **未使用時は破棄する** — 時間あたりコスト: 約 15〜20 ドル
2. 開発／検証環境では **NAT ゲートウェイを 1 台のみ** にする
3. ASG コマンドを使って **業務時間外にスケールダウン** する
4. クリティカルでないワークロードには **スポットインスタンス** を活用する
5. 本番環境では **リザーブドインスタンス** を利用する

#### ASG による手動スケーリング

業務時間外にスケールダウンしてコストを削減します。

```bash
# Get ASG names
aws autoscaling describe-auto-scaling-groups \
  --query "AutoScalingGroups[?contains(AutoScalingGroupName, 'renny-production')].AutoScalingGroupName" \
  --output text

# Scale down to 0
aws autoscaling update-auto-scaling-group \
  --auto-scaling-group-name eks-renny-production-renny-gpu-v4-XXXXXXXXXX \
  --desired-capacity 0 --min-size 0

# Scale back up
aws autoscaling update-auto-scaling-group \
  --auto-scaling-group-name eks-renny-production-renny-gpu-v4-XXXXXXXXXX \
  --desired-capacity 2 --min-size 2
```

### セキュリティに関する考慮事項

* ✅ すべての GPU ノードを **プライベートサブネット** に配置
* ✅ **WebRTC / TURN トラフィック** 向けにセキュリティグループを構成
* ✅ ポッドレベルでの AWS 権限付与に **IRSA** を有効化
* ✅ シークレットは **Kubernetes Secrets** で管理
* ✅ 必要に応じて **ネットワークポリシー** を追加可能

***

### ライセンス

本 Kubernetes デプロイメントは MiniPrem プラットフォームの一部であり、MIT ライセンスでライセンスされています。詳細は LICENSE ファイルを参照してください。

***

### 著作権

**© 2025 UneeQ. All rights reserved.**

[サポート窓口](https://support.digitalhumans.jp/)