• Elasticsearch 또는 AWS OpenSearch 클러스터 설치
  • 버전 요구 사항
    • Elasticsearch
    • OpenSearch
  • 시스템 요구 사항
  • 액세스 요구 사항
    • Elasticsearch 역할 기반 액세스 제어
    • AWS OpenSearch 액세스 제어
      • 리소스 기반 정책 예시
      • Identity-based policy examples
      • Fine-grained access control examples
    • AWS OpenSearch 서비스에 연결
      • HTTP 기본 인증
      • 역할 기반 인증
  • 새로운 Elasticsearch 주요 버전으로 업그레이드
• Elasticsearch 저장소 인덱서
  • 인덱서 설치
    • 종속성 설치
      • Debian / Ubuntu
      • CentOS / RHEL
      • macOS
    • 빌드 및 설치
  • 색인 오류 보기
• 고급 검색 활성화
  • 인스턴스 색인화
    • 사용자 인터페이스에서
    • Rake 작업으로
  • 색인화 상태 확인
  • 백그라운드 작업 상태 모니터링
  • 고급 검색 구성
  • 네임스페이스 및 프로젝트 데이터 양 제한
    • 모든 프로젝트 레코드가 색인됨
• 사용자 정의 언어 분석기 활성화
• 고급 검색 비활성화
• 색인 다시 시작
• 제로 다운타임 다시 색인하기
  • 제로 다운타임 재인덱싱 사용하기
  • 재인덱싱 트리거
    • 제로 다운타임 재인덱싱 트리거
      • Slice multiplier
      • Maximum running slices
  • 가장 최근의 재인덱싱 작업을 실패로 표시하고 인덱싱을 재개하기
• 인덱스 무결성
• 고급 검색 마이그레이션
  • 마이그레이션 사전 파일
  • 보류 중인 마이그레이션 확인
  • 중단된 마이그레이션 재시도
  • 모든 이주(migrations)는 주요 업그레이드를 수행하기 전에 완료되어야 합니다
  • 건너뛸 수 있는 이주
• GitLab 고급 검색 Rake 작업
  • 환경 변수
  • 프로젝트 범위 또는 특정 프로젝트 색인화
• 고급 검색 색인 범위
• 튜닝
  • 최적의 클러스터 구성 선택 가이드
  • 고급 검색 설정
    • Elasticsearch 샤드 수
      • 데이터베이스 데이터가 있는 색인
      • 저장소 데이터가 있는 색인
    • Elasticsearch 복제품 수
  • 대용량 인스턴스 색인화 효율적으로 수행
  • 삭제된 문서
• 전용 Sidekiq 노드 또는 프로세스로 대규모 인스턴스 색인
  • 단일 노드에서 두 개의 프로세스 사용
  • 두 노드, 각각 하나의 프로세스
• 기본 검색으로 복귀
• 재해 복구

Elasticsearch

이 문서에서는 고급 검색을 활성화하는 방법을 설명합니다. 활성화되면, 고급 검색은 더 빠른 검색 응답 시간과 개선된 검색 기능을 제공합니다.

고급 검색을 활성화하려면 다음을 수행해야 합니다:

1. Elasticsearch 또는 AWS OpenSearch 클러스터 설치.
2. 고급 검색 활성화.

Elasticsearch 또는 AWS OpenSearch 클러스터 설치

Elasticsearch 및 AWS OpenSearch는 Linux 패키지에 포함되지 않습니다. 검색 클러스터를 직접 설치하거나 다음과 같이 클라우드 호스팅 오퍼링을 사용할 수 있습니다:

• Elasticsearch Service (Amazon Web Services, Google Cloud Platform, Microsoft Azure에서 사용 가능)
• Amazon OpenSearch Service

검색 클러스터를 별도의 서버에 설치해야 합니다. GitLab과 동일한 서버에서 검색 클러스터를 실행하면 성능 문제가 발생할 수 있습니다.

단일 노드로 구성된 검색 클러스터의 경우, 주 샤드가 할당되어 있기 때문에 클러스터 상태가 항상 노란색입니다. 클러스터는 리플리카 샤드를 주 샤드와 동일한 노드에 할당할 수 없습니다.

참고: 프로덕션 환경에서 새로운 Elasticsearch 클러스터를 사용하기 전에 중요한 Elasticsearch 구성을 확인하세요.

버전 요구 사항

Elasticsearch

• GitLab 15.0에서 Elasticsearch 6.8의 지원이 제거되었습니다.

고급 검색은 다음 Elasticsearch 버전과 호환됩니다.

고급 검색은 Elasticsearch 생명 주기 정책을 따릅니다. GitLab에서 Elasticsearch 지원 버전을 변경할 때는 해당 버전을 제거하기 전에 매월 릴리스 게시물의 제거 중 공지에서 공지합니다.

OpenSearch

Elasticsearch 또는 OpenSearch 버전이 호환되지 않는 경우, 데이터 손실을 방지하기 위해 색인 일시 중지가 되며 elasticsearch.log 파일에 메시지가 기록됩니다.

호환되는 버전을 사용하고 OpenSearch에 연결한 후 Elasticsearch 버전이 호환되지 않음 메시지를 받으면 색인 재개를 수행하세요.

시스템 요구 사항

Elasticsearch 및 AWS OpenSearch는 GitLab 설치 요구 사항보다 더 많은 리소스가 필요합니다.

메모리, CPU 및 저장소 요구 사항은 클러스터에 색인하는 데이터 양에 따라 다릅니다. 많이 사용되는 Elasticsearch 클러스터는 더 많은 리소스가 필요할 수 있습니다. estimate_cluster_size Rake 태스크는 총 리포지토리 크기를 사용하여 고급 검색 저장소 요구 사항을 추정합니다.

액세스 요구 사항

GitLab은 요구 사항 및 사용하는 백엔드 서비스에 따라 HTTP 및 역할 기반 인증 방법을 모두 지원합니다.

Elasticsearch 역할 기반 액세스 제어

Elasticsearch는 클러스터를 더 안전하게 보호하기 위해 역할 기반 액세스 제어를 제공할 수 있습니다. Elasticsearch 클러스터에 액세스하고 작업을 수행하려면 관리자 영역에서 구성된 사용자 이름이 다음 권한을 부여하는 역할을 가지고 있어야 합니다. 사용자 이름은 GitLab에서 검색 클러스터로 요청을 보냅니다.

자세한 내용은 Elasticsearch 역할 기반 액세스 제어 및 Elasticsearch 보안 권한을 참조하세요.

{
  "cluster": ["monitor"],
  "indices": [
    {
      "names": ["gitlab-*"],
      "privileges": [
        "create_index",
        "delete_index",
        "view_index_metadata",
        "read",
        "manage",
        "write"
      ]
    }
  ]
}

AWS OpenSearch 액세스 제어

전제 조건:

• OpenSearch 도메인을 생성할 때 AWS 계정에 AWSServiceRoleForAmazonOpenSearchService이란 이름의 서비스 연결 역할이 있어야 합니다.
• AWS OpenSearch에 대한 도메인 액세스 정책은 es:ESHttp* 동작을 허용해야 합니다.

AWSServiceRoleForAmazonOpenSearchService은 모든 OpenSearch 도메인에서 사용됩니다. 대부분의 경우, 첫 번째 OpenSearch 도메인을 만들 때 AWS Management Console을 사용하면이 역할이 자동으로 생성됩니다. 서비스 연결 역할을 수동으로 만들려면 AWS 문서를 참조하세요.

