id	scp-terraform-provider-iac
name	scp-terraform-provider-iac
description	SCP(Samsung Cloud Platform) Terraform Provider v2로 인프라 코딩 시 반드시 알아야 할 패턴과 함정
source	conversation
scope	project
triggers	["samsungcloudplatformv2","SCP Terraform","SCP provider","SCP 인프라","SCP IaC","SCP VPC","SCP SKE","SCP DBaaS","opentofu SCP"]
quality	high

SCP Terraform Provider v2 IaC 패턴

The Insight

SCP Provider(samsungcloudplatformv2)는 AWS/GCP Terraform Provider와 다르게 동작하는 SCP 고유 제약이 많다. 문서가 부족하고 에러 메시지가 불친절해 실제 배포 없이는 알기 어려운 함정이 다수 존재한다. 이 스킬은 실제 kr-west1 dev 환경 프로비저닝(46개 이슈 해결)에서 발견한 핵심 패턴을 담는다.

Provider 설정

provider "samsungcloudplatformv2" {
  auth_url       = "https://iam.example-cloud.com/v1"
  default_region = "kr-west1"
  # ⚠️ account_id 절대 설정 금지 — HMAC 서명 방식으로 전환되어 모든 API 401 반환
}

허용 리전: kr-west1, kr-east1 (SCP v2 제공 리전)

VPC / 서브넷

항목	올바른 값	잘못된 값
서브넷 타입	`GENERAL`	`PUBLIC`, `PRIVATE`
IGW 타입	`IGW`	`PUBLIC`
서브넷 이름 최대 길이	20자	21자 이상 → 400
VPC당 GENERAL 서브넷 수	최대 3개 (dev 쿼터)	4개 이상 → 400

resource "samsungcloudplatformv2_vpc_subnet" "example" {
  type = "GENERAL"  # PUBLIC/PRIVATE 미지원
}

resource "samsungcloudplatformv2_vpc_internet_gateway" "main" {
  type              = "IGW"
  firewall_enabled  = true
  firewall_loggable = false  # true → 로그 스토리지 미설정 시 400
}

보안 그룹 (Security Group)

# ⚠️ loggable = true → 로그 스토리지 미연결 시 404
resource "samsungcloudplatformv2_security_group_security_group" "main" {
  loggable = false
}

# ⚠️ 프로토콜: ALL 미지원, 소문자만 허용
resource "samsungcloudplatformv2_security_group_security_group_rule" "rule" {
  protocol       = each.value.protocol == "ALL" ? null : lower(each.value.protocol)
  port_range_min = each.value.protocol == "ALL" ? null : each.value.from_port
  port_range_max = each.value.protocol == "ALL" ? null : each.value.to_port
}

레이스 컨디션 방지: 모든 SG 모듈에 depends_on = [module.vpc] 필수

IGW 방화벽

# ⚠️ source/destination_address에 0.0.0.0/0 금지 → 400
# ⚠️ AWS IP 대역(13.x.x.x), link-local(169.254.x.x), UDP OUTBOUND → 400
# ✅ 구체적 공인 IP/CIDR만 허용

resource "samsungcloudplatformv2_firewall_firewall_rule" "igw_ssh" {
  for_each = var.create_firewall ? toset(var.admin_cidr) : toset([])
  firewall_rule_create = {
    direction           = "INBOUND"
    source_address      = [each.value]
    destination_address = [module.bastion.public_ip]  # 공인 IP 명시
    service             = [{ service_type = "TCP", service_value = "22" }]
  }
}

⚠️ 방화벽 사이즈 한도 (exsmall = 최대 5룰)

SCP IGW 방화벽의 기본 사이즈는 exsmall이며, 최대 5개 룰만 허용된다. 5개 초과 시 API는 에러 메시지 없이 HTTP 400만 반환하므로 디버깅이 매우 어렵다.

# 에러 예시 (5룰 초과 시)
Error: Error creating firewall rule
│ statusCode: 400
│ (에러 메시지 없음 — 룰 개수 한도 초과가 원인)

해결책:

SCP 콘솔 → 방화벽 → 사이즈 업그레이드: exsmall → small (최대 50룰) 이상
Terraform Provider에 firewall_size 파라미터 없음 → 콘솔 전용 작업
방화벽 룰 생성 시 레이스 컨디션 방지를 위해 -parallelism=1 권장:

# ✅ 방화벽 룰 생성 시 권장
tofu apply -parallelism=1 -var-file=dev.tfvars

