시스템 및 상태
활성 상태(liveness), 준비 상태(readiness), 메트릭, OpenAPI 문서, 서버 기능.
이 그룹의 작업과 각 작업의 액세스 규칙, 재시도 규칙, 매개 변수, 응답입니다. 모든 요청에는 키가 포함됩니다: Authorization: Bearer <키>(“인증” 참조).
작업
상세 준비 상태 확인
GET HEAD /health/ready
액세스: 유효한 키 또는 세션 · 재시도: 반복해도 안전함(읽기)
데이터베이스와 스토리지가 응답하면 ready로 응답하며, 이 노드의 role(api 또는 reader), 지금 쓰기를 받는지 여부(writable 값은 읽기 게이트웨이이거나 디스크가 여유 공간 예비분을 지키는 동안 false입니다), 읽기 게이트웨이의 공유 다운로드 슬롯, 업로드·다운로드 수용량과 대역폭의 집계 카운터를 함께 제공합니다. 서버가 드레인 중이거나 종속 서비스를 사용할 수 없으면 Retry-After와 함께 503으로 응답합니다. 요청 한도에 포함되지 않으며, 키 없이 쓰는 로드 밸런서에는 getReadinessStatus 작업을 사용합니다.
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
role | string | 예 | api, reader 중 하나 |
sharedDownloads | object | 예 | null일 수 있음 |
sharedDownloads.slot | integer | 예 | 0 이상 |
sharedDownloads.slots | integer | 예 | 0 이상 |
sharedDownloads.active | boolean | 예 | — |
sharedDownloads.leaseSeconds | integer | 예 | 0 이상 |
status | string | 예 | ready 중 하나 |
writable | boolean | 예 | — |
replication | object | 아니요 | null일 수 있음 |
replication.copies | integer | 예 | 0–16 |
replication.required | integer | 예 | 1–16 |
replication.singleCopyUntil | string (date-time) | 예 | null일 수 있음 |
replication.node | string | 아니요 | 63자 이하 |
replication.profile | string | 아니요 | ha-2, ha-3 중 하나 |
replication.peers | object 배열 | 아니요 | 요소 16개 이하 |
replication.peers[].name | string | 예 | 63자 이하 |
replication.peers[].connected | boolean | 예 | — |
replication.peers[].disk | string | 예 | 24자 이하 |
replication.peers[].complete | boolean | 예 | — |
replication.peers[].witness | boolean | 예 | — |
transfers | object | 예 | — |
transfers.uploads | object | 예 | — |
transfers.uploads.admission | object | 예 | — |
transfers.uploads.bandwidth | object | 예 | — |
transfers.uploads.sessions | object | 아니요 | — |
transfers.downloads | object | 예 | — |
transfers.downloads.admission | object | 예 | — |
transfers.downloads.bandwidth | object | 예 | — |
transfers.downloads.sessions | object | 아니요 | — |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/health/ready" \
-H "Authorization: Bearer $ARKVORY_TOKEN"서버 기능과 제한 조회
GET HEAD /api/v1/capabilities
액세스: 유효한 키 또는 세션 · 재시도: 반복해도 안전함(읽기)
API 버전, 게이트웨이 역할, 기능 플래그(예: selfRegistration, mirrorFeed)와 클라이언트가 맞춰야 하는 제한을 반환합니다. 제한에는 가장 큰 객체(maxObjectBytes, 10진 문자열), 최소·최대 멀티파트 세그먼트 크기, 최대 파트 수, 최대 페이지 크기가 있습니다. 클라이언트를 시작할 때 한 번 읽으며, 리소스 목록은 포함하지 않습니다.
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
apiVersions | string 배열 | 예 | — |
gatewayRole | string | 예 | api, reader 중 하나 |
features | boolean 맵 | 예 | — |
limits | object | 예 | — |
limits.maxObjectBytes | string | 아니요 | 10진수 숫자로 쓴 정수이며 문자열로 전송 |
limits.partBytes | integer | 아니요 | 가장 작은 멀티파트 세그먼트입니다. |
limits.maxPartBytes | integer | 아니요 | — |
limits.maxParts | integer | 아니요 | — |
limits.maxPageSize | integer | 아니요 | — |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/capabilities" \
-H "Authorization: Bearer $ARKVORY_TOKEN"로드 밸런서용 준비 상태 확인
GET HEAD /health/status
액세스: 누구나, 키 없이 · 재시도: 반복해도 안전함(읽기)
키가 필요 없고 세부 정보도 반환하지 않습니다. {"status":"ready"} 본문과 함께 200을 반환하거나, unavailable 또는 draining 상태와 Retry-After를 포함한 503을 반환합니다. 종속 서비스 검사는 공유되며 1초 동안 캐시되므로 잦은 프로브가 데이터베이스에 부하를 주지 않고, 프로브는 요청 한도에 포함되지 않습니다.
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
status | string | 예 | ready, unavailable, draining 중 하나 |
응답: 200, 400, 403, 503
예제
curl -X GET "$ARKVORY_URL/health/status"프로세스 생존 확인
GET HEAD /health/live
액세스: 누구나, 키 없이 · 재시도: 반복해도 안전함(읽기)
프로세스가 HTTP에 응답하는 동안 {"status":"ok"} 본문과 함께 200을 반환합니다. 종속 서비스를 검사하지 않으므로 재시작 여부를 판단할 때 사용하고, 트래픽 수신 여부는 getReadinessStatus로 판단합니다.
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
status | string | 예 | ok 중 하나 |
응답: 200, 400, 403, 503
예제
curl -X GET "$ARKVORY_URL/health/live"OpenAPI 문서 조회
GET HEAD /api/v1/openapi.json
액세스: 유효한 키 또는 세션 · 재시도: 반복해도 안전함(읽기)
이 배포의 OpenAPI 3.0 문서를 반환하며, 각 작업의 접근, 재시도, 게이트웨이 규칙을 설명하는 x-arkvory-* 확장을 포함합니다. surface(discovery, identity, catalog, transfers, administration, operations 중 하나)를 지정하면 해당 영역만 반환하며, 알 수 없거나 반복된 쿼리 매개변수는 400입니다. 문서는 모든 호출자에게 같고 어떤 권한도 부여하지 않으므로, 현재 자격 증명으로 호출할 수 있는 작업은 listVisibleOperations로 확인합니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
surface | 쿼리 | string | 아니요 | discovery, identity, catalog, transfers, administration, operations 중 하나; Documentation view only; not filtered by caller permissions. |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
openapi | string | 예 | 3.0.3 중 하나 |
info | object | 예 | — |
paths | object | 예 | — |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/openapi.json" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Prometheus 메트릭 조회
GET HEAD /health/metrics
액세스: 유효한 키 또는 세션 · 재시도: 반복해도 안전함(읽기)
스크레이퍼를 위해 프로세스 메트릭을 Prometheus 텍스트 형식(text/plain; version=0.0.4)으로 반환합니다. 카운터와 히스토그램은 이 프로세스에 속하며 재시작 후 0에서 다시 시작합니다(arkvory_process_start_time_seconds 참조). 레이블은 라우트 템플릿, 메서드, 상태 클래스, 전송 방향으로 제한되며 아티팩트, 키, 계정을 식별하는 이름은 절대 포함하지 않습니다. 스크레이프는 요청 한도에 포함되지 않습니다.
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/health/metrics" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o file현재 자격 증명으로 호출 가능한 작업 목록
GET HEAD /api/v1/operations
액세스: 유효한 키 또는 세션 · 재시도: 반복해도 안전함(읽기)
자격 증명으로 호출할 수 있는 이 게이트웨이의 작업을 operationId 순으로 나열하며, 각 항목에 영역, 재시도 규칙, 필요한 권한 액션, 호출 시점에만 검사되는 conditions(예: resource-state, upload-owner)를 담습니다. repository를 지정하면 해당 리포지토리의 작업이 추가되고(알 수 없거나 접근할 수 없는 리포지토리는 404), surface는 목록을 한 영역으로 좁힙니다. 페이지는 limit개 항목(1–100, 기본 50)으로 구성되며 after에 next 값을 넣어 이어서 조회합니다. 응답은 참고용입니다. 메뉴 구성에 활용할 수 있지만 모든 실제 요청은 다시 인가되며, 읽기 게이트웨이는 변경 메서드를 나열하지 않습니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 쿼리 | string | 아니요 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
surface | 쿼리 | string | 아니요 | discovery, identity, catalog, transfers, administration, operations 중 하나 |
after | 쿼리 | string | 아니요 | ^[A-Za-z][A-Za-z0-9]{0,95}$ 패턴과 일치 |
limit | 쿼리 | integer | 아니요 | 1–100; 기본값 50 |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
apiVersion | string | 예 | v1 중 하나 |
documentVersion | string | 예 | ^\d+\.\d+\.\d+$ 패턴과 일치 |
gatewayRole | string | 예 | api, reader 중 하나 |
repository | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치; null일 수 있음 |
advisory | boolean | 예 | true 중 하나 |
items | object 배열 | 예 | 요소 100개 이하 |
items[].operationId | string | 예 | ^[A-Za-z][A-Za-z0-9]{0,95}$ 패턴과 일치 |
items[].method | string | 예 | get, head, post, put, patch, delete 중 하나 |
items[].path | string | 예 | ^/ 패턴과 일치; 512자 이하 |
items[].summary | string | 예 | 1024자 이하 |
items[].surface | string | 예 | discovery, identity, catalog, transfers, administration, operations 중 하나 |
items[].visibility | string | 예 | public, authenticated, self, repository, owned-resource, delegated, bootstrap, administrator 중 하나 |
items[].retry | string | 예 | read, never-automatic, idempotent, idempotency-key, compare-and-swap, reconcile-upload, reconcile-job 중 하나 |
items[].requiredActions | string 배열 | 예 | 요소 33개 이하; 중복 항목 없음; 각 요소: repository.read, storage.read, storage.manage, diagnostics.read, artifact.read, artifact.list, artifact.delete, artifact.promote, content.read, upload.create, upload.read, upload.write, upload.complete, upload.cancel, job.read, package.read, package.publish, asset.read, asset.write, asset.restore, annotation.read, annotation.write, reference.write, audit.read, service-account.read, service-account.manage, policy.read, policy.manage, credential.read, credential.manage, service-audit.read, backup.read, backup.manage 중 하나 |
items[].conditions | string 배열 | 예 | 요소 6개 이하; 중복 항목 없음; 각 요소: resource-state, upload-owner, job-owner, reference-owner, delegation-target-and-ceiling, own-key 중 하나 |
next | string | 예 | ^[A-Za-z][A-Za-z0-9]{0,95}$ 패턴과 일치; null일 수 있음 |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/operations" \
-H "Authorization: Bearer $ARKVORY_TOKEN"