GitLab은 AWS OpenSearch의 다음과 같은 액세스 제어 방법을 지원합니다:

• VPC 도메인 액세스 정책: AWS OpenSearch 도메인이 VPC 내에서 배포되고 내부적으로 접근 가능한 경우
• 리소스 기반(도메인) 액세스 정책: AWS OpenSearch 도메인이 IAM 정책으로 구성된 경우
• 아이덴티티 기반 정책: 클라이언트가 IAM 주체 및 정책을 사용하여 액세스를 구성하는 경우

미세한 액세스 제어와 같은 고급 옵션도 사용할 수 있습니다.

리소스 기반 정책 예시

여기에는 es:ESHttp* 동작이 허용되는 리소스 기반(도메인) 액세스 정책의 예시가 있습니다:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": [
        "es:ESHttp*"
      ],
      "Resource": "arn:aws:es:us-west-1:987654321098:domain/test-domain/*"
    }
  ]
}

여기에는 es:ESHttp* 동작이 특정 IAM 주체에 대해서만 허용되는 리소스 기반(도메인) 액세스 정책의 예시가 있습니다:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::123456789012:user/test-user"
        ]
      },
      "Action": [
        "es:ESHttp*"
      ],
      "Resource": "arn:aws:es:us-west-1:987654321098:domain/test-domain/*"
    }
  ]
}

Identity-based policy examples

다음은 es:ESHttp* 액션이 허용된 IAM 주체에 부착된 ID 기반 액세스 정책의 예입니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "es:ESHttp*",
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}

Fine-grained access control examples

AWS OpenSearch 클러스터에서 세밀한 액세스 제어로 액세스하고 작업을 수행하려면 GitLab 사용자에게 다음 권한이 있어야 합니다.

자세한 내용은 OpenSearch 액세스 제어 권한 및 역할 생성을 확인하세요.

참고: 인덱스 패턴 *은 고급 검색에 필수적인 몇 가지 권한이 필요합니다.

{
  "cluster_permissions": [
    "cluster_composite_ops",
    "cluster_monitor"
  ],
  "index_permissions": [
    {
      "index_patterns": [
        "gitlab*"
      ],
      "allowed_actions": [
        "data_access",
        "manage_aliases",
        "search",
        "create_index",
        "delete",
        "manage"
      ]
    },
    {
      "index_patterns": [
        "*"
      ],
      "allowed_actions": [
        "indices:admin/aliases/get",
        "indices:monitor/stats"
      ]
    }
  ]
}

AWS OpenSearch 서비스에 연결

액세스 요구 사항에 따라 GitLab 사용자가 다음을 가질 수 있습니다:

• HTTP 기본 인증
• 역할 기반 인증

HTTP 기본 인증

기본적으로 GitLab은 인증 없이 구성된 백엔드에 직접 연결을 시도합니다.

AWS OpenSearch에 사용자를 만든 경우(예: 세밀한 액세스 제어와 함께) AWS OpenSearch URL 또는 고급 검색 설정에 사용자 이름과 암호를 입력할 수 있습니다. 자세한 내용은 AWS 문서를 확인하세요.

역할 기반 인증

역할 기반 인증을 사용하려면:

1. 왼쪽 사이드바에서 맨 아래에서 관리자를 선택하세요.
2. 설정 > 검색을 선택하세요.
3. 고급 검색을 펼쳐보세요.
4. AWS OpenSearch IAM 자격 증명 섹션에서 AWS OpenSearch Service와 IAM 자격 증명 사용 확인란을 선택하세요.
5. 변경 사항 저장을 선택하세요.

IAM 역할의 경우:

• 인스턴스 프로필: 인스턴스 또는 파드(EKS IRSA)에 부착된 IAM 역할을 GitLab이 사용하기 위해 AWS 지역만 설정합니다.
• 특정 역할: GitLab이 키를 사용하여 직접 인증하기 위해 AWS 지역, AWS 액세스 키 ID, 및 AWS 비밀 액세스 키를 설정합니다.

새로운 Elasticsearch 주요 버전으로 업그레이드

• GitLab 15.0에서, Elasticsearch 6.8의 지원이 제거되었습니다.

Elasticsearch를 업그레이드할 때 GitLab 설정을 변경할 필요가 없습니다.

Elasticsearch를 업그레이드하는 동안 다음을 수행해야 합니다:

• 색인 일시 중지하여 변경 사항을 계속 추적할 수 있도록 합니다.
• 고급 검색을 비활성화하여 검색이 HTTP 500 오류로 실패하지 않도록 합니다.

Elasticsearch 클러스터가 완전히 업그레이드되고 활성 상태이면 색인 재개하고 고급 검색을 활성화하세요.

GitLab 15.0 및 이후 버전으로 업그레이드하는 경우 Elasticsearch 7.x 및 이후 버전을 사용해야 합니다.

Elasticsearch 저장소 인덱서

Git 저장소 데이터를 색인하려면 GitLab이 gitlab-elasticsearch-indexer를 사용합니다. 자체 컴파일된 설치에 대해서는 인덱서 설치를 참조하세요.

인덱서 설치

먼저 몇 가지 종속성을 설치한 후 인덱서 자체를 빌드하고 설치해야 합니다.

종속성 설치

이 프로젝트는 텍스트 인코딩을 위해 유니코드 국제 구성요소 (ICU)에 의존하므로 make를 실행하기 전에 플랫폼의 개발 패키지가 설치되어 있는지 확인해야 합니다.

Debian / Ubuntu

Debian이나 Ubuntu에서 설치하려면 다음을 실행하세요:

sudo apt install libicu-dev

CentOS / RHEL

CentOS 또는 RHEL에서 설치하려면 다음을 실행하세요:

sudo yum install libicu-devel

macOS

참고: 먼저 Homebrew를 설치해야 합니다.

macOS에서 설치하려면 다음을 실행하세요:

brew install icu4c
export PKG_CONFIG_PATH="/usr/local/opt/icu4c/lib/pkgconfig:$PKG_CONFIG_PATH"

빌드 및 설치

인덱서를 빌드하고 설치하려면 다음을 실행하세요:

indexer_path=/home/git/gitlab-elasticsearch-indexer

# gitlab-elasticsearch-indexer에 대한 설치 작업 실행:
sudo -u git -H bundle exec rake gitlab:indexer:install[$indexer_path] RAILS_ENV=production
cd $indexer_path && sudo make install

gitlab-elasticsearch-indexer는 /usr/local/bin에 설치됩니다.

PREFIX 환경 변수를 사용하여 설치 경로를 변경할 수 있습니다. 경우에 따라 -E 플래그를 sudo에 전달해야 합니다.

예:

PREFIX=/usr sudo -E make install

설치 후에는 Elasticsearch 활성화를 반드시 확인하세요.

참고: 색인 중에 Permission denied - /home/git/gitlab-elasticsearch-indexer/와 같은 오류가 발생하는 경우 production -> elasticsearch -> indexer_path 설정을 /usr/local/bin/gitlab-elasticsearch-indexer로 설정해야 할 수 있습니다. 이 경로에 바이너리가 설치되기 때문입니다.

색인 오류 보기

