GitLab Cells 개발 가이드라인

GitLab Cells에 대한 배경은 디자인 문서를 참조하세요.

gitlab_main_cell 또는 gitlab_main_clusterwide 스키마 중 하나 선택

사용 사례에 따라 귀하의 기능은 cell-local 또는 clusterwide일 수 있으며, 따라서 기능에 사용되는 테이블도 적절한 스키마를 사용해야 합니다.

테이블을 위한 적절한 스키마를 선택할 때는 Cells 아키텍처의 다음 가이드라인을 고려하세요:

  • 기본적으로 gitlab_main_cell을 선택하세요: 대부분의 테이블은 기본적으로 gitlab_main_cell 스키마에 할당되기를 기대합니다. 테이블의 데이터가 projects 또는 namespaces와 관련된 경우 이 스키마를 선택하세요.

  • Tenant Scale 그룹에 상담하세요: 테이블에 gitlab_main_clusterwide 스키마가 더 적합하다고 생각되면, Tenant Scale 그룹의 승인을 받으세요. 이는 중요하며, 스케일링의 의미가 있으며 스키마 선택을 재고해야 할 수도 있습니다.

gitlab_main_clusterwide 스키마를 가진 테이블은 다른/모든 셀에 복제되기 위해 추가 작업이 필요합니다.

복제 전략은 각 경우마다 다를 수 있으며, 내부 API를 포함할 것입니다.

애플리케이션은 충돌을 방지하기 위해 쓰기를 제한하도록 수정해야 할 수도 있습니다.

또한 팀에 gitlab_main_clusterwide에서 gitlab_main_cell로 테이블을 업데이트하도록 요청할 수 있으며, 이는 해당 테이블에 샤딩 키를 추가해야 할 수도 있습니다.

기존 테이블이 어떻게 분류되는지 이해하려면 이 대시보드를 사용할 수 있습니다.

스키마가 할당된 후, 병합 요청 파이프라인은 다음과 같은 이유로 실패할 수 있으며, 이것은 링크된 가이드라인을 따라 수정할 수 있습니다:

모든 셀 로컬 테이블에 대한 샤딩 키 정의

다음 gitlab_schema를 가진 모든 테이블은 “셀 로컬”로 간주됩니다:

  • gitlab_main_cell
  • gitlab_ci
  • gitlab_sec

새로 생성된 모든 셀 로컬 테이블은 해당 테이블의 db/docs/ 파일에 정의된 sharding_key를 가져야 합니다.

샤딩 키의 목적은 조직 격리 블루프린트에 문서화되어 있지만, 간단히 말해 이 열은 데이터베이스에서 특정 행을 소유하는 조직을 정하는 표준 방법을 제공하는 데 사용됩니다.

이 열은 향후 조직 경계를 넘지 않도록 데이터를 제약하는 데 사용될 것이며, 셀 간의 데이터를 마이그레이션하는 통일된 방법을 제공하는 데도 사용될 것입니다.

외래 키의 실제 이름은 무엇이든 될 수 있지만 projects 또는 groups의 행을 참조해야 합니다. 선택된 sharding_key 열은 null이 될 수 없습니다.

여러 개의 sharding_key를 설정할 수 있으며, nullable 열도 허용되지만, 테이블 내에서 적어도 하나의 키는 non-nullable이어야 함을 보장하는 체크 제약 조건이 있어야 합니다.

다음은 유효한 샤딩 키의 예입니다:

  • 테이블 항목이 프로젝트에만 속하는 경우:

    sharding_key:
  project_id: projects

  • 테이블 항목이 프로젝트에 속하고 외래 키가 target_project_id인 경우:

    sharding_key:
  target_project_id: projects

  • 테이블 항목이 네임스페이스/그룹에만 속하는 경우:

    sharding_key:
  namespace_id: namespaces

  • 테이블 항목이 네임스페이스/그룹에만 속하고 외래 키가 group_id인 경우:

    sharding_key:
  group_id: namespaces

  • 테이블 항목이 네임스페이스 또는 프로젝트에 속하는 경우:

    sharding_key:
  project_id: projects
  namespace_id: namespaces

샤딩 키는 변경 불가능해야 합니다

sharding_key의 선택은 항상 변경 불가능해야 합니다. 따라서, 귀하의 기능이 프로젝트 또는 그룹/네임스페이스 간에 데이터를 이동할 수 있는 사용자 경험을 필요로 하는 경우, 이동 기능을 재설계하여 새로운 행을 생성해야 할 수도 있습니다. 이와 관련된 예시는 문제 이동 기능에서 확인할 수 있습니다. 이 기능은 기존 issues 행의 project_id 열을 실제로 변경하지 않고 대신 새로운 issues 행을 생성하고 원본 issues 행과 데이터베이스에서 연결을 생성합니다. 데이터를 이동해야 하는 특히 어려운 기존 기능이 있는 경우, 샤딩 키를 관리하는 방법에 대해 논의하기 위해 조기 단계에서 Tenant Scale 팀에 연락해야 합니다.

프로젝트 및 네임스페이스에 동일한 샤딩 키 사용

개발자는 테이블에 의해 사용되는 기능이 개발되고 있는 프로젝트에 속할 수 있는 테이블에 대해서만 namespace_id를 사용하도록 선택할 수도 있습니다. 이는 그룹 및 프로젝트 통합 청사진을 따릅니다. 이 경우 namespace_id는 네임스페이스가 속하는 그룹이 아닌 ProjectNamespace의 ID여야 합니다.

