Org Mover 내부 API
GitLab v19.6요약
Org Mover 컨트롤 플레인은 GitLab.com 셀 간 이동 중에 조직의 유지 보수 수명 주기를 제어하기 위해 이 내부 API를 사용합니다. Org Mover API는 사용자 토큰이 아닌 서비스 수준 JWT로 요청을 인증하기 때문에 내부 엔드포인트를 사용합니다.
Org Mover 컨트롤 플레인은 GitLab.com 셀 간 이동 중에 조직의 유지 보수 수명 주기를 제어하기 위해 이 내부 API를 사용합니다. 다른 소비자는 이 API를 사용할 수 없습니다. 이 문서는 GitLab 코드베이스에서 작업하는 사람을 위한 문서입니다.
Org Mover API는 사용자 토큰이 아닌 서비스 수준 JWT로 요청을 인증하기 때문에 내부 엔드포인트를 사용합니다.
인증#
이 엔드포인트는 Org Mover 컨트롤 플레인이 서명한 ES256 JWT로 인증합니다.
개인 키는 컨트롤 플레인만 보유합니다.
각 셀은 gitlab.yml의 org_mover.public_key_files 설정에 나열된 공개 키를 신뢰합니다.
다운타임 없이 키를 교체하려면 이전 키와 새 키를 모두 나열합니다.
컨트롤 플레인이 새 키로 서명하기 시작한 후에 이전 키를 제거합니다.
설정이 비어 있거나 셀이 비활성화되어 있으면 엔드포인트는 모든 토큰을 거부합니다.
클라이언트는 Gitlab-Org-Mover-Api-Request 헤더에 토큰을 전달합니다. 토큰은 다음 요구 사항을 충족해야 합니다.
| 필드 | 요구 사항 |
|---|---|
alg 헤더 |
ES256. |
kid 헤더 |
서명 키의 RFC 7638 지문(thumbprint). |
iss |
gitlab-org-mover. |
aud |
대상 셀을 단일 문자열로 지정합니다: gitlab-org-mover-api:cell-<cell_id>. 다른 셀 또는 셀 목록을 대상으로 하는 토큰은 거부됩니다. |
iat |
토큰이 발급된 시간. 5분보다 오래되었거나 30초를 넘게 미래인 토큰은 거부됩니다. |
| 크기 | JSON Web Signature(JWS) 컴팩트 직렬화 기준 최대 2 KB. |
토큰이 없거나 유효하지 않으면 401을 반환합니다. 공개 키 파일을 읽을 수 없으면 엔드포인트는 500을 반환합니다.
각 유지 보수 엔드포인트는 org_mover_maintenance_api 기능 플래그로 조직별로도 제어되며, 이 플래그는
대상 조직을 액터로 하여 확인합니다. 조직에 대해 플래그가 비활성화되어 있거나
조직이 존재하지 않으면 엔드포인트는 404를 반환합니다. 플래그는 기본적으로 비활성화되어 있으며
이동하는 기간에만 조직별로 활성화합니다.
운영자는 플래그를 전역으로 활성화해서는 안 됩니다.
플래그는 저절로 만료되지 않으므로, 운영자는 이동이 끝난 후에 플래그를 비활성화해야 합니다.
유지 보수 수명 주기#
조직은 유지 보수 전환 중에 다음 상태를 거칩니다.
active: 조직이 평소와 같이 운영되고 있습니다.maintenance_initialization: 전환이 시작되었으며, 조직이 남은 작업을 비우고 있습니다.maintenance: 조직의 작업이 완전히 비워졌으며 안정적인 유지 보수 상태입니다.
전환은 멱등적입니다. 조직이 이미 대상 상태에 있으면 엔드포인트는
전환을 다시 실행하지 않고 204를 반환합니다.
maintenance_initialization 상태부터 GitLab은 웹, REST API, GraphQL, Git, Git LFS,
컨테이너 레지스트리 요청을 포함해 해당 조직에 대한 요청을 차단합니다. 유지 보수 사유가
migration 또는 incident이면 차단된 웹, API, GraphQL, Git LFS 요청은 Retry-After 헤더와 함께
503을 반환합니다. 다른 사유에서는 403을 반환합니다. Git 요청은 모든 사유에서 거부됩니다.
내부 엔드포인트#
모든 유지 보수 엔드포인트에는 정수 organization_id가 필요합니다. 값이 없거나 정수가 아니면 400을 반환합니다.
현재 상태 보고#
GET 명령으로 조직의 현재 수명 주기 상태를 가져옵니다.
응답에는 조직의 전체 상태가 담기므로, 유지 보수 수명 주기 상태 외에
unconfirmed, confirmed, soft_deleted, deletion_in_progress가 될 수도 있습니다.
GET /internal/org_mover/maintenance_state
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
organization_id |
integer | 예 | 조직의 ID. |
요청 예시:
curl --header "Gitlab-Org-Mover-Api-Request: <json-web-token>" \
"https://gitlab.example.com/api/v4/internal/org_mover/maintenance_state?organization_id=2"
응답 예시:
{
"state": "active"
}
유지 보수 준비 상태 보고#
GET 명령으로 조직의 작업이 비워져 유지 보수 상태로 안전하게 들어갈 수 있는지 확인합니다.
GET /internal/org_mover/maintenance_readiness
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
organization_id |
integer | 예 | 조직의 ID. |
요청 예시:
curl --header "Gitlab-Org-Mover-Api-Request: <json-web-token>" \
"https://gitlab.example.com/api/v4/internal/org_mover/maintenance_readiness?organization_id=2"
응답 예시:
{
"ready": false,
"blocking_reason": "active CI jobs"
}
조직이 준비되면 ready는 true이고 blocking_reason은 null입니다. 그렇지 않으면
blocking_reason에 처음 실패한 확인 항목인 active batched background migrations,
pending migrations, active CI jobs 중 하나가 표시됩니다.
준비 상태 확인은 아직 완성되지 않았으므로 사유가 더 추가될 수 있습니다. 진행 상황은
작업 항목 602822를 참고합니다.
유지 보수 시작#
POST 명령으로 유지 보수 전환(active에서 maintenance_initialization)을 시작합니다.
POST /internal/org_mover/start_maintenance
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
organization_id |
integer | 예 | 조직의 ID. |
maintenance_reason |
string | 예 | 유지 보수에 들어가는 사유. migration, isolation, incident, billing, legal 중 하나. |
요청 예시:
curl --request POST \
--header "Gitlab-Org-Mover-Api-Request: <json-web-token>" \
--header "Content-Type: application/json" \
--data '{"organization_id": 2, "maintenance_reason": "migration"}' \
"https://gitlab.example.com/api/v4/internal/org_mover/start_maintenance"
요청이 성공하면 204를 반환합니다. 유효하지 않은 maintenance_reason은 400을 반환하며,
active도 아니고 이미 maintenance_initialization도 아닌 조직은 422를 반환합니다.
기본 조직은 유지 보수에 들어갈 수 없으며 항상 422를 반환합니다.
유지 보수 확인#
POST 명령으로 유지 보수 전환(maintenance_initialization에서 maintenance)을 완료합니다.
POST /internal/org_mover/confirm_maintenance
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
organization_id |
integer | 예 | 조직의 ID. |
요청 예시:
curl --request POST \
--header "Gitlab-Org-Mover-Api-Request: <json-web-token>" \
--header "Content-Type: application/json" \
--data '{"organization_id": 2}' \
"https://gitlab.example.com/api/v4/internal/org_mover/confirm_maintenance"
요청이 성공하면 204를 반환합니다. 조직의 작업이 아직 비워지지 않았으면 요청은
메시지에 차단 사유를 담아 409를 반환합니다. 클라이언트는 maintenance_readiness를 폴링하다가
409 이후에 재시도할 수 있습니다. maintenance_initialization 상태가 아닌 조직은 422를 반환하며, 이는 영구적입니다.
유지 보수 취소#
POST 명령으로 조직이 유지 보수 상태에 도달하기 전에 유지 보수 초기화를 중단하고
active로 되돌립니다(maintenance_initialization에서 active).
POST /internal/org_mover/cancel_maintenance
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
organization_id |
integer | 예 | 조직의 ID. |
요청 예시:
curl --request POST \
--header "Gitlab-Org-Mover-Api-Request: <json-web-token>" \
--header "Content-Type: application/json" \
--data '{"organization_id": 2}' \
"https://gitlab.example.com/api/v4/internal/org_mover/cancel_maintenance"
요청이 성공하면 204를 반환합니다. active도 아니고
maintenance_initialization도 아닌 조직은 422를 반환합니다.
유지 보수 종료#
POST 명령으로 조직을 유지 보수 상태에서 active로 되돌립니다
(maintenance에서 active).
POST /internal/org_mover/exit_maintenance
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
organization_id |
integer | 예 | 조직의 ID. |
요청 예시:
curl --request POST \
--header "Gitlab-Org-Mover-Api-Request: <json-web-token>" \
--header "Content-Type: application/json" \
--data '{"organization_id": 2}' \
"https://gitlab.example.com/api/v4/internal/org_mover/exit_maintenance"
요청이 성공하면 204를 반환합니다. active도 아니고 maintenance도 아닌
조직은 422를 반환합니다.
셀 매니페스트 가져오기#
GET 명령으로 이 셀의 Org Mover 매니페스트를 JSON 형식의 orgmover.manifest.v1.Manifest로 가져옵니다.
매니페스트에는 이동 시 함께 옮겨야 하는 데이터베이스, 테이블, 오브젝트 스토리지 소스,
Gitaly 리포지터리 소스가 나열됩니다. GitLab은 db/docs의 테이블 사전과 각 테이블의 실제 칼럼으로
요청할 때마다 매니페스트를 생성하므로, 실행 중인 GitLab 버전과 일치합니다.
매니페스트는 조직이 아닌 셀을 설명하므로 이 엔드포인트는 organization_id를 받지 않습니다.
이 엔드포인트는 org_mover_manifest_api 기능 플래그로 제어되며, 플래그는 인스턴스에 대해 확인합니다.
플래그가 비활성화되어 있으면 엔드포인트는 404를 반환합니다.
GET /internal/org_mover/manifest
요청 예시:
curl --header "Gitlab-Org-Mover-Api-Request: <json-web-token>" \
"https://gitlab.example.com/api/v4/internal/org_mover/manifest"
응답 예시(축약):
{
"service": "gitlab-rails",
"siphon": {
"databases": {
"gitlab_main": {
"type": "SIPHON_DATABASE_TYPE_POSTGRESQL",
"tables": [
{
"table": "projects",
"sharding_key": { "organization_id": "SHARDING_KEY_ORGANIZATIONS" },
"columns": [{ "name": "id", "type": "bigint" }]
}
]
}
}
},
"generated_at": "2026-11-05T04:00:00Z",
"object_storage": {
"storages": { "uploads": {} },
"sources": [
{
"database": { "name": "gitlab_main", "table": "project_uploads" },
"handler": "OBJECT_STORAGE_HANDLER_UPLOADS",
"storage": "uploads"
}
]
},
"gitaly": {
"storages": { "default": {} },
"sources": [
{
"database": { "name": "gitlab_main", "table": "project_repositories" },
"handler": "GITALY_HANDLER_REPOSITORY"
}
]
}
}
응답은 큽니다. 개발 인스턴스에서는 약 1,000개의 테이블이 나열되며 크기는 약 550 KB입니다.