GitLab Elasticsearch Indexer에서의 오류는 elasticsearch.log 파일 및 json.exception.class가 Gitlab::Elastic::Indexer::Error인 sidekiq.log 파일에서 보고됩니다. 이러한 오류는 Git 저장소 데이터를 색인화할 때 발생할 수 있습니다.

고급 검색 활성화

필수 조건:

• 인스턴스의 관리자 액세스 권한이 있어야 합니다.

고급 검색을 활성화하려면:

1. 왼쪽 사이드바에서 맨 아래에서 관리를 선택합니다.
2. 설정 > 검색을 선택합니다.
3. 고급 검색 설정을 Elasticsearch 클러스터에 맞게 구성하십시오. 아직 Elasticsearch로 검색 활성화 확인란은 선택하지 마십시오.
4. 인스턴스 색인화를 해야 합니다.
5. 선택 사항. 색인화 상태 확인를 합니다.
6. 색인화가 완료되면, Elasticsearch로 검색 활성화 확인란을 선택한 후 변경 사항 저장을 선택합니다.

참고: Elasticsearch 클러스터가 활성화되어 있는 동안 Elasticsearch가 다운된 경우, 인스턴스가 변경 사항을 색인화 작업 대기열에 추가하지만 유효한 Elasticsearch 클러스터를 찾을 수 없어 이슈 등의 문서를 업데이트하는 데 문제가 발생할 수 있습니다.

저장소 데이터가 50GB 이상인 GitLab 인스턴스의 경우 대규모 인스턴스 효율적으로 색인화하기를 참조하세요.

인스턴스 색인화

사용자 인터페이스에서

• GitLab 17.3에 도입.

필수 조건:

• 인스턴스의 관리자 액세스 권한이 있어야 합니다.

사용자 인터페이스에서 초기 색인화를 수행하거나 색인을 다시 만들 수 있습니다.

고급 검색을 활성화하고 사용자 인터페이스에서 인스턴스를 색인화하려면:

1. 왼쪽 사이드바에서 맨 아래에서 관리를 선택합니다.
2. 설정 > 검색을 선택합니다.
3. Elasticsearch 색인화 확인란을 선택한 후 변경 사항 저장을 선택합니다.
4. 인스턴스 색인화를 선택합니다.

Rake 작업으로

필수 조건:

• 인스턴스의 관리자 액세스 권한이 있어야 합니다.

전체 인스턴스를 색인화하려면 다음 Rake 작업을 사용하십시오:

# 경고: 이 작업은 모든 기존 색인을 삭제합니다
# Linux 패키지를 사용하는 설치의 경우
sudo gitlab-rake gitlab:elastic:index

# 경고: 이 작업은 모든 기존 색인을 삭제합니다
# 독자적으로 컴파일된 설치의 경우
bundle exec rake gitlab:elastic:index RAILS_ENV=production

특정 데이터를 색인화하려면 다음 Rake 작업을 사용하십시오:

# Linux 패키지를 사용하는 설치의 경우
sudo gitlab-rake gitlab:elastic:index_epics
sudo gitlab-rake gitlab:elastic:index_work_items
sudo gitlab-rake gitlab:elastic:index_group_wikis
sudo gitlab-rake gitlab:elastic:index_namespaces
sudo gitlab-rake gitlab:elastic:index_projects
sudo gitlab-rake gitlab:elastic:index_snippets
sudo gitlab-rake gitlab:elastic:index_users

# 독자적으로 컴파일된 설치의 경우
bundle exec rake gitlab:elastic:index_epics RAILS_ENV=production
bundle exec rake gitlab:elastic:index_work_items RAILS_ENV=production
bundle exec rake gitlab:elastic:index_group_wikis RAILS_ENV=production
bundle exec rake gitlab:elastic:index_namespaces RAILS_ENV=production
bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production
bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production
bundle exec rake gitlab:elastic:index_users RAILS_ENV=production

색인화 상태 확인

필수 조건:

• 인스턴스의 관리자 액세스 권한이 있어야 합니다.

색인화 상태를 확인하려면:

1. 왼쪽 사이드바에서 맨 아래에서 관리를 선택합니다.
2. 설정 > 검색을 선택합니다.
3. 색인화 상태를 확장합니다.

백그라운드 작업 상태 모니터링

필수 조건:

• 인스턴스의 관리자 액세스 권한이 있어야 합니다.

백그라운드 작업 상태를 모니터링하려면:

1. 왼쪽 사이드바에서 맨 아래에서 관리를 선택합니다.
2. 모니터링 > 백그라운드 작업을 선택합니다.
3. Sidekiq 대시보드에서 대기열(Queues)를 선택하고 elastic_commit_indexer 및 elastic_wiki_indexer 대기열이 0으로 줄어들 때까지 기다립니다. 이러한 대기열에는 프로젝트 및 그룹의 코드 및 위키 데이터를 색인화하기 위한 작업이 포함되어 있습니다.

고급 검색 구성

다음과 같은 Elasticsearch 설정을 사용할 수 있습니다:

경고: 최대 대량 요청 크기(MiB) 및 대량 요청 동시성 값 증가는 Sidekiq 성능에 부정적인 영향을 미칠 수 있습니다. Sidekiq 로그에서 증가된 scheduling_latency_s 지속 시간을 확인하면 이 값을 기본값으로 되돌려야 합니다. 자세한 내용은 이슈 322147을 참조하십시오.

네임스페이스 및 프로젝트 데이터 양 제한

네임스페이스 및 프로젝트 데이터 양 제한 확인란을 선택하면 네임스페이스 및 프로젝트를 색인할 수 있습니다. 네임스페이스가 그룹인 경우 해당 하위 그룹과 해당 하위 그룹에 속한 프로젝트도 색인됩니다.

모든 네임스페이스가 색인된 경우에만 고급 검색에서 크로스 그룹 코드/커밋 검색(글로벌)이 제공됩니다. 특정 시나리오에서는 네임스페이스의 일부만 색인된 경우, 전역 검색은 코드 또는 커밋 범위를 제공하지 않습니다. 이는 색인된 네임스페이스의 범위에서만 가능합니다. 특정 네임스페이스에 대한 범위에서만 코드/커밋 검색이 가능합니다. 색인된 여러 네임스페이스에서 코드/커밋 검색을 할 수 없습니다(일부 네임스페이스만 색인된 경우). 예를 들어, 두 그룹이 색인된 경우, 두 그룹 모두에 대해 단일 코드 검색을 실행할 수 없습니다. 첫 번째 그룹에서만 코드 검색을 실행한 다음 두 번째 그룹에서 실행할 수 있습니다.

네임스페이스 또는 프로젝트를 지정하지 않으면, 프로젝트 레코드만 색인됩니다.

경고: 인스턴스를 이미 색인한 경우, 필터링이 올바르게 작동하려면 모든 기존 데이터를 삭제하도록 인덱스를 다시 생성해야 합니다. 이를 위해 gitlab:elastic:recreate_index 및 gitlab:elastic:clear_index_status rake 작업을 실행해야 합니다. 이후 목록에서 네임스페이스나 프로젝트를 제거하면 Elasticsearch 색인에서 해당 데이터가 예상대로 삭제됩니다.

모든 프로젝트 레코드가 색인됨

• GitLab 16.7에서 도입됨. 기본적으로 비활성화된 search_index_all_projects 플래그로.
• GitLab 16.11에서 일반적으로 사용 가능함. search_index_all_projects 플래그가 제거됨.

