InfoGrab DocsInfoGrab Docs

네임스페이스 상태 상속 전파

요약

GitLab은 네임스페이스 계층 구조를 트리로 나타냅니다. 네임스페이스 트리 자체의 구조는 네임스페이스를 참조합니다. 기존 모델은 읽는 시점에 상위 항목 체인을 따라 올라가며 네임스페이스의 유효 상태를 결정했습니다. 전파 모델은 네임스페이스의 상태가 바뀔 때 그 결과 상태를 모든 하위 요소에 기록합니다.

GitLab은 네임스페이스 계층 구조를 트리로 나타냅니다. 루트 요소는 최상위 네임스페이스이며, 자식 요소는 하위 그룹과 Namespaces::ProjectNamespace 레코드입니다. 각 네임스페이스에는 ancestor_inherited(기본 활성 상태), archived, deletion_scheduled 같은 상태가 있습니다. 네임스페이스에 상태를 설정하면 GitLab은 그 상태를 트리의 모든 하위 요소에 적용합니다.

네임스페이스 트리 자체의 구조는 네임스페이스를 참조합니다. 기반이 되는 배치 반복 알고리즘은 트리 계층 구조의 배치 반복을 참조합니다.

조회 대신 전파를 사용하는 이유#

기존 모델은 읽는 시점에 상위 항목 체인을 따라 올라가며 네임스페이스의 유효 상태를 결정했습니다. 깊이 중첩된 프로젝트를 읽으면 상태를 찾을 때까지 상위 항목을 하나씩 확인했습니다. 이 방식에는 몇 가지 문제가 있었습니다.

  • 상태를 확인할 때마다 계층 구조를 따라가야 하므로 쿼리 오버헤드가 추가되었습니다.
  • 유효 상태가 하위 요소마다 다르게 추론되었습니다.
  • 읽기 성능을 허용 가능한 수준으로 유지하려면 캐싱이 필요했고, 이로 인해 복잡성이 증가했습니다.

전파 모델은 네임스페이스의 상태가 바뀔 때 그 결과 상태를 모든 하위 요소에 기록합니다. 그러면 읽기는 상위 항목 탐색 없이 단일 칼럼 비교가 됩니다. 대신 쓰기가 더 많은 작업을 수행하며, 그 작업이 비동기로 이루어진다는 트레이드오프가 있습니다.

자세한 내용은 ADR 003: 상태 전파 모델을 참조합니다.

전파되는 상태#

다음 상태가 전파에 참여합니다.

상태 우선순위 설명
ancestor_inherited 0 기본 활성 상태
archived 1 네임스페이스와 그 하위 요소가 보관됩니다.
deletion_scheduled 2 네임스페이스와 그 하위 요소가 삭제 예약됩니다.
maintenance 6 조직 이전 중 네임스페이스와 그 하위 요소가 읽기 전용 모드가 됩니다.

우선순위 값은 정식 네임스페이스 상태 열거형을 그대로 따르므로, maintenance는 연속된 순위가 아니라 6을 사용합니다. 우선순위 비교에서는 순서만 중요하며, maintenance의 우선순위가 가장 높습니다.

우선순위가 높은 상태가 낮은 상태보다 우선합니다. 우선순위가 낮은 전파는 이미 우선순위가 높은 상태에 있는 하위 요소를 덮어쓰지 않습니다. 예를 들어 deletion_scheduled 상태인 네임스페이스는 상위 항목이 archived를 전파해도 바뀌지 않습니다.

maintenance 상태는 네임스페이스와 그 하위 요소를 읽기 전용 모드로 전환하여 전체 계층 구조를 조직 이전에 대비시킵니다. maintenance 상태는 아직 사용되지 않으며, 전파도 아직 완전히 연결되지 않았습니다.

transfer_in_progress, transfer_scheduled 같은 다른 상태는 전파되지 않습니다. 네임스페이스 수준의 이전은 선택한 네임스페이스에만 영향을 주며, 하위 요소의 유효 상태에는 영향을 주지 않습니다.

구성 요소#

전파는 함께 동작하는 네 가지 구성 요소를 사용합니다.

Mermaid 다이어그램 (10줄)
소스 코드 보기
%%{init: { "flowchart": { "useMaxWidth": true } }}%%
flowchart TD
  accTitle: Namespace state propagation components
  accDescr: A state change writes an outbox record, a worker reads the outbox and drives the iterator, and the iterator returns descendant IDs to update.

A[State change on a namespace] --> B[Outbox record in namespace_state_propagations] B --> C[StatePropagationWorker] C --> D[StatePropagationIterator] D --> E[Conditional UPDATE of descendant states] F[StatePropagationCronWorker] -.recovers lost or stalled records.-> B

트랜잭션 아웃박스#

네임스페이스 상태가 바뀌면 GitLab은 같은 데이터베이스 트랜잭션에서 상태 변경과 아웃박스 레코드를 함께 기록합니다. 아웃박스 레코드는 namespace_state_propagations 테이블의 행입니다. 두 쓰기가 함께 커밋되므로 전파 요청은 유실될 수 없습니다. 레코드를 처리하는 워커가 비정상 종료되어도 레코드가 남아 재시도됩니다.

이 패턴은 트랜잭셔널 아웃박스입니다. Namespaces::StatePropagation 모델은 시작점이 된 namespace_id, source_state, target_state, 그리고 pending 또는 processing인 status를 저장합니다. 네임스페이스에는 하위 요소가 상속하는 상태를 바꾸는 전환마다 하나씩, 여러 레코드가 있을 수 있습니다. 고유 부분 인덱스는 네임스페이스마다 processing 레코드를 하나만 허용합니다. 한 네임스페이스의 레코드가 정렬되는 방식은 동일 네임스페이스 순서 지정을 참조합니다.

