CB-Tumblebug version upgrade guide (v0.12.25 → v0.13.2) (Korean)

[seokho-son]

CB-Tumblebug 업그레이드 가이드: v0.12.25 → v0.13.2

CB-Tumblebug v0.12.25를 사용 중인 모듈이 v0.13.2로 올릴 때 필요한 변경 사항.

• 대상: CB-Tumblebug REST API를 호출하는 상위 모듈
• 기준: v0.12.25 태그 ↔ v0.13.2 태그의 코드·Swagger 비교 결과

영향도 요약

#	변경	영향	해당 여부
§1	기본 보안그룹이 SSH(22)만 개방	노드 생성 직후 서비스 포트가 막혀 있음	infraDynamic 사용 시 대부분 해당
§2-1	postCommand → postCommands (필드 제거)	부트스트랩 명령 요청/응답 파싱 실패	Infra 생성 시 부트스트랩 명령을 쓰면 해당
§2-2	nodeUserPassword 필드 제거	해당 필드 전송 시 요청 거부 가능	이 필드를 보내던 경우만
§3	일부 API 제거 (objectStorage 레거시 경로, sqlDb, K8s 컨테이너 명령)	호출 시 404	해당 API를 쓰던 경우만
§4	동작 변경 (삭제 fail-closed 등)	코드 수정 없이 동작하나 가정이 달라짐	참고

기본 기능(Infra 생성·조회·원격 명령·삭제)만 쓰는 프로젝트라면 §1과 §2-1이 사실상 전부임.

---

1. 사용 방식이 바뀌는 변경 — 기본 보안그룹이 SSH만 개방함

가장 많은 모듈이 영향을 받는 변경.

Infra 동적 생성(POST /ns/{nsId}/infraDynamic)에서 sgTemplateId를 지정하지 않으면 자동 생성되는 공유 보안그룹의 기본 정책이 바뀜.

	v0.12.25	v0.13.2
기본 규칙	TCP 1-65535 전체 개방 UDP 1-65535 전체 개방 ICMP 전체 개방	TCP 22 (SSH)만 개방

즉 노드 생성 직후에는 SSH 접속만 가능하고, 웹 서버·애플리케이션 포트·노드 간 통신 포트는 막혀 있음. 기존에 "인프라만 만들면 서비스 포트가 열려 있다"고 가정하던 자동화는 이 버전부터 동작하지 않음. API 호출 자체는 성공하므로 오류가 나지 않고, 서비스 접속이 안 되는 형태로 나타남에 유의.

대응 방법 (셋 중 하나 선택)

방법 A — 생성 후 필요한 포트만 추가 (권장)

# Infra 생성 시 자동 생성된 보안그룹 ID 확인
curl -u default:default \
  "http://<tb>/tumblebug/ns/default/infra/<infraId>?option=accessinfo"

# 필요한 포트 추가
curl -u default:default -X POST \
  "http://<tb>/tumblebug/ns/default/resources/securityGroup/<sgId>/rules" \
  -H 'Content-Type: application/json' \
  -d '{
        "firewallRules": [
          {"ports": "80",   "protocol": "TCP", "direction": "inbound", "cidr": "0.0.0.0/0"},
          {"ports": "443",  "protocol": "TCP", "direction": "inbound", "cidr": "0.0.0.0/0"}
        ]
      }'

규칙 삭제는 같은 경로에 DELETE 사용. 최소 권한 원칙에 맞고 서비스별로 필요한 포트만 열 수 있어 권장함.

방법 B — 생성 시 다른 보안그룹 템플릿 지정

infraDynamic 요청에 sgTemplateId를 지정하면 해당 템플릿으로 보안그룹이 만들어짐. NodeGroup 단위로도 지정 가능.

{
  "name": "infra01",
  "sgTemplateId": "sg-usecase-web",     // Infra 전체에 적용
  "nodeGroups": [
    { "name": "g1", "specId": "...", "imageId": "...",
      "sgTemplateId": "sg-openall" }    // 이 NodeGroup만 별도 적용(선택)
  ]
}

기본 제공 템플릿 (실제 규칙 기준):

템플릿 ID	인바운드 규칙	용도
sg-default	TCP 22	기본값. 관리 접속만
sg-ssh	TCP 22, ICMP + VNet 내부 전체 TCP/UDP	SSH 접속 + 노드 간 통신이 필요한 경우
sg-usecase-web	TCP 22, 80, 443, 8080, 8443, ICMP	웹/애플리케이션 서버
sg-aws-web	TCP 22, 80, 443	AWS 웹 구성
sg-k8s	TCP/UDP 전체, ICMP	쿠버네티스 노드 그룹
sg-openall	TCP/UDP 전체, ICMP	v0.12.25의 기존 기본값과 동일. 개발·테스트용

템플릿 목록 조회: GET /ns/system/template/securityGroup

기존 동작을 최소 수정으로 유지하려면 sgTemplateId: "sg-openall" 한 줄만 추가하면 됨. 다만 전 포트 개방이므로 개발·테스트 환경에 한정해 사용할 것을 권함.