네임스페이스 및 프로젝트 데이터 양 제한 확인란을 선택하면:

• 모든 프로젝트 레코드가 색인됩니다.
• 연결된 데이터(이슈, 병합 요청 또는 코드)는 색인되지 않습니다.

네임스페이스 또는 프로젝트를 지정하지 않으면, 프로젝트 레코드만 색인됩니다.

사용자 정의 언어 분석기 활성화

전제 조건:

• 인스턴스에 대한 관리자 액세스가 있어야 합니다.

Elastic에서 smartcn 및 kuromoji 분석 플러그인을 사용하여 중국어 및 일본어의 언어 지원을 개선할 수 있습니다.

사용자 정의 언어 분석기를 활성화하려면:

1. 원하는 플러그인을 설치하고, 플러그인 설치 지침은 Elasticsearch 설명서를 참조하십시오. 플러그인은 클러스터의 모든 노드에 설치되어야 하며, 각 노드는 설치 후에 재시작되어야 합니다. 플러그인 목록은 이 섹션의 이후의 표를 참조하십시오.
2. 왼쪽 사이드바에서 하단에 있는 관리자를 선택합니다.
3. 설정 > 검색을 선택합니다.
4. 사용자 정의 분석기: 언어 지원을 찾습니다.
5. 색인에 대한 플러그인 지원을 활성화합니다.
6. 변경 사항을 적용하려면 변경 사항 저장을 선택합니다.
7. 제로 다운타임 다시 색인하기를 트리거하거나 모든 것을 처음부터 다시 색인하여 업데이트된 매핑이 있는 새 인덱스를 만듭니다.
8. 이전 단계가 완료된 후 검색에 대한 플러그인 지원을 활성화합니다.

설치할 내용에 대한 지침은 다음 Elasticsearch 언어 플러그인 옵션을 참조하십시오:

고급 검색 비활성화

전제 조건:

• 인스턴스에 대한 관리자 액세스가 있어야 합니다.

GitLab에서 고급 검색을 비활성화하려면:

1. 왼쪽 사이드바에서 하단에 있는 관리자를 선택합니다.
2. 설정 > 검색을 선택합니다.
3. Elasticsearch 색인화와 Elasticsearch 사용으로 검색 확인란을 지웁니다.
4. 변경 사항 저장을 선택합니다.

5. 옵션. 여전히 작동 중인 Elasticsearch 인스턴스에서 기존 색인을 삭제합니다:

   # 리눅스 패키지를 사용하는 설치의 경우
   sudo gitlab-rake gitlab:elastic:delete_index
   
   # 직접 컴파일한 설치의 경우
   bundle exec rake gitlab:elastic:delete_index RAILS_ENV=production
   

색인 다시 시작

전제 조건:

• 인스턴스에 대한 관리자 액세스가 있어야 합니다.

색인을 다시 시작하려면:

1. 왼쪽 사이드바에서 하단에 있는 관리자를 선택합니다.
2. 설정 > 검색을 선택합니다.
3. 고급 검색을 확장합니다.
4. Elasticsearch 색인 일시 중지 확인란을 해제합니다.

제로 다운타임 다시 색인하기

이 다시 색인 방법의 아이디어는 Elasticsearch 다시 색인 API와 Elasticsearch 인덱스 별칭 기능을 이용하여 작업을 수행하는 것입니다. GitLab이 데이터를 읽기/쓰기하는 primary 인덱스에 연결되는 인덱스 별칭을 설정합니다. 다시 색인 프로세스가 시작되면 primary 인덱스의 쓰기를 일시적으로 일시 중지합니다. 그런 다음 다른 인덱스를 생성하고 다시 색인 API를 호출하여 새 인덱스로 인덱스 데이터를 이동시킵니다. 다시 색인 작업이 완료되면 인덱스 별칭을 이에 연결된 새로운 primary 인덱스로 변경합니다. 끝에 쓰기를 재개하고 일반적인 작업이 다시 재개됩니다.

제로 다운타임 재인덱싱 사용하기

새로운 인덱스를 생성하고 기존 데이터를 복사하지 않고는 변경할 수 없는 인덱스 설정 또는 매핑을 구성하려면 제로 다운타임 재인덱싱을 사용할 수 있습니다. 제로 다운타임 재인덱싱을 사용하여 누락된 데이터를 고치는 데는 사용하지 마십시오. 제로 다운타임 재인덱싱은 데이터가 이미 인덱싱되지 않았다면 검색 클러스터에 데이터를 추가하지 않습니다. 재인덱싱을 시작하기 전에 고급 검색 마이그레이션을 모두 완료해야 합니다.

재인덱싱 트리거

사전 요구 사항:

• 인스턴스에 대한 관리자 액세스권이 있어야 합니다.

재인덱싱을 트리거하려면 다음을 수행합니다:

1. 관리자로서 GitLab 인스턴스에 로그인합니다.
2. 왼쪽 사이드바에서 맨 아래쪽에 있는 관리자를 선택합니다.
3. 설정 > 검색을 선택합니다.
4. Elasticsearch 제로 다운타임 재인덱싱을 확장합니다.
5. 클러스터 재인덱싱 트리거를 선택합니다.

인덱싱은 Elasticsearch 클러스터의 크기에 따라 긴 프로세스가 될 수 있습니다.

이 프로세스가 완료된 후, 원래의 인덱스는 14일 후에 삭제될 예정입니다. 재인덱싱 프로세스를 트리거한 동일한 페이지에서 취소 버튼을 눌러 이 작업을 취소할 수 있습니다.

재인덱싱이 진행 중일 때, 동일한 섹션에서 진행 상황을 확인할 수 있습니다.

제로 다운타임 재인덱싱 트리거

사전 요구 사항:

• 인스턴스에 대한 관리자 액세스권이 있어야 합니다.

제로 다운타임 재인덱싱을 트리거하려면 다음을 수행합니다:

1. 왼쪽 사이드바에서 맨 아래쪽에 있는 관리자를 선택합니다.
2. 설정 > 검색을 선택합니다.

3. Elasticsearch 제로 다운타임 재인덱싱을 확장합니다. 다음 설정이 사용할 수 있습니다:

   • Slice multiplier
   • Maximum running slices

Slice multiplier

Slice multiplier는 재인덱싱 중 슬라이스의 수를 계산합니다.

GitLab은 수동 슬라이싱을 사용하여 재인덱싱을 효율적이고 안전하게 제어하며, 실패한 슬라이스만 다시 시도할 수 있도록 합니다.

이 배수는 기본적으로 2이며, 인덱스 당 샤드 수에 적용됩니다. 예를 들어, 이 값이 2이고 인덱스에 20개의 샤드가 있다면 재인덱싱 작업은 40개의 슬라이스로 나뉩니다.

Maximum running slices

최대 실행 슬라이스 매개변수는 기본적으로 60이며, Elasticsearch 재인덱싱 중 동시에 실행될 수 있는 최대 슬라이스 수에 해당합니다.

이 값을 너무 높게 설정하면 클러스터가 검색 및 쓰기로 심각한 성능 영향을 받을 수 있습니다. 이 값을 너무 낮게 설정하면 재인덱싱 프로세스가 완료되기까지 매우 긴 시간이 걸릴 수 있습니다.

