docs(blog-ci): keep only configuration and operation commands
This commit is contained in:
1 parent
4336d923aa
commit
ede18d4ec4
1 file changed
+26
-138
+26
-138
@@ -1,159 +1,47 @@
|
||||
# Blog CI/CD
|
||||
|
||||
`make-space`의 Tekton 구조를 따릅니다. `dahyeon/blog`의 `staging`/`prod` push만
|
||||
받으며 `main`, PR, 브랜치 삭제 이벤트는 배포하지 않습니다. 두 환경 모두 각각
|
||||
소스 revision을 빌드합니다. staging 이미지의 별도 승격 파이프라인은 없습니다.
|
||||
`staging`·`prod` push를 배포합니다. Webhook: `https://tekton-hook.dahyeon.us/blog`
|
||||
|
||||
```text
|
||||
signed Gitea push
|
||||
-> blog-clone (정확한 SHA와 브랜치 최신 커밋 확인)
|
||||
-> blog-quality (Dockerfile quality: fmt + SSR tests/architecture + WASM check)
|
||||
-> blog-build-arm64 (CDN 도구 검사 -> BuildKit image+rootfs -> CDN package/upload/HEAD 검증)
|
||||
-> blog-update-gitops (환경별 digest/source revision/CDN release/replica 커밋)
|
||||
-> Argo CD 자동 Sync
|
||||
```
|
||||
| 브랜치 | Pipeline | 서비스 URL |
|
||||
| --- | --- | --- |
|
||||
| `staging` | `blog-staging` | `https://blog-staging.dahyeon.us` |
|
||||
| `prod` | `blog-prod` | `https://rabbitmaus.com` |
|
||||
|
||||
| 브랜치 | Pipeline | 갱신 파일 | URL |
|
||||
| --- | --- | --- | --- |
|
||||
| `staging` | `blog-staging` | `apps/blog/overlays/staging/kustomization.yaml` | `https://blog-staging.dahyeon.us` |
|
||||
| `prod` | `blog-prod` | `apps/blog/overlays/prod/kustomization.yaml` | `https://rabbitmaus.com` |
|
||||
## CDN 설정
|
||||
|
||||
## 실행 계약
|
||||
[pipeline.yaml](pipeline.yaml)의 Pipeline 파라미터 기본값을 수정합니다.
|
||||
|
||||
`foundation.yaml`은 ServiceAccount와 namespace RBAC, `infisical-secret.yaml`은 CI
|
||||
자격 증명, `tasks.yaml`과 `pipeline.yaml`은 실행 단계, `trigger.yaml`과 `ingress.yaml`은
|
||||
서명된 webhook 수신을 담당합니다. 클러스터 범위 권한과 공통 리소스 정책은 platform에 둡니다.
|
||||
|
||||
PipelineRun은 공유 `tekton-ci`의 ARM64 노드 `heize`와 10 GiB `local-path` PVC를 사용합니다.
|
||||
`kubernetes.io/hostname: heize`로 모든 작업을 고정하며, 소스 PVC도 이 노드에 배치됩니다.
|
||||
최대 시간은 90분(Tasks 85분)입니다. quality의 메모리 요청은 6Gi, 이미지 빌드는 2Gi이며
|
||||
두 빌드의 메모리 제한은 각각 20Gi입니다. 의존성은 Cargo jobs=4, 실제 앱 컴파일은
|
||||
WASM jobs=3 → SSR jobs=4 순서이며 incremental은 끕니다. 도구는 버전·SHA256을 고정한
|
||||
공식 ARM64/AMD64 바이너리로 설치합니다. quality는 jobs=3이며 dev/test debug symbols도 끕니다.
|
||||
공통 quota와 완료 실행 정리는 platform-state 소유입니다.
|
||||
|
||||
quality는 rootless BuildKit으로 앱 Dockerfile의 `quality-deps`를 먼저 빌드·캐시한 다음
|
||||
`quality` target을 명시적으로 빌드합니다. cargo-leptos는 release에서만 설치합니다.
|
||||
내부의 `sh tools/ci/check.sh`는 Rust 1.100.0으로 fmt·SSR 테스트(아키텍처 포함, `ssr`)·
|
||||
WASM check(`hydrate`)를 실행합니다. 의존성 준비와 앱 검사 모두 배포와 같은 기능을 사용하며
|
||||
`dev-ui`를 제외합니다. 카탈로그 전용 코드와 테스트는 앱 README의 별도 검증 절차로 실행합니다.
|
||||
SSR 컴파일은 테스트가 담당하며 중복 check는 실행하지 않습니다.
|
||||
MongoDB/Infisical에는 연결하지 않습니다. 상호작용·라우팅·폼·
|
||||
hydration 변경 시 필요한 Playwright 검증은 앱 README의 별도 절차로 실행합니다.
|
||||
이 초안은 DB 기반 브라우저 테스트를 자동화하지 않습니다.
|
||||
|
||||
빌드는 같은 SHA를 별도 디렉터리에 clone하고 앱 Dockerfile의 `runtime` target을 실행합니다.
|
||||
공통 도구 → cargo-chef 의존성 → WASM → SSR 순서로 빌드하며 서버와 WASM 컴파일은 겹치지 않습니다.
|
||||
`sha-<40자리 소스 SHA>-<PipelineRun UID>` 태그로 push한 뒤 실제 digest를 배포합니다.
|
||||
이미지에는 SSR 바이너리·site·라이선스가 들어가며 Node와 dev-ui는 포함하지 않습니다.
|
||||
DB/Entra ID Secret은 quality, Docker build, WASM 번들에서 사용하지 않습니다.
|
||||
|
||||
CDN 공개 설정은 `pipeline.yaml`의 각 Pipeline 파라미터 기본값으로 관리합니다. ConfigMap을
|
||||
생성하거나 참조하지 않으며, 빌드 Task는 전달받은 값을 같은 이름의 환경 변수로 사용합니다.
|
||||
|
||||
| Pipeline 파라미터 | prod 기본값 | staging 기본값 |
|
||||
| 파라미터 | prod | staging |
|
||||
| --- | --- | --- |
|
||||
| `CDN_URL_PREFIX` | `blog` | `blog-staging` |
|
||||
| `CDN_BASE_URL` | `https://cdn.rabbitmaus.com` | 동일 |
|
||||
| `CDN_S3_BUCKET_NAME` | `rabbitmaus` | 동일 |
|
||||
| `AWS_REGION` | `ap-southeast-2` | 동일 |
|
||||
|
||||
`CDN_URL_PREFIX`는 도메인 뒤의 한 경로 구간이며, `CDN_BASE_URL`에는 경로와 끝 `/`를
|
||||
붙이지 않습니다. 필요하면 PipelineRun의 같은 이름 파라미터로 기본값을 재정의할 수 있습니다.
|
||||
GitOps 완료 키 검사에도 전달받은 `CDN_URL_PREFIX`를 사용합니다.
|
||||
CI에서 source SHA + LF + PipelineRun UID의 SHA-256 앞 16자를
|
||||
계산하고 같은 CDN 설정을 SSR·WASM에 컴파일합니다. BuildKit은 단일 solve에서 image와 local
|
||||
rootfs를 함께 내보냅니다. `/app/site`를 다시 빌드하지 않고 앱 저장소 `tools/cdn`으로 포장합니다.
|
||||
## 자격 증명
|
||||
|
||||
CDN 단계의 `workingDir`는 공유 볼륨 루트인 `/workspace/build`로 두고, 스크립트에서
|
||||
`cd /workspace/build/source`를 실행합니다. 아직 clone하지 않은 경로를 `workingDir`로
|
||||
지정하면 컨테이너 준비 과정이 root 소유 디렉터리를 먼저 만들어 UID 1000의 Git 쓰기를
|
||||
막을 수 있습니다. checkout 디렉터리는 `clone-source`가 직접 만들도록 유지합니다.
|
||||
Infisical 플랫폼 프로젝트 `8520b8c0-3796-4fd6-a03c-6f0508c8c42c`, 환경 `prod`, 경로 `/platform/tekton/blog`:
|
||||
|
||||
`pkg/`는 원본·br·gzip, `assets/`는 WOFF2 원본만 S3에 게시합니다. 나머지 공개 파일은
|
||||
프로젝트 HTTPS 원본이 제공합니다. 모든 객체를 조건부 PUT 후 checksum-enabled HEAD로
|
||||
검사하며, 완료 매니페스트가 성공해야 CDN Task 결과와 후속 GitOps 갱신을 허용합니다.
|
||||
GitOps annotation에는 release ID와 S3 완료 키도 남깁니다. 충돌하는 객체는 덮어쓰지 않고
|
||||
실패하며 이전 릴리즈·부분 업로드를 자동 삭제하지 않습니다.
|
||||
| 키 | 용도 |
|
||||
| --- | --- |
|
||||
| `GITEA_USERNAME` | Git bot 계정 |
|
||||
| `GITEA_TOKEN` | 소스 읽기·service-state 쓰기 |
|
||||
| `HARBOR_DOCKER_CONFIG_JSON` | 이미지 push |
|
||||
| `GITEA_WEBHOOK_SECRET` | Webhook 서명 검증 |
|
||||
| `AWS_ACCESS_KEY_ID` | S3 업로드 |
|
||||
| `AWS_SECRET_ACCESS_KEY` | S3 업로드 |
|
||||
|
||||
Infisical 플랫폼 프로젝트의 `prod` 환경, 기존 `/platform/tekton/blog` 경로에
|
||||
`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`를 등록합니다. 기존 `blog-ci-credentials`가
|
||||
공용 Kubernetes Secret `blog-cdn`으로 동기화하며 prod/staging의 `publish-cdn` step만 받습니다.
|
||||
이 공용 CI 주체에는 버킷의 `blog/*`, `blog-staging/*` 두 prefix에 대한
|
||||
`s3:PutObject`·`s3:GetObject` 권한이 필요합니다. 임시 자격 증명은
|
||||
`AWS_SESSION_TOKEN`을 Secret template에 추가합니다. 앱 Pod에는 S3 쓰기 권한이 없습니다.
|
||||
S3 권한: `rabbitmaus/blog/*`, `rabbitmaus/blog-staging/*`에 `s3:PutObject`, `s3:GetObject`.
|
||||
앱 런타임 Secret은 [앱 설정](../../apps/blog/README.md)을 참고합니다.
|
||||
|
||||
CloudFront 리소스와 Function은 이 변경에 포함하지 않습니다. 두 S3 behavior와
|
||||
`/blog/*` → prod HTTPS, `/blog-staging/*` → staging HTTPS, CORS·OAC·압축 선택을 먼저 구성해야
|
||||
합니다. 업로드 성공은 CF 설정의 정확성까지 보장하지 않습니다. 앱 저장소의
|
||||
`tools/cdn/README.md`에 객체·메타데이터·참조 변환과 로컬 검증 계약을 정리했습니다.
|
||||
## 검증·상태 확인
|
||||
|
||||
두 BuildKit 작업은 `registry.dahyeon.us/dahyeon/blog`의
|
||||
`cache-quality-deps-arm64-<staging|prod>`, `cache-quality-arm64-<staging|prod>`,
|
||||
`cache-release-arm64-<staging|prod>` 태그를 `mode=max`로 저장합니다.
|
||||
앱 검사 전에 의존성 캐시를 저장하여 검사 실패 시에도 다음 실행에서 재사용합니다.
|
||||
같은 브랜치의 캐시를 읽어 도구 레이어도 재사용하되,
|
||||
검사의 test 산출물과 배포의 release 산출물은 별도 의존성 단계로 관리합니다.
|
||||
변경 없는 검사 입력은 성공한 quality 레이어를 재사용할 수 있습니다.
|
||||
최초 실행은 캐시가 없어도 진행합니다. 캐시 태그는 덮어쓰기를 허용하고 Harbor 정리 정책에서
|
||||
유지해야 합니다. 동시 실행이 같은 캐시 태그를 갱신하면 마지막 실행의 캐시가 남습니다.
|
||||
캐시는 일반 빌드 레이어에 저장하며 임시 BuildKit의 cache mount나 실행별 PVC에 의존하지 않습니다.
|
||||
|
||||
GitOps push 직전에 소스 브랜치 최신 SHA를 다시 확인합니다. service-state가 병렬
|
||||
실행으로 앞서간 경우 자동 rebase나 force push 없이 실패하므로 최신 소스로 재실행합니다.
|
||||
어느 Task든 실패하면 후속 GitOps 변경은 실행하지 않습니다.
|
||||
|
||||
## 처음 연결할 때
|
||||
|
||||
1. 앱의 배포 브랜치에 `Dockerfile`, `.dockerignore`, `tools/ci/check.sh`, `tools/cdn`(잠금 파일 포함)과 컴파일에
|
||||
필요한 생성 자산이 커밋되어 있어야 합니다. 로컬 미커밋 파일은 CI에 전달되지 않습니다.
|
||||
2. Harbor `dahyeon/blog` 접근 권한을 준비합니다. CI에는 push robot을,
|
||||
`blog-staging`/`blog-prod`의 `harbor-registry`에는 pull 권한을 준비합니다.
|
||||
기존 서비스와 동일하게 pull Secret 생성은 이 매니페스트의 범위 밖입니다.
|
||||
3. 플랫폼 Infisical 프로젝트 `8520b8c0-3796-4fd6-a03c-6f0508c8c42c`, 환경 `prod`,
|
||||
경로 `/platform/tekton/blog`에 다음 값을 등록합니다.
|
||||
|
||||
| 키 | 용도 |
|
||||
| --- | --- |
|
||||
| `GITEA_USERNAME` | 소스 읽기·service-state 쓰기 bot |
|
||||
| `GITEA_TOKEN` | 해당 bot의 토큰 |
|
||||
| `HARBOR_DOCKER_CONFIG_JSON` | CI push용 Docker config JSON |
|
||||
| `GITEA_WEBHOOK_SECRET` | push 서명 검증 |
|
||||
| `AWS_ACCESS_KEY_ID` | prod/staging 공용 S3 게시 자격 증명 |
|
||||
| `AWS_SECRET_ACCESS_KEY` | 해당 AWS 키의 비밀 키 |
|
||||
|
||||
4. [앱 런타임 Secret](../../apps/blog/README.md)의 staging/prod 6개 키와 공유
|
||||
`infisical-auth` identity의 프로젝트·환경·경로 권한을 확인합니다.
|
||||
5. platform-state의 네임스페이스·EventListener ClusterRole/Binding·`blog-ci`
|
||||
Application·prod 자동 Sync 허용·`rabbitmaus.com` HTTP-01 solver를 반영합니다.
|
||||
service-state의 `ci/blog`, 앱 overlays도 `main`에 반영합니다. 두 저장소 사이의
|
||||
적용 순서는 sync-wave만으로 보장되지 않으므로 컨트롤러·네임스페이스·Secret이
|
||||
준비된 뒤 첫 push를 보냅니다. 초안은 두 환경 모두 replica 0으로 시작합니다.
|
||||
6. 앱 DNS가 Ingress로 연결되도록 설정합니다. `rabbitmaus.com`의 HTTP-01 challenge
|
||||
경로는 외부에서 접근 가능해야 합니다. 모든 블로그 Ingress는 SSL redirect를 끕니다.
|
||||
7. Gitea `dahyeon/blog`에 JSON push webhook
|
||||
`https://tekton-hook.dahyeon.us/blog`를 등록하고 동일한 서명 secret을 사용합니다.
|
||||
공유 webhook 호스트의 TLS Secret은 기존 lolympus Ingress가 발급합니다.
|
||||
|
||||
초안 작성만으로 webhook, Harbor 권한, Secret 값, DNS를 생성하거나 클러스터에 적용하지
|
||||
않습니다. DB 마이그레이션·시드와 Entra ID 기능 구현도 실행하지 않습니다.
|
||||
|
||||
## 검증과 운영
|
||||
저장소 루트에서 실행합니다.
|
||||
|
||||
```sh
|
||||
kubectl kustomize ci/blog
|
||||
kubectl kustomize apps/blog/overlays/staging
|
||||
kubectl kustomize apps/blog/overlays/prod
|
||||
kubectl apply --dry-run=server -k ci/blog
|
||||
node ../blog/tools/cdn/verify-pipeline.mjs . ../platform-state
|
||||
kubectl -n tekton-ci get pipelineruns -l app.kubernetes.io/name=blog
|
||||
kubectl -n argocd get application blog-ci
|
||||
```
|
||||
|
||||
앱 저장소에서 `node tools/cdn/verify-pipeline.mjs ../service-state ../platform-state`를 실행하면
|
||||
Pipeline → Task 파라미터 전달, ConfigMap 제거, Docker·Rust 설정 이름, Argo CD `ci`
|
||||
프로젝트의 리소스 허용 목록까지 검사합니다.
|
||||
|
||||
CRD와 namespace가 준비된 클러스터에서는 별도로
|
||||
`kubectl apply --dry-run=server -k ci/blog`를 실행합니다. 실제 연결 검증은 서명된 staging
|
||||
push 한 건으로 PipelineRun, Harbor digest, service-state 커밋, Argo CD Sync, `/healthz`와
|
||||
SSR/hydration을 확인합니다. 잘못된 서명·다른 브랜치·삭제 SHA는 실행을 만들면 안 됩니다.
|
||||
|
||||
Secret 갱신 후 앱 Pod 재생성이 필요하며, 파이프라인의 성공은 Argo CD rollout 완료를
|
||||
의미하지 않습니다. 배포 완료는 해당 Application의 Synced/Healthy 상태까지 확인합니다.
|
||||
Reference in new issue
Block a user