# 또는 방화벽 룰만 타깃 적용
tofu apply -parallelism=1 -target=module.firewall -var-file=dev.tfvars

VM (Virtual Server)

resource "samsungcloudplatformv2_virtualserver_server" "bastion" {
  state          = "ACTIVE"   # ⚠️ 이 필드 누락 시 "Invalid server state. State: " 400
  server_type_id = "s1v4m8"  # 형식: s1v{cpu}m{mem}
  boot_volume = {
    size = 16  # ⚠️ 8GB 배수만 허용. 최솟값 16GB (2 units × 8GB)
    type = "SSD"
    delete_on_termination = true
  }
}

이미지 data source 필터: status, visibility 필터 제거 — SCP 이미지 API와 불일치 多. os_distro + name regex만 사용.

키페어 (Keypair)

# ⚠️ terraform import 미지원 → SCP에 이미 존재하면 409
# 해결: SCP 콘솔에서 키페어 삭제 후 tofu apply
resource "samsungcloudplatformv2_virtualserver_keypair" "keypair" {
  name = "${var.environment}-bastion-keypair"
}

coalesce(var.keypair_name, "default") 패턴 사용 시 기본값은 반드시 null (빈 문자열 아님)
이름 변경(rename) API 미지원 → destroy + create 패턴

SKE (Kubernetes Cluster)

# 지원 버전 확인 필수 — 콘솔 SKE 생성 화면에서 확인
k8s_version = "v1.32.8"  # 예시. 미지원 버전 → 404

node_pools = [{
  os_type = "ubuntu 22.04"  # v1.32.8: ubuntu 24.04 미지원
}]

DBaaS (EPAS / Redis)

variable "maintenance_start_time" {
  default = "0100"  # ⚠️ "0000" (자정) 미지원 → 400
}

variable "backup_frequency_minute" {
  default = 1440  # ⚠️ 60(매시간)이면 retention_period_day 검증 실패
}

Load Balancer

loadbalancer_create = {
  layer_type = "L4"  # ⚠️ 누락 시 "Invalid value for layer type: " 400
}
lb_server_group_create = {
  lb_method = "ROUND_ROBIN"  # ⚠️ "algorithm" 필드명 오류 → lb_method
  vpc_id    = var.vpc_id     # ⚠️ 필수 (누락 → 400)
  subnet_id = var.subnet_id  # ⚠️ 필수 (누락 → 400)
}
lb_listener_create = {
  routing_action = "LB_SERVER_GROUP"  # ⚠️ 누락 시 400
}

⚠️ SCP LB SDK v1.2 Deprecated (2026-03-31 만료)

SCP Load Balancer API v1.2가 deprecated 상태이며, Terraform으로 LB 생성 시 리스너 생성 단계에서 LB가 ACTIVE 상태가 되지 않아 반복 에러가 발생한다.

# 에러 예시 (LB SDK v1.2 deprecated 관련)
Error: Error creating listener
│ Cannot create listener. Associated Load Balancer is not in the ACTIVE state.(ERROR)
│
│ (원인: LB SDK v1.2 deprecated로 인한 내부 상태 전이 실패)

해결책:

enable_user_lb = false (기본값)로 설정해 Terraform LB 리소스 비활성화
SCP 콘솔에서 수동 생성 권장 (또는 SCP 지원팀에 API v2 마이그레이션 문의)
신규 배포 시 LB 모듈 적용 전 SCP 콘솔에서 API 버전 상태 확인

운영 패턴

API Rate Limit (429)

# 병렬 refresh 429 발생 시
tofu apply -parallelism=3 -var-file=dev.tfvars
# 또는
tofu apply -refresh=false -var-file=dev.tfvars  # state 캐시 사용

방화벽 룰 생성 시 직렬 실행 권장

# ✅ 방화벽 룰은 반드시 parallelism=1로 적용 (레이스 컨디션 + 사이즈 한도 초과 방지)
tofu apply -parallelism=1 -var-file=dev.tfvars

스키마 확인

tofu providers schema -json | python3 -c "
import json,sys
s=json.load(sys.stdin)
r=s['provider_schemas']['registry.terraform.io/samsungsdscloud/samsungcloudplatformv2']['resource_schemas']
print(json.dumps(r['samsungcloudplatformv2_<resource_name>']['block'], indent=2))
" 2>/dev/null

S3 백엔드 (Object Storage)