이에 대한 최적의 값은 클러스터 크기에 따라 다르며, 재인덱싱 중 검색 성능이 저하되는 것을 수용할 여부 및 재인덱싱이 빠르게 완료되고 인덱싱을 재개하는 것이 얼마나 중요한지에 따라 다릅니다.

가장 최근의 재인덱싱 작업을 실패로 표시하고 인덱싱을 재개하기

사전 요구 사항:

• 인스턴스에 대한 관리자 액세스권이 있어야 합니다.

미완료된 재인덱싱 작업을 포기하고 인덱싱을 재개하려면 다음을 수행합니다:

1. 최근에 실행된 재인덱싱 작업을 실패로 표시합니다:

   # 리눅스 패키지를 사용하는 설치의 경우
   sudo gitlab-rake gitlab:elastic:mark_reindex_failed
   
   # 자체 컴파일된 설치의 경우
   bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production
   

2. 왼쪽 사이드바에서 맨 아래쪽에 있는 관리자를 선택합니다.
3. 설정 > 검색을 선택합니다.
4. 고급 검색을 확장합니다.
5. Elasticsearch 인덱싱 일시 중지 확인란을 해제합니다.

인덱스 무결성

• GitLab 15.10에서 도입되었으며 search_index_integrity라는 플래그로 비활성화되어 있습니다.
• GitLab 16.4에 일반적으로 사용 가능하며 search_index_integrity 플래그가 제거되었습니다.

인덱스 무결성은 누락된 리포지토리 데이터를 감지하고 수정합니다. 이 기능은 코드 검색이 그룹 또는 프로젝트에 대해 일치하는 결과를 반환하지 않을 때 자동으로 사용됩니다.

고급 검색 마이그레이션

백그라운드에서 재인덱싱 마이그레이션이 실행 중이므로 수동 개입이 필요하지 않습니다. 이는 일반적으로 고급 검색에 새로운 기능이 추가되거나 콘텐츠가 인덱싱되는 방식을 추가하거나 변경하는 경우 발생합니다.

마이그레이션 사전 파일

• GitLab 16.3에서 도입되었습니다.

모든 마이그레이션에는 ee/elastic/docs/ 폴더에 해당하는 사전 파일이 있으며, 다음 정보가 포함되어 있습니다:

name:
version:
description:
group:
milestone:
introduced_by_url:
obsolete:
marked_obsolete_by_url:
marked_obsolete_in_milestone:

예를 들어, 마이그레이션이 언제 도입되었는지 또는 언제 사용되지 않게 되었는지를 확인할 수 있습니다.

보류 중인 마이그레이션 확인

보류 중인 고급 검색 마이그레이션을 확인하려면 다음 명령을 실행합니다:

curl "$CLUSTER_URL/gitlab-production-migrations/_search?size=100&q=*" | jq .

이렇게 하면 다음과 유사한 내용이 반환됩니다:

{
  "took": 14,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "gitlab-production-migrations",
        "_type": "_doc",
        "_id": "20230209195404",
        "_score": 1,
        "_source": {
          "completed": true
        }
      }
    ]
  }
}

마이그레이션과 관련된 문제를 디버그하려면 elasticsearch.log 파일을 확인하십시오.

중단된 마이그레이션 재시도

일부 마이그레이션은 재시도 제한이 있습니다. 마이그레이션이 재시도 제한 시간 내에 완료되지 못하면 중단되고 고급 검색 통합 설정에서 알림이 표시됩니다.

마이그레이션이 중단된 이유를 디버그하고 마이그레이션을 재시도하기 전에 문제를 해결하는 것이 좋습니다.

문제의 원인을 해결했다고 믿을 때:

1. 왼쪽 사이드바에서 맨 아래쪽에 있는 관리자를 선택합니다.
2. 설정 > 검색을 선택합니다.
3. 고급 검색을 확장합니다.
4. Elasticsearch 마이그레이션 중단 경고 상자 안에서 마이그레이션 재시도를 선택합니다. 마이그레이션이 백그라운드에서 재시도할 예정입니다.

마이그레이션에 성공하지 못하면 새로운 인덱스를 처음부터 다시 만드는 것을 고려할 수 있습니다. 이로 인해 문제를 건너뛸 수 있습니다. 왜냐하면 새로 생성된 인덱스는 모든 마이그레이션을 건너뛰며, 올바르고 최신의 스키마로 인덱싱이 다시 생성되기 때문입니다. 해당 문제를 해결할 수 없는 경우 마지막 수단으로 index를 처음부터 다시 만드는 것을 고려할 수 있습니다.

모든 이주(migrations)는 주요 업그레이드를 수행하기 전에 완료되어야 합니다

주요 GitLab 버전으로 업그레이드하려면 해당 주요 버전 이전의 최신 부 버전까지 존재하는 모든 이주를 완료해야 합니다. 또한, 주요 버전 업그레이드를 진행하기 전에 멈춘 이주를 다시 시도하고 해결해야 합니다. 자세한 내용은 업그레이드를 위한 이주를 참조하십시오.

제거된 이주는 폐기 처리되었습니다. 새 버전에서 제거된 이주가 완료되지 않은 상태에서 GitLab을 업그레이드하면, 해당 버전에서 제거된 보류 중인 이주는 실행하거나 다시 시도할 수 없습니다. 이 경우, 색인을 다시 처음부터 만들어야 합니다.

건너뛸 수 있는 이주

건너뛸 수 있는 이주는 특정 조건이 충족될 때에만 실행됩니다. 예를 들어, 특정 버전의 Elasticsearch에 의존하는 이주는 해당 버전에 도달할 때까지 건너뛸 수 있습니다.

건너뛸 수 있는 이주가 완료되지 않은 상태에서 이주가 폐기 처리되면 변경사항을 적용하려면 색인을 다시 만들어야 합니다.

GitLab 고급 검색 Rake 작업

다음과 같은 Rake 작업이 제공됩니다:

• 색인 생성 및 설치
• 고급 검색 비활성화 시 인덱스 삭제
• GitLab 데이터를 인덱싱합니다.

다음은 일부 사용 가능한 Rake 작업입니다:

환경 변수

Rake 작업 외에도 프로세스를 수정하는 데 사용할 수 있는 몇 가지 환경 변수가 있습니다.

프로젝트 범위 또는 특정 프로젝트 색인화

ID_FROM 및 ID_TO 환경 변수를 사용하여 제한된 수의 프로젝트를 색인화할 수 있습니다. 이는 스테이징 색인화에 유용할 수 있습니다.

root@git:~# sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1 ID_TO=100

ID_FROM 및 ID_TO가 또는 같음 비교를 사용하므로 두 값이 동일한 프로젝트 ID로 설정되면 하나의 프로젝트만 색인화할 수 있습니다.

