• Elasticsearch 또는 AWS OpenSearch 클러스터 설치
  • 버전 요구 사항
    • Elasticsearch
    • OpenSearch
  • 시스템 요구 사항
  • 접근 요구 사항
    • Elasticsearch에 대한 역할 기반 액세스 제어
    • AWS OpenSearch에 대한 액세스 제어
      • 리소스 기반 정책 예제
      • ID 기반 정책 예시
      • 세밀한 접근 제어 예시
    • AWS OpenSearch 서비스에 연결하기
      • HTTP 기본 인증
      • 역할 기반 인증
  • 새로운 Elasticsearch 주요 버전으로 업그레이드
• Elasticsearch 저장소 인덱서
  • 인덱서 설치
    • 의존성 설치
      • Debian / Ubuntu
      • CentOS / RHEL
      • macOS
    • 빌드 및 설치
  • 인덱싱 오류 보기
• 고급 검색 활성화
  • 인스턴스 색인
    • 사용자 인터페이스에서
    • Rake 작업으로
  • 색인 상태 확인
  • 백그라운드 작업 상태 모니터링
  • 고급 검색 구성
  • 네임스페이스 및 프로젝트 데이터 인덱스 양 제한
    • 모든 프로젝트 레코드가 인덱싱됨
• 사용자 지정 언어 분석기 활성화
• 고급 검색 비활성화
• 인덱싱 재개
• 무중단 재인덱싱
  • 무중단 재인덱싱 사용
  • 재인덱싱 트리거
    • 무중단 재인덱싱 트리거
      • 슬라이스 곱셈기
      • 최대 실행 슬라이스
  • 가장 최근의 재색인 작업을 실패로 표시하고 인덱싱 재개
• 인덱스 무결성
• 고급 검색 마이그레이션
  • 마이그레이션 사전 파일
  • 보류 중인 마이그레이션 확인
  • 중단된 마이그레이션 다시 수행하기
  • 주요 업그레이드 전에 모든 마이그레이션이 완료되어야 함
  • 건너뛸 수 있는 마이그레이션
• GitLab 고급 검색 Rake 작업
  • 환경 변수
  • 프로젝트 범위 또는 특정 프로젝트 인덱싱
• 고급 검색 인덱스 범위
• 조정
  • 최적 클러스터 구성 선택에 대한 안내
  • 고급 검색 설정
    • Elasticsearch 샤드 수
      • 데이터베이스 데이터를 포함하는 인덱스
      • 리포지토리 데이터를 포함하는 인덱스
    • Elasticsearch 복제본 수
  • 대형 인스턴스를 효율적으로 인덱싱
  • 삭제된 문서
• 전용 Sidekiq 노드 또는 프로세스를 사용하여 대형 인스턴스 인덱싱
  • 단일 노드, 두 프로세스
  • 두 노드, 각 1개의 프로세스
• 기본 검색으로 되돌리기
• 재해 복구

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

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

고급 검색은 다음 Elasticsearch 버전과 함께 작동합니다.

고급 검색은 Elasticsearch 생애 주기 정책을 따릅니다.
GitLab에서 Elasticsearch 지원 버전을 변경할 경우
우리는 이를 중단 예정 노트에 발표합니다.
이를 제거하기 전에 월간 릴리스 게시물에서 공지합니다.

OpenSearch

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

호환되는 버전을 사용하고 OpenSearch에 연결한 후 Elasticsearch version not compatible 메시지가 표시되면, 색인 재개를 참조하세요.

시스템 요구 사항

Elasticsearch와 AWS OpenSearch는
GitLab 설치 요구 사항보다 더 많은 자원을 요구합니다.

메모리, CPU 및 저장소 요구 사항은 클러스터에 색인화하는 데이터 양에 따라 달라집니다.
활발히 사용되는 Elasticsearch 클러스터는 더 많은 자원을 요구할 수 있습니다.
estimate_cluster_size Rake 작업은 전체 저장소 크기를 사용하여
고급 검색 저장소 요구 사항을 추정합니다.

접근 요구 사항

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

Elasticsearch에 대한 역할 기반 액세스 제어

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

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

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

AWS OpenSearch에 대한 액세스 제어

사전 요구 사항:

• OpenSearch 도메인을 생성할 때 AWSServiceRoleForAmazonOpenSearchService라는 서비스 링크 역할을 AWS 계정에 만들어야 합니다.
• AWS OpenSearch의 도메인 액세스 정책은 es:ESHttp* 작업을 허용해야 합니다.

