# 1. 인프라 배포 (CDK)

AWS CDK(Cloud Development Kit)를 사용해 OSMO가 실행될 클라우드 인프라를 한 번에 생성합니다. 수동으로 AWS 콘솔에서 하나씩 만들 필요 없이, 코드 한 줄로 전체 환경이 만들어집니다.

**OSMO는 다음 인프라가 필요합니다:**

* **EKS (Kubernetes)** — OSMO 서비스와 워크플로 Pod가 실행되는 곳
* **RDS (PostgreSQL)** — 워크플로 메타데이터, 사용자 정보를 저장하는 데이터베이스
* **ElastiCache (Redis)** — 워크플로 작업 큐를 관리하는 메시지 브로커
* **S3** — 학습 데이터셋과 워크플로 로그를 저장하는 오브젝트 스토리지

### 사전 요구 사항

* AWS 계정 — 권장 리전: `us-west-2`
* GPU 인스턴스 서비스 할당량 확인 — AWS 콘솔 → [Service Quotas](https://console.aws.amazon.com/servicequotas/) → EC2 → `Running On-Demand G and VT instances` 값이 필요한 vCPU 수 이상인지 확인
  * g6e.12xlarge = 48 vCPU (Train 노드)
  * g5.12xlarge = 48 vCPU (Sim 노드)

{% hint style="warning" %}
GPU 인스턴스 할당량이 부족하면 노드가 프로비저닝되지 않습니다. 배포 전 Service Quotas에서 할당량을 확인하세요.
{% endhint %}

***

### 1.1 환경 설정

```bash
# 리포지토리 클론
git clone --depth 1 https://github.com/hi-space/aws-physical-ai-recipes.git ~/aws-physical-ai-recipes

# CDK 프로젝트 설정
cd ~/aws-physical-ai-recipes/osmo/cdk
npm install

# 도구 확인
aws --version
aws sts get-caller-identity   # 현재 로그인된 AWS 계정 확인
node --version    # >= 18
npx cdk --version # >= 2.x
kubectl version --client
helm version
```

***

### 1.2 CDK Bootstrap (최초 1회)

해당 리전에서 CDK를 처음 사용하는 경우 bootstrap을 실행합니다:

```bash
npx cdk bootstrap aws://$(aws sts get-caller-identity --query Account --output text)/us-west-2
```

***

### 1.3 인프라 배포 (\~20분)

```bash
npx cdk deploy --context region=us-west-2 --require-approval never
```

{% hint style="info" %}
배포 완료까지 약 20분 소요됩니다. EKS 클러스터 생성에 \~10분, RDS 생성에 \~8분이 걸립니다.
{% endhint %}

<details>

<summary>CDK가 생성하는 인프라 구성</summary>

| 카테고리 | 리소스                                 | 설명                    |
| ---- | ----------------------------------- | --------------------- |
| 네트워킹 | VPC, 2x Public/Private Subnet       | Multi-AZ 고가용성         |
| 네트워킹 | NAT Gateway, Internet Gateway       | Private 서브넷 아웃바운드     |
| EKS  | Cluster (v1.30)                     | Kubernetes 컨트롤 플레인    |
| EKS  | System 노드그룹 (m5.xlarge ×2)          | OSMO 서비스 워크로드         |
| EKS  | GPU-Train 노드그룹 (g6e.12xlarge, 0\~4) | GR00T 학습, 4×L40S GPU  |
| EKS  | GPU-Sim 노드그룹 (g5.12xlarge, 0\~8)    | Isaac Sim, 4×A10G GPU |
| EKS  | Addons (EBS CSI, Secrets Store CSI) | 스토리지 및 시크릿 관리         |
| 데이터  | RDS PostgreSQL (db.t3.medium)       | OSMO 메타데이터 저장         |
| 데이터  | ElastiCache Redis (cache.t3.medium) | Job 큐                 |
| 데이터  | S3 Bucket (Intelligent Tiering)     | 워크플로 데이터/로그           |
| 보안   | Secrets Manager                     | DB 자격 증명 관리           |
| IAM  | Cluster Role, Node Role             | EKS 권한                |

</details>

***

### 1.4 배포 완료 확인

```bash
# 노드그룹이 3개 생성되었는지 확인
aws eks list-nodegroups --cluster-name osmo-eks --region us-west-2
```

**예상 출력:**

```json
{
    "nodegroups": ["gpu-sim", "gpu-train", "system"]
}
```

{% hint style="success" %}
노드그룹 3개가 출력되면 배포가 성공한 것입니다. 다음 단계로 진행하세요.
{% endhint %}

***

### 1.5 배포되는 리소스 요약

| 리소스                  | 사양                           | 용도                         |
| -------------------- | ---------------------------- | -------------------------- |
| EKS Cluster          | Kubernetes v1.30             | OSMO 서비스 및 워크플로 실행 환경      |
| System Node Group    | m5.xlarge × 2                | OSMO 서비스, Kai Scheduler 실행 |
| GPU-Train Node Group | g6e.12xlarge (4×L40S), 0\~4대 | GR00T 모델 학습                |
| GPU-Sim Node Group   | g5.12xlarge (4×A10G), 0\~8대  | Isaac Sim 시뮬레이션            |
| RDS PostgreSQL       | db.t3.medium                 | OSMO 메타데이터 저장              |
| ElastiCache Redis    | cache.t3.medium              | 작업 큐 관리                    |
| S3 Bucket            | Intelligent Tiering          | 워크플로 데이터/로그 저장             |

{% hint style="info" %}
GPU 노드그룹은 `desiredSize=0`으로 설정되어 있어 평소에는 비용이 발생하지 않습니다. 워크플로 실행 시에만 수동으로 스케일업합니다.
{% endhint %}

***

### Troubleshooting

| 증상                              | 원인               | 해결                                                                                            |
| ------------------------------- | ---------------- | --------------------------------------------------------------------------------------------- |
| `osmo-db-secret already exists` | 이전 배포의 잔여 Secret | `aws secretsmanager delete-secret --secret-id osmo-db-secret --force-delete-without-recovery` |
| ROLLBACK\_COMPLETE 상태           | 리소스 생성 실패 후 롤백   | `aws cloudformation delete-stack --stack-name Osmo` 후 재배포                                     |
| 배포 20분 이상 대기                    | RDS 생성에 시간 소요    | 정상. CloudFormation 콘솔에서 진행 상황 확인                                                              |
| `InsufficientInstanceCapacity`  | GPU 리전 재고 부족     | 다른 인스턴스 타입 또는 리전 사용                                                                           |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hi-space.gitbook.io/physical-ai-on-aws/physical-ai-on-aws-guide/nvidia-osmo-on-aws/1.-infra-deploy.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.