상태 우선순위#

Namespaces::Stateful::StatePrecedence 모듈은 전파가 덮어쓸 수 있는 하위 요소 상태를 결정합니다. overwritable_states(source_state, target_state) 메서드는 우선순위 표에 따라 전파가 변경할 수 있는 하위 요소 상태를 반환합니다.

덮어쓸 수 있는 상태의 집합은 대상 상태와 네임스페이스가 벗어나는 상태에 모두 따라 달라집니다.

소스 상태 대상 상태 덮어쓸 수 있는 하위 요소 상태 이유
ancestor_inherited archived ancestor_inherited 활성 상태의 하위 요소를 보관합니다.
ancestor_inherited deletion_scheduled ancestor_inherited, archived 활성 및 보관된 하위 요소의 삭제를 예약합니다.
archived deletion_scheduled ancestor_inherited, archived 활성 및 보관된 하위 요소의 삭제를 예약합니다.
archived ancestor_inherited archived 보관을 해제하되 deletion_scheduled에서 멈춥니다.
deletion_scheduled ancestor_inherited deletion_scheduled, archived 삭제로 함께 처리된 모든 항목을 복원하되, 자체적으로 삭제를 예약한 하위 요소에서 멈춥니다.

소스 상태와 대상 상태의 우선순위가 같거나 지원되지 않는 조합이면 메서드는 빈 배열을 반환하고 하위 요소는 변경되지 않습니다.

상태 전파 워커#

Namespaces::StatePropagationWorker가 전파를 수행합니다. 지정된 namespace_id에 대해 워커는 해당 네임스페이스의 아웃박스 레코드를 오래된 것부터 가져옵니다. 레코드마다 워커는 다음을 수행합니다.

  1. 레코드가 processing이면 이전 실행이 아직 활성 상태이거나 해당 프로세스가 종료된 것이므로 중단합니다. 그렇지 않으면 레코드를 processing으로 표시합니다.
  2. StatePrecedence로 덮어쓸 수 있는 상태를 계산합니다.
  3. 이터레이터가 하위 요소를 배치 단위로 순회하도록 구동합니다.
  4. 배치마다 조건부 업데이트를 적용합니다.
  5. 전파가 완료되면 아웃박스 레코드를 삭제한 다음 다음 레코드로 계속합니다.

워커는 레코드 사이에서만 실행 시간 제한을 확인합니다. 제한을 초과했고 레코드가 남아 있으면, 워커는 다음 레코드를 시작하지 않고 해당 네임스페이스에 대해 자신을 다시 큐에 넣습니다. 이렇게 하면 레코드가 많은 네임스페이스가 워커 슬롯을 오래 점유하지 않습니다. 레코드 하나는 항상 끝까지 실행되므로, 큰 하위 트리를 한 번 순회하는 작업은 여전히 제한을 초과할 수 있습니다.

업데이트는 전파를 시작한 네임스페이스를 변경하지 않습니다. 그 네임스페이스는 이미 새 상태를 가지고 있으며, 레코드가 기록된 이후 다시 바뀌었을 수도 있습니다.

조건부 업데이트는 아직 덮어쓸 수 있는 상태에 있는 하위 요소만 변경합니다.

UPDATE namespaces
SET state = :target_state
WHERE id IN (:batch_ids)
  AND state IN (:overwritable_states)

워커가 도중에 오류를 발생시키면 아웃박스 레코드를 pending으로 되돌리고 Sidekiq이 잡을 재시도합니다. 워커 프로세스가 대신 종료되면, 조정 워커가 레코드를 초기화하고 다시 큐에 넣을 때까지 레코드는 processing 상태로 남습니다.

상태 인식 이터레이터#

Gitlab::Database::Namespaces::StatePropagationIterator는 트리 계층 구조의 배치 반복에 설명된 네임스페이스 트리 이터레이터의 하위 클래스입니다. 기본 이터레이터는 계층 구조를 깊이 우선으로 순회하며 하위 요소 ID를 배치 단위로 반환합니다. 하위 클래스는 상태가 필터에 포함된 네임스페이스로 순회를 제한하는 state_filter를 추가합니다.

워커는 덮어쓸 수 있는 상태와 대상 상태를 함께 필터로 전달합니다. 이미 대상 상태인 하위 요소를 거쳐서도 순회가 계속되도록 대상 상태를 포함합니다. 이터레이터는 순회가 시작되는 네임스페이스의 상태를 확인하지 않습니다. 그런 다음 조건부 업데이트가 덮어쓸 수 있는 상태의 하위 요소만 변경되도록 보장합니다.

상태만으로는 자체적으로 삭제를 예약한 하위 요소와, 전파를 통해 deletion_scheduled를 상속한 하위 요소를 구분할 수 없습니다. 차이는 namespace_details.deletion_scheduled_at에 있습니다. schedule_deletion 전환은 이 칼럼을 설정하지만, 전파는 설정하지 않습니다.

상위 항목이 삭제를 취소하면(deletion_scheduled에서 ancestor_inherited 또는 archived로), 워커는 options: { preserve_descendants_deletion: true }를 전달합니다. 이 옵션을 사용하면 이터레이터는 deletion_scheduled_at이 설정된 모든 하위 요소를 경계로 취급합니다. 이터레이터는 해당 하위 요소와 그 하위 트리를 건너뛰므로, 이들은 삭제 예약을 유지합니다. 전파의 루트는 결코 경계가 되지 않습니다. 다른 상태 변경은 이 옵션을 설정하지 않으며 namespace_details를 확인하지 않습니다.