AWSServiceRoleForAmazonOpenSearchService는 모든 OpenSearch 도메인에서 사용됩니다.

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

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

• VPC 도메인 액세스 정책: AWS OpenSearch 도메인이 VPC 내부에 배포되고 액세스 가능한 경우
• 리소스 기반(도메인) 액세스 정책: AWS OpenSearch 도메인이 IAM 정책으로 구성된 경우
• ID 기반 정책: 클라이언트가 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/*"
    }
  ]
}

다음은 특정 IAM 주체에 대해서만 es:ESHttp* 작업이 허용되는 리소스 기반(도메인) 액세스 정책의 예입니다:

{
  "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/*"
    }
  ]
}

ID 기반 정책 예시

다음은 es:ESHttp* 작업이 허용되는 IAM 주체에 연결된 ID 기반 접근 정책의 예입니다:

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

세밀한 접근 제어 예시

세밀한 접근 제어를 통해 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. 왼쪽 사이드바에서 하단의 Admin을 선택합니다.
2. Settings > Search를 선택합니다.
3. Advanced Search를 확장합니다.
4. AWS OpenSearch IAM 자격 증명 섹션에서, Use AWS OpenSearch Service with IAM credentials 체크박스를 선택합니다.
5. Save changes를 선택합니다.

IAM 역할을 사용하기 위해 다음을 선택할 수 있습니다:

• 인스턴스 프로필: GitLab이 인스턴스 또는 포드(EKS IRSA)에 연결된 IAM 역할을 사용하도록 AWS 지역만 설정합니다.
• 특정 역할: GitLab이 키를 사용하여 직접 인증할 수 있도록 AWS 지역, AWS 접근 키 ID, 그리고 AWS 비밀 접근 키를 설정합니다.

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

• Elasticsearch 6.8에 대한 지원은 제거되었습니다 (GitLab 15.0).

Elasticsearch를 업그레이드할 때 GitLab 구성 변경이 필요하지 않습니다.

Elasticsearch 업그레이드 중에는:

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

Elasticsearch 클러스터가 완전히 업그레이드되고 활성화되면, 인덱싱 재개하고 고급 검색을 활성화합니다.

GitLab 15.0 이상으로 업그레이드할 때는 Elasticsearch 7.x 이상을 사용해야 합니다.

Elasticsearch 저장소 인덱서

Git 저장소 데이터를 인덱싱하기 위해, GitLab은 gitlab-elasticsearch-indexer를 사용합니다.

자체 컴파일 설치의 경우, 인덱서 설치를 참조하세요.

인덱서 설치

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

의존성 설치

이 프로젝트는 텍스트 인코딩을 위해 International Components for Unicode (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 환경 변수를 사용하여 변경할 수 있습니다.

그럴 경우 sudo에 -E 플래그를 전달하는 것을 기억하세요.

예시:

PREFIX=/usr sudo -E make install

설치 후, Elasticsearch 활성화를 반드시 수행하세요.

참고:

인덱싱 중에 Permission denied - /home/git/gitlab-elasticsearch-indexer/와 같은 오류가 발생하면, gitlab.yml 파일의 production -> elasticsearch -> indexer_path 설정을 /usr/local/bin/gitlab-elasticsearch-indexer로 설정해야 할 수도 있습니다. 이는 바이너리가 설치된 위치입니다.

인덱싱 오류 보기

GitLab Elasticsearch Indexer에서 발생한 오류는 elasticsearch.log 파일과 sidekiq.log 파일에 json.exception.class이 Gitlab::Elastic::Indexer::Error인 형태로 보고됩니다.

이 오류는 Git 저장소 데이터를 인덱싱할 때 발생할 수 있습니다.

고급 검색 활성화

전제 조건:

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

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

1. 왼쪽 사이드바 하단에서 Admin을 선택합니다.
2. Settings > Search를 선택합니다.
3. Elasticsearch 클러스터에 대한 고급 검색 설정을 구성합니다. Elasticsearch 사용 설정 체크박스를 선택하지 마세요.
4. 인스턴스 인덱싱을 수행합니다.
5. 선택 사항. 인덱싱 상태 확인을 수행합니다.
6. 인덱싱이 완료되면 Elasticsearch 사용 설정 체크박스를 선택한 후 변경 사항 저장을 선택합니다.

참고:

Elasticsearch가 활성화된 상태에서 Elasticsearch 클러스터가 다운되면, 문서를 업데이트하는 데 문제가 발생할 수 있습니다.

그 이유는 인스턴스가 변경 사항을 인덱싱하기 위한 작업을 큐에 넣지만 유효한 Elasticsearch 클러스터를 찾을 수 없기 때문입니다.

50GB 이상의 저장소 데이터를 가진 GitLab 인스턴스는 대규모 인스턴스를 효율적으로 인덱싱하는 방법을 참조하세요.

인스턴스 색인

사용자 인터페이스에서

• GitLab 17.3에서 도입됨.

필수 조건:

• 인스턴스에 대한 관리자 액세스 권한이 필요합니다.

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

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

1. 왼쪽 사이드바에서 맨 아래의 Admin을 선택합니다.

2. Settings > Search를 선택합니다.

3. Elasticsearch indexing 체크박스를 선택한 다음 Save changes를 선택합니다.

4. Index the instance를 선택합니다.

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. 왼쪽 사이드바에서 맨 아래의 Admin을 선택합니다.

2. Settings > Search를 선택합니다.

3. Indexing status를 확장합니다.

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

필수 조건:

• 인스턴스에 대한 관리자 액세스 권한이 필요합니다.

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

1. 왼쪽 사이드바에서 맨 아래의 Admin을 선택합니다.

2. Monitoring > Background jobs를 선택합니다.

3. Sidekiq 대시보드에서 Queues를 선택하고 elastic_commit_indexer 및 elastic_wiki_indexer 큐가 0이 될 때까지 기다립니다.

   이 큐에는 프로젝트 및 그룹의 코드와 위키 데이터를 색인화하는 작업이 포함되어 있습니다.

고급 검색 구성

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

경고:

Maximum bulk request size (MiB) 및 Bulk request concurrency 값을 증가시키면 Sidekiq 성능에 부정적인 영향을 미칠 수 있습니다. Sidekiq 로그에서 scheduling_latency_s 기간이 증가하는 경우 기본값으로 복원하십시오. 자세한 내용은 문제 322147을 참조하십시오.

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

네임스페이스 및 프로젝트 데이터 인덱스 양 제한 체크박스를 선택하면 인덱싱할 네임스페이스와 프로젝트를 지정할 수 있습니다. 네임스페이스가 그룹인 경우, 해당 그룹에 속한 하위 그룹과 프로젝트도 인덱싱됩니다.

고급 검색은 모든 네임스페이스가 인덱싱된 경우에만 교차 그룹 코드/커밋 검색(글로벌)을 제공합니다. 인덱싱된 네임스페이스의 하위 집합만 있는 경우, 글로벌 검색은 코드 또는 커밋 범위를 제공하지 않습니다. 이는 인덱싱된 네임스페이스의 범위 내에서만 가능합니다. 여러 개의 인덱싱된 네임스페이스에서 코드/커밋 검색을 수행할 방법은 없습니다(네임스페이스의 하위 집합만 인덱싱된 경우). 예를 들어 두 그룹이 인덱싱된 경우, 두 그룹에서 단일 코드 검색을 실행할 수 없습니다. 첫 번째 그룹에서 코드를 검색하고 그 다음에 두 번째 그룹에서 검색할 수 있습니다.

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

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

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

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

네임스페이스 및 프로젝트 데이터 인덱스 양 제한 체크박스를 선택하면:

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

네임스페이스나 프로젝트를 지정하지 않으면 오직 프로젝트 레코드만 인덱싱됩니다.

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

전제 조건:

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

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

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

1. 필요한 플러그인을 설치하고, 플러그인 설치 지침에 대한 Elasticsearch 문서를 참조하세요. 플러그인은 클러스터의 모든 노드에 설치해야 하며, 설치 후 각 노드를 재시작해야 합니다. 플러그인 목록은 이 섹션의 나중에 있는 표를 참조하세요.

2. 왼쪽 사이드바에서 하단의 관리자를 선택합니다.

3. 설정 > 검색을 선택합니다.

4. 사용자 지정 분석기: 언어 지원을 찾습니다.

5. 인덱싱을 위한 플러그인 지원을 활성화합니다.

6. 변경 사항이 반영되려면 변경 사항 저장을 선택합니다.

7. 제로다운타임 재인덱싱을 트리거하거나 모든 것을 처음부터 재인덱싱하여 업데이트된 매핑으로 새 인덱스를 생성합니다.

8. 이전 단계가 완료된 후 검색을 위한 플러그인 지원을 활성화합니다.

설치할 내용에 대한 안내는 다음 Elasticsearch 언어 플러그인 옵션을 참조하세요:

고급 검색 비활성화

사전 요구 사항:

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

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

1. 왼쪽 사이드바 하단에서 Admin을 선택합니다.

2. Settings > Search를 선택합니다.

3. Elasticsearch indexing 및 Search with Elasticsearch enabled 체크 박스를 선택 해제합니다.

4. Save changes를 선택합니다.

5. 선택 사항. 여전히 온라인 상태인 Elasticsearch 인스턴스의 기존 인덱스를 삭제합니다:

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

인덱싱 재개

사전 요구 사항:

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

인덱싱을 재개하려면:

1. 왼쪽 사이드바 하단에서 Admin을 선택합니다.

2. Settings > Search를 선택합니다.

3. Advanced Search를 확장합니다.

4. Pause Elasticsearch indexing 체크 박스를 선택 해제합니다.

무중단 재인덱싱

이 재인덱싱 방법의 아이디어는 Elasticsearch reindex API와 Elasticsearch 인덱스 별칭 기능을 활용하여 작업을 수행하는 것입니다. 우리는 GitLab이 읽기/쓰기에 사용하는 primary 인덱스에 연결되는 인덱스 별칭을 설정합니다. 재인덱싱 프로세스가 시작되면 우리는 primary 인덱스에 대한 쓰기를 일시 중지합니다. 그런 다음 다른 인덱스를 생성하고 Reindex API를 호출하여 인덱스 데이터를 새 인덱스로 마이그레이션합니다. 재인덱싱 작업이 완료되면 인덱스 별칭을 새 인덱스에 연결하여 새로운 primary 인덱스로 전환합니다. 마지막으로 쓰기를 재개하고 일반적인 작업이 다시 시작됩니다.

무중단 재인덱싱 사용

무중단 재인덱싱을 사용하여 새 인덱스를 생성하고 기존 데이터를 복사하지 않고는 변경할 수 없는 인덱스 설정이나 매핑을 구성할 수 있습니다. 무중단 재인덱싱을 사용하여 누락된 데이터를 수정해서는 안 됩니다. 무중단 재인덱싱은 이미 인덱싱되지 않은 데이터는 검색 클러스터에 추가하지 않습니다. 재인덱싱을 시작하기 전에 모든 고급 검색 마이그레이션을 완료해야 합니다.

재인덱싱 트리거

사전 요구 사항:

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

재인덱싱을 트리거하려면:

1. 관리자 권한으로 GitLab 인스턴스에 로그인합니다.

2. 왼쪽 사이드바 하단에서 Admin을 선택합니다.

3. Settings > Search를 선택합니다.

4. Elasticsearch zero-downtime reindexing을 확장합니다.

5. Trigger cluster reindexing을 선택합니다.

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

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

재인덱싱이 실행되는 동안 동일한 섹션에서 진행 상황을 따라갈 수 있습니다.

무중단 재인덱싱 트리거

사전 요구 사항:

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

무중단 재인덱싱을 트리거하려면:

1. 왼쪽 사이드바 하단에서 Admin을 선택합니다.

2. Settings > Search를 선택합니다.

3. Elasticsearch zero-downtime reindexing을 확장합니다.

   다음 설정을 사용할 수 있습니다:

   • Slice multiplier

   • Maximum running slices

슬라이스 곱셈기

슬라이스 곱셈기는 재색인 중 슬라이스 수를 계산합니다.

GitLab은 수동 슬라이스를 사용하여 재색인을 효율적이고 안전하게 제어합니다. 이를 통해 사용자는 실패한 슬라이스만 다시 시도할 수 있습니다.

곱셈기의 기본 값은 2이며 인덱스당 샤드 수에 적용됩니다.

예를 들어, 이 값이 2이고 인덱스에 20개의 샤드가 있는 경우, 재색인 작업은 40개의 슬라이스로 나뉩니다.

최대 실행 슬라이스

최대 실행 슬라이스 매개변수의 기본 값은 60이며, Elasticsearch 재색인 중 동시에 실행할 수 있는 최대 슬라이스 수에 해당합니다.

이 값을 너무 높게 설정하면 클러스터가 검색 및 쓰기로 인해 고속으로 포화 상태가 될 수 있으므로 성능에 악영향을 줄 수 있습니다.

이 값을 너무 낮게 설정하면 재색인 과정이 완료되는 데 매우 오랜 시간이 걸릴 수 있습니다.

이 값의 최적 수치는 클러스터 크기에 따라 다르며, 재색인 중 검색 성능 저하를 받아들일 수 있는지 여부 및 재색인이 빠르게 끝나고 인덱싱이 재개되는 것이 얼마나 중요한지에 따라 달라집니다.

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

전제 조건:

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

미완성 재색인 작업을 포기하고 인덱싱을 재개하려면:

1. 가장 최근의 재색인 작업을 실패로 표시하십시오:

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

2. 왼쪽 사이드바 하단에서 Admin을 선택합니다.

3. Settings > Search를 선택합니다.

4. Advanced Search를 확장합니다.

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 파일을 확인하세요.

중단된 마이그레이션 다시 수행하기

일부 마이그레이션은 재시도 한도를 가지고 있습니다. 만약 마이그레이션이 재시도 한도 내에 완료되지 않으면, 중단되며 고급 검색 통합 설정에서 알림이 표시됩니다.

왜 마이그레이션이 중단되었는지 디버그하기 위해 elasticsearch.log 파일을 확인하고, 마이그레이션을 다시 시도하기 전에 필요한 변경을 수행하는 것이 좋습니다.

실패 원인을 수정했다고 생각되면:

1. 왼쪽 사이드바에서 맨 아래의 Admin을 선택합니다.

2. Settings > Search를 선택합니다.

3. Advanced Search를 확장합니다.

4. Elasticsearch migration halted 경고 상자 안에서 Retry migration을 선택합니다. 마이그레이션은 백그라운드에서 다시 시도되도록 예약됩니다.

마이그레이션이 성공하지 않는 경우, 인덱스를 처음부터 다시 생성하는 최후의 수단을 고려할 수 있습니다.

이 방법을 사용하면 문제를 건너뛸 수 있습니다. 새로 생성된 인덱스는 올바른 최신 스키마로 인덱스가 다시 생성되기 때문에 모든 마이그레이션을 건너뛰게 됩니다.

주요 업그레이드 전에 모든 마이그레이션이 완료되어야 함

주요 GitLab 버전으로 업그레이드하기 전에 해당 주요 버전 이전의 최신 마이너 버전까지 존재하는 모든 마이그레이션을 완료해야 합니다. 또한, 주요 버전 업그레이드를 진행하기 전에 중단된 마이그레이션을 해결하고 다시 시도해야 합니다. 추가 정보는 업그레이드를 위한 마이그레이션을 참조하세요.

제거된 마이그레이션은 효용이 없다고 표시됩니다.

모든 보류 중인 고급 검색 마이그레이션이 완료되기 전에 GitLab을 업그레이드하면, 새 버전에서 제거된 모든 보류 중인 마이그레이션을 실행하거나 다시 시도할 수 없습니다. 이 경우, 인덱스를 처음부터 다시 생성해야 합니다.

건너뛸 수 있는 마이그레이션

건너뛸 수 있는 마이그레이션은 조건이 충족될 때만 실행됩니다.

예를 들어, 특정 버전의 Elasticsearch에 의존하는 마이그레이션은 해당 버전이 도달할 때까지 건너뛸 수 있습니다.

만약 건너뛸 수 있는 마이그레이션이 효용이 없다고 표시될 때까지 실행되지 않았다면, 변경 사항을 적용하기 위해서는 인덱스를 다시 생성해야 합니다.

GitLab 고급 검색 Rake 작업

Rake 작업은 다음을 위해 사용 가능합니다:

• 인덱서를 빌드하고 설치합니다.
• Elasticsearch 비활성화 시 인덱스를 삭제합니다.
• 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는 or equal to 비교를 사용하므로, 둘 다 같은 프로젝트 ID로 설정하여 단일 프로젝트만 인덱싱할 수 있습니다:

root@git:~# sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=5 ID_TO=5
Indexing project repositories...I, [2019-03-04T21:27:03.083410 #3384]  INFO -- : Indexing GitLab User / test (ID=33)...
I, [2019-03-04T21:27:05.215266 #3384]  INFO -- : Indexing GitLab User / test (ID=33) is done!

고급 검색 인덱스 범위

검색을 수행할 때 GitLab 인덱스는 다음 범위를 사용합니다:

조정

최적 클러스터 구성 선택에 대한 안내

클러스터 구성을 선택하는 데 대한 기본 안내는 Elastic Cloud Calculator를 참조할 수 있습니다. 아래에서 더 많은 정보를 찾을 수 있습니다.

• 일반적으로 복제본이 있는 2-node 클러스터 구성을 사용하는 것이 좋으며, 이는 내구성을 제공합니다. 저장소 사용량이 빠르게 증가하고 있다면 수평 스케일링(노드 추가)을 미리 계획하는 것이 좋습니다.

• 검색 클러스터에 HDD 저장소를 사용하는 것은 권장하지 않으며, 성능에 부정적인 영향을 미칩니다. SSD 저장소(NVMe 또는 SATA SSD 드라이브 등)를 사용하는 것이 좋습니다.

• 대형 인스턴스와 함께 코디네이팅 전용 노드를 사용하지 않아야 합니다. 코디네이팅 전용 노드는 데이터 노드보다 작으므로 성능 및 고급 검색 마이그레이션에 영향을 미칠 수 있습니다.

• 다양한 검색 클러스터 크기 및 구성을 기준으로 검색 성능을 벤치마킹하기 위해 GitLab 성능 도구를 사용할 수 있습니다.

• Heap size는 물리적 RAM의 50%를 초과해서는 안 됩니다. 또한, 제로 기반 압축 oops의 임계값을 초과해서도 안 됩니다. 정확한 임계값은 다르지만, 대부분의 시스템에서 26GB는 안전하며 일부 시스템에서는 30GB까지 클 수 있습니다. 자세한 내용은 Heap size settings 및 Setting JVM options를 참조하세요.

• refresh_interval은 인덱스당 설정입니다. 데이터가 실시간으로 필요하지 않다면 기본값 1s에서 더 큰 값으로 조정하는 것이 좋습니다. 이는 신선한 결과를 얼마나 빨리 볼 수 있는지를 변경합니다. 이 점이 중요하다면 기본값에 최대한 가깝게 유지하는 것이 좋습니다.

• 많은 무거운 인덱싱 작업이 있는 경우 indices.memory.index_buffer_size를 30% 또는 40%로 높이는 것이 좋습니다.

고급 검색 설정

Elasticsearch 샤드 수

단일 노드 클러스터에서는 인덱스당 Elasticsearch 샤드 수를 CPU 코어 수와 동일하게 설정하십시오. 평균 샤드 크기는 몇 GB에서 30 GB 사이로 유지하십시오.

다중 노드 클러스터에서는 인덱스당 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

평균 샤드 크기는 몇 GB에서 30 GB 사이로 유지하십시오. 평균 샤드 크기가 30 GB를 초과하는 경우 인덱스의 샤드 크기를 증가시키고 제로 다운타임 재색인을 트리거하십시오. 클러스터의 건강성을 보장하기 위해 노드당 샤드 수는 구성된 힙 크기의 20배를 초과해서는 안 됩니다. 예를 들어, 30 GB 힙을 가진 노드는 최대 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 작업을 예약합니다. 진행 상태를 보려면 관리자 영역의 모니터링 > 백그라운드 작업 > 대기열 탭에서 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입니다. 두 매개변수는 선택 사항입니다. 위의 예는 ID 1001에서 ID 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의 삭제된 문서 처리에서, “전반적으로 최대 세그먼트 크기를 줄이는 것 외에는 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']의 항목을 고려하세요:

• ["feature_category=global_search", "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 작업을 실행하여 기존 작업 마이그레이션을 수행합니다:

두 노드, 각 1개의 프로세스

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

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 재구성 하여 변경 사항이 적용되도록 합니다.

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 재구성 하여 변경 사항이 적용되도록 합니다.

6. Rake 작업을 실행하여 기존 작업 마이그레이션을 수행합니다:

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

기본 검색으로 되돌리기

때때로 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를 검색하여 모든 프로젝트 DELETE를 찾습니다. 또 다른 ElasticDeleteProjectWorker를 트리거해야 합니다.

또한 정기적으로 Elasticsearch 스냅샷을 생성하여 처음부터 다시 인덱싱하지 않고 데이터 손실에서 복구하는 데 걸리는 시간을 줄일 수 있습니다.