carnufex/gitops-app-onboarding

GitOps 앱 온보딩

이 방법은 일반적입니다. 클러스터의 세부 정보 (경로, 허용 목록, 레지스트리, 스토리지 클래스, 게이트웨이, 참조 앱, 알림 위치)는 GitOps 저장소의 .claude/profiles/gitops.md에 있습니다. 프로필을 먼저 읽으십시오. 프로필이 없으면, 저장소 (ApplicationSet, AppProject, 시크릿 저장소, 기존 앱 하나 둘, 모니터링 폴더)를 읽어 templates/profile.md에서 생성하고, 사용자에게 프로필을 작성했음을 한 줄로 알리십시오. 경로를 추측하지 마십시오.

앱이 라이브가 되는 방법

• 디렉토리 생성기가 있는 ApplicationSet은 프로필의 앱 디렉토리 아래 각 폴더를 자체 ArgoCD 애플리케이션 및 네임스페이스로 변환합니다. 폴더는 유효한 kustomization.yaml이 있으면 한 번에 배포됩니다.
• ArgoCD가 추적하는 브랜치로 푸시되기 전에는 아무것도 클러스터에 도달하지 않습니다. kubectl로만 적용된 변경 사항은 다음 동기화에서 되돌려집니다.
• 플랫폼 구성 요소 (CNI, 스토리지, 컨트롤러)는 앱 디렉토리에 넣지 않습니다. 프로필에 해당 위치가 명시되어 있습니다.

새 네임스페이스는 동일한 커밋에서 모든 곳에 허용되어야 합니다

프로필의 허용 목록 섹션에는 네임스페이스를 명명하는 모든 파일이 나열됩니다 (일반적으로: AppProject destinations, ClusterSecretStore conditions, 그리고 앱이 LB IP가 필요한 경우 LoadBalancer IP 풀 및 L2/BGP 알림 선택자). 하나라도 놓치면 앱이 동기화되지 않거나, ExternalSecret이 SecretSyncError 상태로 남거나, LB IP가 알림되지 않습니다. 폴더를 추가하는 커밋에서 모든 해당 파일에 네임스페이스를 추가하십시오.

온보딩 순서 (가장 작은 안전한 형태 먼저)

1. ns.yaml: 프로필의 파드 보안 레이블이 있는 네임스페이스.
2. kustomization.yaml: 종속성 순서의 리소스 (네임스페이스 및 구성, 그다음 워크로드, 그다음 라우트).
3. 시크릿: 먼저 시크릿 백엔드에 항목을 생성한 다음 (프로필: 시크릿), 시크릿당 ExternalSecret을 만듭니다. 절대 시크릿 값을 커밋하지 마십시오. 부트스트랩 및 비상 시크릿은 Git 밖에 유지됩니다.
4. 런타임 매니페스트 (Deployment, Service, PVC, ConfigMap), 이미지 이름과 시크릿 이름이 확인된 후에만. 실제 헬스 엔드포인트, 리소스 요청, 네임스페이스의 파드 보안 수준에서 요구하는 보안 컨텍스트에 대한 준비성 및 활성 프로브.
5. 3AM 신호 (아래), 워크로드와 동일한 변경 사항에 포함.
6. 라우트, 마지막으로, 이미지가 실행되고 시크릿이 확인되며 프로브가 통과된 후 (노출 참조).
7. 앱 폴더의 README.md: 앱이 무엇인지, 런타임 종속성, 시크릿 이름, 스토리지, 접근 방법.

규칙 (프로필에 값이 있음)

• 이미지: 프로필에서 앱이 움직이는 태그를 추적한다고 명시하지 않는 한 tag@sha256:<다이제스트> 고정; 자체 이미지는 변경 불가능한 태그로 프로필의 레지스트리에서 가져옵니다. 비공개 이미지는 프로필의 풀 시크릿 패턴이 필요합니다.
• 시크릿: 프로필의 ClusterSecretStore에 대한 ExternalSecret 리소스, 절대 인라인 Secret 데이터를 사용하지 않음.
• 스토리지: 프로필의 스토리지 클래스와 각각의 용도 (작은 복제 블록 볼륨 vs NFS의 대량 데이터). 프로필의 용량 제한은 하드 제한입니다.
• 라우팅: 공용 및 내부 게이트웨이와 그 호스트 패턴; LoadBalancer Service를 통한 원시 TCP/UDP.
• 새로운 것을 발명하기보다 프로필의 참조 앱 형태를 복사하십시오.

3AM 신호

푸시하기 전에 질문하십시오: 이 앱이 오전 3시에 고장난다면, 어떻게 알 수 있으며, 무엇을 먼저 볼까?

• 앱은 사람에게 도달하는 경보로 보호되어야 합니다: 프로필의 모니터링 경보 규칙에 네임스페이스와 워크로드를 추가 (사용 불가 레플리카, 크래시 루프, 대기 중인 파드 또는 PVC), 또는 해당 규칙이 감지할 수 없는 실패 모드 (드레이닝을 멈춘 큐, 실행을 멈춘 작업, 만료되는 인증서 또는 토큰)가 있는 경우 앱별 규칙을 추가하십시오.
• 앱의 로그는 실패한 내용과 이를 국소화하는 ID를 말해야 합니다. 이미지가 우리 것이고 그렇지 않다면, 그것은 작업입니다.
• 커밋 메시지에 신호를 기록하십시오: 3 am: <경보 이름> via <수신자>.

노출

앱이 실행되고, 시크릿이 확인되고, 헬스 체크가 통과될 때까지 공용 라우트를 추가하지 마십시오. 내부 전용 도구는 내부 게이트웨이에만 연결되며 공용 라우트를 얻지 않습니다. 공개적으로 노출할 때는 공용 인그레스 경로 (DNS, 터널, 인증서)에 대해 프로필의 관련 스킬을 따르십시오.

온보딩 후 (확인, 추정하지 않음)

1. 푸시; 새 애플리케이션이 나타나고 수렴되는지 확인 (kubectl get applications.argoproj.io -n argocd, 또는 프로필의 확인 명령). 프로필에 방법이 나와 있으면 폴링 지연을 건너뛰기 위해 새로 고침을 요청하십시오.
2. 확인: 애플리케이션 Synced 및 Healthy, 모든 ExternalSecret SecretSynced, 파드 준비 완료, 라우트 응답, 경보 규칙이 로드됨 (모니터링 스택의 규칙 목록에 나타남).
3. 수렴되지 않으면 체인을 위에서 아래로 따라가십시오: 허용 목록 → 시크릿 → ArgoCD 동기화 오류 → 파드 → 라우팅. 허용 목록이 일반적인 원인입니다. 프로필의 관련 스킬에 클러스터의 진단 스킬이 명시되어 있습니다.