조정 워커#

Namespaces::StatePropagationCronWorker는 유실되었거나 정체된 전파 잡을 복구합니다. config/schedule.yml에 정의된 고정 일정에 따라 워커는 다음을 수행합니다.

  1. 오래됨 임계값을 초과한 pending 레코드의 수를 세어 stale_pending_total에 더합니다. 이 집계는 초기화 전에 실행되므로, 다음 단계에서 초기화된 레코드는 오래된 것으로 다시 집계되지 않습니다.
  2. 멈춤 임계값을 초과한 processing 레코드를 pending으로 되돌리고 started_at을 지우며, 초기화한 레코드 수를 stuck_processing_total에 더합니다.
  3. pending 레코드가 있는 네임스페이스마다 StatePropagationWorker 잡을 하나씩 큐에 넣습니다. 카운터는 이 단계 전에 업데이트되므로, 다시 큐에 넣는 데 실패해도 오래되었거나 멈춘 레코드가 가려지지 않습니다.
  4. 메트릭에 설명된 pending 및 processing 아웃박스 게이지를 갱신합니다.

StatePropagationWorker의 중복 제거는 네임스페이스마다 둘 이상의 잡이 큐에 들어가지 않도록 합니다. 다른 잡이 실행되는 동안 잡이 중복으로 삭제되면, 그사이 생성된 레코드를 처리하기 위해 워커가 이후에 한 번 더 실행됩니다. 잡이 레코드를 processing으로 선점해야 하고 고유 부분 인덱스가 네임스페이스마다 processing 레코드를 하나만 허용하므로, 네임스페이스마다 한 번에 레코드 하나만 적용됩니다.

동일 네임스페이스 순서 지정#

네임스페이스는 이전 변경의 전파가 끝나기 전에 다시 상태가 바뀔 수 있습니다. 예를 들어 하위 요소가 아직 보관되는 동안 그룹이 보관되었다가 보관 해제되는 경우입니다.

GitLab은 한 네임스페이스의 레코드를 id 순서로 한 번에 하나씩 적용하며, 각 레코드는 끝까지 실행됩니다. 레코드는 병합되거나 건너뛰지 않으므로 다음이 보장됩니다.

  • 레코드의 source_state는 레코드가 실행될 때 하위 요소가 상속하는 상태와 항상 일치합니다.
  • 보존되는 상태가 올바르게 저장되고 복원됩니다. 예를 들어 보관이 절반만 적용된 상태에서 삭제를 예약해도 모든 하위 요소의 archived가 보존됩니다.
  • 모든 레코드가 끝나면 하위 요소는 네임스페이스의 마지막 전환에 해당하는 상태를 가집니다.

id 순서는 한 네임스페이스의 커밋 순서와 일치합니다. 전환은 레코드를 삽입하기 전에 네임스페이스 행을 잠그고, 트랜잭션이 커밋될 때까지 잠금을 유지합니다. 같은 네임스페이스의 두 번째 전환은 그 잠금을 기다리므로 레코드가 더 큰 id를 받습니다.

잠금은 레코드의 순서를 정하지만, 두 번째 요청이 불러온 상태를 갱신하지는 않습니다. 두 요청이 어느 쪽이 커밋하기 전에 네임스페이스를 불러오면, 두 번째 레코드의 source_state가 오래된 값일 수 있습니다. 이슈 638361에서 이를 추적합니다.

실패한 레코드는 완료될 때까지 같은 네임스페이스의 이후 레코드를 차단합니다.

메트릭#

Gitlab::NamespaceStatePropagation::Metrics는 전파의 Prometheus 메트릭을 정의합니다. target_state 레이블은 archived와 같이 전파된 상태입니다. 카디널리티를 제한하기 위해 어떤 메트릭에도 namespace_id 레이블이 없습니다.

이름 유형 레이블 설명
gitlab_namespaces_state_propagation_duration_seconds Histogram target_state 아웃박스 레코드를 processing으로 표시한 시점부터 삭제할 때까지의 시간입니다. 상태를 전파하는 성공한 실행에 대해서만 관측됩니다.
gitlab_namespaces_state_propagation_batches_total Counter target_state 이터레이터가 산출하고 워커가 업데이트하는 하위 요소 배치입니다.
gitlab_namespaces_state_propagation_boundary_rewinds_total Counter None 이터레이터가 경계를 지나 커서를 되감은 횟수입니다. 순회를 끝내는 경계는 집계되지 않습니다.
gitlab_namespaces_state_propagation_failures_total Counter target_state 오류가 발생한 StatePropagationWorker 실행입니다. 오류는 다시 발생시킵니다. 네임스페이스 상태가 아닌 target_state는 unknown으로 레이블이 지정됩니다.
gitlab_namespaces_state_propagation_pending_records Gauge None namespace_state_propagations의 pending 레코드 수입니다.
gitlab_namespaces_state_propagation_processing_records Gauge None namespace_state_propagations의 processing 레코드 수입니다.
gitlab_namespaces_state_propagation_stuck_processing_total Counter None 30분보다 오래전에 시작되어 StatePropagationCronWorker가 pending으로 되돌린 processing 레코드입니다.
gitlab_namespaces_state_propagation_stale_pending_total Counter None 15분보다 오래전에 생성된 pending 레코드입니다. StatePropagationCronWorker는 실행할 때마다 현재 개수를 더하므로, 레코드가 오래된 상태로 남아 있는 동안 카운터가 계속 증가합니다.

