From 05c1afe718c6cb21ba1a7076bb906e0be2b6aef4 Mon Sep 17 00:00:00 2001 From: jungwoo choi Date: Sat, 29 Aug 2026 11:50:56 +0900 Subject: [PATCH] =?UTF-8?q?chore(cli):=20=EC=8A=A4=EC=BA=90=ED=8F=B4?= =?UTF-8?q?=EB=93=9C=20=EC=A0=95=EB=A6=AC(project=20init=20=EC=9D=B4=20com?= =?UTF-8?q?mands/README/DATA-SOURCES=20=EC=A0=9C=EC=99=B8)=20+=20SKILL=20?= =?UTF-8?q?=EC=8A=AC=EB=A6=BC=ED=99=94=20=E2=80=94=200.16.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- .claude/skills/yakcloud-deploy/SKILL.md | 156 ++++++++---------------- bin/yakcloud | 13 +- 2 files changed, 56 insertions(+), 113 deletions(-) diff --git a/.claude/skills/yakcloud-deploy/SKILL.md b/.claude/skills/yakcloud-deploy/SKILL.md index 6016e45..f1fd056 100644 --- a/.claude/skills/yakcloud-deploy/SKILL.md +++ b/.claude/skills/yakcloud-deploy/SKILL.md @@ -1,122 +1,64 @@ --- name: yakcloud-deploy -description: Scaffold and wire up YakCloud declarative CI/CD for a project — Gitea Actions (tag push) → build/push images → reconcile data sources → deploy workloads → bind → tenant cluster. Use when the user wants to deploy this project to YakCloud, set up the Gitea Actions workflow, create the yakcloud.yaml manifest, bind data sources, add a custom domain, or start a brand-new project from a minimal starter. +description: Deploy a project to YakCloud — yakcloud CLI (local kind dev → managed val/prod) or Gitea Actions (v* tag push) → build/push image → reconcile data sources → deploy workloads → bind env → custom domain. Use when deploying this project to YakCloud, editing yakcloud.yaml, binding data sources, adding a domain, or starting a new project. --- -# YakCloud 배포 스킬 (선언적 CI/CD) +# YakCloud 배포 스킬 -VS Code로 개발 → 커밋 → **`v*` 태그 push** 하면, Gitea Actions가 이미지를 빌드/푸시하고 -YakCloud 콘솔 API로 **데이터소스 리컨실 + 워크로드 배포 + 바인딩**을 자동 처리한다. +`yakcloud` CLI 로 **로컬 kind 개발 → 관리형 검증/운영**을 한 줄기로 배포한다. 또는 `v*` 태그 push → +Gitea Actions 가 이미지 빌드/푸시 + 콘솔 API 로 데이터소스 리컨실·워크로드 배포·바인딩을 자동 처리. -이 스킬은 **아무 프로젝트에나 이 파이프라인을 심는다.** `yakcloud` CLI(권장) 또는 스타터 레포로 -스캐폴딩하고, 매니페스트를 채운 뒤 1회 시크릿만 설정하면 끝. 빈 프로젝트면 프레임워크 중립 **스타터**로 바로 시작. -> 이 스킬은 **번들 파일을 두지 않는다**(SKILL.md 하나). 실제 템플릿은 CLI 또는 스타터 레포(`yakenator/yakcloud-starter`)에서 온다. - -## 언제 쓰나 -- "이 프로젝트를 YakCloud에 배포/자동화" / "Gitea CI/CD 붙여줘" / "yakcloud.yaml 만들어줘" -- "새 프로젝트 시작해서 배포까지" (→ `yakcloud project init`) -- "데이터소스(Postgres/Mongo/…) 연결/바인딩" / "커스텀 도메인으로 노출" - -## CLI 가 있으면 우선 사용 -`yakcloud` CLI 가 설치돼 있으면(`command -v yakcloud`) 스캐폴딩/배포/환경설정을 이걸로 처리한다. +## CLI (권장) 설치: `curl -fsSL https://gitea.yakenator.io/yakenator/yakcloud-starter/raw/branch/main/install.sh | sh` -> 설치 시 **Claude Code 전역 슬래시 명령 `/yakcloud`** 도 함께 생성된다(`~/.claude/commands/yakcloud.md`). 예: `/yakcloud project init my-app`, `/yakcloud datasource ls`, `/yakcloud project deploy`. 이후 `yakcloud upgrade` 가 CLI와 슬래시 명령을 함께 최신화. +(전역 `/yakcloud` 슬래시 명령도 설치됨. `yakcloud upgrade` 로 최신화.) 자격 저장 = `yakcloud login`. -**프로젝트 라이프사이클 (로컬 kind dev → 관리형 val/prod, 한 줄기 직선)** -- **"클러스터 생성"** → `yakcloud cluster create [--template S|M] [--nodes N] [--golden]` (배포토큰으로 프로비저닝, 완료까지 대기). `yakcloud cluster ls` 로 목록. 검증/운영 클러스터를 만들어 매니페스트 environments 에 지정. -- **"프로젝트 초기화"** → 빈 폴더에서 `yakcloud project init [name]` (스타터+CI+매니페스트+이 스킬) -- **"로컬 개발"**(권장 반복 루프) → `yakcloud dev up`(최초 1회 — 로컬 kind 생성+인그레스) → `yakcloud dev deploy`. `requires` 소스+`workloads` 가 로컬에서 **관리형과 동일한 바인딩 env**로 뜬다(콘솔/CI·인터넷 불필요, 오프라인 반복). `dev status`/`dev clean`/`dev down`. 로그인돼 있으면 이 로컬 클러스터가 **콘솔 클러스터 목록('내 로컬 클러스터')에도 자동 등록/해제**된다(콘솔은 접속 않고 목록 표시만). 상세 `docs/local-dev-cluster.md`. -- **"개발 배포"**(관리형 개발 클러스터) → `yakcloud project deploy` (자동 버전업 → 태그 push → CI 빌드 → **개발 클러스터**). 기본 도메인으로 확인. -- **"승격"**(개발→검증→운영) → `yakcloud project promote [vX.Y.Z] [--to val|prod]` (그 이미지를 **재빌드 없이 상위 환경으로**; `--to prod` 는 운영 도메인 부착). 검증계(val)는 선택 — `environments` 에 없으면 개발→운영 2단계 -- **"프로젝트 개괄"** → `yakcloud project info` · 사전 점검 → `yakcloud project check [--env dev|val|prod]` -- 매니페스트 `environments.{dev,val,prod}.cluster` (val 선택, + `prod.domains`). **로컬 개발은 `yakcloud dev`(로컬 kind)**, 상위 환경(val/prod)은 관리형 클러스터 — 같은 매니페스트·같은 바인딩 계약(직선 파리티). +**라이프사이클** +- `yakcloud project init [name]` — 빈 폴더에 스캐폴딩(앱·CI·매니페스트·엔진). +- `yakcloud cluster create [--template S|M] [--nodes N] [--golden]` · `yakcloud cluster ls`. +- **로컬 dev**(반복 루프) — `yakcloud dev up`(최초 1회, 로컬 kind+인그레스) → `yakcloud dev deploy`. + `requires` 소스+`workloads` 가 로컬에 **관리형과 동일한 바인딩 env**로 뜬다(오프라인). `dev status/clean/down`. + 로그인 시 콘솔 '내 로컬 클러스터'에 자동 등록/해제. 상세 `docs/local-dev-cluster.md`. +- **배포/승격** — `yakcloud project deploy` (v* 태그 push → CI → 개발 클러스터) · `--local`(러너 없이 로컬 + build+push+리컨실) · `yakcloud project promote [vX.Y.Z] --to val|prod` (같은 이미지, 재빌드 없이 승격). +- **앱 설정** — `domain [wl]` · `scale ` · `set --image/--port/--health/--cpu/--mem/--path/--rewrite` + · `env KEY=VAL [--secret K] [--unset K]` · `datasource ls` · `source add [plan] [--shared]` · `bind|unbind `. -**배포환경 설정(앱별) — 매니페스트 수정 + 배포중이면 재빌드 없이 라이브 반영** -- `yakcloud domain [wl]` 도메인 등록 + 워크로드 할당 -- `yakcloud scale ` replicas -- `yakcloud set --image/--port/--health/--cpu/--mem/--path/--rewrite` -- `yakcloud env KEY=VAL … [--secret KEY] [--unset KEY]` -- `yakcloud datasource ls` (=`source ls`) 클러스터에서 이용 가능한 소스 목록(이름·타입·내부/외부·상태·플랜) -- `yakcloud source add [plan]` · `yakcloud source rm ` -- `yakcloud bind ` · `yakcloud unbind ` +## 매니페스트 (`yakcloud.yaml`) +- `project` — 이름(이미지 경로). +- `environments.{dev,val,prod}.cluster` — 대상 클러스터 이름/id (val 선택, +`prod.domains`). 로컬 dev 는 `yakcloud dev`. +- `requires[]` — `{ name, type, plan | mode: shared }`. type ∈ postgresql·mysql·mariadb·mongodb·redis·minio·rabbitmq·solr·oracle. + 이름이 클러스터의 READY 소스와 일치하면 스킵, 없으면 프로비저닝(shared=공유 외부, 백엔드가 격리 DB 민팅). +- `workloads[]` — `build`(도커 컨텍스트)·`image`(`gitea.yakenator.io//-:${TAG}`)·`port`· + `health`·`replicas`(≥2 무중단)·`resources{cpu,mem}`·`expose{path,rewrite,host|hosts}`·`binds[]{alias,source}`. -CLI 가 없거나 세밀 조정이 필요하면 아래 수동 절차를 따른다. +## 데이터소스 바인딩 env (앱은 하드코딩 말고 이 env 로 접속) +`binds: {alias, source}` → `alias`(대문자, 하이픈→언더스코어)가 env 프리픽스. 공통 `_HOST`·`_PORT`. +| type | 추가 키 | `_URL` | +|---|---|---| +| postgresql | `_USERNAME _PASSWORD _DB` | `postgresql://u:pw@host:port/db` | +| mysql·mariadb | `_USERNAME _PASSWORD _DB` | `mysql://u:pw@host:port/db` | +| mongodb | `_USERNAME _PASSWORD _DB` | `mongodb://u:pw@host:port/db?authSource=db` | +| redis | `_USERNAME`(빈) `_PASSWORD _DB` | `redis://:pw@host:port/db` | +| minio | `_ACCESS_KEY _SECRET_KEY _ENDPOINT _BUCKET _REGION` | =`_ENDPOINT` | +비밀번호/키는 인클러스터 Secret 으로 주입되고 브라우저/포털에 노출되지 않는다. -## 에이전트 실행 절차 +## 1회 준비 (CI 배포 시 — 사용자가 설정, 에이전트 대행 불가) +1. **배포 토큰**(콘솔 → 설정 → 배포 토큰, `yakd_…`) · **Gitea 토큰**(`read:repository`+`write:package`+`read:package`). +2. 레포 시크릿(Gitea → Settings → Actions → Secrets): `YAKCLOUD_URL`=`https://console.yakenator.io` · + `YAKCLOUD_TOKEN`=배포토큰 · `YAKCLOUD_CLUSTER`=대상 이름/id · `REGISTRY_TOKEN`=Gitea 토큰. +3. 러너: 전용 러너(라벨 `ci-polyglot`)가 공유로 떠 있으면 레포 Actions 만 켠다. + (러너 없이 확실히 하려면 `yakcloud project deploy --local` — 로컬 build/push/리컨실.) -### 0) 상황 파악 -- 이미 `yakcloud project init` 으로 스캐폴딩된 프로젝트면 루트에 `yakcloud.yaml`·`scripts/`·`.gitea/`·`app.py` 가 이미 있다 → 바로 §3 이후로. -- 빈/신규면 §1, 기존 앱이면 §1-B. Gitea 원격 여부(`git remote -v`)도 확인(없으면 사용자에게 레포 URL 요청). - -### 1) 스캐폴딩 (신규/빈 프로젝트) -- **CLI 있으면(권장)**: `yakcloud project init [name]` — 앱·CI·매니페스트·이 스킬을 한 번에 생성. -- **CLI 없으면**: `install.sh` 로 CLI 설치 후 init, 또는 스타터 레포에서 루트 파일을 복사: - ```sh - git clone --depth 1 https://gitea.yakenator.io/yakenator/yakcloud-starter .yc-tmp - cp -R .yc-tmp/app.py .yc-tmp/Dockerfile .yc-tmp/yakcloud.yaml .yc-tmp/scripts .yc-tmp/DATA-SOURCES.md . - cp -R .yc-tmp/.gitea . && rm -rf .yc-tmp - ``` - 스타터 앱 = 프레임워크 무의존 최소 HTTP 서버(`PORT` 리슨, `/healthz` 200). 이후 §3 매니페스트 작성. - -### 1-B) 기존 앱에 부착 -1. 앱이 **`PORT` env로 리슨 + `/healthz`(또는 health 경로) 제공**하는지 확인. 없으면 추가 제안. -2. 데이터소스 접속정보를 **하드코딩하지 말고 주입 env**(`_URL` 등)로 읽도록 수정 제안. 키 규약: 루트 `DATA-SOURCES.md`(스타터에서 복사). -3. 각 배포 단위마다 `Dockerfile` 필요(없으면 언어에 맞게 생성). 베이스 이미지는 Gitea 미러(`gitea.yakenator.io/yakenator/{node,python,...}`). -4. CI/배포 플러밍(`scripts/yakcloud_deploy.py`·`scripts/yakcloud_ctl.py`·`.gitea/workflows/deploy.yml`·`yakcloud.yaml`)은 §1 처럼 스타터 레포에서 복사(또는 `yakcloud project init` 이 대신 처리). - -### 3) 매니페스트(`yakcloud.yaml`) 채우기 (핵심) -사용자와 함께 값을 정한다: -- `project`: 프로젝트 이름(이미지 경로에 사용). -- `cluster`: 배포 대상 클러스터 **이름 또는 콘솔 id** (콘솔 대시보드에서 확인). 여러 개면 여기서 특정. -- `requires`: 필요한 데이터 소스 목록 `{ name, type, plan }`. 없으면 `[]`. - - `type` ∈ `postgresql·mysql·mariadb·mongodb·redis·minio·rabbitmq·solr·oracle`, `plan` ∈ `small·medium·large`. - - 이 이름의 소스가 클러스터에 이미 READY면 스킵, 없으면 자동 프로비저닝. -- `workloads[]`: - - `build`: 도커 빌드 컨텍스트 경로(예 `./` 또는 `./api`). **CI가 이 컨텍스트를 빌드해 `image`로 push.** - - `image`: `gitea.yakenator.io//-:${TAG}` (`${TAG}`=릴리스 태그로 치환). - - `port`·`health`·`replicas`(≥2 권장 → 무중단 롤링)·`resources{cpu,mem}`. - - `expose`: `{ path, rewrite, host? }` — `host` 지정 시 등록 도메인으로 노출(미지정=클러스터 기본 도메인). 여러 도메인은 `hosts: [a, b]`. - - `binds[]`: `{ alias, source }` — `source`는 위 `requires` 이름, `alias`는 env 프리픽스(대문자화). 예 `alias: db` → `DB_URL/DB_HOST/…` 주입. - -### 4) 1회 준비 (사용자에게 안내 — 에이전트가 대신 못 함) -아래를 **사용자가** 설정하도록 명확히 출력: -1. **배포 토큰(PAT)**: 콘솔 → **설정 → 배포 토큰** → 발급(`yakd_…`, 한 번만 표시). 계정 스코프(어느 클러스터든). -2. **Gitea 토큰**: 스코프 `read:repository` + `write:package` + `read:package`. (레포 read 없으면 CI `git clone` 403) -3. **레포 시크릿**(Gitea: Settings → Actions → Secrets): - | 이름 | 값 | - |---|---| - | `YAKCLOUD_URL` | `https://console.yakenator.io` | - | `YAKCLOUD_TOKEN` | 1의 배포 토큰(`yakd_…`) | - | `YAKCLOUD_CLUSTER` | 대상 클러스터 이름/ id (생략 시 매니페스트 `cluster:`) | - | `REGISTRY_TOKEN` | 2의 Gitea 토큰 | -4. **러너**: 전용 러너(라벨 `ci-polyglot`)가 이미 공유로 떠 있으면 레포 **Actions만 켜면** 됨. 없으면 GUIDE의 러너 등록 참고. - -### 5) 배포 +## 배포 / 도메인 ```sh -git add -A && git commit -m "yakcloud: CI/CD 스캐폴딩" -git push origin main -git tag v0.1.0 && git push origin v0.1.0 # v* 태그만 배포 트리거(일반 커밋은 배포 안 함) +yakcloud project deploy # 또는: git tag v0.1.0 && git push origin v0.1.0 +yakcloud domain app.example.com web # 관리형 도메인=즉시 Active, 외부=TXT 검증 ``` -→ Gitea **Actions** 탭에서 실행 확인. 성공 시 콘솔 **앱 탭 / 데이터 소스 / 도메인**에 반영. -로컬 사전 점검: `YAKCLOUD_URL=… YAKCLOUD_TOKEN=… python3 scripts/yakcloud_deploy.py yakcloud.yaml --dry-run` +사전 점검: `yakcloud project check`. 성공 시 콘솔 앱 탭 / 데이터 소스 / 도메인에 반영. -### 6) 커스텀 도메인(선택) -콘솔 **설정 → 도메인 → 도메인 추가**로 등록(관리형 도메인은 즉시 Active). 매니페스트 `expose.host`에 지정하거나 -콘솔 앱 편집 폼에서 선택. 여러 도메인은 `expose.hosts: [a.example.com, b.example.com]`. - -## 동작/규약 요점 -- **트리거**: `v*` 태그 push만. 일반 커밋은 배포 안 함. -- **멱등/무중단**: 기존 배포는 이미지 PATCH(→ kubectl apply 롤링). replicas≥2 + health면 무중단. -- **자격**: 데이터소스 비밀번호/키는 인클러스터 Secret으로 주입되고 브라우저/포털에 노출되지 않음. 앱은 `_URL` 등으로 접속. - -## 트러블슈팅(실제 겪은 것) -| 증상 | 원인 → 해결 | -|---|---| -| CI `git clone … 403` | REGISTRY_TOKEN에 레포 read 없음 → `read:repository` 추가 | -| `docker create` 실패(잡 시작 안 됨) | 러너 config에서 docker.sock **중복 마운트** → act 기본 마운트만(수동 제거) | -| 배포 중 `429 RATE_LIMITED` | CLI가 `retryAfterSec` 백오프로 재시도(내장) | -| 다른 러너가 잡 가져감 | 라벨 충돌 → 전용 라벨(`runs-on`) 사용 | -| 소스 프로비저닝 `405` | 배포 토큰엔 소스 생성 권한 없음 → (1) **인클러스터(local)**: 콘솔에서 소스 먼저 만들고 `requires[].name`·`binds[].source`를 그 소스명으로; (2) **공유 외부(shared, 소용량 S용)**: `requires` 에 `mode: shared` 선언(`yakcloud source add mongodb --shared`; 콘솔/API 등록도 가능) → 배포 시 백엔드가 클러스터별 격리 DB/계정 민팅. `yakcloud project check`가 미리 경고(READY 소스 목록 출력) | -| 태그 push 했는데 아무 일도 안 남 | 레포에 **러너 0개**(잡이 조용히 큐잉) → `yakcloud project deploy`가 배포 전 러너 프리플라이트 경고. 러너 없으면 `yakcloud project deploy --local`(로컬 빌드·push 후 API 배포) | -| 헬스체크 `/healthz` 404/이상 | 엣지가 `/healthz`를 **가로챔** → 배포 검증은 앱 실제 경로(`/`)로. 컨테이너 readiness엔 여전히 `health:` 사용 OK | -| `ModuleNotFoundError: yaml`(직접 배포) | `pip install pyyaml`(또는 `pip3 install --break-system-packages pyyaml`). CI 이미지엔 포함됨 | +## 규약 / 트러블슈팅 +- 트리거 = `v*` 태그 push 만(일반 커밋 배포 안 함). 기존 배포는 이미지 PATCH 롤링(replicas≥2+health=무중단). +- 소스 프로비저닝 `405` → 콘솔에서 소스 먼저 만들거나 `mode: shared`(소용량 S). `yakcloud project check` 로 사전 확인. +- 태그 push 후 무반응 → 레포 러너 0개. `yakcloud project deploy --local`. +- 헬스 `/healthz` 404 → 엣지가 가로챔. 배포 검증은 앱 실제 경로(`/`)로(컨테이너 readiness 엔 `health:` OK). +- `ModuleNotFoundError: yaml`(직접 배포) → `pip install pyyaml`(CI 이미지엔 포함). diff --git a/bin/yakcloud b/bin/yakcloud index ef629d4..e8b3bbf 100755 --- a/bin/yakcloud +++ b/bin/yakcloud @@ -16,7 +16,7 @@ set -uo pipefail # -e 미사용: 'test && action' 관용구가 값 없을 때 REPO="${YAKCLOUD_STARTER_REPO:-https://gitea.yakenator.io/yakenator/yakcloud-starter}" BRANCH="${YAKCLOUD_STARTER_BRANCH:-main}" -VERSION="0.15.0" +VERSION="0.16.0" # 로컬 개발 클러스터(kind) — 개발 후 운영까지 '직선 배포'의 dev 구간. DEV_CTX="${YAK_DEV_CONTEXT:-kind-yak-dev}" DEV_CLUSTER="${YAK_DEV_CLUSTER:-yak-dev}" @@ -149,8 +149,9 @@ cmd_project_init() { rm -rf "$tmp/s/.git" cp -R "$tmp/s/." . rm -rf "$tmp" - # CLI 배포 파일(전역 yakcloud 사용)은 사용자 프로젝트에 불필요 → 스캐폴드에서 제거. - rm -rf bin install.sh + # 사용자 프로젝트에 불필요한 배포/전역/문서 파일은 스캐폴드에서 제거 — 앱+엔진+CI+SKILL 만 깔끔히 남긴다. + # bin·install.sh=CLI 배포용 · .claude/commands=전역 슬래시명령(중복) · README/DATA-SOURCES=스타터 문서. + rm -rf bin install.sh .claude/commands README.md DATA-SOURCES.md [ -n "$name" ] && [ -f yakcloud.yaml ] && { sed -i.bak "s/^project: .*/project: $name/" yakcloud.yaml && rm -f yakcloud.yaml.bak; } git rev-parse --git-dir >/dev/null 2>&1 || git init -q echo "✓ 스캐폴딩 완료 ($(pwd))" @@ -532,12 +533,12 @@ cmd_project_update() { cp "$tmp/s/scripts/yakcloud_dev.py" scripts/ 2>/dev/null || true # 로컬 kind 리컨실 엔진(직선 dev) rm -f scripts/yakcloud_migrate.py # 옛 migrate 잔재 제거 cp "$tmp/s/.gitea/workflows/deploy.yml" .gitea/workflows/ 2>/dev/null || true - cp "$tmp/s/DATA-SOURCES.md" DATA-SOURCES.md 2>/dev/null || true rm -rf .claude/skills/yakcloud-deploy cp -R "$tmp/s/.claude/skills/yakcloud-deploy" .claude/skills/ 2>/dev/null || true rm -rf "$tmp" - rm -rf bin install.sh # 옛 스캐폴드 잔재(CLI 배포 파일) 정리 - echo "✓ 최신화 완료 — scripts/·.gitea/·.claude 스킬 갱신(app.py·yakcloud.yaml·Dockerfile 그대로)" + # 비프로젝트 파일 정리(스캐폴드 최소화): CLI 배포용 + 전역 슬래시명령 + 스타터 문서. + rm -rf bin install.sh .claude/commands README.md DATA-SOURCES.md + echo "✓ 최신화 완료 — scripts/·.gitea/·.claude/skills 갱신(app.py·yakcloud.yaml·Dockerfile 그대로)" } usage() {