Nexus Docker Mirror Cutover

Nexus docker-mirror + buildcache cutover (registry-cache CT113 대체)

이 문서는 독립 registry-cache LXC(CT113 @ 10.10.10.150: docker.io 프록시 :5000, ghcr 프록시 :5002, 빌드 캐시 :5001, 6개 노드용 k3s 미러)를 단일 Nexus 인스턴스로 흡수한 역사적 기록입니다. 이것은 Nexus 통합 P3의 비가역 라이브 스텝이었고, 노드별로 롤백을 준비한 채 신중하게 적용됐습니다. cutover는 완료됐습니다(CT113는 2026-06-18 파괴). 이 페이지는 절차의 기록 + 롤백 참조로 유지합니다.

패키지와 Docker Hub pull-through 캐시는 Nexus가, OCI 빌드 레이어 캐시는 GHCR가 소유합니다 — Build & Package Cache Topology 참고.

cutover 전체 흐름

flowchart TB
  s1["Step 1\nNexus repo provision (additive, safe)\nprovision_repos.py"] --> s2["Step 2\n8083 노드-접근 노출\nNodePort 30083 -> 8083"]
  s2 --> s3["Step 3\nk3s registry 미러 cutover\n노드별, 하나씩 + verify"]
  s3 --> s4["Step 4\nCI buildcache evaluated\nNexus reserved until HTTPS writer"]
  s4 --> s5["Step 5\nCT113 해체 (DONE 2026-06-18)"]
  s3 -. 실패 시 .-> rb["롤백: 옛 registries.yaml 복원\n-> CT113 + k3s 재시작"]

전제 조건 (저장소 안)

Nexus docker-dockerhub (registry-1.docker.io 프록시)와 docker-group (멤버 docker-internal + docker-dockerhub, read connector 포트 8083). GHCR은 직접 인증 경로입니다.
platform/k8s/apps/nexus: Service + Deployment이 포트 8083(docker-group) 노출.

Step 1 — 새 repo provision (additive, 안전)

Nexus ClusterIP에 도달 가능한 노드에서(원래 P1 provisioning대로):

NEXUS_URL=http://<nexus-clusterip>:8081 NEXUS_ADMIN_PASSWORD=<admin-pw-from-OpenBao> \
  python3 ops/nexus/provision_repos.py

Idempotent. 검증: docker-group이 8083에서 V2로 응답하고 docker.io pull을 서빙:

curl -s -o /dev/null -w '%{http_code}' http://<nexus>:8083/v2/   # 401/200 = connector up

Step 2 — 8083 노드-접근 노출

docker-group(8083)은 registries.yaml용으로 모든 k3s 노드에서 도달 가능해야 합니다. nexus Service에 NodePort(예: 30083 -> 8083)를 추가하거나, kube-proxy 경유로 노드가 ClusterIP :8083에 도달 가능한지 확인하세요(P1은 노드 146에서 10.43.x:8081 사용). 팟 재스케줄 안정성을 위해 노드별 NodePort + http://127.0.0.1:30083를 선호합니다.

Step 3 — k3s registry 미러 cutover (노드별, 하나씩)

토폴로지 registry_cache.k3s_mirror_nodes의 각 노드(pve-worker0:112, pve-worker1:143, pve-worker2:129, pve-worker3:145, pve1:141, pve2:146)에서 /etc/rancher/k3s/registries.yaml를 재작성:

mirrors:
  docker.io:
    endpoint: ["http://127.0.0.1:30083"]
configs:
  "127.0.0.1:30083":
    auth: { username: "workspace-tools-puller", password: "<FRACTALOPS_NEXUS_PULL_PASSWORD from OpenBao runtime scope>" }

그다음 systemctl restart k3s(control) / k3s-agent(workers). 다음 노드로 넘어가기 전에 fresh pull을 검증하세요(crictl pull docker.io/library/busybox:latest). ghcr.io mirror는 제거하고 직접 registry 인증을 유지합니다.

# 노드에서 cutover 후 검증
crictl pull docker.io/library/busybox:latest && echo "pull OK"

Step 4 — CI 이미지 buildcache writer

토폴로지 registry_cache.buildcache_ref(10.10.10.150:5001/fractalops/buildcache)는 Nexus docker-internal hosted repo로 repoint됐습니다. 다만 CI registry cache writer는 다시 HTTPS GHCR fallback으로 둡니다. 이유는 BuildKit registry cache exporter가 plain-HTTP nexus.nexus.svc.cluster.local:8082에 HTTPS로 붙어 cache import/export가 실패하기 때문입니다. Nexus docker-group pull-through mirror는 계속 CI base/layer read 경로로 사용합니다.

Cloudflare nexus-buildcache.yamon.io edge는 외부 projection으로 남기지만 대용량 OCI layer cache push 경로가 아닙니다. 그 경로는 edge upload limit에서 413 Payload Too Large를 맞을 수 있습니다. Nexus를 CI buildcache writer로 다시 승격하려면 내부 HTTPS/TLS 경로(예: Gateway API/HTTPRoute)와 명시적 FRACTALOPS_BUILDCACHE_REGISTRY가 먼저 필요합니다. cache_to/from은 이미 ignore-error=true를 달고 있어 오설정은 빌드 실패가 아니라 캐시 미스로 degrade됩니다.

Step 5 — CT113 해체 — DONE (2026-06-18 LXC 파괴; repo 정리 2026-06-20)

LXC CT113 정지 + 파괴 (2026-06-18).
사용되지 않던 registry-cache installer와 테스트 삭제.
토폴로지 registry_cache 블록을 Nexus로 repoint(host_ip = Nexus ClusterIP, buildcache_ref: nexus.nexus.svc.cluster.local:8082/..., 포트 8082/8083); 역사적 키 이름은 소비되는 빌드-캐시 config으로 유지(죽은 10.10.10.150/CT id 없음).
문서를 단일 Nexus 캐시 평면에 맞춤(operations/docker-cache, current-stack-IA, requirements, manual-ko).

pip-cache / apt-cacher (P4) — 유사

pip: uv/pip 인덱스를 https://nexus.yamon.io/repository/pypi-group/simple/(또는 in-cluster http://nexus.nexus.svc:8081/repository/pypi-group/simple/)로 지정; pip-cache LXC 해체.
apt: sources를 https://nexus.yamon.io/repository/apt-debian/로 지정; apt-cacher LXC 해체.
apt-debian은 debian/trixie만 프록시. 어떤 이미지든 ubuntu 미러를 풀면 apt-ubuntu 프록시 repo를 먼저 추가.

롤백 (전체 cutover)

각 노드의 직전 registries.yaml(CT113 엔드포인트) 복원 + k3s 재시작; 토폴로지 buildcache_ref 되돌리기. CT113는 Step 5까지 켜져 있었으므로 cutover 동안 롤백이 항상 가능했습니다.