노드 간 통신이 필요하면 sg-ssh를 참고할 것. 규칙의 cidr에 "internal" 키워드를 쓰면 프로비저닝 시점에 해당 VNet의 CIDR로 치환되어, 외부에 포트를 열지 않고 노드 간 통신만 허용할 수 있음. 직접 규칙을 추가할 때도 같은 키워드 사용 가능.

{"ports": "1-65535", "protocol": "TCP", "direction": "inbound", "cidr": "internal"}

단, 서로 다른 CSP에 걸친 노드가 공인 IP로 통신하는 경우는 이 규칙으로 커버되지 않음.

방법 C — 기본 템플릿 자체를 조직 정책에 맞게 변경

기본 정책은 코드가 아니라 템플릿(init/templates/sg-default.json)에 있음. 운영 정책에 맞춰 이 템플릿을 수정한 뒤 초기화하면, 서버 재빌드 없이 기본값을 바꿀 수 있음.

---

2. 기존 API의 요청/응답이 깨지는 변경

2-1. postCommand 제거 → postCommands로 대체

Infra 생성 시 부트스트랩 명령을 지정하는 필드가 다단계(phase) 구조로 바뀜. 구 필드는 제거되어, 무시되는 것이 아니라 요청 자체가 거부될 수 있음.

영향 대상: model.InfraDynamicReq, model.InfraReq, model.InfraInfo(응답)

구분	v0.12.25	v0.13.2
요청	postCommand	postCommands (배열), postCommandAsync
응답	postCommandResult	postCommandResults, postCommandStatus, postCommandRequestId

// v0.12.25
{ "postCommand": { "command": ["apt-get update"], "userName": "cb-user" } }

// v0.13.2 — 단일 명령도 한 개짜리 phase로 표현
{ "postCommands": [ { "command": ["apt-get update"] } ] }

// 여러 단계를 순서대로 실행하고, 대상도 지정 가능
{
  "postCommands": [
    { "command": ["curl -fsSL https://.../control-plane.sh | bash"], "nodeGroupId": "master" },
    { "command": ["curl -fsSL https://.../worker.sh | bash"], "nodeGroupId": "worker",
      "continueOnError": true, "timeoutMinutes": 30 }
  ],
  "postCommandAsync": true
}

postCommands[]의 필드: command(필수), userName, nodeGroupId / nodeId / labelSelector(대상 지정, 셋 중 하나), continueOnError, timeoutMinutes.

비동기 실행: postCommandAsync: true로 두면 노드 프로비저닝 완료 시점에 응답이 반환되고 명령은 백그라운드로 실행됨. 진행 상황은 아래로 확인.

GET /ns/{nsId}/stream/cmd/infra/{infraId}?xRequestId={postCommandRequestId}   # SSE 스트리밍
GET /ns/{nsId}/infra/{infraId}                                               # postCommandStatus 폴링

postCommandStatus 값: None / Running / Completed / CompletedWithErrors / Failed / Skipped

2-2. nodeUserPassword 제거

model.CreateNodeGroupDynamicReq에서 nodeUserPassword 필드가 제거됨. Linux 노드는 SSH 키로 접속하며, CSP가 요구하는 경우(Windows) 서버가 내부적으로 임의 비밀번호를 생성함. 이 필드를 보내던 코드는 제거해야 함.

---

3. 제거된 API (사용 중인 경우만 해당)

기본 Infra 기능만 쓰는 프로젝트에는 해당 없음. 아래 API를 호출하던 경우에만 조치 필요.

3-1. 레거시 objectStorage 경로 (네임스페이스 없는 경로)

/resources/objectStorage/... 형태의 비-네임스페이스 경로 11개가 제거됨. 동일 기능의 네임스페이스 경로는 v0.12.25에도 이미 있었으므로 경로만 바꾸면 됨.

제거: GET|POST|PUT|DELETE /resources/objectStorage/{objectStorageName}...
대체: GET|POST|PUT|DELETE /ns/{nsId}/resources/objectStorage/{osId}...

3-2. sqlDb API → 신규 rdbms API로 대체

관리형 DB를 다루던 sqlDb 경로 4개가 제거되고, 네이티브 RDBMS 관리 API로 대체됨. 경로만 바뀐 것이 아니라 요청/응답 스키마가 완전히 다른 신규 API이므로, sqlDb를 쓰던 코드는 재작성이 필요함 (신규 API 개요는 §5 참고).

제거: GET|POST   /ns/{nsId}/resources/sqlDb
      GET|DELETE /ns/{nsId}/resources/sqlDb/{sqlDbId}
대체: GET|POST   /ns/{nsId}/resources/rdbms
      GET|DELETE /ns/{nsId}/resources/rdbms/{rdbmsId}

3-3. K8s 컨테이너 원격 명령·파일 전송 API

K8sCluster 컨테이너 대상 API 2개가 제거됨. 노드(VM) 대상 원격 명령(POST /ns/{nsId}/cmd/infra/{infraId})과 파일 전송은 그대로 유지됨.

제거: POST /ns/{nsId}/cmd/k8sCluster/{k8sClusterId}
      POST /ns/{nsId}/transferFile/k8sCluster/{k8sClusterId}