root@git:~# sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=5 ID_TO=5
프로젝트 저장소 색인화 중...I, [2019-03-04T21:27:03.083410 #3384]  INFO -- : GitLab 사용자 / 테스트(ID=33) 색인화 중...
I, [2019-03-04T21:27:05.215266 #3384]  INFO -- : GitLab 사용자 / 테스트(ID=33) 색인화 완료!

고급 검색 색인 범위

검색 시 GitLab 색인은 다음 스코프를 사용합니다.

튜닝

최적의 클러스터 구성 선택 가이드

기본적인 클러스터 구성을 선택하는 가이드는 Elastic Cloud Calculator를 참조할 수 있습니다. 아래에서 더 많은 정보를 얻을 수 있습니다.

• 일반적으로, 적어도 복제본이 있는 2노드 클러스터 구성을 사용하는 것이 좋습니다. 저장 공간 사용량이 빠르게 증가하는 경우, 가로 스케일링(노드 추가)을 미리 계획하는 것이 좋습니다.
• 검색 클러스터에 HDD 저장소를 사용하는 것은 성능에 부정적인 영향을 미치기 때문에 권장되지 않습니다. 대신 SSD 저장소 (예: NVMe 또는 SATA SSD 드라이브)를 사용하는 것이 좋습니다.
• 대규모 인스턴스에 대해 좌표 전용 노드를 사용하는 것은 권장되지 않습니다. 좌표 전용 노드는 데이터 노드보다 작기 때문에 성능과 고급 검색 마이그레이션에 영향을 줄 수 있습니다.
• GitLab 성능 도구를 사용하여 다양한 검색 클러스터 크기 및 구성으로 검색 성능을 벤치마킹할 수 있습니다.
• Heap 크기는 물리적 RAM의 50% 이상으로 설정해서는 안 됩니다. 또한, 영구 압축 옵셋을 위한 임계값보다 많이 설정해서는 안 됩니다. 정확한 임계값은 시스템에 따라 다르지만 대부분의 시스템에서 26GB는 안전하며 일부 시스템에서는 30GB까지 큰 경우도 있습니다. 자세한 내용은 Heap 크기 설정 및 JVM 옵션 설정을 참조하세요.
• refresh_interval은 색인당 설정값입니다. 실시간 데이터가 필요하지 않은 경우 기본값 1초에서 더 큰 값으로 조정할 수 있습니다. 이는 신선한 결과를 얼마나 빨리 볼 수 있는지를 변경합니다. 이것이 중요하다면 기본값에 가능한 가깝게 유지해야 합니다.
• 많은 양의 색인 작업이 있는 경우 indices.memory.index_buffer_size를 30% 또는 40%로 늘리고 싶을 수 있습니다.

고급 검색 설정

Elasticsearch 샤드 수

단일 노드 클러스터의 경우, 색인당 Elasticsearch 샤드 수를 CPU 코어 수로 설정합니다. 평균 샤드 크기를 몇 기가바이트에서 30기가바이트로 유지합니다.

다중 노드 클러스터의 경우, 색인당 Elasticsearch 샤드 수를 적어도 5로 설정합니다.

색인의 샤드 크기를 업데이트하려면 설정을 변경하고 제로 다운타임 재색인을 트리거합니다.

데이터베이스 데이터가 있는 색인

• gitlab:elastic:estimate_shard_sizes는 GitLab 16.11에서 도입되었습니다.

데이터베이스 데이터를 포함하는 색인의 경우:

• gitlab-production-projects
• gitlab-production-issues
• gitlab-production-epics
• gitlab-production-merge_requests
• gitlab-production-notes
• gitlab-production-users

Rake 작업 gitlab:elastic:estimate_shard_sizes를 실행하여 샤드 수를 결정합니다. 이 작업은 근사 문서 개수와 샤드 및 복제 크기에 대한 권장 사항을 반환합니다.

저장소 데이터가 있는 색인

저장소 데이터를 포함하는 색인의 경우:

• gitlab-production
• gitlab-production-wikis
• gitlab-production-commits

평균 샤드 크기를 몇 기가바이트에서 30기가바이트로 유지합니다. 만약 평균 샤드 크기가 30GB를 초과하는 경우, 색인의 샤드 크기를 늘리고 제로 다운타임 재색인을 트리거합니다. 클러스터가 건강 상태를 유지하기 위해, 노드당 샤드 수는 구성된 Heap 크기의 20배를 넘어서는 안 됩니다. 예를 들어, 30GB의 힙을 가진 노드는 최대 600개의 샤드를 가져야 합니다.

Elasticsearch 복제품 수

단일 노드 클러스터의 경우, 인덱스 당 Elasticsearch 복제품 수를 0으로 설정합니다.

멀티 노드 클러스터의 경우, 각 샤드에 하나의 복제품이 있도록 Elasticsearch 인덱스 당 복제품 수를 1로 설정합니다. 한 노드를 잃는 경우 인덱스가 손상되지 않도록 0이 아니어야 합니다.

대용량 인스턴스 색인화 효율적으로 수행

전제 조건:

• 해당 인스턴스에 관리자 액세스해야 합니다.

경고: 대용량 인스턴스를 색인화하면 많은 Sidekiq 작업이 생성됩니다. 이 작업에 대비하려면 확장 가능한 설정을 준비하거나 추가 Sidekiq 프로세스를 만들어야 합니다.

고급 검색 기능을 활성화하는 경우에 데이터 양이 많아 색인화에 문제가 발생하는 경우:

1. Elasticsearch 호스트 및 포트 구성.

2. 빈 인덱스 생성:

   # Linux 패키지를 사용하는 경우
   sudo gitlab-rake gitlab:elastic:create_empty_index
   
   # 직접 컴파일된 설치인 경우
   bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production
   

3. GitLab 인스턴스를 재색인하는 경우, 인덱스 상태를 지웁니다:

   # Linux 패키지를 사용하는 경우
   sudo gitlab-rake gitlab:elastic:clear_index_status
   
   # 직접 컴파일된 설치인 경우
   bundle exec rake gitlab:elastic:clear_index_status RAILS_ENV=production
   

4. Elasticsearch 색인화 확인란 선택.

5. 대용량 Git 저장소의 색인화에는 시간이 걸립니다. 이 프로세스를 가속화하려면 색인화 속도를 조정할 수 있습니다:

   • refresh_interval을 임시로 늘릴 수 있습니다.

   • 복제품 수를 0으로 설정할 수 있습니다. 이 설정은 인덱스의 각 주 샤드의 사본 수를 제어합니다. 따라서 0의 복제품은 효율적으로 샤드의 복제를 비활성화하므로 색인화 성능이 향상됩니다. 이는 신뢰성 및 쿼리 성능 측면에서 중요한 교환이므로 초기 색인화가 완료된 후에는 고려된 값으로 복제품을 설정하는 것이 중요합니다.

   색인화 시간이 20% 감소할 것으로 예상됩니다. 색인화가 완료된 후에는 refresh_interval 및 number_of_replicas를 원하는 값으로 되돌릴 수 있습니다.

   참고: 이 단계는 선택 사항이지만 대형 색인화 작업의 속도를 크게 향상시킬 수 있습니다.

   curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \
        --data '{
          "index" : {
              "refresh_interval" : "30s",
              "number_of_replicas" : 0
          } }'
   

6. 프로젝트 및 해당 데이터를 색인화합니다:

   # Linux 패키지를 사용하는 경우
   sudo gitlab-rake gitlab:elastic:index_projects
   
   # 직접 컴파일된 설치인 경우
   bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production
   

   이로써 각 색인화가 필요한 프로젝트에 대해 Sidekiq 작업을 대기열에 넣습니다. 관리자 영역에서 Monitoring > Background jobs > Queues Tab에 들어가서 elastic_commit_indexer를 선택하거나 Rake 작업을 사용하여 색인화 상태를 확인할 수 있습니다:

   # Linux 패키지를 사용하는 경우
   sudo gitlab-rake gitlab:elastic:index_projects_status
   
   # 직접 컴파일된 설치인 경우
   bundle exec rake gitlab:elastic:index_projects_status RAILS_ENV=production
   
   색인화가 65.55% 완료되었습니다 (6555/10000 프로젝트)
   

   프로젝트 색인화를 일정 범위로 제한하려면 ID_FROM 및 ID_TO 매개변수를 지정할 수 있습니다:

   # Linux 패키지를 사용하는 경우
   sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000
   
   # 직접 컴파일된 설치인 경우
   bundle exec rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 RAILS_ENV=production
   

   ID_FROM 및 ID_TO는 프로젝트 ID입니다. 두 매개변수 모두 선택 사항입니다. 위의 예제는 1001부터 (포함) 2000까지의 모든 프로젝트를 색인화합니다.

   참고: gitlab:elastic:index_projects에 의해 대기열에 넣은 프로젝트 색인화 작업이 때때로 중단될 수 있습니다. 이는 여러 이유로 발생할 수 있지만 색인화 작업을 다시 실행해도 안전합니다.

   또한 gitlab:elastic:clear_index_status Rake 작업을 사용하여 진행 상태를 “잊도록”하여 다시 색인화 프로세스를 재시도할 수 있습니다.

7. 에픽, 그룹 위키, 개인 스니펫 및 사용자는 프로젝트와 관련되어 있지 않으므로 별도로 색인화해야 합니다:

   # Linux 패키지를 사용하는 경우
   sudo gitlab-rake gitlab:elastic:index_epics
   sudo gitlab-rake gitlab:elastic:index_group_wikis
   sudo gitlab-rake gitlab:elastic:index_snippets
   sudo gitlab-rake gitlab:elastic:index_users
   
   # 직접 컴파일된 설치인 경우
   bundle exec rake gitlab:elastic:index_epics RAILS_ENV=production
   bundle exec rake gitlab:elastic:index_group_wikis RAILS_ENV=production
   bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production
   bundle exec rake gitlab:elastic:index_users RAILS_ENV=production
   

8. 색인화 후 복제 및 다시 즉시 적용 (이전에 refresh_interval을 늘린 경우에만):

   curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \
        --data '{
          "index" : {
              "number_of_replicas" : 1,
              "refresh_interval" : "1s"
          } }'
   

   위의 즉시 적용 후 강제 병합을 호출해야 합니다.

   Elasticsearch 6.x 이상의 경우 강제 병합을 진행하기 전에 인덱스가 읽기 전용 모드에 있는지 확인하세요:

   curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \
        --data '{
          "settings": {
            "index.blocks.write": true
          } }'
   

   그런 다음 강제 병합을 시작합니다:

   curl --request POST 'localhost:9200/gitlab-production/_forcemerge?max_num_segments=5'
   

   그런 다음 인덱스를 다시 쓰기 모드로 변경합니다:

   curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \
        --data '{
          "settings": {
            "index.blocks.write": false
          } }'
   