소요 시간 히스토그램은 0.1, 0.5, 1, 5, 15, 30, 60, 120, 300, 600, 1800초 버킷을 사용합니다.

StatePropagationCronWorker는 실행이 끝날 때마다 두 게이지를 모두 갱신합니다. 각 개수는 테이블 전체를 대상으로 하며 Sidekiq 프로세스 전반에서 합산하면 과다 집계되므로, 게이지는 max 멀티프로세스 모드를 사용합니다. 프로세스는 크론 워커가 해당 프로세스에서 다시 실행되거나 프로세스가 재시작될 때까지 마지막으로 설정한 값을 유지합니다. 따라서 아웃박스가 비워진 뒤에도 게이지는 이전에 크론 워커를 실행한 프로세스의 오래된 값을 보고할 수 있습니다.

오래된 레코드에 대해 알림을 설정하려면 게이지 대신 stuck_processing_total 및 stale_pending_total 카운터를 사용합니다. 카운터는 단조 증가하며 프로세스 전반에서 합산되므로, 아웃박스가 비워진 뒤에도 오래된 값을 보고하지 않습니다. 절대값 대신 increase(...[window]) > 0에 대해 알림을 설정합니다. 모든 Sidekiq 프로세스는 시작할 때 두 카운터를 0으로 생성합니다. increase()는 시계열의 첫 번째 샘플을 무시하므로, 첫 실제 증가로 생성된 카운터는 그 증가를 놓치게 됩니다. stale_pending_total은 실행할 때마다 오래된 레코드 수를 더하므로, 증가율은 크론 일정에 따라 달라집니다.

StatePropagationCronWorker의 실패는 별도로 집계되지 않습니다. 대신 이 워커에는 표준 sidekiq_jobs_failed_total 메트릭을 사용합니다.

로깅#

전파는 Gitlab::AppLogger에 구조화된 로그 항목을 기록합니다. 각 이벤트에는 검색할 수 있는 고유한 message 값이 있습니다.

message 수준 필드
Namespace state propagation started info class_name, gl_namespace_id, source_state, target_state
Namespace state propagation completed info class_name, gl_namespace_id, target_state, batch_count, duration_s, descendants_updated
Namespace state propagation cursor rewound info class_name, gl_namespace_id, boundary_id, boundary_state, depth_before, depth_after
Namespace state propagation failed error class_name, gl_namespace_id, target_state, error_type, error_message

다음은 이 항목에 대한 설명입니다.

  • gl_namespace_id는 전파가 시작된 네임스페이스입니다.
  • descendants_updated는 조건부 업데이트가 변경한 행만 집계하므로, 이 값은 방문한 네임스페이스 수보다 작을 수 있습니다.
  • duration_s는 배치 순회 시간만 포함합니다.
  • depth_before와 depth_after는 이터레이터가 경계를 지나 되감기 전후의 커서 경로 길이입니다.

아웃박스 레코드가 존재하지 않거나, 덮어쓸 수 있는 하위 요소 상태가 없거나, 다른 잡이 이미 레코드를 선점한 경우에는 항목이 기록되지 않습니다. 실패가 기록된 후 오류가 다시 발생하므로, 재시도와 조정은 이전과 동일하게 동작합니다.

예시 따라 하기#

각 노드에 현재 상태가 표시된 다음 계층 구조를 가정합니다.

Mermaid 다이어그램 (10줄)
소스 코드 보기
%%{init: { "flowchart": { "useMaxWidth": true } }}%%
flowchart TD
  accTitle: Example namespace hierarchy before propagation
  accDescr: A top-level group that is active, with one active subgroup, one archived subgroup, and one subgroup scheduled for deletion.

Root["Top-level group (ancestor_inherited)"] --> A["Subgroup A (ancestor_inherited)"] Root --> B["Subgroup B (archived)"] Root --> C["Subgroup C (deletion_scheduled)"] A --> A1["Project A1 (ancestor_inherited)"] B --> B1["Project B1 (archived)"]

최상위 그룹을 보관하면 source_state가 ancestor_inherited이고 target_state가 archived인 전파가 실행됩니다. StatePrecedence.overwritable_states(:ancestor_inherited, :archived)는 [:ancestor_inherited]를 반환하므로 활성 상태의 하위 요소만 변경됩니다.

결과는 다음과 같습니다.

Mermaid 다이어그램 (10줄)
소스 코드 보기
%%{init: { "flowchart": { "useMaxWidth": true } }}%%
flowchart TD
  accTitle: Example namespace hierarchy after archiving the top-level group
  accDescr: The top-level group, subgroup A, and project A1 become archived. Subgroup B stays archived. Subgroup C stays scheduled for deletion.

Root["Top-level group (archived)"] --> A["Subgroup A (archived)"] Root --> B["Subgroup B (archived)"] Root --> C["Subgroup C (deletion_scheduled)"] A --> A1["Project A1 (archived)"] B --> B1["Project B1 (archived)"]

이 예시에서는 다음과 같습니다.

  • 하위 그룹 A와 프로젝트 A1은 ancestor_inherited에서 archived로 바뀝니다.
  • 하위 그룹 B와 프로젝트 B1은 이미 archived이므로 바뀌지 않습니다.
  • deletion_scheduled의 우선순위가 archived보다 높으므로 하위 그룹 C는 deletion_scheduled로 유지됩니다.

기반이 된 머지 리퀘스트#

전파 알고리즘은 여러 머지 리퀘스트에 걸쳐 구축되었습니다.

전체 계획은 에픽 21607을 참조합니다.

