yakcloud-starter/.claude/skills/yakcloud-deploy/SKILL.md

name, description

name

description

yakcloud-deploy

Develop, verify, and deploy this project via the yakcloud CLI (local kind dev → managed val/prod) — never docker-compose. Build/push image → reconcile data sources → deploy workloads → bind env → custom domain. Use when running/testing/verifying the app locally, setting up a local dev environment, deploying to YakCloud, editing yakcloud.yaml, binding data sources, adding a domain, or starting a new project. If tempted to use docker-compose / docker run to run this app, use `yakcloud project deploy` (local kind) instead.

YakCloud 배포 스킬

yakcloud CLI 로 로컬 kind 개발 → 관리형 검증/운영을 한 줄기로 배포한다. 또는 v* 태그 push → Gitea Actions 가 이미지 빌드/푸시 + 콘솔 API 로 데이터소스 리컨실·워크로드 배포·바인딩을 자동 처리.

개발·검증도 yakcloud — docker-compose 금지 (원칙)

이 프로젝트의 앱은 로컬 개발·검증부터 운영까지 전 구간을 yakcloud 로 진행한다.

• 로컬 실행·검증 = yakcloud project deploy (로컬 kind 자동 생성, 오프라인·무료, 운영과 동일한 바인딩 env·데이터소스).
• docker compose / docker-compose / docker run 으로 앱을 띄우지 마라 — 프로젝트 .claude/settings.json 이 이를 차단하고, Dockerfile 은 yakcloud 의 이미지 빌드 전용이다. compose 스택은 운영과 환경이 달라져 파리티가 깨진다.
• 데이터소스는 손으로 컨테이너를 띄우지 말고 yakcloud.yaml 의 requires 로 선언한다. (각 프로젝트 루트 CLAUDE.md 에 같은 규칙이 항상 로드되도록 심겨 있다 — yakcloud project init 이 생성.)

실행 규약 (패스스루) — 최우선

/yakcloud <args> 로 호출되면 yakcloud <args> 를 Bash 로 그대로 실행하고 출력만 보여준다. 사전점검(설치/폴더/설정 확인)·결과 재검증·부연설명을 붙이지 말 것 — 터미널에서 직접 친 것과 동일하게 동작. CLI 가 스스로 전제조건을 검사하고 오류를 안내하므로, 실패하면 그 출력을 그대로 전달하고 필요한 만큼만 후속 조치.

안전장치 — 아래 "되돌리기 어렵거나 외부로 나가는" 서브커맨드만 실행 전 1줄로 확인하고 승인 시 실행: project deploy · project promote · domain · cluster create · dev down · source add · datasource migrate apply (그 외 project init/info/check · dev up/deploy/status · datasource ls/capture · cluster ls · config/login 등 읽기·로컬·멱등 명령은 확인 없이 즉시 실행.)

CLI (권장)

설치: curl -fsSL https://gitea.yakenator.io/yakenator/yakcloud-starter/raw/branch/main/install.sh | sh (전역 /yakcloud 슬래시 명령도 설치됨. yakcloud upgrade 로 최신화.) 자격 저장 = yakcloud login.

라이프사이클

• yakcloud project init [name] — 빈 폴더에 스캐폴딩(앱·CI·매니페스트·엔진).
• yakcloud cluster create <name> [--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 <fqdn> [wl] · scale <wl> <n> · set <wl> --image/--port/--health/--cpu/--mem/--path/--rewrite · env <wl> KEY=VAL [--secret K] [--unset K] · datasource ls · source add <name> <type> [plan] [--shared] · bind|unbind <wl> <source> <alias>.

매니페스트 (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/<GITEA_USER>/<project>-<name>:${TAG})·port· health·replicas(≥2 무중단)·resources{cpu,mem}·expose{path,rewrite,host|hosts}·binds[]{alias,source}.

데이터소스 바인딩 env (앱은 하드코딩 말고 이 env 로 접속)

binds: {alias, source} → alias(대문자, 하이픈→언더스코어)가 env 프리픽스. 공통 <A>_HOST·<A>_PORT.

type	추가 키	<A>_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/리컨실.)

배포 / 도메인

yakcloud project deploy            # 또는: git tag v0.1.0 && git push origin v0.1.0
yakcloud domain app.example.com web   # 관리형 도메인=즉시 Active, 외부=TXT 검증

사전 점검: yakcloud project check. 성공 시 콘솔 앱 탭 / 데이터 소스 / 도메인에 반영.

규약 / 트러블슈팅

• 트리거 = 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 이미지엔 포함).