9. 색인화가 완료된 후, Elasticsearch 사용으로 검색 확인란 선택.

삭제된 문서

GitLab 객체에 변경 또는 삭제가 발생할 때(병합 요청 설명이 변경됨, 저장소의 기본 브랜치에서 파일이 삭제됨, 프로젝트가 삭제됨 등), 해당 색인된 문서가 삭제됩니다. 그러나 이것들은 “소프트” 삭제이기 때문에 “삭제된 문서”의 총 수와 따라서 낭비되는 공간이 늘어납니다. Elasticsearch는 이러한 삭제된 문서를 제거하기 위해 세그먼트를 지능적으로 병합합니다. 그러나 GitLab 설치에서의 활동량 및 종류에 따라 색인에서 최대 50%의 공간이 낭비될 수 있습니다.

일반적으로 우리는 기본 설정으로 Elasticsearch가 병합하고 공간을 자동으로 회수하도록 권장합니다. 삭제된 문서 처리에 따르면 “최대 세그먼트 크기를 낮추는 것 외에는, Lucene 기본 설정을 변경하지 않고 삭제가 회수되는 시기에 대해 과도하게 걱정할 필요가 없습니다.”

그러나 일부 큰 설치에서는 병합 정책 설정을 조정할 수 있습니다:

• 기본 5GB에서 2GB 또는 3GB로 index.merge.policy.max_merged_segment 크기를 줄이는 것을 고려해보세요. 병합은 50% 이상의 삭제가 있는 경우에만 발생합니다. 더 작은 세그먼트 크기는 병합이 빈번하게 발생하도록 합니다.

  curl --request PUT localhost:9200/gitlab-production/_settings ---header 'Content-Type: application/json' \
       --data '{
         "index" : {
           "merge.policy.max_merged_segment": "2gb"
         }
       }'
  

• 또한 삭제가 얼마나 개입적으로 타겟팅되는지를 제어하는 index.merge.policy.reclaim_deletes_weight를 조정할 수 있습니다. 그러나 이로 인해 비용이 많이든 병합 결정이 발생할 수 있으므로 교환 관계를 이해하지 못한다면 이를 변경하지 않도록 권장합니다.

  curl --request PUT localhost:9200/gitlab-production/_settings ---header 'Content-Type: application/json' \
       --data '{
         "index" : {
           "merge.policy.reclaim_deletes_weight": "3.0"
         }
       }'
  

• 삭제된 문서를 제거하기 위해 강제 병합을 수행하지 마십시오. 문서에는 이로 인해 회수되지 않을 수 있는 매우 큰 세그먼트가 발생하고, 중요한 성능 또는 가용성 문제를 야기할 수 있음을 경고합니다.

전용 Sidekiq 노드 또는 프로세스로 대규모 인스턴스 색인

경고: 대다수 인스턴스는 이를 구성할 필요가 없을 것입니다. 아래 단계는 라우팅 규칙 이라는 Sidekiq의 고급 설정을 사용합니다. 작업을 완전히 잃지 않도록 하려면 라우팅 규칙을 사용하는 영향을 충분히 이해하십시오.

대규모 인스턴스를 색인하는 것은 Sidekiq 노드와 프로세스를 압도할 수 있으므로 시간이 오래 걸리고 리소스가 많이 소모될 수 있습니다. 이는 GitLab의 성능 및 가용성에 부정적인 영향을 미칩니다.

GitLab은 여러 Sidekiq 프로세스를 시작할 수 있기 때문에, 하나의 특정한 큐(또는 큐 그룹)를 색인하는 데 전용 워커를 생성할 수 있습니다. 이러한 방법으로 색인 큐가 항상 전용 워커를 갖도록 보장할 수 있으며, 다른 큐는 충돌을 피하기 위해 다른 전용 워커를 갖게 할 수 있습니다.

이를 위해 라우팅 규칙 옵션을 사용하여 Sidekiq가 워커 일치 질의에 따라 작업을 특정 큐로 라우팅하도록 합니다.

이를 다루기 위해, 일반적으로 다음 두 가지 옵션 중 하나를 권장합니다. 다음 중 하나를 선택할 수 있습니다: - 단일 노드에서 두 개의 큐 그룹 사용. - 두 노드 각각에서 한 개의 큐 그룹 사용.

아래 단계에 대해 sidekiq['routing_rules'] 항목을 고려해 보십시오: - 모든 색인 작업이 global_search 큐로 라우팅되도록 ["feature_category=global_search", "global_search"]. - 나머지 모든 색인 작업이 default 큐로 라우팅되도록 ["*", "default"].