네임스페이스 상태 상속 전파

GitLab v19.6
원문 보기

요약

GitLab은 네임스페이스 계층 구조를 트리로 나타냅니다. 네임스페이스 트리 자체의 구조는 네임스페이스를 참조합니다. 기존 모델은 읽는 시점에 상위 항목 체인을 따라 올라가며 네임스페이스의 유효 상태를 결정했습니다. 전파 모델은 네임스페이스의 상태가 바뀔 때 그 결과 상태를 모든 하위 요소에 기록합니다.

GitLab은 네임스페이스 계층 구조를 트리로 나타냅니다. 루트 요소는 최상위 네임스페이스이며, 자식 요소는 하위 그룹과 Namespaces::ProjectNamespace 레코드입니다. 각 네임스페이스에는 ancestor_inherited(기본 활성 상태), archived, deletion_scheduled 같은 상태가 있습니다. 네임스페이스에 상태를 설정하면 GitLab은 그 상태를 트리의 모든 하위 요소에 적용합니다.

네임스페이스 트리 자체의 구조는 네임스페이스를 참조합니다. 기반이 되는 배치 반복 알고리즘은 트리 계층 구조의 배치 반복을 참조합니다.

조회 대신 전파를 사용하는 이유#

기존 모델은 읽는 시점에 상위 항목 체인을 따라 올라가며 네임스페이스의 유효 상태를 결정했습니다. 깊이 중첩된 프로젝트를 읽으면 상태를 찾을 때까지 상위 항목을 하나씩 확인했습니다. 이 방식에는 몇 가지 문제가 있었습니다.

  • 상태를 확인할 때마다 계층 구조를 따라가야 하므로 쿼리 오버헤드가 추가되었습니다.
  • 유효 상태가 하위 요소마다 다르게 추론되었습니다.
  • 읽기 성능을 허용 가능한 수준으로 유지하려면 캐싱이 필요했고, 이로 인해 복잡성이 증가했습니다.

전파 모델은 네임스페이스의 상태가 바뀔 때 그 결과 상태를 모든 하위 요소에 기록합니다. 그러면 읽기는 상위 항목 탐색 없이 단일 칼럼 비교가 됩니다. 대신 쓰기가 더 많은 작업을 수행하며, 그 작업이 비동기로 이루어진다는 트레이드오프가 있습니다.

자세한 내용은 ADR 003: 상태 전파 모델을 참조합니다.

전파되는 상태#

다음 상태가 전파에 참여합니다.

상태 우선순위 설명
ancestor_inherited 0 기본 활성 상태
archived 1 네임스페이스와 그 하위 요소가 보관됩니다.
deletion_scheduled 2 네임스페이스와 그 하위 요소가 삭제 예약됩니다.
maintenance 6 조직 이전 중 네임스페이스와 그 하위 요소가 읽기 전용 모드가 됩니다.

우선순위 값은 정식 네임스페이스 상태 열거형을 그대로 따르므로, maintenance는 연속된 순위가 아니라 6을 사용합니다. 우선순위 비교에서는 순서만 중요하며, maintenance의 우선순위가 가장 높습니다.

우선순위가 높은 상태가 낮은 상태보다 우선합니다. 우선순위가 낮은 전파는 이미 우선순위가 높은 상태에 있는 하위 요소를 덮어쓰지 않습니다. 예를 들어 deletion_scheduled 상태인 네임스페이스는 상위 항목이 archived를 전파해도 바뀌지 않습니다.

maintenance 상태는 네임스페이스와 그 하위 요소를 읽기 전용 모드로 전환하여 전체 계층 구조를 조직 이전에 대비시킵니다. maintenance 상태는 아직 사용되지 않으며, 전파도 아직 완전히 연결되지 않았습니다.

transfer_in_progress, transfer_scheduled 같은 다른 상태는 전파되지 않습니다. 네임스페이스 수준의 이전은 선택한 네임스페이스에만 영향을 주며, 하위 요소의 유효 상태에는 영향을 주지 않습니다.

구성 요소#

전파는 함께 동작하는 네 가지 구성 요소를 사용합니다.

Mermaid 다이어그램 (10줄)
소스 코드 보기
%%{init: { "flowchart": { "useMaxWidth": true } }}%%
flowchart TD
  accTitle: Namespace state propagation components
  accDescr: A state change writes an outbox record, a worker reads the outbox and drives the iterator, and the iterator returns descendant IDs to update.

A[State change on a namespace] --> B[Outbox record in namespace_state_propagations] B --> C[StatePropagationWorker] C --> D[StatePropagationIterator] D --> E[Conditional UPDATE of descendant states] F[StatePropagationCronWorker] -.recovers lost or stalled records.-> B

트랜잭션 아웃박스#

네임스페이스 상태가 바뀌면 GitLab은 같은 데이터베이스 트랜잭션에서 상태 변경과 아웃박스 레코드를 함께 기록합니다. 아웃박스 레코드는 namespace_state_propagations 테이블의 행입니다. 두 쓰기가 함께 커밋되므로 전파 요청은 유실될 수 없습니다. 레코드를 처리하는 워커가 비정상 종료되어도 레코드가 남아 재시도됩니다.

이 패턴은 트랜잭셔널 아웃박스입니다. Namespaces::StatePropagation 모델은 시작점이 된 namespace_id, source_state, target_state, 그리고 pending 또는 processing인 status를 저장합니다. 네임스페이스에는 하위 요소가 상속하는 상태를 바꾸는 전환마다 하나씩, 여러 레코드가 있을 수 있습니다. 고유 부분 인덱스는 네임스페이스마다 processing 레코드를 하나만 허용합니다. 한 네임스페이스의 레코드가 정렬되는 방식은 동일 네임스페이스 순서 지정을 참조합니다.

