Samsung Cloud Platform (SCP) 기반의 엔터프라이즈급 GitOps 인프라 자동화 플랫폼
Samsung Cloud Platform(SCP) 위에서 Kubernetes 인프라 전체를 코드(IaC)로 선언하고, Git을 단일 진실의 원천으로 삼아 dev·staging·prod 환경을 자동으로 프로비저닝·배포·거버넌스합니다. 운영 리소스 100%를 Terraform/GitOps로 관리하여 수동 변경 없이 감사 가능한 인프라를 실현합니다.
핵심 기술 스택:
OpenTofu 1.8.8 · Argo CD · SCP Provider v3.1.7 · OpenBao · OPA/Kyverno
Production-Ready 체크리스트:
| 항목 | 상태 |
|---|---|
| SCP 전 환경(dev/staging/prod) IaC 완성 | ✅ |
| GitOps 자동 동기화 (dev/staging) + 수동 승인 (prod) | ✅ |
| 보안 정책 자동화 (OPA + Kyverno + Conftest) | ✅ |
| 시크릿 중앙 관리 (OpenBao HA Raft) | ✅ |
| IaC Drift 자동 감지 (매일 09:00 KST) | ✅ |
| 멀티 AZ 고가용성 (staging/prod) | ✅ |
| eBPF 런타임 보안 모니터링 (Tetragon) | 🔄 |
| Tekton 기반 자체 호스팅 CI/CD | 🔄 |
핵심 문서 바로가기
| 질문 | 답 |
|---|---|
| 이 프로젝트가 뭔가요? | Samsung Cloud Platform(SCP) 위에 Kubernetes 인프라를 코드로 자동 관리하는 플랫폼입니다 |
| GitOps가 뭔가요? | Git을 "진실의 원천"으로 삼아, Git에 변경을 push하면 인프라/앱이 자동으로 동기화되는 방식입니다 |
| IaC(OpenTofu)가 뭔가요? | 서버·네트워크·DB 등 인프라를 코드 파일(.tf)로 선언하면 자동으로 생성/변경/삭제해주는 도구입니다 |
| 어디서 시작할까요? | 👉 빠른 시작 가이드 → 상세 프로비저닝 가이드 |
- 🚀 처음 오셨나요?
- 문서 네비게이션
- 프로젝트 개요
- 아키텍처
- 디렉토리 구조
- 사전 요구사항
- 빠른 시작 가이드
- 4개 레이어 저장소 전략
- 환경별 설정
- 정책 및 거버넌스
- CI/CD 파이프라인
- 관련 문서
- 라이선스
상황별로 어떤 문서를 먼저 읽어야 할지 안내합니다.
| 상황 | 시작 문서 | 다음 문서 | 참고 문서 |
|---|---|---|---|
| 처음 인프라를 구축하는 경우 | PROVISIONING.md | ARCHITECTURE.md | node-pool-design.md |
| 운영 중 장애·문제가 발생한 경우 | operator-guide.md | runbooks/ | provisioning-issues.md |
| 보안 감사를 준비하는 경우 | SECURITY.md | security-requirements/ | NETWORK.md |
| 정책·거버넌스를 변경하는 경우 | CONTRIBUTING.md | policies/ | ARCHITECTURE.md#5 |
| 아키텍처를 이해하고 싶은 경우 | docs/architecture/ | ARCHITECTURE.md | NETWORK.md |
| 브랜치·릴리스 절차를 확인하는 경우 | BRANCHING.md | CONTRIBUTING.md | — |
docs/
├── PROVISIONING.md # 환경 구축 단계별 가이드 (첫 구축 시 시작점)
├── ARCHITECTURE.md # IaC·GitOps·정책 아키텍처 상세
├── NETWORK.md # 서브넷·방화벽·Squid 프록시 설계
├── SECURITY.md # 보안 정책·자격증명·인시던트 대응
├── BRANCHING.md # 브랜치 전략·릴리스 절차
├── CONTRIBUTING.md # 기여 가이드·코딩 컨벤션
├── ROADMAP.md # Phase별 구축 로드맵
├── operator-guide.md # Day-0~Day-2 운영 절차
├── node-pool-design.md # SKE 노드 풀 설계
├── provisioning-issues.md # SCP API 오류 해결 사례 (P-01~P-48)
├── architecture/ # 아키텍처 다이어그램·심화 문서
│ ├── overview.md
│ ├── network-topology.md
│ ├── gitops-flow.md
│ └── security-architecture.md
├── runbooks/ # 장애 대응 런북
│ ├── argocd-disaster-recovery.md
│ ├── cluster-recovery.md
│ ├── database-failover.md
│ ├── vault-unseal.md
│ └── certificate-rotation.md
└── security-requirements/ # 보안 요구사항·규정 준수
├── access-control/
├── audit/
├── compliance/ # CSAP, ISO27001, PIPA, SOC2
├── incident-response/
├── supply-chain/
└── threat-models/
SCP GitOps Infrastructure는 Samsung Cloud Platform 위에서 운영되는 Kubernetes 환경을 완전히 코드로 관리하는 플랫폼입니다. Infrastructure-as-Code(OpenTofu)와 GitOps(Argo CD)를 결합하여 인프라의 선언적 관리, 자동화된 배포, 정책 기반 거버넌스를 실현합니다.
| 기능 | 도구 | 설명 |
|---|---|---|
| IaC 엔진 | OpenTofu + samsungcloudplatformv2 v3.1.7 | 인프라 프로비저닝 및 라이프사이클 관리 |
| GitOps 엔진 | Argo CD | Kubernetes 앱 지속적 배포 |
| 정책 거버넌스 | OPA + Kyverno + Conftest | 이중 레이어 정책 적용 |
| 상태 관리 | SCP Object Storage (S3 호환) | 암호화된 원격 상태 파일 (sse_algorithm = "AES256") |
| 보안 스캔 | Checkov + tfsec | IaC 보안 및 규정 준수 |
| 시크릿 관리 | OpenBao (Vault 호환) + External Secrets | K8s 시크릿 자동 동기화 |
| 관측성 | SigNoz (ClickHouse 기반) | 메트릭, 트레이스, 로그 통합 |
| AIOps | 드리프트 감지 + 자동 PR | AI 기반 자율 운영 |
각 환경(dev / staging / prod)은 독립된 SCP 인프라, GitLab 저장소, Argo CD 인스턴스를 가집니다. 이 GitHub 저장소는 템플릿으로서 각 환경 GitLab 저장소 구성의 기준이 되며, Argo CD는 GitLab을 GitOps 소스로 사용합니다.
graph TD
GH["🗂️ GitHub Template Repo<br/>(이 저장소 — 템플릿/기준)"]
GH -->|"템플릿 기반 구성"| GL_DEV["GitLab DEV Repo"]
GH -->|"템플릿 기반 구성"| GL_STG["GitLab STAGING Repo"]
GH -->|"템플릿 기반 구성"| GL_PRD["GitLab PROD Repo"]
subgraph DEV_ENV["DEV 독립 인프라 (kr-west1)"]
GL_DEV -->|"GitOps · Auto-Sync"| ARGO_DEV["Argo CD"]
ARGO_DEV --> SKE_DEV["SKE DEV 클러스터 v1.32.8<br/>system/app/signoz 풀"]
SCP_DEV["SCP 리소스 (VPC / IAM / Storage)"]
end
subgraph STG_ENV["STAGING 독립 인프라 (kr-west1)"]
GL_STG -->|"GitOps · Auto-Sync"| ARGO_STG["Argo CD"]
ARGO_STG --> SKE_STG["SKE STAGING 클러스터 v1.32.8<br/>system/app/signoz/ai 풀"]
SCP_STG["SCP 리소스 (VPC / IAM / Storage)"]
end
subgraph PRD_ENV["PROD 독립 인프라 (kr-west1)"]
GL_PRD -->|"GitOps · 수동 승인"| ARGO_PRD["Argo CD"]
ARGO_PRD --> SKE_PRD["SKE PROD 클러스터 v1.32.8<br/>system/app/signoz/ai/batch 풀"]
SCP_PRD["SCP 리소스 (VPC / IAM / Storage)"]
end
scp-gitops-gemini/
├── .github/
│ └── workflows/
│ ├── terraform-validate.yaml # OpenTofu 검증 워크플로우
│ ├── policy-check.yaml # 정책 검증 워크플로우
│ └── gitops-sync.yaml # GitOps 동기화 워크플로우
│
├── modules/ # 재사용 가능한 OpenTofu 모듈
│ ├── environment/ # 환경 종합 모듈 (모든 리소스 조합)
│ ├── ske-cluster/ # SCP SKE 클러스터 모듈
│ ├── vpc/ # SCP VPC/서브넷/IGW 모듈
│ ├── database/ # SCP DBaaS (EPAS, Redis) 모듈
│ ├── security/ # SCP 보안 그룹/방화벽 모듈
│ ├── bastion/ # Bastion 호스트 모듈 (DB용/K8s용)
│ ├── keypair/ # SCP 키페어 관리 모듈
│ ├── squid-proxy/ # Squid 포워드 프록시 모듈
│ ├── load-balancer/ # SCP 로드밸런서 모듈
│ ├── object-storage/ # SCP Object Storage 모듈
│ └── iam/ # SCP IAM 역할/정책 모듈
│
├── environments/ # 환경별 OpenTofu 설정 (flat 구조)
│ ├── main.tf # 루트 모듈 진입점
│ ├── variables.tf # 변수 정의
│ ├── providers.tf # samsungcloudplatformv2 provider + 버전 제약 (OpenTofu >= 1.11.5)
│ ├── data.tf # data source 정의
│ ├── dev.tfvars # 개발 환경 변수
│ ├── staging.tfvars # 스테이징 환경 변수
│ └── prod.tfvars # 프로덕션 환경 변수
│
├── gitops-control-plane/ # GitOps 컨트롤 플레인
│ ├── argocd/ # Argo CD 설정
│ │ ├── apps/ # App-of-Apps 정의
│ │ └── projects/ # Argo CD 프로젝트
│ └── applicationsets/ # ApplicationSet 정의
│
├── cluster-services/ # 클러스터 공통 서비스
│ ├── argocd/ # Argo CD Helm 설치
│ ├── openbao/ # OpenBao (Vault 호환) 시크릿 관리
│ ├── secrets/ # External Secrets Operator
│ ├── service-mesh/ # Istio Ambient Mesh
│ ├── monitoring/ # SigNoz (ClickHouse 기반 관측성)
│ ├── cert-manager/ # 인증서 자동화
│ ├── network-policies/ # K8s 네트워크 정책
│ ├── rbac/ # 역할 기반 접근 제어
│ └── registry-mirror/ # SCP CR containerd 미러
│
├── policies/ # Policy-as-Code
│ ├── opa/ # OPA Rego 정책 + 단위 테스트
│ │ └── *_test.rego # 31개 OPA 단위 테스트
│ ├── kyverno/ # Kyverno ClusterPolicy (10개)
│ └── conftest/ # Conftest Terraform 플랜 정책
│
├── app-manifests/ # 애플리케이션 매니페스트 템플릿
│ ├── base/ # 기본 매니페스트
│ └── overlays/ # 환경별 오버레이
│ ├── dev/
│ ├── staging/
│ └── prod/
│
├── docs/ # 문서
│ ├── ARCHITECTURE.md # 아키텍처 상세 (provider, 노드풀, 제약사항)
│ ├── PROVISIONING.md # 프로비저닝 단계별 가이드
│ ├── operator-guide.md # 운영자 가이드 (Day-0~Day-2)
│ ├── node-pool-design.md # SKE 노드 풀 설계 (워크로드 기반)
│ ├── provisioning-issues.md # 프로비저닝 이슈 트래커 (P-01~P-46)
│ ├── NETWORK.md # 네트워크 보안 설계
│ ├── SECURITY.md # 보안 가이드
│ ├── ROADMAP.md # 도입 로드맵
│ └── CONTRIBUTING.md # 기여 가이드
│
├── .claude/
│ └── skills/
│ └── scp-terraform-provider-iac/ # SCP Provider v2 IaC 패턴 (팀 공유 스킬)
│ └── SKILL.md
│
├── .gitignore
├── Makefile # 공통 작업 자동화 (TF ?= tofu)
└── README.md # 이 파일
| 도구 | 최소 버전 | macOS | Windows | Linux |
|---|---|---|---|---|
| OpenTofu | >= 1.11.5 | brew install opentofu |
winget install OpenTofu.OpenTofu |
snap install opentofu --classic |
| kubectl | >= 1.32 | brew install kubectl |
winget install Kubernetes.kubectl |
snap install kubectl --classic |
| Argo CD CLI | >= 2.14 | brew install argocd |
GitHub Releases | GitHub Releases |
| Helm | >= 3.16 | brew install helm |
winget install Helm.Helm |
snap install helm --classic |
| OPA | >= 0.66 | brew install opa |
winget install OpenPolicyAgent.OPA |
GitHub Releases |
| Conftest | >= 0.58 | brew install conftest |
winget install Conftest.Conftest |
GitHub Releases |
| tflint | >= 0.55 | brew install tflint |
winget install TFLint.TFLint |
GitHub Releases |
| checkov | >= 3.2 | pip install checkov |
pip install checkov |
pip install checkov |
-
SCP 콘솔에서 API 자격 증명 발급
-
~/.scpconf파일 생성:
[default]
auth_method = iam
access_key = YOUR_ACCESS_KEY
secret_key = YOUR_SECRET_KEY
project_id = YOUR_PROJECT_ID
region = kr-west1- 환경 변수 설정 (선택):
export AWS_ACCESS_KEY_ID="YOUR_ACCESS_KEY" # OpenTofu S3 백엔드용
export AWS_SECRET_ACCESS_KEY="YOUR_SECRET_KEY"
⚠️ 주의:~/.scpconf에account_id설정 금지 — HMAC 서명 방식으로 전환되어 모든 API 401 반환.
git clone https://github.com/your-org/scp-gitops-gemini.git
cd scp-gitops-geminimake check-tools# environments/dev.tfvars를 복사하여 실제 값 입력
cp environments/dev.tfvars environments/dev.tfvars.local
vi environments/dev.tfvars # account_id, admin_cidr 등 수정
# OpenTofu 초기화
make init ENV=devmake plan ENV=devmake fmt # 코드 포맷
make validate # 유효성 검사
make security-scan # 보안 스캔
make policy-test # OPA/Conftest 정책 테스트# ⚠️ 방화벽 룰이 포함된 경우 parallelism=1 권장 (exsmall 5룰 제한)
make apply ENV=dev# Helm 차트 SCP CR OCI에 업로드 (최초 1회)
./scripts/bootstrap-helm-charts.sh
# Argo CD 로그인 및 App-of-Apps 동기화
make argocd-login
argocd app sync app-of-apps본 프로젝트는 관심사 분리 원칙에 따라 4개의 논리적 레이어로 구성됩니다:
graph LR
subgraph L1["레이어 1: 인프라 기반"]
TF["modules/ + environments/<br/>SCP 클라우드 리소스<br/>변경: plan → 리뷰 → apply"]
end
subgraph L2["레이어 2: GitOps 컨트롤 플레인"]
GCP["gitops-control-plane/<br/>cluster-services/<br/>변경: PR → Argo CD 자동 동기화"]
end
subgraph L3["레이어 3: 정책 거버넌스"]
POL["policies/<br/>OPA Rego + Kyverno + Conftest<br/>변경: 정책 테스트 → PR → 배포"]
end
subgraph L4["레이어 4: 애플리케이션"]
APP["app-manifests/<br/>Kustomize 오버레이<br/>변경: PR → Argo CD 자동 동기화"]
end
L1 --> L2 --> L3 --> L4
4계층 서브넷 + Zero 0.0.0.0/0 원칙으로 설계됩니다:
- Public: Bastion, Squid VM (관리자 접근만 허용)
- Private K8s: SKE 워커 노드 (외부 직접 접근 불가)
- Private DB: EPAS, Redis (Bastion 통해서만 접근)
모든 아웃바운드 트래픽은 Squid 프록시(포트 43128)를 경유하며, 도메인 화이트리스트로 필터링됩니다.
상세 설계: docs/NETWORK.md
| 환경 | 풀 구성 | 기본 스펙 | 오토스케일 |
|---|---|---|---|
| dev | system / app / signoz (3풀) | s1v4m8 (4vC/8GB) | app: 1~3 |
| staging | system / app / signoz / ai (4풀) | s1v8m16 (8vC/16GB) | app: 2 |
| prod | system / app / signoz / ai / batch (5풀) | s1v8m16 / s1v16m32 | app: 3 |
상세 설계: docs/node-pool-design.md
| 항목 | dev | staging | prod |
|---|---|---|---|
| 리전 | kr-west1 | kr-west1 | kr-west1 |
| AZ | 단일 (kr-west1a) | 멀티 | 멀티 |
| HA | ❌ | ✅ | ✅ |
| Argo CD 동기화 | 자동 | 자동 | 수동 승인 |
| prevent_destroy | ❌ | ❌ | ✅ |
| LB 관리 | 콘솔 수동 | 콘솔 수동 | 콘솔 수동 |
⚠️ LB 주의: SCP LB SDK v1.2 deprecated (2026-03-31 만료) — Terraform으로 LB 생성 시 ERROR 상태 반복.enable_user_lb = false(기본값) 유지 후 SCP 콘솔에서 수동 생성.
- 리전 제한 (
kr-west1,kr-east1만 허용) - 태그 필수 규정 (
environment,team,managed-by) - 보안 규칙 (암호화, 퍼블릭 스토리지 금지)
- 컨테이너 보안 컨텍스트 강제 (
runAsNonRoot,readOnlyRootFilesystem) - 리소스 limit/request 필수
- 승인된 레지스트리만 허용 (
registry.example.com, SCP CR) - 특권 컨테이너 금지
flowchart TD
PR["📝 PR 생성"] --> TF["terraform-validate<br/>fmt → validate → tflint → checkov"]
PR --> PC["policy-check<br/>opa-test → kyverno-validate → conftest"]
TF --> GATE{모든 검사 통과?}
PC --> GATE
GATE -->|"Yes"| REV["👥 PR 리뷰 & Merge"]
GATE -->|"No"| FIX["🔧 코드 수정"]
FIX --> PR
REV --> SYNC["gitops-sync<br/>Argo CD 동기화"]
SYNC --> DONE(["✅ 배포 완료"])
| 문서 | 목적 | 주 대상 독자 |
|---|---|---|
| PROVISIONING.md | 환경 구축 단계별 절차 (dev → staging → prod) | 인프라 엔지니어, 초기 구축 담당자 |
| ARCHITECTURE.md | IaC·GitOps·정책 아키텍처 상세, SCP Provider 제약사항 | 전체 팀, 아키텍트 |
| NETWORK.md | 서브넷·방화벽·Squid 프록시 설계 및 보안 그룹 규칙 | 네트워크 엔지니어, 보안 담당자 |
| SECURITY.md | 자격증명 관리, 보안 정책, 인시던트 대응 절차 | 보안 담당자, 감사자 |
| BRANCHING.md | Git 브랜치 전략, 태그 기반 릴리스 절차 | 개발자, DevOps 엔지니어 |
| CONTRIBUTING.md | 코딩 컨벤션, PR 가이드, 기여 방법 | 기여자, 신규 팀원 |
| 문서 | 목적 | 주 대상 독자 |
|---|---|---|
| operator-guide.md | Day-0~Day-2 운영 절차, 일상 운영 명령어 | SRE, 운영 담당자 |
| node-pool-design.md | 워크로드 기반 SKE 노드풀 설계 원칙 | 인프라 엔지니어, 아키텍트 |
| provisioning-issues.md | SCP API 오류 해결 사례 모음 (P-01~P-48) | 인프라 엔지니어 (트러블슈팅 시) |
| ROADMAP.md | Phase별 구축 계획 및 진행 현황 | 프로젝트 관리자, 전체 팀 |
| 문서 | 목적 | 주 대상 독자 |
|---|---|---|
| docs/architecture/ | 아키텍처 다이어그램·GitOps 플로우·네트워크 토폴로지 | 아키텍트, 신규 팀원 |
| docs/runbooks/ | Argo CD 복구·클러스터 장애·DB 페일오버·Vault 언실 | SRE, 운영 담당자 |
| docs/security-requirements/ | CSAP·ISO27001·PIPA·SOC2 규정 준수, 위협 모델 | 보안 담당자, 감사자 |
이 프로젝트는 Apache License 2.0 하에 배포됩니다.
참고: 이 프로젝트는 Samsung Cloud Platform(SCP) 전용으로 설계되었습니다. 허용 리전:
kr-west1,kr-east1(SCP v2 제공 리전). AWS, GCP, Azure 등 다른 클라우드 플랫폼과의 호환성은 보장되지 않습니다.