# Getting Started

## 현재 구현과 템플릿 확인하기

이 저장소에는 실제 `lab` 구성이 이미 조립되어 있습니다.

1. `gitops/clusters/lab/main`에서 namespace와 ordered stage 조립 방식을
   확인합니다.
2. 다음 명령으로 platform과 app이 감사용 cluster root에서 합쳐지는 결과를
   확인합니다. `all`은 render/schema/policy 감사 전용이며 직접 apply하지
   않습니다.

   ```bash
   kubectl kustomize gitops/clusters/lab/main/all >/dev/null
   ```

3. 다중 계정·리전·클러스터가 필요하면 account/project, region, cluster 경계를
   ADR로 결정한 뒤 `infrastructure/live/<env>/<leaf>`와
   `gitops/clusters/<env>/<cluster>`로 확장합니다.
4. 새 파일은 현재 구현을 참고하되 각 책임 폴더의 `_template`에서 생성합니다.

```text
현재 구현 확인 ──▶ 경계 결정 ──▶ _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 파일을 추가하기 전에 다음 선택 파일을
만들고 한 값만 활성화합니다.

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

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

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

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

## 3. Foundation bootstrap

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

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

## 4. Infrastructure 작성

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

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

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

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

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

## 5. Desired state 조립

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

```bash
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. 검증

```bash
make doctor
make check
kubectl kustomize gitops/clusters/lab/main/namespaces
kubectl kustomize gitops/clusters/lab/main/all >/dev/null
```

프로젝트에서 실제 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 기준

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