상태 우선순위#

Namespaces::Stateful::StatePrecedence 모듈은 전파가 덮어쓸 수 있는 하위 요소 상태를 결정합니다. overwritable_states(source_state, target_state) 메서드는 우선순위 표에 따라 전파가 변경할 수 있는 하위 요소 상태를 반환합니다.

덮어쓸 수 있는 상태의 집합은 대상 상태와 네임스페이스가 벗어나는 상태에 모두 따라 달라집니다.

소스 상태 대상 상태 덮어쓸 수 있는 하위 요소 상태 이유
ancestor_inherited archived ancestor_inherited 활성 상태의 하위 요소를 보관합니다.
ancestor_inherited deletion_scheduled ancestor_inherited, archived 활성 및 보관된 하위 요소의 삭제를 예약합니다.
archived deletion_scheduled ancestor_inherited, archived 활성 및 보관된 하위 요소의 삭제를 예약합니다.
archived ancestor_inherited archived 보관을 해제하되 deletion_scheduled에서 멈춥니다.
deletion_scheduled ancestor_inherited deletion_scheduled, archived 삭제로 함께 처리된 모든 항목을 복원하되, 자체적으로 삭제를 예약한 하위 요소에서 멈춥니다.

소스 상태와 대상 상태의 우선순위가 같거나 지원되지 않는 조합이면 메서드는 빈 배열을 반환하고 하위 요소는 변경되지 않습니다.

상태 전파 워커#

Namespaces::StatePropagationWorker가 전파를 수행합니다. 지정된 namespace_id에 대해 워커는 해당 네임스페이스의 아웃박스 레코드를 오래된 것부터 가져옵니다. 레코드마다 워커는 다음을 수행합니다.

  1. 레코드가 processing이면 이전 실행이 아직 활성 상태이거나 해당 프로세스가 종료된 것이므로 중단합니다. 그렇지 않으면 레코드를 processing으로 표시합니다.
  2. StatePrecedence로 덮어쓸 수 있는 상태를 계산합니다.
  3. 이터레이터가 하위 요소를 배치 단위로 순회하도록 구동합니다.
  4. 배치마다 조건부 업데이트를 적용합니다.
  5. 전파가 완료되면 아웃박스 레코드를 삭제한 다음 다음 레코드로 계속합니다.

워커는 레코드 사이에서만 실행 시간 제한을 확인합니다. 제한을 초과했고 레코드가 남아 있으면, 워커는 다음 레코드를 시작하지 않고 해당 네임스페이스에 대해 자신을 다시 큐에 넣습니다. 이렇게 하면 레코드가 많은 네임스페이스가 워커 슬롯을 오래 점유하지 않습니다. 레코드 하나는 항상 끝까지 실행되므로, 큰 하위 트리를 한 번 순회하는 작업은 여전히 제한을 초과할 수 있습니다.

업데이트는 전파를 시작한 네임스페이스를 변경하지 않습니다. 그 네임스페이스는 이미 새 상태를 가지고 있으며, 레코드가 기록된 이후 다시 바뀌었을 수도 있습니다.

조건부 업데이트는 아직 덮어쓸 수 있는 상태에 있는 하위 요소만 변경합니다.

UPDATE namespaces
SET state = :target_state
WHERE id IN (:batch_ids)
  AND state IN (:overwritable_states)

워커가 도중에 오류를 발생시키면 아웃박스 레코드를 pending으로 되돌리고 Sidekiq이 잡을 재시도합니다. 워커 프로세스가 대신 종료되면, 조정 워커가 레코드를 초기화하고 다시 큐에 넣을 때까지 레코드는 processing 상태로 남습니다.

상태 인식 이터레이터#

Gitlab::Database::Namespaces::StatePropagationIterator는 트리 계층 구조의 배치 반복에 설명된 네임스페이스 트리 이터레이터의 하위 클래스입니다. 기본 이터레이터는 계층 구조를 깊이 우선으로 순회하며 하위 요소 ID를 배치 단위로 반환합니다. 하위 클래스는 상태가 필터에 포함된 네임스페이스로 순회를 제한하는 state_filter를 추가합니다.

워커는 덮어쓸 수 있는 상태와 대상 상태를 함께 필터로 전달합니다. 이미 대상 상태인 하위 요소를 거쳐서도 순회가 계속되도록 대상 상태를 포함합니다. 이터레이터는 순회가 시작되는 네임스페이스의 상태를 확인하지 않습니다. 그런 다음 조건부 업데이트가 덮어쓸 수 있는 상태의 하위 요소만 변경되도록 보장합니다.

상태만으로는 자체적으로 삭제를 예약한 하위 요소와, 전파를 통해 deletion_scheduled를 상속한 하위 요소를 구분할 수 없습니다. 차이는 namespace_details.deletion_scheduled_at에 있습니다. schedule_deletion 전환은 이 칼럼을 설정하지만, 전파는 설정하지 않습니다.

상위 항목이 삭제를 취소하면(deletion_scheduled에서 ancestor_inherited 또는 archived로), 워커는 options: { preserve_descendants_deletion: true }를 전달합니다. 이 옵션을 사용하면 이터레이터는 deletion_scheduled_at이 설정된 모든 하위 요소를 경계로 취급합니다. 이터레이터는 해당 하위 요소와 그 하위 트리를 건너뛰므로, 이들은 삭제 예약을 유지합니다. 전파의 루트는 결코 경계가 되지 않습니다. 다른 상태 변경은 이 옵션을 설정하지 않으며 namespace_details를 확인하지 않습니다.

