환경별 Connector 설치

대상: 사내 인프라 담당자 — 가상화 / 클라우드 환경에서 커넥터 설치 선행 조건: 기본 설치 가이드 (Connector 설치 가이드) 1~3장 숙지 본 문서는 환경별 차이만 다룸 — 페어링 / secrets / 업데이트 등 공통 절차는 기본 가이드 참고

secrets 디렉토리는 기본 가이드의 /etc/mcp-connector/secrets 그대로 사용 — 환경에 따라 경로만 조정.

환경별 권장도

1. Nutanix AHV / 일반 가상화 (vSphere, KVM 등)

1-1. VM 생성 시 권장 사양

1-2. VM 생성 후 절차

1. SSH 로 VM 접속
2. Docker 설치

   # Ubuntu
   curl -fsSL https://get.docker.com | sudo sh
   sudo usermod -aG docker $USER
   newgrp docker
   

3. 이후 기본 가이드 4장 으로 진행

1-3. Nutanix 특이사항

• AHV 의 ARM64 / x86 구분: 일반적으로 x86. Connector 이미지는 linux/amd64 + linux/arm64 모두 빌드되어 있어 자동 적합
• VM Time Sync: NTP 설정 필수 — mTLS 인증서 검증이 시간에 민감
• Snapshot / 복제: 운영 안정성 좋아짐. 단 인증서가 들어있는 docker volume (mcp-hub-connector-state-*) 도 함께 백업 필수

2. 클라우드 (AWS / Azure / NCP / GCP)

2-1. 권장 구성

                            ┌──── VPC ─────────────────────┐
                            │                              │
    [WRKS AI Cloud] ────────│──→ [커넥터 EC2]              │
                            │     (Public Subnet 권장 X,    │
                            │     Private Subnet + NAT 권장) │
                            │                              │
                            │     ▼                        │
                            │  ┌─ VPN / Direct Connect ─┐ │
                            │  │  (사내 DC 와 연결)        │ │
                            │  └────────────────────────┘ │
                            └──────────────────────────────┘
                                          ↓
                                  [사내 DB / ERP]

핵심: 커넥터는 Private Subnet + NAT Gateway 권장. Public IP 부여 불필요 (outbound 만).

2-2. AWS EC2 — 단계별

Step 1. EC2 인스턴스 생성

Step 2. NAT Gateway 설정 확인

• VPC → NAT Gateway 있는지 확인
• Private Subnet 의 라우팅 테이블이 NAT 으로 지정돼 있는지

Step 3. Docker + 커넥터 설치

# Amazon Linux 2023
sudo dnf install -y docker
sudo systemctl enable --now docker
sudo usermod -aG docker ec2-user

# 또는 Ubuntu
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

이후 기본 가이드 4장 절차.

Step 4. (선택) AWS Secrets Manager 연동

평문 .env 파일 대신 Secrets Manager 사용 가능 — entrypoint 스크립트 또는 awscli 로 fetch 후 /var/secrets/*.env 에 적기. 본 가이드 범위 밖 — 필요 시 별도 문의.

2-3. Azure VM

설치 절차는 위 EC2 와 동일.

2-4. NCP (Naver Cloud Platform)

• Server > Server 생성 → Ubuntu 또는 CentOS
• VPC > Subnet 의 NAT Gateway 활성화
• ACG (Access Control Group): outbound 443 허용

2-5. 클라우드 공통 유의

• 사내망 → 클라우드 VPC 연결 필수: VPN / Direct Connect / ExpressRoute. 커넥터가 사내 DB 에 접근해야 함
• 이미지 자동 업데이트 X: AMI / 이미지 sticky 태그 사용 X — Studio 가 알려주면 수동 업데이트
• 로그 / 모니터링: CloudWatch / Azure Monitor 등에 컨테이너 로그 수집 권장 (사고 추적)

3. Windows Server + WSL2 + Ubuntu 중첩 구성

권장도 △ — Linux VM 가능하면 그쪽으로. 부득이한 경우만.

3-1. 셋업이 오래 걸리는 이유

1. WSL2 활성화 (재부팅 1~2회)
2. Ubuntu 배포판 설치 + 초기 설정
3. WSL2 안에 Docker 설치
4. 자동 시작 / systemd 설정
5. 네트워크 (WSL2 NAT) 디버깅

총 1~2 시간. 단축 팁 아래 정리.

3-2. 사전 확인

3-3. WSL2 + Ubuntu 설치

# PowerShell (관리자)
wsl --install -d Ubuntu-22.04
# 재부팅 후 Ubuntu 사용자명/비밀번호 설정

3-4. systemd 활성화 (Docker 자동 시작용)

# Ubuntu (WSL2 안)
sudo tee /etc/wsl.conf > /dev/null <<EOF
[boot]
systemd=true
EOF

# PowerShell — WSL2 재시작
wsl --shutdown
wsl

3-5. Docker 설치 (WSL2 Ubuntu 안)

curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
exit  # 새 shell 로 재진입 (그룹 권한)

3-6. Windows 부팅 시 WSL2 자동 시작

작업 스케줄러 (Task Scheduler) 에 등록:

3-7. 커넥터 컨테이너 실행

이후 기본 가이드 4장 명령 — WSL2 Ubuntu 안에서 실행.

3-8. Windows 특이 트러블슈팅

추천: Windows Server 환경이면 Hyper-V 로 Ubuntu VM 1대 만드는 게 WSL2 보다 단순하고 안정적입니다 (관리자 협의).

4. Docker Desktop (Windows / macOS) — PoC 전용

• PoC / 개발 환경 만 사용. 운영 X
• 사용자 로그아웃 / 컴퓨터 절전 시 컨테이너 정지
• Studio 의 페어링 화면에서 "Docker Desktop" 선택 시 host.docker.internal 같은 가상 호스트 매핑 명령이 자동 생성됨

5. 환경 별 체크리스트

6. 문의

• 환경별 특수성 / 사전 협의 사항: WRKS 담당자에게 연락
• 사내 네트워크 / 보안 검토: 사내 인프라 / 보안팀과 협업

같이 보세요:

• 기본 커넥터 설치 → Connector 설치 가이드
• 툴킷 사용 → Toolkit 사용 가이드
• DB 별 연동 상세 → DB 연동 가이드