sidekiq['queue_groups']에 있는 적어도 한 프로세스에는 mailers 큐를 포함해야 합니다. 그렇지 않으면 메일러 작업은 전혀 처리되지 않습니다.

참고: 라우팅 규칙(sidekiq['routing_rules'])은 모든 GitLab 노드(특히 GitLab Rails 및 Sidekiq 노드)에서 동일해야 합니다.

경고: 여러 프로세스를 시작할 때, 프로세스 수는 Sidekiq에 할당하려는 CPU 코어 수를 초과해서는 안됩니다. 각 Sidekiq 프로세스는 사용 가능한 작업량 및 동시성 설정에 따라 하나의 CPU 코어만 사용할 수 있습니다. 자세한 내용은 여러 Sidekiq 프로세스 실행를 참고하십시오.

단일 노드에서 두 개의 프로세스 사용

한 노드에 색인 및 비색인 Sidekiq 프로세스를 모두 만들려면 다음을 수행합니다:

1. Sidekiq 노드에서 /etc/gitlab/gitlab.rb 파일을 다음과 같이 변경하십시오:

   sidekiq['enable'] = true
   
   sidekiq['routing_rules'] = [
      ["feature_category=global_search", "global_search"],
      ["*", "default"],
   ]
   
   sidekiq['queue_groups'] = [
      "global_search", # global_search 큐를 청취하는 프로세스
      "default,mailers" # default 및 mailers 큐를 청취하는 프로세스
   ]
   
   sidekiq['min_concurrency'] = 20
   sidekiq['max_concurrency'] = 20
   

   GitLab 16.11 및 이전 버전을 사용 중이라면 명시적으로 큐 셀렉터를 비활성화하십시오:

   sidekiq['queue_selector'] = false
   

2. 변경 내용이 적용되도록 파일을 저장하고 GitLab을 다시 구성하십시오.
3. 다른 모든 Rails 및 Sidekiq 노드에서 sidekiq['routing_rules']이 위와 동일한지 확인하십시오.
4. 기존 작업을 이전하는 Rake 작업을 실행하십시오:

참고: GitLab을 다시 구성한 후 Rake 작업을 즉시 실행하는 것이 중요합니다. GitLab을 다시 구성한 후 기존 작업은 Rake 작업이 작업을 마이그레이션하기 시작할 때까지 처리되지 않습니다.

두 노드, 각각 하나의 프로세스

이러한 큐 그룹을 두 노드에서 처리하려면:

1. 색인 Sidekiq 프로세스를 설정하려면 색인 Sidekiq 노드에서 /etc/gitlab/gitlab.rb 파일을 다음과 같이 변경하십시오:

   sidekiq['enable'] = true
   
   sidekiq['routing_rules'] = [
      ["feature_category=global_search", "global_search"],
      ["*", "default"],
   ]
   
   sidekiq['queue_groups'] = [
     "global_search", # global_search 큐를 수신 대기하는 프로세스
   ]
   
   sidekiq['min_concurrency'] = 20
   sidekiq['max_concurrency'] = 20
   

   GitLab 16.11 이전 버전을 사용하는 경우 명시적으로 모든 큐 셀렉터를 비활성화하십시오:

   sidekiq['queue_selector'] = false
   

2. 파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성(reconfigure)하십시오.

3. 색인되지 않는 Sidekiq 프로세스를 설정하려면 색인되지 않는 Sidekiq 노드에서 /etc/gitlab/gitlab.rb 파일을 다음과 같이 변경하십시오:

   sidekiq['enable'] = true
   
   sidekiq['routing_rules'] = [
      ["feature_category=global_search", "global_search"],
      ["*", "default"],
   ]
   
   sidekiq['queue_groups'] = [
      "default,mailers" # default 및 mailers 큐를 수신 대기하는 프로세스
   ]
   
   sidekiq['min_concurrency'] = 20
   sidekiq['max_concurrency'] = 20
   

   GitLab 16.11 이전 버전을 사용하는 경우 명시적으로 모든 큐 셀렉터를 비활성화하십시오:

   sidekiq['queue_selector'] = false
   

4. 다른 모든 Rails 및 Sidekiq 노드에서 sidekiq['routing_rules']가 위와 동일한지 확인하십시오.
5. 파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성(reconfigure)하십시오.

6. 기존 작업을 마이그레이션하기 위해 Rake 작업을 실행하십시오:

   sudo gitlab-rake gitlab:sidekiq:migrate_jobs:retry gitlab:sidekiq:migrate_jobs:schedule gitlab:sidekiq:migrate_jobs:queued
   

참고: GitLab을 재구성한 직후에 Rake 작업을 즉시 실행하는 것이 중요합니다. GitLab을 재구성한 후에는 기존 작업이 Rake 작업이 작업을 마이그레이션하는 것을 시작할 때까지 처리되지 않습니다.

기본 검색으로 복귀

때때로 Elasticsearch 인덱스 데이터에 문제가 발생할 수 있습니다. 그러한 경우 GitLab에서는 검색 결과가 없을 때 “기본 검색”으로 복귀할 수 있도록 허용합니다. 이 “기본 검색”은 해당 범위에서 기본 검색이 지원되는 경우에만 작동합니다. 이 “기본 검색”은 인스턴스의 모든 정밀 검색을 비활성화한 것처럼 작동하며 (예: PostgreSQL 데이터 및 Git 데이터를 사용한 검색).

재해 복구

Elasticsearch는 GitLab의 보조 데이터 저장소입니다. Elasticsearch에 저장된 모든 데이터는 특히 PostgreSQL 및 Gitaly와 같은 다른 데이터 소스에서 다시 생성할 수 있습니다. Elasticsearch 데이터 저장소가 손상된 경우 모든 것을 처음부터 다시 색인할 수 있습니다.

Elasticsearch 인덱스가 너무 큰 경우 처음부터 모든 것을 다시 색인하는 데 너무 많은 다운타임을 야기할 수 있습니다. Elasticsearch 인덱스의 불일치를 자동으로 찾지 못할 수 있지만 누락된 업데이트를 확인하기 위해 로그를 검토할 수 있습니다. 데이터를 더 빨리 복구하기 위해 다음을 재실행할 수 있습니다:

1. elasticsearch.log에서 track_items를 검색하여 모든 동기화된 비-저장소 업데이트를 찾으십시오. 이러한 항목을 다시 ::Elastic::ProcessBookkeepingService.track!를 통해 보내야 합니다.

2. elasticsearch.log에서 indexing_commit_range를 검색하여 모든 저장소 업데이트를 찾으십시오. 로그에서 가장 오래된 from_sha를 사용하여 IndexStatus#last_commit/last_wiki_commit을 설정한 다음 프로젝트를 다시 색인하기 위해 ElasticCommitIndexerWorker 및 ElasticWikiIndexerWorker를 트리거해야 합니다.

3. sidekiq.log에서 ElasticDeleteProjectWorker를 검색하여 모든 프로젝트 삭제를 찾으십시오. 다른 ElasticDeleteProjectWorker를 트리거해야 합니다.

모든 것을 처음부터 다시 색인하지 않고도 데이터 손실로부터 빠르게 복구하기 위해 정기적으로 Elasticsearch 스냅숏을 촬영할 수도 있습니다.