K8s 워크로드 제어가 필요하면 kubeconfig(GET /ns/{nsId}/k8sCluster/{k8sClusterId} 응답의 접속 정보)로 kubectl/클라이언트 라이브러리를 직접 사용할 것.

---

4. 코드 수정 없이도 알아둘 동작 변경

4-1. 자원 삭제가 fail-closed로 바뀜 (tombstone)

이전에는 CSP 측 삭제가 실패해도 CB-Tumblebug 기록이 지워져 고아 자원이 남을 수 있었음. 이제 삭제 요청 시 기록에 deletionRequestedAt(tombstone)이 찍히고, CSP 측 제거가 확인될 때까지 기록이 유지됨. vNet/subnet 등은 해제 중 Deleting 상태로 표시됨.

• 삭제 API 호출 후 목록에 자원이 잠시 남아 있어도 오류가 아님 — 상태/deletionRequestedAt으로 진행 여부 확인
• 삭제 직후 목록이 비어 있다고 가정하는 로직이 있다면 조정 필요
• 삭제가 막힌 자원은 재시도 또는 reconcile API(§5)로 정리

4-2. DataDisk에 zone 지정 지원

디스크는 노드와 같은 존에 있어야 연결 가능(확인 결과 지원 CSP 8곳 모두 교차 존 연결을 거부함).

• DataDiskReq에 zone 필드 추가 (미지정 시 커넥션의 기본 존)
• 노드 지정 생성(POST /ns/{nsId}/infra/{infraId}/node/{nodeId}/dataDisk)은 존을 지정하지 않으면 해당 노드의 존을 자동 상속함 — 별도 조치 불필요
• 교차 존 연결 시도는 CSP 오류 대신 명확한 메시지로 사전 거부됨

4-3. 자격증명 검증 실패 사유 노출

POST /tumblebug/credential 응답의 각 연결에 verifiedMessage 필드가 추가됨. 기존에는 verified: false만 보여 원인 파악이 불가능했음. 시크릿 만료·권한 부족·네트워크 오류가 구분되므로, 초기화 스크립트에서 이 값을 로그에 남기면 진단이 쉬워짐.

{ "configName": "azure-koreacentral", "verified": false,
  "verifiedMessage": "The client secret has expired. Issue a new secret in the Azure portal and register the credential again. (CSP error: AADSTS7000222)" }

4-4. NodeGroup 스케일아웃 안정화

POST /ns/{nsId}/infra/{infraId}/nodegroup/{nodegroupId} (노드 추가) 관련 수정.

• 기존 노드의 이름을 재사용해 레코드를 덮어쓰고 CSP 자원을 고아로 만들던 문제 수정
• numNodesToAdd 검증 추가, 노드가 없는 NodeGroup 요청 시 명확한 오류 반환(기존에는 서버 패닉)

4-5. 기타

• support API 쿼리 파라미터 cspType → providerName 정리 (기존 cspType도 계속 동작, 신규 코드만 providerName 권장)
• Infra 상태 조회·종료·삭제가 7,000 노드 이상에서도 메모리 문제 없이 동작하도록 대규모 안정화
• 원격 명령 로그 보존 시간 연장, SSE 스트리밍 안정화, 배스천 노드 교체 메커니즘 개선

---

5. (참고) 신규 API — 필요할 때 살펴볼 것

업그레이드 자체에는 조치가 필요 없으나, 활용하면 좋은 신규 기능 요약.

• 프로비저닝 실패 모델링 + 재시도: 실패한 노드의 NodeInfo에 failure 필드(실패 분류, retryable, CSP 오류 코드, 대안 존 제안)가 기록되고, POST /ns/{nsId}/infra/{infraId}/retryFailedNodes로 실패 노드를 원래 구성 그대로 재생성 가능 (재고 부족 등 일시 실패에 유용). 요청 자체가 문제인 경우는 PUT .../nodeGroupDynamic/{nodeGroupId}로 NodeGroup을 수정된 요청으로 교체.
• 네임스페이스 전체 조회: GET /ns/{nsId}/resources/node, GET /ns/{nsId}/resources/nlb — Infra마다 순회하던 N+1 호출 제거.
• RDBMS 관리: GET /rdbms/capability로 유효 스펙 조회 후 POST /ns/{nsId}/resources/rdbms로 관리형 DB 생성 (sqlDb의 대체, §3-2).
• CSP 실측 감사: POST /ns/{nsId}/infra/{infraId}/audit — CSP SDK 직접 조회로 기록과 실제 상태를 대조하고 고아 VM 정리(remediate=true) 가능.
• 자원 정합성 관리: vNet/objectStorage/rdbms 대상 reconcile / reconcile/prune API.
• 디스크 지원 정보: GET /disk/support, GET /ns/{nsId}/resources/spec/{specId}/diskOptions — CSP·스펙별 디스크 타입/크기 제약 조회.
• 헬스 체크: GET /livez (프로세스 생존, K8s livenessProbe 용도. 기존 /readyz는 초기화 완료 여부).
• 서브넷 분산 배치: NodeGroup 요청에 distributeSubnets: true로 여러 가용영역 분산 배치.

---