terraform {
  backend "s3" {
    endpoints = { s3 = "https://..." }  # deprecated: endpoint (단수)
    skip_credentials_validation = true
    encrypt                     = true
    sse_algorithm               = "AES256"
  }
}

버전 정보

Provider: samsungcloudplatformv2 v3.1.7
IaC 도구: OpenTofu 1.8.x (tofu 명령)
허용 리전: kr-west1, kr-east1

id	scp-terraform-provider-iac
name	scp-terraform-provider-iac
description	SCP(Samsung Cloud Platform) Terraform Provider v2로 인프라 코딩 시 반드시 알아야 할 패턴과 함정
source	conversation
scope	project
triggers	["samsungcloudplatformv2","SCP Terraform","SCP provider","SCP 인프라","SCP IaC","SCP VPC","SCP SKE","SCP DBaaS","opentofu SCP"]
quality	high

SCP Terraform Provider v2 IaC 패턴

The Insight

Provider 설정

provider "samsungcloudplatformv2" {
  auth_url       = "https://iam.example-cloud.com/v1"
  default_region = "kr-west1"
  # ⚠️ account_id 절대 설정 금지 — HMAC 서명 방식으로 전환되어 모든 API 401 반환
}

허용 리전: kr-west1, kr-east1 (SCP v2 제공 리전)

VPC / 서브넷

항목	올바른 값	잘못된 값
서브넷 타입	`GENERAL`	`PUBLIC`, `PRIVATE`
IGW 타입	`IGW`	`PUBLIC`
서브넷 이름 최대 길이	20자	21자 이상 → 400
VPC당 GENERAL 서브넷 수	최대 3개 (dev 쿼터)	4개 이상 → 400

resource "samsungcloudplatformv2_vpc_subnet" "example" {
  type = "GENERAL"  # PUBLIC/PRIVATE 미지원
}

resource "samsungcloudplatformv2_vpc_internet_gateway" "main" {
  type              = "IGW"
  firewall_enabled  = true
  firewall_loggable = false  # true → 로그 스토리지 미설정 시 400
}

보안 그룹 (Security Group)

# ⚠️ loggable = true → 로그 스토리지 미연결 시 404
resource "samsungcloudplatformv2_security_group_security_group" "main" {
  loggable = false
}

# ⚠️ 프로토콜: ALL 미지원, 소문자만 허용
resource "samsungcloudplatformv2_security_group_security_group_rule" "rule" {
  protocol       = each.value.protocol == "ALL" ? null : lower(each.value.protocol)
  port_range_min = each.value.protocol == "ALL" ? null : each.value.from_port
  port_range_max = each.value.protocol == "ALL" ? null : each.value.to_port
}

레이스 컨디션 방지: 모든 SG 모듈에 depends_on = [module.vpc] 필수

IGW 방화벽

# ⚠️ source/destination_address에 0.0.0.0/0 금지 → 400
# ⚠️ AWS IP 대역(13.x.x.x), link-local(169.254.x.x), UDP OUTBOUND → 400
# ✅ 구체적 공인 IP/CIDR만 허용

resource "samsungcloudplatformv2_firewall_firewall_rule" "igw_ssh" {
  for_each = var.create_firewall ? toset(var.admin_cidr) : toset([])
  firewall_rule_create = {
    direction           = "INBOUND"
    source_address      = [each.value]
    destination_address = [module.bastion.public_ip]  # 공인 IP 명시
    service             = [{ service_type = "TCP", service_value = "22" }]
  }
}

⚠️ 방화벽 사이즈 한도 (exsmall = 최대 5룰)

# 에러 예시 (5룰 초과 시)
Error: Error creating firewall rule
│ statusCode: 400
│ (에러 메시지 없음 — 룰 개수 한도 초과가 원인)

해결책:

SCP 콘솔 → 방화벽 → 사이즈 업그레이드: exsmall → small (최대 50룰) 이상
Terraform Provider에 firewall_size 파라미터 없음 → 콘솔 전용 작업
방화벽 룰 생성 시 레이스 컨디션 방지를 위해 -parallelism=1 권장:

# ✅ 방화벽 룰 생성 시 권장
tofu apply -parallelism=1 -var-file=dev.tfvars

# 또는 방화벽 룰만 타깃 적용
tofu apply -parallelism=1 -target=module.firewall -var-file=dev.tfvars

VM (Virtual Server)

