Getting Started

이 문서는 이 저장소가 채택한 공통 템플릿 구조와 새 catalog 항목 생성 규칙을 설명합니다. Project GitOps의 실제 입문 순서와 운영 gate는 intern-guide.md와 runbook을 우선합니다.

예제를 먼저 확인하기

실제 파일을 만들기 전에 두 예제를 설계 참고 자료로 사용합니다.

examples/minimal에서 단일 환경의 canonical 폴더와 조립 방식을 확인합니다.
다음 명령으로 platform과 app이 cluster root에서 합쳐지는 결과를 확인합니다.
```
kubectl kustomize examples/minimal/gitops/clusters/dev/main
```
다중 계정·리전·클러스터가 필요하면 examples/scaled/README.md에서 경로와 state 분리 기준을 선택합니다.
실제 파일은 examples에서 복사하지 않고 각 책임 폴더의 _template에서 생성합니다.

examples ──▶ 구조 선택 ──▶ _template 복사 ──▶ live/clusters 구현

1. 프로젝트 선택 기록

구현을 추가하기 전에 다음 항목을 결정하고 docs/decisions에 ADR을 작성합니다.

cloud/on-prem provider와 account/project 구조
Terraform, OpenTofu, Pulumi 등 IaC 엔진
Kustomize 중심 또는 Helm 사용 범위
Flux 또는 Argo CD 등 GitOps 컨트롤러
External Secrets 또는 SOPS 등 비밀 관리 방식
admission policy와 observability 운영 범위

선택하지 않은 도구의 빈 폴더를 모두 만들 필요는 없습니다.

Terraform/OpenTofu를 선택했다면 IaC 파일을 추가하기 전에 다음 선택 파일을 만들고 한 값만 활성화합니다.

cp infrastructure/.iac-engine.example infrastructure/.iac-engine

.iac-engine에는 주석을 제외하고 tofu 또는 terraform 한 줄만 남깁니다. 선택한 도구와 version을 CI에도 설치·고정하고 project-specific init -backend=false/validate 검사를 추가합니다.

2. 프로젝트 메타데이터 설정

README.md의 제목과 프로젝트 범위를 바꿉니다.
.github/CODEOWNERS.example을 실제 소유자로 수정한 뒤 CODEOWNERS로 이름을 바꿉니다.
SECURITY.md에 조직의 보안 연락처와 SLA를 추가합니다.
선택한 도구 버전을 프로젝트의 버전 관리 방식으로 고정합니다.
branch protection과 required check를 설정합니다.

3. Foundation bootstrap

bootstrap/foundation 아래에 remote state, locking, 초기 CI identity 등 다른 인프라가 의존하는 최소 구성을 작성합니다.

Foundation은 일반 infrastructure state와 분리하고 변경 권한을 좁게 유지합니다. 이미 조직 공통 foundation이 있다면 이 폴더에는 외부 의존 계약과 초기화 방법만 문서화해도 됩니다.

4. Infrastructure 작성

작은 프로젝트는 component와 live root만으로 시작합니다.

cp -R infrastructure/components/_template infrastructure/components/kubernetes-cluster
mkdir -p infrastructure/live/dev
cp -R infrastructure/live/_template infrastructure/live/dev/cluster

동일한 조합이 여러 환경에서 반복될 때만 stack을 추가합니다.

cp -R infrastructure/stacks/_template infrastructure/stacks/cluster

live root마다 backend/state를 분리하고, provider credential은 파일에 저장하지 않습니다.

5. Desired state 조립

필요한 catalog 템플릿을 복사합니다.

cp -R gitops/platform/_template gitops/platform/core
cp -R gitops/apps/_template gitops/apps/example-api
mkdir -p gitops/clusters/dev
cp -R gitops/clusters/_template gitops/clusters/dev/main

component의 base에 공통값을 두고, 환경 차이가 있을 때만 overlay를 추가합니다. 마지막으로 cluster kustomization.yaml이 사용할 component를 참조하게 합니다. 복사된 README의 __REPLACE_ME_*__ 값을 모두 실제 메타데이터로 바꿉니다. controller에 연결하기 전에 실제 cluster root를 로컬에서 렌더해 확인합니다.

6. GitOps bootstrap

desired-state root가 준비되고 클러스터가 생성되면 bootstrap/gitops에서 GitOps 컨트롤러 하나를 선택해 설치합니다. 이 단계에는 다음만 포함합니다.

controller 설치 또는 설치 선언
repository/OCI source 연결
검증된 gitops/clusters/<...> root reconcile 연결
controller가 secret manager에 접근하는 최소 identity

일반 platform addon과 application은 이 단계에 넣지 않습니다.

7. 검증

make doctor
make check
kubectl kustomize examples/minimal/gitops/clusters/dev/main
kubectl kustomize gitops/clusters/dev/main

프로젝트에서 실제 IaC, Helm, policy 파일을 추가하면 필요한 validator를 scripts/validate.sh에 명시적으로 추가하고 CI에서도 같은 make check를 호출합니다. 도구가 없을 때 조용히 성공하도록 만들지 않습니다.

첫 환경은 다음 조건을 모두 만족하면 완료된 것으로 봅니다.

실제 live root의 대상, state, owner와 실행 절차가 작성되어 있다.
실제 cluster root가 필요한 catalog base/overlay를 참조하고 비어 있지 않다.
cluster root 렌더 결과와 IaC plan이 리뷰 가능하다.
GitOps bootstrap root가 _template이 아닌 실제 cluster root를 가리킨다.
비밀 관리, rollback과 담당자 연락 경로가 문서화되어 있다.

8. 운영 준비

production apply 승인 및 concurrency lock
backup/restore와 disaster recovery runbook
cluster와 addon upgrade 정책
secret rotation과 접근 감사
alert routing과 담당자
비용, 용량, SLO 기준

운영 준비가 끝나기 전에는 예제 값을 production에 재사용하지 않습니다.

5.7 KiB Raw Blame History