조정 워커#

Namespaces::StatePropagationCronWorker는 유실되었거나 정체된 전파 잡을 복구합니다. config/schedule.yml에 정의된 고정 일정에 따라 워커는 다음을 수행합니다.

  1. 오래됨 임계값을 초과한 pending 레코드의 수를 세어 stale_pending_total에 더합니다. 이 집계는 초기화 전에 실행되므로, 다음 단계에서 초기화된 레코드는 오래된 것으로 다시 집계되지 않습니다.
  2. 멈춤 임계값을 초과한 processing 레코드를 pending으로 되돌리고 started_at을 지우며, 초기화한 레코드 수를 stuck_processing_total에 더합니다.
  3. pending 레코드가 있는 네임스페이스마다 StatePropagationWorker 잡을 하나씩 큐에 넣습니다. 카운터는 이 단계 전에 업데이트되므로, 다시 큐에 넣는 데 실패해도 오래되었거나 멈춘 레코드가 가려지지 않습니다.
  4. 메트릭에 설명된 pending 및 processing 아웃박스 게이지를 갱신합니다.

StatePropagationWorker의 중복 제거는 네임스페이스마다 둘 이상의 잡이 큐에 들어가지 않도록 합니다. 다른 잡이 실행되는 동안 잡이 중복으로 삭제되면, 그사이 생성된 레코드를 처리하기 위해 워커가 이후에 한 번 더 실행됩니다. 잡이 레코드를 processing으로 선점해야 하고 고유 부분 인덱스가 네임스페이스마다 processing 레코드를 하나만 허용하므로, 네임스페이스마다 한 번에 레코드 하나만 적용됩니다.

동일 네임스페이스 순서 지정#

네임스페이스는 이전 변경의 전파가 끝나기 전에 다시 상태가 바뀔 수 있습니다. 예를 들어 하위 요소가 아직 보관되는 동안 그룹이 보관되었다가 보관 해제되는 경우입니다.

GitLab은 한 네임스페이스의 레코드를 id 순서로 한 번에 하나씩 적용하며, 각 레코드는 끝까지 실행됩니다. 레코드는 병합되거나 건너뛰지 않으므로 다음이 보장됩니다.

  • 레코드의 source_state는 레코드가 실행될 때 하위 요소가 상속하는 상태와 항상 일치합니다.
  • 보존되는 상태가 올바르게 저장되고 복원됩니다. 예를 들어 보관이 절반만 적용된 상태에서 삭제를 예약해도 모든 하위 요소의 archived가 보존됩니다.
  • 모든 레코드가 끝나면 하위 요소는 네임스페이스의 마지막 전환에 해당하는 상태를 가집니다.

id 순서는 한 네임스페이스의 커밋 순서와 일치합니다. 전환은 레코드를 삽입하기 전에 네임스페이스 행을 잠그고, 트랜잭션이 커밋될 때까지 잠금을 유지합니다. 같은 네임스페이스의 두 번째 전환은 그 잠금을 기다리므로 레코드가 더 큰 id를 받습니다.

잠금은 레코드의 순서를 정하지만, 두 번째 요청이 불러온 상태를 갱신하지는 않습니다. 두 요청이 어느 쪽이 커밋하기 전에 네임스페이스를 불러오면, 두 번째 레코드의 source_state가 오래된 값일 수 있습니다. 이슈 638361에서 이를 추적합니다.

실패한 레코드는 완료될 때까지 같은 네임스페이스의 이후 레코드를 차단합니다.

메트릭#

Gitlab::NamespaceStatePropagation::Metrics는 전파의 Prometheus 메트릭을 정의합니다. target_state 레이블은 archived와 같이 전파된 상태입니다. 카디널리티를 제한하기 위해 어떤 메트릭에도 namespace_id 레이블이 없습니다.

이름 유형 레이블 설명
gitlab_namespaces_state_propagation_duration_seconds Histogram target_state 아웃박스 레코드를 processing으로 표시한 시점부터 삭제할 때까지의 시간입니다. 상태를 전파하는 성공한 실행에 대해서만 관측됩니다.
gitlab_namespaces_state_propagation_batches_total Counter target_state 이터레이터가 산출하고 워커가 업데이트하는 하위 요소 배치입니다.
gitlab_namespaces_state_propagation_boundary_rewinds_total Counter None 이터레이터가 경계를 지나 커서를 되감은 횟수입니다. 순회를 끝내는 경계는 집계되지 않습니다.
gitlab_namespaces_state_propagation_failures_total Counter target_state 오류가 발생한 StatePropagationWorker 실행입니다. 오류는 다시 발생시킵니다. 네임스페이스 상태가 아닌 target_state는 unknown으로 레이블이 지정됩니다.
gitlab_namespaces_state_propagation_pending_records Gauge None namespace_state_propagations의 pending 레코드 수입니다.
gitlab_namespaces_state_propagation_processing_records Gauge None namespace_state_propagations의 processing 레코드 수입니다.
gitlab_namespaces_state_propagation_stuck_processing_total Counter None 30분보다 오래전에 시작되어 StatePropagationCronWorker가 pending으로 되돌린 processing 레코드입니다.
gitlab_namespaces_state_propagation_stale_pending_total Counter None 15분보다 오래전에 생성된 pending 레코드입니다. StatePropagationCronWorker는 실행할 때마다 현재 개수를 더하므로, 레코드가 오래된 상태로 남아 있는 동안 카운터가 계속 증가합니다.

