Skip to content

dev-setup-devcontainer.md

Latest commit

 

History

History
154 lines (112 loc) · 4.5 KB

dev-setup-devcontainer.md

File metadata and controls

154 lines (112 loc) · 4.5 KB
Raw

Windows 개발 환경 설정 — Dev Container

Windows 환경에서 VS Code Dev Container를 이용해 postgres-operator 개발 환경을 구성하는 가이드. 실제 코드는 Linux 컨테이너 안에서 실행되므로 Makefile, bash 스크립트, envtest가 모두 정상 동작한다.

📍 문서 지도: DOCS_MAP.ko.md · 대안 환경: dev-setup-wsl.md · E2E 실행 시나리오: WORK_HANDOFF.ko.md §3

사전 요구사항

항목 버전 설치 여부 확인
Windows 10 21H2+ 또는 11 winver
Docker Desktop 4.x+ docker version
VS Code 최신 code --version
VS Code 확장 — Dev Containers ms-vscode-remote.remote-containers VS Code 확장 탭

Docker Desktop이 실행 중이어야 한다. 트레이 아이콘에서 "Running" 상태 확인.

1. devcontainer.json 확인

go.mod는 go 1.26.0을 요구한다. 컨테이너 빌드 전에 .devcontainer/devcontainer.json의 Go 이미지 버전이 golang:1.26인지 확인한다.

.devcontainer/devcontainer.json:

{
  "name": "Kubebuilder DevContainer",
  "image": "golang:1.26",
  ...
}

2. VS Code에서 컨테이너 열기

  1. VS Code에서 저장소 폴더(C:\keiailab\postgres-operator) 열기
  2. 좌하단 파란 아이콘 클릭 → "Reopen in Container" 선택
  3. 또는 Ctrl+Shift+P → Dev Containers: Reopen in Container
  4. 컨테이너 빌드 완료까지 대기 (최초 실행 시 이미지 pull + post-install.sh 실행으로 5~10분 소요)

post-install.sh가 자동으로 아래 도구를 설치한다:

도구 설명
kind 로컬 Kubernetes 클러스터 (e2e 테스트용)
kubebuilder CRD/RBAC 스캐폴딩 CLI
kubectl Kubernetes 클라이언트

3. 설치 확인

컨테이너 터미널에서:

go version       # go version go1.26.x linux/amd64
kind version     # kind v0.x.x
kubectl version --client
kubebuilder version
docker --version # Docker Desktop DinD

4. 빌드 및 테스트

# Go 의존성 다운로드
go mod download

# 단위 테스트 — 클러스터 불필요, 가장 빠름
make test-unit

# CRD/RBAC 생성 + 통합 테스트 (envtest 사용)
make test

# 전체 품질 게이트: lint + test + audit + validate
make gate

5. 로컬 Kubernetes 클러스터 띄우기 (e2e 테스트)

# kind 클러스터 생성 (make test-e2e가 자동으로 수행하지만 수동으로도 가능)
kind create cluster --name postgres-operator-dev

# kubeconfig 확인
kubectl cluster-info --context kind-postgres-operator-dev

# e2e 테스트 실행
make test-e2e

# 클러스터 삭제
kind delete cluster --name postgres-operator-dev

6. Operator 이미지 빌드 및 클러스터 적재

# 이미지 빌드
make docker-build IMG=postgres-operator:dev

# kind 클러스터에 이미지 로드 (registry push 없이 로컬 테스트)
kind load docker-image postgres-operator:dev --name postgres-operator-dev

# Helm으로 배포
helm install postgres-operator ./charts/postgres-operator \
  --set image.repository=postgres-operator \
  --set image.tag=dev \
  --set image.pullPolicy=Never

7. 주요 Make 타겟 정리

타겟 동작 소요 시간
make test-unit 단위 테스트 (envtest 불필요) ~30초
make test 단위 + 통합 테스트 ~2분
make test-e2e kind 기반 e2e 테스트 ~10분
make lint golangci-lint ~1분
make gate lint + test + audit + validate ~5분
make manifests generate CRD/RBAC/DeepCopy 재생성 ~20초
make build manager 바이너리 빌드 ~1분
make docker-build 컨테이너 이미지 빌드 ~3분

트러블슈팅

Docker Desktop이 컨테이너 안에서 인식 안 될 때

Docker Desktop → Settings → Resources → WSL Integration에서 "Enable integration with my default WSL distro"가 켜져 있는지 확인.

post-install.sh 실행 중 curl 타임아웃

회사 네트워크 프록시 환경이면 .devcontainer/devcontainer.json에 프록시 환경 변수 추가:

"remoteEnv": {
  "GO111MODULE": "on",
  "HTTP_PROXY": "http://proxy.example.com:8080",
  "HTTPS_PROXY": "http://proxy.example.com:8080"
}

go: module lookup disabled by GONOSUMCHECK

go env -w GONOSUMDB="*"
go env -w GOFLAGS="-mod=mod"

CRD 변경 후 테스트 실패

API 타입(api/v1alpha1/) 수정 후에는 반드시 재생성 필요:

make manifests generate