---

# 서론 – 왜 Terraform CDK를 떠나야 할까?

클라우드 인프라를 코드로 관리하는 Infrastructure as Code(IaC) 가 점점 보편화되면서, 많은 개발팀이 Terraform CDK(Cloud Development Kit)를 선택했습니다. CDK는 친숙한 프로그래밍 언어로 인프라를 정의할 수 있게 해 주어 초보자에게도 큰 매력을 주었죠. 하지만 실제 프로젝트를 진행하면서 다음과 같은 문제점이 드러납니다.

1. 복잡한 추상화 – CDK가 제공하는 레이어가 오히려 디버깅을 어렵게 만든다.

2. 제한된 플러그인 생태계 – Terraform Provider는 풍부하지만, CDK용 래퍼는 아직 미비하다.

3. 팀 간 협업 어려움 – 코드 스타일이 다양해지면서 리뷰와 유지보수가 복잡해진다.

이러한 이유로 많은 팀이 Terraform CDK를 떠나 기존 Terraform HCL 혹은 다른 IaC 도구로 전환하고 있습니다. 이번 글에서는 “Terraform CDK에서 탈피”하는 구체적인 전략과, 전환 과정에서 겪게 되는 흔한 고민들을 초보자도 이해하기 쉬운 형태로 정리합니다.

---

# 본론

# 1️⃣ Terraform CDK의 장단점 정리

| 구분 | 장점 | 단점 |

|------|------|------|

| 생산성 | 익숙한 언어(TypeScript, Python 등)로 인프라 정의 | 추상화 레이어가 많아 실제 리소스와 차이 발생 |

| 재사용성 | 함수·클래스로 모듈화 가능 | 복잡한 모듈은 가독성 저하 |

| 커뮤니티 | Terraform Provider와 동일한 생태계 | CDK 전용 플러그인·예제 부족 |

핵심 포인트: CDK는 프로그래밍 언어의 장점을 살리지만, IaC의 핵심인 명시적 선언과는 다소 거리가 있습니다. 초보자는 “코드가 복잡해지면 디버깅이 어려워진다”는 점을 기억하세요.

# 2️⃣ 전환 대상 도구 선정 기준

전환을 고민한다면 아래 3가지 기준을 먼저 점검해 보세요.

| 기준 | 설명 | 적용 예시 |

|------|------|-----------|

| 학습 곡선 | 팀원들의 기존 스킬셋과 얼마나 맞는가 | 기존에 HCL 경험이 있다면 Terraform HCL 선택 |

| 플러그인 지원 | 사용하려는 클라우드 서비스와 Provider 호환성 | AWS, GCP, Azure 모두 풍부한 Provider 제공 |

| 자동화 파이프라인 | CI/CD와 연동이 쉬운가 | GitHub Actions, GitLab CI와 바로 연결 가능 |

예를 들어, AWS Lambda와 DynamoDB를 주로 운영한다면 Terraform HCL이 가장 안정적인 선택이 될 수 있습니다. 반면, 복잡한 로직을 코드로 구현해야 할 경우 Pulumi 같은 다른 IaC 도구를 검토해 보는 것도 좋습니다.

# 3️⃣ 실제 전환 단계 – 단계별 체크리스트

1. 현황 파악

   • CDK 프로젝트의 cdk.json, package.json 등을 분석한다.

   • 현재 사용 중인 Provider와 리소스 목록을 추출한다 (cdk synth → terraform plan).

2. HCL 템플릿 생성

   • 추출한 리소스 정보를 바탕으로 기본 HCL 파일(main.tf, variables.tf)을 만든다.

   • 변수와 출력값은 명시적 선언으로 전환해 가독성을 높인다.

3. 테스트 환경 구축

   • 로컬에서 terraform init → terraform validate → terraform plan을 실행한다.

   • 기존 CDK와 동일한 상태 파일(terraform.tfstate)을 사용해 차이를 확인한다.

4. CI/CD 파이프라인 적용

   • GitHub Actions 예시:

yaml

     name: Terraform Deploy

     on:

       push:

         branches: [ main ]

     jobs:

       apply:

         runs-on: ubuntu-latest

         steps:

           - uses: actions/checkout@v3

           - uses: hashicorp/setup-terraform@v2

           - run: terraform init

           - run: terraform plan -out=plan.out

           - run: terraform apply -auto-approve plan.out

• 기존 CDK 파이프라인을 대체하거나 병행 운영한다.

5. 팀 교육 및 문서화

   • HCL 기본 문법, terraform fmt, terraform validate 사용법을 워크숍 형태로 공유한다.

   • 전환 가이드와 FAQ를 내부 위키에 정리해 두면 재발 방지에 도움이 된다.

# 4️⃣ 전환 후 얻을 수 있는 기대 효과

| 기대 효과 | 구체적인 이점 |

|-----------|---------------|

| 가독성 향상 | 선언형 코드가 직관적이라 리뷰가 쉬워진다. |

| 디버깅 효율 | terraform plan 결과가 실제 적용될 리소스를 정확히 보여준다. |

| 플러그인 활용 | Provider가 최신 버전으로 빠르게 업데이트된다. |

| 비용 관리 | 상태 파일을 명확히 관리해 리소스 누락을 방지한다. |

특히 클라우드 자동화 측면에서 Terraform HCL은 “코드가 곧 인프라”라는 원칙을 가장 명확히 구현해 줍니다. 초보자도 terraform apply 한 번으로 전체 스택을 배포할 수 있기 때문에, 학습 곡선이 급격히 낮아지는 장점이 있습니다.

# 5️⃣ 전환 시 흔히 마주치는 문제와 해결책

| 문제 | 원인 | 해결책 |

|------|------|--------|

| 상태 파일 충돌 | CDK와 HCL이 동시에 같은 리소스를 관리 | 전환 전 terraform state rm 으로 기존 리소스 제거 후 재등록 |

| Provider 버전 불일치 | CDK가 최신 Provider를 자동 사용 | required_providers 블록에 명시적으로 버전 지정 |

| 변수 매핑 오류 | CDK에서 사용하던 cdk.context.json을 그대로 사용 | HCL variables.tf에 맞게 변수 이름과 타입 재정의 |

---

# 결론 – 이제는 선택의 문제, 행동으로 옮기자

Terraform CDK는 처음 IaC를 접하는 개발자에게 큰 진입 장벽을 낮춰 주었지만, 규모가 커지고 복잡도가 증가할수록 선언형 Terraform HCL 혹은 다른 IaC 도구가 더 적합한 경우가 많습니다.

다음 단계를 실행해 보세요.

1. 현재 프로젝트의 CDK 사용 현황을 목록화한다.

2. 위 체크리스트를 기반으로 HCL 전환 파일을 하나씩 만들어 본다.

3. 작은 테스트 환경에서 CI/CD 파이프라인을 적용해 보고, 문제점을 기록한다.

4. 팀 전체에 교육 세션을 진행하고, 전환 가이드를 위키에 정리한다.

이 과정을 통해 인프라 코드(Infrastructure as Code) 를 보다 투명하고 효율적으로 관리할 수 있습니다. 클라우드 자동화(Cloud Automation)의 핵심은 “코드가 곧 인프라”라는 단순 명료함에 있습니다. 지금 바로 작은 파일 하나부터 시작해 보세요. 여러분의 팀이 더 빠르고 안정적인 클라우드 환경을 구축하는 데 큰 도움이 될 것입니다. 🚀