resource "samsungcloudplatformv2_virtualserver_server" "bastion" {
  state          = "ACTIVE"   # ⚠️ 이 필드 누락 시 "Invalid server state. State: " 400
  server_type_id = "s1v4m8"  # 형식: s1v{cpu}m{mem}
  boot_volume = {
    size = 16  # ⚠️ 8GB 배수만 허용. 최솟값 16GB (2 units × 8GB)
    type = "SSD"
    delete_on_termination = true
  }
}

이미지 data source 필터: status, visibility 필터 제거 — SCP 이미지 API와 불일치 多. os_distro + name regex만 사용.

키페어 (Keypair)

# ⚠️ terraform import 미지원 → SCP에 이미 존재하면 409
# 해결: SCP 콘솔에서 키페어 삭제 후 tofu apply
resource "samsungcloudplatformv2_virtualserver_keypair" "keypair" {
  name = "${var.environment}-bastion-keypair"
}

coalesce(var.keypair_name, "default") 패턴 사용 시 기본값은 반드시 null (빈 문자열 아님)
이름 변경(rename) API 미지원 → destroy + create 패턴

SKE (Kubernetes Cluster)

# 지원 버전 확인 필수 — 콘솔 SKE 생성 화면에서 확인
k8s_version = "v1.32.8"  # 예시. 미지원 버전 → 404

node_pools = [{
  os_type = "ubuntu 22.04"  # v1.32.8: ubuntu 24.04 미지원
}]

DBaaS (EPAS / Redis)

variable "maintenance_start_time" {
  default = "0100"  # ⚠️ "0000" (자정) 미지원 → 400
}

variable "backup_frequency_minute" {
  default = 1440  # ⚠️ 60(매시간)이면 retention_period_day 검증 실패
}

Load Balancer

loadbalancer_create = {
  layer_type = "L4"  # ⚠️ 누락 시 "Invalid value for layer type: " 400
}
lb_server_group_create = {
  lb_method = "ROUND_ROBIN"  # ⚠️ "algorithm" 필드명 오류 → lb_method
  vpc_id    = var.vpc_id     # ⚠️ 필수 (누락 → 400)
  subnet_id = var.subnet_id  # ⚠️ 필수 (누락 → 400)
}
lb_listener_create = {
  routing_action = "LB_SERVER_GROUP"  # ⚠️ 누락 시 400
}

⚠️ SCP LB SDK v1.2 Deprecated (2026-03-31 만료)

SCP Load Balancer API v1.2가 deprecated 상태이며, Terraform으로 LB 생성 시 리스너 생성 단계에서 LB가 ACTIVE 상태가 되지 않아 반복 에러가 발생한다.

# 에러 예시 (LB SDK v1.2 deprecated 관련)
Error: Error creating listener
│ Cannot create listener. Associated Load Balancer is not in the ACTIVE state.(ERROR)
│
│ (원인: LB SDK v1.2 deprecated로 인한 내부 상태 전이 실패)

해결책:

enable_user_lb = false (기본값)로 설정해 Terraform LB 리소스 비활성화
SCP 콘솔에서 수동 생성 권장 (또는 SCP 지원팀에 API v2 마이그레이션 문의)
신규 배포 시 LB 모듈 적용 전 SCP 콘솔에서 API 버전 상태 확인

운영 패턴

API Rate Limit (429)

# 병렬 refresh 429 발생 시
tofu apply -parallelism=3 -var-file=dev.tfvars
# 또는
tofu apply -refresh=false -var-file=dev.tfvars  # state 캐시 사용

방화벽 룰 생성 시 직렬 실행 권장

# ✅ 방화벽 룰은 반드시 parallelism=1로 적용 (레이스 컨디션 + 사이즈 한도 초과 방지)
tofu apply -parallelism=1 -var-file=dev.tfvars

스키마 확인

tofu providers schema -json | python3 -c "
import json,sys
s=json.load(sys.stdin)
r=s['provider_schemas']['registry.terraform.io/samsungsdscloud/samsungcloudplatformv2']['resource_schemas']
print(json.dumps(r['samsungcloudplatformv2_<resource_name>']['block'], indent=2))
" 2>/dev/null

S3 백엔드 (Object Storage)

terraform {
  backend "s3" {
    endpoints = { s3 = "https://..." }  # deprecated: endpoint (단수)
    skip_credentials_validation = true
    encrypt                     = true
    sse_algorithm               = "AES256"
  }
}

버전 정보

Provider: samsungcloudplatformv2 v3.1.7
IaC 도구: OpenTofu 1.8.x (tofu 명령)
허용 리전: kr-west1, kr-east1