organization_id를 샤딩 키로 사용

보통, project_id 또는 namespace_id는 가장 일반적인 샤딩 키입니다. 그러나 테이블이 프로젝트 또는 네임스페이스에 속하지 않는 경우도 있습니다.

이러한 경우, 아래 지침을 따르고 organization_id를 샤딩 키로 선택할 수 있습니다:

  • sharding_key 열은 변경 불가능해야 합니다.
  • 루트 수준 모델(예: namespaces)에 대해서만 organization_id를 추가하고, 잎 수준 모델(예: issues)에는 추가하지 않습니다.
  • 그러한 테이블은 그룹 또는 프로젝트와 관련된 데이터를 포함하지 않도록 해야 합니다(또는 그룹/프로젝트에 속한 레코드). 대신, project_id 또는 namespace_id를 사용하십시오.
  • 행이 많은 테이블은 좋은 후보가 아닙니다.
  • 이 테이블을 참조하는 다른 테이블이 있을 경우, 참조 테이블의 레코드가 다른 조직으로 이동되어도 애플리케이션이 계속 작동해야 합니다.

organization_id가 샤딩 키에 대한 최상의 옵션이라고 생각되면, Tenant Scale 그룹의 승인을 받으십시오. 이는 데이터 마이그레이션에 영향을 미치며 샤딩 키의 선택을 재고해야 할 수 있기 때문에 중요합니다.

예시로, 기존 테이블에 organization_id를 샤딩 키로 추가한 이 문제를 참조하세요.

desired_sharding_key 정의하여 자동으로 sharding_key를 백필

우리는 백필이 필요 없는 수백 개의 테이블에 sharding_key를 백필해야 합니다. 이 과정에는 새로운 열을 추가하고 데이터베이스의 관련 테이블에서 데이터를 백필하며, 다음으로 인덱스, 외래 키 및 널이 아닌 제약 조건을 추가하는 병합 요청을 만드는 것이 포함됩니다.

개발자들의 반복적인 노력을 최소화하기 위해, 우리는 특정 테이블에 대해 sharding_key를 백필하는 방법을 간결하게 설명하는 방법을 도입했습니다. 이 콘텐츠는 후속 자동화에 사용되어 모든 필요한 병합 요청을 생성하는 데 사용됩니다.

desired_sharding_key의 예시는 https://gitlab.com/gitlab-org/gitlab/-/merge_requests/139336에 추가되었으며, 다음과 같습니다:

--- # db/docs/security_findings.yml
table_name: security_findings
classes:
- Security::Finding

...

desired_sharding_key:
  project_id:
    references: projects
    backfill_via:
      parent:
        foreign_key: scanner_id
        table: vulnerability_scanners
        table_primary_key: id # 선택적. 기본값은 'id'
        sharding_key: project_id
        belongs_to: scanner

이 YAML 데이터가 어떻게 사용될 것인지 가장 잘 이해할 수 있도록, 우리는 GraphQL에서 수동으로 만든 병합 요청 https://gitlab.com/gitlab-org/gitlab/-/merge_requests/136800에 매핑할 수 있습니다. 아이디어는 이를 자동으로 생성하는 것입니다. YAML의 내용은 부모 테이블과 배치된 백그라운드 마이그레이션에서 백필할 sharding_key를 지정하고, 모델에 sharding_key를 자동으로 채우기 위해 before_save에 추가될 belongs_to 관계를 지정합니다.

부모 테이블에 desired_sharding_key가 있을 때 정의하기

기본적으로, desired_sharding_key 구성은 선택한 sharding_key가 부모 테이블에 존재하는지 검증합니다. 그러나 부모 테이블에도 desired_sharding_key 구성이 있으며 백필이 대기 중인 경우, awaiting_backfill_on_parent 필드를 포함해야 합니다. 예를 들어:

desired_sharding_key:
  project_id:
    references: projects
    backfill_via:
      parent:
        foreign_key: package_file_id
        table: packages_package_files
        table_primary_key: id # 선택 사항. 기본값은 'id'
        sharding_key: project_id
        belongs_to: package_file
    awaiting_backfill_on_parent: true

이 desired_sharding_key 구조가 sharding_key의 백필에 적합하지 않은 엣지 케이스가 있을 수 있습니다. 이러한 경우 테이블을 소유한 팀은 sharding_key를 수동으로 추가하기 위한 필요한 병합 요청을 생성해야 합니다.

특정 테이블의 sharding key 면제

특정 테이블은 다음을 추가하여 sharding key 면제를 받을 수 있습니다.

exempt_from_sharding: true

이것은 다음과 같은 경우에 사용될 수 있습니다:

  • JiHu 전용 테이블, .com 데이터베이스에 데이터가 없기 때문에. !145905
  • operations_feature_flag_scopes와 같이 곧 삭제될 예정인 테이블. !147541
  • 셀의 운영을 지원하기 위해 필수적으로 존재해야 하며, 셀마다 고유한 데이터를 가지지만, sharding key를 정의할 수 없는 테이블. 예를 들어, zoekt_nodes.

테이블이 sharding key 요구 사항에서 면제될 경우, 해당 테이블은 우리의 진행 대시보드에 표시되지 않습니다.

면제된 테이블은 외래 키 또는 느슨한 외래 키 참조를 가져서는 안 됩니다. 데이터가 이동할 때 대상 셀의 데이터베이스에서 외래 키 위반이 발생할 수 있습니다. 예시와 가능한 솔루션은 #471182에서 확인하세요.