소요 시간 히스토그램은 0.1, 0.5, 1, 5, 15, 30, 60, 120, 300, 600, 1800초 버킷을 사용합니다.

StatePropagationCronWorker는 실행이 끝날 때마다 두 게이지를 모두 갱신합니다. 각 개수는 테이블 전체를 대상으로 하며 Sidekiq 프로세스 전반에서 합산하면 과다 집계되므로, 게이지는 max 멀티프로세스 모드를 사용합니다. 프로세스는 크론 워커가 해당 프로세스에서 다시 실행되거나 프로세스가 재시작될 때까지 마지막으로 설정한 값을 유지합니다. 따라서 아웃박스가 비워진 뒤에도 게이지는 이전에 크론 워커를 실행한 프로세스의 오래된 값을 보고할 수 있습니다.

오래된 레코드에 대해 알림을 설정하려면 게이지 대신 stuck_processing_total 및 stale_pending_total 카운터를 사용합니다. 카운터는 단조 증가하며 프로세스 전반에서 합산되므로, 아웃박스가 비워진 뒤에도 오래된 값을 보고하지 않습니다. 절대값 대신 increase(...[window]) > 0에 대해 알림을 설정합니다. 모든 Sidekiq 프로세스는 시작할 때 두 카운터를 0으로 생성합니다. increase()는 시계열의 첫 번째 샘플을 무시하므로, 첫 실제 증가로 생성된 카운터는 그 증가를 놓치게 됩니다. stale_pending_total은 실행할 때마다 오래된 레코드 수를 더하므로, 증가율은 크론 일정에 따라 달라집니다.

StatePropagationCronWorker의 실패는 별도로 집계되지 않습니다. 대신 이 워커에는 표준 sidekiq_jobs_failed_total 메트릭을 사용합니다.

로깅#

전파는 Gitlab::AppLogger에 구조화된 로그 항목을 기록합니다. 각 이벤트에는 검색할 수 있는 고유한 message 값이 있습니다.

message 수준 필드
Namespace state propagation started info class_name, gl_namespace_id, source_state, target_state
Namespace state propagation completed info class_name, gl_namespace_id, target_state, batch_count, duration_s, descendants_updated
Namespace state propagation cursor rewound info class_name, gl_namespace_id, boundary_id, boundary_state, depth_before, depth_after
Namespace state propagation failed error class_name, gl_namespace_id, target_state, error_type, error_message

다음은 이 항목에 대한 설명입니다.

  • gl_namespace_id는 전파가 시작된 네임스페이스입니다.
  • descendants_updated는 조건부 업데이트가 변경한 행만 집계하므로, 이 값은 방문한 네임스페이스 수보다 작을 수 있습니다.
  • duration_s는 배치 순회 시간만 포함합니다.
  • depth_before와 depth_after는 이터레이터가 경계를 지나 되감기 전후의 커서 경로 길이입니다.

아웃박스 레코드가 존재하지 않거나, 덮어쓸 수 있는 하위 요소 상태가 없거나, 다른 잡이 이미 레코드를 선점한 경우에는 항목이 기록되지 않습니다. 실패가 기록된 후 오류가 다시 발생하므로, 재시도와 조정은 이전과 동일하게 동작합니다.

예시 따라 하기#

각 노드에 현재 상태가 표시된 다음 계층 구조를 가정합니다.

Mermaid 다이어그램 (10줄)
소스 코드 보기
%%{init: { "flowchart": { "useMaxWidth": true } }}%%
flowchart TD
  accTitle: Example namespace hierarchy before propagation
  accDescr: A top-level group that is active, with one active subgroup, one archived subgroup, and one subgroup scheduled for deletion.

Root["Top-level group (ancestor_inherited)"] --> A["Subgroup A (ancestor_inherited)"] Root --> B["Subgroup B (archived)"] Root --> C["Subgroup C (deletion_scheduled)"] A --> A1["Project A1 (ancestor_inherited)"] B --> B1["Project B1 (archived)"]

최상위 그룹을 보관하면 source_state가 ancestor_inherited이고 target_state가 archived인 전파가 실행됩니다. StatePrecedence.overwritable_states(:ancestor_inherited, :archived)는 [:ancestor_inherited]를 반환하므로 활성 상태의 하위 요소만 변경됩니다.

결과는 다음과 같습니다.

Mermaid 다이어그램 (10줄)
소스 코드 보기
%%{init: { "flowchart": { "useMaxWidth": true } }}%%
flowchart TD
  accTitle: Example namespace hierarchy after archiving the top-level group
  accDescr: The top-level group, subgroup A, and project A1 become archived. Subgroup B stays archived. Subgroup C stays scheduled for deletion.

Root["Top-level group (archived)"] --> A["Subgroup A (archived)"] Root --> B["Subgroup B (archived)"] Root --> C["Subgroup C (deletion_scheduled)"] A --> A1["Project A1 (archived)"] B --> B1["Project B1 (archived)"]

이 예시에서는 다음과 같습니다.

  • 하위 그룹 A와 프로젝트 A1은 ancestor_inherited에서 archived로 바뀝니다.
  • 하위 그룹 B와 프로젝트 B1은 이미 archived이므로 바뀌지 않습니다.
  • deletion_scheduled의 우선순위가 archived보다 높으므로 하위 그룹 C는 deletion_scheduled로 유지됩니다.

기반이 된 머지 리퀘스트#

전파 알고리즘은 여러 머지 리퀘스트에 걸쳐 구축되었습니다.

전체 계획은 에픽 21607을 참조합니다.