ORAS_CACHE·디스크 수위, 동시 계층과 4→12→30→90초 백오프, digest·SHA-256 수락 표, FAQ. 본문은 Git shallow·Webhook 시리즈·단일 패키지 매니저 목록과 겹치지 않게 OCI 레이어형 아티팩트에만 초점을 둡니다. 홈·블로그 목록·Helm OCI 국경 매트릭스·GHCR·컨테이너 레지스트리 풀은 공개 페이지만 연결했습니다.
시나리오와 병목
공유 원격 Mac 풀에서는 xcodebuild·파생 데이터·OCI blob 캐시가 한 NVMe에 몰리기 쉽고, 국경 WAN에서는 매니페스트 왕복 RTT와 레이어 동시 풀이 체감 지연을 지배합니다. HTTP 429는 종종 순수 대역보다 동시 클라이언트·아티팩트 본수에서 먼저 옵니다. CI 안정성은 digest 고정과 펼친 파일의 체크섬 검수에서 갈립니다.
oras pull --concurrency와 잡 안 동시 아티팩트부터 낮춥니다.ORAS_CACHE를 빌드 산출·DerivedData와 다른 경로·가능하면 다른 볼륨에 둡니다.shasum -a 256 -c 이중 게이트를 권장합니다.실행 이미지 중심 파이프라인은 컨테이너 레지스트리 풀 매트릭스와 역할을 나누는 것이 검색·운영 모두에 유리합니다.
ORAS vs 전통 아티팩트 저장소
ORAS는 OCI Distribution 호환 레지스트리에 올린 비이미지 아티팩트를, Docker와 유사한 인증·레이어 전송으로 다루는 CLI·라이브러리 생태계입니다. 2026년에는 원격 빌드 노드가 늘면서 “컨테이너 + 차트 + 바이너리 번들”을 한 Registry 정책으로 묶는 팀이 늘고, 그때 선택·비교가 중요해집니다.
| 방식 | 강점 | 약점·비용 | 이렇게 고름 |
|---|---|---|---|
| OCI + ORAS | digest 고정, 레이어 재사용, Helm·이미지와 동일 엔드포인트 | 매니페스트·미디어타입 학습 | SDK tarball·검증 번들·가중치의 판본 핀닝(pinning) |
| 범용 아티팩트 저장소(Artifactory 등) | 감사·ACL·레거시 통합 | OCI 외 API·클라이언트 증가 | 규정상 전용 상품만 허용될 때 |
| 오브젝트 스토리지 + 프리사인 | 구현이 단순 | 중복 전송·디듑 약함 | 단발 대용량 단일 파일 |
선정 요약: 이미 Helm OCI나 이미지를 같은 Registry에 두었다면 ORAS로 비컨테이너까지 통합하는 편이 운영 단가가 낮습니다.
원격 Mac의 캐시 디렉터리와 디스크 수위
ORAS_CACHE는 레이어 임시·재개에 쓰이며, 빌드 출력과 같은 APFS 볼륨이면 링크 단계와 쓰기 경쟁으로 p95가 나빠질 수 있습니다.
| 계층 | 경로 예(macOS) | 역할 | 비고 |
|---|---|---|---|
ORAS_CACHE |
$HOME/Library/Caches/oras-ci/$CI_JOB_ID |
레이어 히트·재시도 | 잡마다 하위 디렉터리로 오염 격리 |
| 풀 출력 | $CI_WORKSPACE/.ci/oras-out |
펼친 산출·검증 입력 | 이후 스텝은 읽기 전용 권장 |
| 풀 공유 캐시 | 별도 APFS 볼륨·정책 허용 시 외장 | 노드 간 재사용 | 동시 풀·디스크 FAQ의 임계와 병용 |
디스크 수위(운영 복붙): 데이터 볼륨 사용률 80%·85%·90%에서 각각 경고·스로틀·풀 중단 게이트. 여유 공간 ≥25GB → 12GB → 6GB 삼단을 병행하면 온콜이 읽기 쉽습니다.
국경 대역폭과 재시도 매개변수
아래 값은 초기값입니다. p95 지연·429 비율에 따라 ±1계층만 조정하세요. 실패 백오프 임계(초): 1회차 4, 2회차 12·동시 --concurrency 1단계 감소, 3회차 30, 4회차 90, 5회차 이후 중단(필요 시 상한 120으로 클립). 5xx·연결 리셋에도 동일 사다리를 적용해도 무방합니다.
| 러너 프로필 | --concurrency |
잡 내 동시 아티팩트 | 429/5xx 백오프(초) |
|---|---|---|---|
| 보수적·공유 풀·불안정 WAN | 2 | 1 | 4 → 12(−동시) → 30 → 90 (최대 120) |
| 균형·NVMe·안정 이그레스 | 3 | 1~2 | 동일(429 다발 시 2로 하향) |
| 공격적·전용 Mac·동일 리전 미러 | 4~6 | 2~3 | 1→3→9→30(최대 60) — 자체 캐시 뒤에서만 |
셸 조각(복사): 플레이스홀더는 대문자 스네이크로 치환하세요.
# 국경 WAN 초기값(동일 리전이면 ORAS_CONCURRENCY=4~6까지 실험)
export ORAS_CACHE="${ORAS_CACHE:-$HOME/Library/Caches/oras-ci/$CI_JOB_ID}"
export ORAS_CONCURRENCY="${ORAS_CONCURRENCY:-3}"
mkdir -p "$ORAS_CACHE" "${ORAS_OUT:-$CI_WORKSPACE/.ci/oras-out}"
printf '%s' "${REGISTRY_TOKEN}" | oras login "${REGISTRY_HOST}" -u "${REGISTRY_USER}" --password-stdin
for i in 1 2 3 4 5; do
oras pull "${ORAS_REF}" -o "${ORAS_OUT:-$CI_WORKSPACE/.ci/oras-out}" --concurrency "${ORAS_CONCURRENCY}" && break
case "$i" in
1) sleep "${B1:-4}";;
2) sleep "${B2:-12}"; ORAS_CONCURRENCY=$(( ORAS_CONCURRENCY > 1 ? ORAS_CONCURRENCY - 1 : 1 ));;
3) sleep "${B3:-30}";;
4) sleep "${B4:-90}";;
*) echo "oras pull 포기"; exit 1;;
esac
doneCI 게이트 수용(체크섬·descriptor)
「풀 성공」만으로는 부족한 팀은 descriptor digest와 파일 SHA-256 이층으로 막습니다. JSON-LD는 BlogPosting·Article 본문과 BreadcrumbList 내비에 더해, 절차는 HowTo, Q&A는 FAQPage로 나누면 리치 결과에 유리합니다.
# descriptor digest (jq 예시)
test "$(oras manifest fetch "${ORAS_REF}" --descriptor | jq -r '.digest')" = "${EXPECTED_DESCRIPTOR_DIGEST}"
# 펼친 파일 — expected.sha256 은「해시 경로」형식(shasum -a 256 출력 그대로)
shasum -a 256 -c expected.sha256| 게이트 | 합격 기준 | 실패 시 흔한 원인 |
|---|---|---|
| 매니페스트 digest | CI 변수 기대값과 완전 일치 | 변동 태그, 미러 지연 |
| artifactType / 미디어타입 | 허용 목록 포함 | 잘못된 리포지토리·실험 태그 |
| 파일 SHA-256 | shasum -a 256 -c 종료 코드 0 |
재압축·CRLF·부분 다운로드 |
| 재시도 로그 | 429 시 백오프 초·ORAS_CONCURRENCY 변화가 남음 |
무한 재시도, 동시성 미조정 |
FAQ
Q. oras pull과 docker pull을 어떻게 나누나요?
A. 실행 이미지는 docker 계열, digest로 고정할 바이너리·데이터 번들은 ORAS가 단순합니다. 캐시 디렉터리는 반드시 분리하세요.
Q. digest는 맞는데 shasum이 깨집니다.
A. gzip 레벨이나 개행 변환을 의심하고, 동일 파이프라인에서 expected.sha256을 다시 생성해 고정합니다.
Q. 429가 잦습니다.
A. --concurrency를 내리고 동시 아티팩트를 1~2본으로 제한한 뒤, 4→12→30→90초 사다리를 적용하세요. 효과가 없으면 리전 미러·잡 분산을 검토합니다.
요약
국경 환경에서는 동시 계층·캐시 경로·백오프 임계·이중 체크섬을 한 번에 문서화해야 재현성이 생깁니다. OCI 아티팩트화는 Registry 운영을 단순화하지만, Apple Silicon NVMe 수위를 무시하면 오히려 전체 잡이 느려질 수 있습니다.