diff --git a/infrastructure/ci/gitea-runner/README.md b/infrastructure/ci/gitea-runner/README.md new file mode 100644 index 0000000..cf44fff --- /dev/null +++ b/infrastructure/ci/gitea-runner/README.md @@ -0,0 +1,232 @@ +# Gitea Actions runner + +Gitea Actions job을 실행하는 runner 하나를 desktop 호스트(k3s 노드 +`192.168.0.107`)의 Docker 컨테이너로 운영한다. Kubernetes 리소스가 아니므로 +`host-nginx`와 같이 호스트 설정의 버전 관리 위치로 둔다. + +상태(2026-11-07): `desktop-runner`(id 1)를 `donghyeon.kang` 사용자 범위로 등록했다. +Gitea API에서 `online`, `busy=false`, label `ubuntu-latest`다. 아직 job을 돌리지 +않았으므로 Testcontainers 동작은 첫 CI job에서 확인한다. 아래 「적용 기록」을 본다. + +## 결정 + +| 항목 | 값 | 이유 | +| --- | --- | --- | +| 위치 | desktop 호스트 Docker, 컨테이너 `gitea-runner` | 소유자 결정(2026-11-07) | +| 이미지 | `docker.io/gitea/runner:5.4.1-dind@sha256:8bcb489f9dd6be500de22bcaa8512ef57b81ae50315db8c7a1dc1b74978a76f4` | 공식 runner. `gitea/act_runner`는 Docker Hub에서 deprecated이고 `gitea/runner`로 옮겨졌다 | +| 동시 실행 | `runner.capacity: 1` | desktop은 다른 빌드·Docker 작업과 함께 쓴다 | +| label | `ubuntu-latest` → `docker.gitea.com/runner-images:ubuntu-24.04-v26.11.03@sha256:b96ba465021b1a4c6a1c9e79220c2b9bfad0f29b09dbb528bbfb35411443a3a4` | 공식 runner 이미지 하나, 날짜 태그와 digest로 고정 | +| 재시작 | `restart: always`, Docker service `enabled` | 컨테이너 종료·Docker 재시작·재부팅 뒤 다시 뜬다 | +| 등록 범위 | 사용자 `donghyeon.kang` | 그 사용자 소유 repository의 job만 받는다 | +| 자원 상한 | CPU 6, 메모리 10g | 아래 「자원 상한」 | + +버린 대안: + +- `gitea/act_runner:0.6.1`: Docker Hub 설명이 "Deprecated Gitea runner. Moved to + gitea/runner"이고 2026-04-30 이후 갱신이 없다. +- 호스트 `docker.sock`을 job에 주는 기본 이미지: job이 desktop Docker를 root처럼 쓴다. +- `-dind-rootless`: 격리는 더 강하지만 Testcontainers 호환(rootless 소켓 경로, + Ryuk, 포트 노출)을 따로 확인해야 해서 이번에는 고르지 않았다. + +Java·Go 같은 큰 toolchain은 기본 runner 이미지에 없다. workflow가 +`actions/setup-java` 같은 setup action으로 설치한다. 기본 이미지에는 Node.js, +git, Docker CLI(Buildx, Compose 포함)가 있다. + +## job 안의 Docker와 위험 + +Testcontainers처럼 job이 Docker를 써야 하므로 job 컨테이너에 Docker API를 준다. +공식 runner가 주는 방법은 세 가지다. + +| 방법 | job이 쓰는 daemon | 위험 | +| --- | --- | --- | +| 기본 이미지 + 호스트 `/var/run/docker.sock` | desktop 호스트 daemon | job이 `docker run --privileged -v /:/host`로 호스트 root를 얻는다. 다른 컨테이너·이미지·볼륨도 지울 수 있다 | +| **`-dind` (선택)** | runner 컨테이너 안의 별도 daemon | 호스트 소켓과 호스트의 다른 컨테이너에는 닿지 않는다. 다만 runner 컨테이너가 `--privileged`이므로, job이 안쪽 daemon에 privileged 컨테이너를 띄우면 여전히 호스트 장치에 닿을 수 있다 | +| `-dind-rootless` | runner 안의 rootless daemon(UID 1000) | 탈출해도 UID 1000 권한이다. AppArmor `rootlesskit` 프로필, slirp4netns가 필요하고 Testcontainers 호환을 따로 확인해야 한다 | + +고른 방법은 공식 문서가 권장하는 `-dind`다. 막은 것과 남은 것은 다음과 같다. + +- 호스트 Docker 소켓은 runner에도 job에도 mount하지 않는다. job은 runner의 Docker + proxy를 거쳐 안쪽 daemon만 쓴다. +- job 컨테이너는 privileged가 아니다(`container.privileged: false`). workflow의 + `container.options`에 있는 `--privileged`, `--cap-add`, `--device` 같은 옵션은 + runner가 버린다. +- workflow가 호스트 경로나 runner 볼륨을 mount하지 못한다(`container.valid_volumes: []`). +- job이 proxy로 만든 컨테이너·네트워크·볼륨은 job이 끝나면 지운다(`container.sweep: true`). +- runner를 `donghyeon.kang` 사용자 범위로만 등록해 다른 사용자의 repository job은 받지 않는다. +- **남은 위험:** job이 Docker API로 안쪽 daemon에 `--privileged` 컨테이너를 띄우는 것은 + proxy가 막지 않는다. 그래서 신뢰하는 repository의 workflow만 이 runner에서 돌린다. + 외부 기여자의 fork PR workflow를 승인 없이 돌리지 않는다. 더 강한 격리가 + 필요하면 `-dind-rootless`나 job마다 새로 만드는 ephemeral VM으로 옮긴다. + +## 자원 상한 + +desktop은 12코어, 메모리 31GiB다(2026-11-07 `nproc`, `free -g`). 다른 세션의 +Gradle·Docker 게이트는 `flock /tmp/claude-gates/heavy.lock`으로 서로 순서를 +지키지만 runner job은 그 lock을 쓰지 않는다. 그래서 runner 컨테이너에 상한을 +걸어 job이 desktop 자원의 절반을 넘지 못하게 한다. + +- `cpus: 6`: 12코어의 절반이다. +- `mem_limit: 10g`: 절반(15.5GiB)보다 작다. Gradle daemon과 test JVM, Testcontainers + PostgreSQL 컨테이너를 함께 돌릴 여유를 두고, 다른 세션 게이트가 쓸 메모리를 남긴다. +- dind 안의 daemon과 job 컨테이너가 모두 runner 컨테이너 cgroup 안에서 돌기 때문에 + 이 상한이 CI 작업 전체에 걸린다. 메모리가 넘치면 커널이 runner 컨테이너 안의 + 프로세스를 종료하므로 job이 OOM으로 실패한다. 그때는 상한을 올리기 전에 job의 + JVM heap 설정부터 본다. + +## 디스크와 정리 + +안쪽 daemon의 데이터(job 이미지, Testcontainers 이미지, 빌드 cache)는 이름 있는 +볼륨 `gitea-runner_docker`에 쌓인다. desktop root 디스크는 228G 중 182G를 쓰고 +있다(2026-11-07, 여유 34G). 예상 사용량은 다음과 같다. + +| 항목 | 크기 | +| --- | --- | +| runner 이미지(`gitea/runner:5.4.1-dind`) | 약 133MB | +| job 이미지(`runner-images:ubuntu-24.04`) | amd64 압축 543MB, 안쪽 daemon에서 2.325GB(2026-11-07 실측) | +| Testcontainers 이미지(PostgreSQL, Ryuk 등) | 수백 MB | +| actions/cache(`/data/cache`) | 상한 5GB | + +runner는 job이 끝나면 job 컨테이너와 proxy로 만든 컨테이너·네트워크·볼륨을 +지우지만(`container.sweep: true`) 이미지는 지우지 않는다. 정리 주기는 다음과 같다. + +- 매주 한 번 사용량을 본다. + + ```bash + docker system df -v | grep gitea-runner + docker exec gitea-runner docker system df + ``` + +- 안쪽 사용량이 15GB를 넘거나 root 디스크 여유가 20G 아래로 내려가면 job이 없을 때 + 안쪽 이미지를 정리한다. 고정된 job 이미지도 지워지므로 다음 job이 압축 약 543MB를 + 다시 받는다. + + ```bash + docker exec gitea-runner docker image prune -a -f + docker exec gitea-runner docker builder prune -f + ``` + +- 볼륨 `gitea-runner_docker` 자체를 지우는 것은 runner를 완전히 지울 때만 한다 + (「되돌리기」). 등록 파일이 있는 `gitea-runner_data`와 섞지 않는다. + +## 파일과 위치 + +| 무엇 | 위치 | +| --- | --- | +| 원본 설정 | 이 디렉터리의 `compose.yaml`, `config.yaml` | +| desktop 실행 폴더 | `/home/donghyeon/.local/share/gitea-runner/` (`compose.yaml`, `config.yaml`, `secrets/`) | +| 등록 파일 `.runner` | Docker 볼륨 `gitea-runner_data`의 `/data/.runner` (runner 자격 증명, Secret으로 취급) | +| job 이미지·안쪽 daemon 데이터 | Docker 볼륨 `gitea-runner_docker` (`/var/lib/docker`) | +| actions/cache 저장소 | `gitea-runner_data`의 `/data/cache`, 상한 5GB | + +`compose.yaml`은 Git checkout에서 바로 실행하지 않는다. checkout의 branch가 +바뀌면 runner 설정도 조용히 바뀌기 때문이다. 실행 폴더에 복사하고 SHA-256을 비교한다. + +## 설치와 등록 + +전제: Gitea 서버에서 Actions가 켜져 있어야 한다 +([Gitea 서비스](../../services/gitea/README.md)). 등록 token은 사용자 +`donghyeon.kang`의 설정 → Actions → Runners 화면이나 API +`POST /api/v1/user/actions/runners/registration-token`(Gitea 1.27)에서 받는다. token은 runner를 +등록할 수 있는 자격 증명이므로 출력·로그·Git에 남기지 않는다. + +1. 실행 폴더를 만들고 설정 두 개를 복사한다. + + ```bash + install -d -m 0700 ~/.local/share/gitea-runner ~/.local/share/gitea-runner/secrets + install -m 0644 infrastructure/ci/gitea-runner/compose.yaml infrastructure/ci/gitea-runner/config.yaml ~/.local/share/gitea-runner/ + sha256sum infrastructure/ci/gitea-runner/*.yaml ~/.local/share/gitea-runner/*.yaml + ``` + +2. 등록 token을 편집기로 `~/.local/share/gitea-runner/secrets/registration-token`에 + 한 줄로 저장하고 권한을 `0600`으로 둔다. + +3. 이미지를 받고 digest를 확인한 뒤 시작한다. + + ```bash + cd ~/.local/share/gitea-runner + docker compose pull + docker compose up -d + docker compose logs runner + ``` + + 처음 시작할 때 `/data/.runner`가 없으면 token file로 등록하고 daemon을 띄운다. + 로그에 `Runner registered successfully`가 나와야 한다. + +4. 등록이 끝나면 token file을 지운다. `.runner`가 있으면 다시 읽지 않는다. + + ```bash + rm ~/.local/share/gitea-runner/secrets/registration-token + ``` + +5. Gitea에서 runner가 online인지 본다. API + `GET /api/v1/user/actions/runners`의 `status`가 `online`이고 label이 + `ubuntu-latest`여야 한다. + +## 운영 + +- 상태: `docker compose ps`, `docker compose logs --tail 100 runner` +- 설정 변경: 이 디렉터리를 고친 뒤 실행 폴더에 다시 복사하고 + `docker compose up -d --force-recreate`. runner는 시작할 때만 설정을 읽는다. + 재생성은 실행 중인 job을 취소하므로 job이 없을 때 한다. +- 이미지 올리기: `compose.yaml`의 tag와 digest를 함께 바꾼다. 등록 파일은 그대로 유효하다. + major가 바뀌면 [Upgrading](https://docs.gitea.com/runner/upgrade/)의 호환 변경을 먼저 읽는다. +- 디스크: 「디스크와 정리」의 주기를 따른다. + +## 되돌리기 + +runner만 내리기(등록 유지): + +```bash +cd ~/.local/share/gitea-runner && docker compose down +``` + +runner를 완전히 지우기: + +1. Gitea 사용자 설정 → Actions → Runners에서 `desktop-runner`를 삭제한다. +2. 컨테이너와 볼륨을 지운다. `.runner`와 job 이미지가 함께 사라진다. + + ```bash + cd ~/.local/share/gitea-runner && docker compose down --volumes + ``` + +3. 실행 폴더 `~/.local/share/gitea-runner`를 지운다. + +Gitea 서버의 Actions까지 끄려면 `services/gitea/profiles/oidc/values/baseline.yaml`을 +되돌리고 `scripts/bootstrap/apply-gitea-oidc.sh --execute`로 다시 적용한다. + +## 적용 기록 + +2026-11-07 (KST) + +- 18:3x 서버: Gitea values 커밋 `87dee1f`를 소유자가 `apply-gitea-oidc.sh --execute`로 + 적용했다(manifest SHA-256 `f082cba5…abbc`). `GET /api/v1/user/actions/runners`가 + 200을 돌려주고 등록 token API가 동작한다. +- 18:32 등록: 등록 token을 API로 받아 실행 폴더의 `secrets/registration-token`(0600)에 + 화면 출력 없이 저장하고 `docker compose up -d`로 시작했다. 로그에 + `Runner registered successfully`, `labels: [ubuntu-latest], declare successfully`가 + 나왔다. 등록 뒤 token file을 지웠다. +- 확인: Gitea API에서 `desktop-runner` id 1, `status=online`, `busy=false`. + `docker inspect`에서 `NanoCpus=6000000000`, `Memory=10737418240`, + `Privileged=true`, `RestartPolicy=always`, publish한 port 없음. +- 안쪽 daemon: Docker `29.9.3`, cgroup v2. compose network `gitea-runner_default`의 + `tcp://0.0.0.0:2376`도 열리지만 `--tlsverify`이고 client 인증서가 컨테이너 밖에 + 없으며 host에 publish하지 않는다. +- 재시작: `docker restart gitea-runner` 뒤 다시 등록하지 않고 같은 `.runner`로 daemon이 + 올라왔다. 호스트 재부팅은 시험하지 않았다(`restart: always`, Docker service `enabled`). +- 첫 job을 빠르게 하려고 job 이미지를 안쪽 daemon에 미리 받았다. 안쪽 `docker system df` + 2.325GB, 호스트 볼륨 `gitea-runner_docker` 2.234GB. root 디스크 여유는 34G에서 31G로 줄었다. +- 등록 token은 Gitea에서 reset하기 전까지 다른 runner도 등록할 수 있다. 더 등록할 + 계획이 없으면 사용자 설정 → Actions → Runners에서 token을 reset한다. + +## 출처 + +- [Gitea Runner: Install with Docker](https://docs.gitea.com/runner/installation/docker/) +- [Gitea Runner: Registration](https://docs.gitea.com/runner/registration/) +- [Gitea Runner: Configuration](https://docs.gitea.com/runner/configuration/), + [Example configuration](https://docs.gitea.com/runner/reference/config-example/) +- [Gitea Runner: Labels](https://docs.gitea.com/runner/labels/), + [Jobs (Docker inside jobs)](https://docs.gitea.com/runner/jobs/) +- [gitea/runner v5.4.1 release](https://gitea.com/gitea/runner/releases/tag/v5.4.1), + [container.sweep opt-in 변경](https://gitea.com/gitea/runner/pulls/1389) +- [gitea/runner-images](https://gitea.com/gitea/runner-images) +- [Gitea 1.27 config cheat sheet: Actions, Repository](https://docs.gitea.com/1.27/administration/config-cheat-sheet) diff --git a/infrastructure/ci/gitea-runner/compose.yaml b/infrastructure/ci/gitea-runner/compose.yaml new file mode 100644 index 0000000..8973b99 --- /dev/null +++ b/infrastructure/ci/gitea-runner/compose.yaml @@ -0,0 +1,40 @@ +# Single Gitea Actions runner on the desktop host (docker compose). +# Copy this file and config.yaml to the runtime folder named in README.md +# and run `docker compose up -d` there. Do not run it from a Git checkout. +name: gitea-runner + +services: + runner: + # Official Gitea Runner 5.4.1, dind flavour, pinned by index digest. + image: docker.io/gitea/runner:5.4.1-dind@sha256:8bcb489f9dd6be500de22bcaa8512ef57b81ae50315db8c7a1dc1b74978a76f4 + container_name: gitea-runner + hostname: desktop-runner + # Starts again after a crash, a Docker restart and a host reboot. + restart: always + # Required by the bundled Docker daemon that runs the jobs. Jobs never + # see the host Docker socket. See README.md for what this still allows. + privileged: true + environment: + GITEA_INSTANCE_URL: https://git.learn.hyeonworks.com + GITEA_RUNNER_NAME: desktop-runner + # Read only while /data/.runner does not exist yet. + GITEA_RUNNER_REGISTRATION_TOKEN_FILE: /run/gitea-runner/registration-token + CONFIG_FILE: /config.yaml + volumes: + - ./config.yaml:/config.yaml:ro + - ./secrets:/run/gitea-runner:ro + - data:/data + - docker:/var/lib/docker + # Every job container runs inside this container's cgroup, so these + # limits cap all CI work on the shared desktop. + cpus: 6 + mem_limit: 10g + logging: + driver: json-file + options: + max-size: 10m + max-file: "3" + +volumes: + data: + docker: diff --git a/infrastructure/ci/gitea-runner/config.yaml b/infrastructure/ci/gitea-runner/config.yaml new file mode 100644 index 0000000..5a7f2ec --- /dev/null +++ b/infrastructure/ci/gitea-runner/config.yaml @@ -0,0 +1,38 @@ +# Gitea Runner 5.4.1 configuration for the single desktop runner. +# Every key not listed here keeps the default printed by +# `gitea-runner config generate` for that version. + +log: + level: info + +runner: + # The dind image starts in /data, a named volume. The registration file + # holds the runner credential and must stay on that volume. + file: .runner + # One job at a time. The desktop also runs other build and Docker work. + capacity: 1 + # The only label. runs-on: ubuntu-latest runs in this image, pinned by tag + # and index digest so a moved tag cannot change the job environment. + labels: + - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-24.04-v26.11.03@sha256:b96ba465021b1a4c6a1c9e79220c2b9bfad0f29b09dbb528bbfb35411443a3a4" + +cache: + enabled: true + dir: /data/cache + # The desktop root disk is shared. Bound the actions/cache store. + size_limit: 5GB + +container: + # Job containers stay unprivileged. Workflow options that could escape the + # container (--privileged, --cap-add, --device, ...) are dropped. + privileged: false + # Workflows may not bind-mount runner volumes or host paths. + valid_volumes: [] + # Empty: jobs get the runner's own Docker daemon (the dind daemon inside + # the runner container) through the runner's Docker proxy, so + # Testcontainers works. The host Docker socket is never mounted. + docker_host: "" + # CI-only runner: remove the containers, networks and volumes a job + # created through the proxy when the job ends. + sweep: true + force_pull: false