• 버전 요구 사항
  • Elasticsearch 버전 요구 사항
  • OpenSearch 버전 요구 사항
• 시스템 요구 사항
• Elasticsearch 설치
• 새로운 Elasticsearch 주요 버전으로 업그레이드
• Elasticsearch 리포지터리 인덱서
  • 소스에서 인덱서 설치
    • 의존성 설치
      • Debian / Ubuntu
      • CentOS / RHEL
      • macOS
    • 빌드 및 설치
  • 색인 오류보기
• 고급 검색 활성화
  • 모든 프로젝트 인덱싱 설정으로 활성화
  • 고급 검색 구성
  • 액세스 요구사항
    • Elasticsearch와 역할 권한
    • 세밀한 접근 제어를 사용하는 AWS OpenSearch 서비스
      • 내부 데이터베이스의 마스터 사용자로 연결
      • IAM 사용자로 연결
      • 세밀한 액세스 제어의 권한
  • 네임스페이스 및 프로젝트 데이터를 색인화할 양 제한
    • 모든 프로젝트 레코드가 색인화됩니다
• 사용자 정의 언어 분석기 활성화
• 고급 검색 비활성화
• 색인 재개
• 제로 다운타임 재색인
  • 제로 다운타임 재색인 사용
  • 고급 검색 관리를 통한 재색인 트리거
    • Elasticsearch 제로 다운타임 재색인
      • 분할 배수
      • 최대 실행 분할
  • 가장 최근의 재색인 작업을 실패로 표시하고 색인 재개하기
• 색인 무결성
• 고급 검색 마이그레이션
  • 마이그레이션 사전 파일
  • 보류 중인 마이그레이션 확인
  • 중단된 마이그레이션 재시도
  • 주요 업그레이드 전에 모든 마이그레이션이 완료되어야 함
• GitLab 고급 검색 Rake 작업
  • 환경 변수
  • 프로젝트 범위 또는 특정 프로젝트 색인화
• 고급 검색 색인 범위
• 튜닝
  • 적절한 클러스터 구성 선택 안내
  • 고급 검색 통합 설정 안내
  • 대형 인스턴스를 효율적으로 색인하는 방법
  • 삭제된 문서
• 전용 Sidekiq 노드나 프로세스로 대규모 인스턴스 색인
  • 단일 노드의 두 프로세스
  • 두 개의 노드마다 하나의 프로세스
• 기본 검색으로 되돌리기
• 데이터 복구: Elasticsearch는 보조 데이터 리포지터리만 사용

Elasticsearch

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

버전 요구 사항

Elasticsearch 버전 요구 사항

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

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

고급 검색은 Elasticsearch 지원 종료 정책을 따릅니다. GitLab의 Elasticsearch 지원 버전을 변경할 때는 삭제되기 전에 월간 릴리스 게시물의 중요 공지에서 발표합니다.

OpenSearch 버전 요구 사항

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

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

시스템 요구 사항

Elasticsearch는 GitLab 시스템 요구 사항에 기술된 요구 사항 외에도 추가 리소스가 필요합니다.

데이터 양에 따라 메모리, CPU 및 리포지터리 리소스량이 달라집니다. 빈번하게 사용되는 Elasticsearch 클러스터는 더 많은 리소스가 필요할 수 있습니다. estimate_cluster_size Rake 작업은 고급 검색 리포지터리 요구 사항을 추정하기 위해 총 리포지터리 크기를 사용합니다.

Elasticsearch 설치

Elasticsearch는 Linux 패키지에 포함되어 있지 않으며, 직접 설치해야 하며 해당 버전을 선택해야 합니다. Elasticsearch를 설치하는 자세한 정보는 이 페이지의 범위를 벗어납니다.

Elasticsearch는 별도의 서버에 설치해야 합니다. GitLab과 동일한 서버에서 Elasticsearch를 실행하는 것은 권장되지 않으며 GitLab 인스턴스 성능을 저하시킬 수 있습니다.

단일 노드 Elasticsearch 클러스터의 기능적인 클러스터 상태는 기본 샤드 할당으로 인해 항상 옐로우입니다. Elasticsearch는 리플리카 샤드를 기본 샤드와 동일한 노드에 할당할 수 없습니다.

검색 인덱스는 다음 후에 업데이트됩니다:

• 데이터베이스 또는 리포지터리에 데이터 추가 시
• 관리 영역에서 Elasticsearch를 활성화시킬 때

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

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

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

Elasticsearch 업그레이드 중에 색인을 일시 중지하여 변경 사항을 계속 추적할 수 있어야 합니다. Elasticsearch 클러스터가 완전히 업그레이드되고 활성화된 후, 색인 계속을 해야 합니다.

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

Elasticsearch 리포지터리 인덱서

GitLab은 Git 리포지터리 데이터를 색인하기 위해 Go로 작성된 인덱서를 사용합니다.

GitLab 버전에 따라 Go 인덱서의 설치 절차가 다릅니다:

• Linux 패키지 설치의 경우 Go 인덱서가 포함됩니다.
• 직접 컴파일하여 설치한 경우 소스에서 인덱서 설치를 참조하세요.
• GitLab Development Kit을 사용하는 경우 GDK의 Elasticsearch를 참조하세요.
• GitLab Helm 차트를 사용하는 경우, 인덱서가 이미 포함되어 있습니다.

소스에서 인덱서 설치

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

의존성 설치

이 프로젝트는 텍스트 인코딩을 위해 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

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를 활성화해야 합니다.

색인 오류보기

GitLab Elasticsearch Indexer에서의 오류는 elasticsearch.log 파일과 sidekiq.log 파일에 json.exception.class가 Gitlab::Elastic::Indexer::Error인 것으로 보고됩니다. 이러한 오류는 Git 리포지터리 데이터를 색인할 때 발생할 수 있습니다.

고급 검색 활성화

요구 사항:

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

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

1. 왼쪽 사이드바에서 가장 아래에서 관리자 영역을 선택합니다.

2. 설정 > 고급 검색을 선택합니다.

   고급 검색 섹션을 보려면 활성 GitLab Premium 라이선스가 필요합니다.
3. 고급 검색 설정을 구성합니다. Elasticsearch 사용으로 검색 확인란을 선택하지 마세요.

4. Rake 작업을 사용하여 모든 데이터를 색인화합니다. 작업은 이미 존재하지 않은 경우 빈 색인을 생성하고 색인화가 이미 활성화되어 있지 않은 경우 Elasticsearch 색인을 활성화합니다:

   # 경고: 기존 인덱스가 모두 삭제됩니다
   # Omnibus 설치
   sudo gitlab-rake gitlab:elastic:index
      
   # 경고: 기존 인덱스가 모두 삭제됩니다
   # 소스 설치
   bundle exec rake gitlab:elastic:index RAILS_ENV=production
   

5. 선택 사항. 백그라운드 작업 상태를 모니터링합니다.
   1. 왼쪽 사이드바에서 모니터링 > 백그라운드 작업을 선택합니다.
   2. Sidekiq 대시보드에서 큐를 선택하고 elastic_commit_indexer와 elastic_wiki_indexer 큐가 0으로 줄어들 때까지 기다립니다. 이러한 큐에는 그룹 및 프로젝트에 대한 코드 및 위키 데이터를 색인화하는 작업이 포함되어 있습니다.
6. 색인화가 완료된 후, Elasticsearch 사용으로 검색 확인란을 선택하고 변경 사항 저장을 선택합니다.

50GB 이상의 리포지터리 데이터를 갖는 GitLab 인스턴스의 경우 대규모 인스턴스를 효율적으로 인덱싱하는 방법을 참조합니다.

모든 프로젝트 인덱싱 설정으로 활성화

모든 프로젝트 인덱싱 설정은 초기 색인화에만 사용할 수 있으며 인덱스를 처음부터 다시 생성하는 데는 사용할 수 없습니다. 모든 프로젝트 인덱싱을 사용하여 고급 검색을 활성화하려면:

1. 왼쪽 사이드바에서 가장 아래에서 관리자 영역을 선택합니다.
2. 설정 > 고급 검색을 선택합니다.
3. Elasticsearch 색인화 확인란을 선택한 후 변경 사항 저장을 선택합니다.
4. 모든 프로젝트 인덱싱을 선택합니다.
5. 선택 사항. 진행 상황을 확인하려면 진행 상황 확인을 선택합니다.

에픽스, 그룹 위키, 개인 코드片, 사용자를 색인화하려면 Rake 작업을 사용해야 합니다:

# Omnibus 설치
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

고급 검색 구성

다음 Elasticsearch 설정이 제공됩니다:

액세스 요구사항

Elasticsearch와 역할 권한

Elasticsearch에 액세스하여 작업을 수행하려면 GitLab에서 다음과 같은 권한을 가진 역할이 필요합니다:

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

자세한 내용은 Elasticsearch 보안 권한을 참조하십시오.

세밀한 접근 제어를 사용하는 AWS OpenSearch 서비스

GitLab에서 세밀한 액세스 제어를 사용하여 Self-managed AWS OpenSearch 서비스를 사용하려면 다음 권장 구성 중 하나를 사용해보세요.

인스턴스의 도메인 액세스 정책을 es:ESHttp* 작업을 허용하도록 구성할 수 있습니다. 다음 예제 구성을 사용자 또는 리소스 제한을 위해 사용자 정의할 수 있습니다:

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

자세한 내용은 Amazon OpenSearch Service에서 Identity and Access Management을 참조하십시오.

내부 데이터베이스의 마스터 사용자로 연결

내부 데이터베이스의 사용자를 사용하여 세밀한 액세스 제어를 사용하는 경우 OpenSearch에 연결하려면 HTTP 기본 인증을 사용해야 합니다. 마스터 사용자 이름과 암호를 OpenSearch URL의 일부로 제공하거나 고급 검색 설정의 사용자 이름과 암호 텍스트 상자에 제공할 수 있습니다. 자세한 내용은 Tutorial: 내부 사용자 데이터베이스 및 HTTP 기본 인증을 참조하십시오.

IAM 사용자로 연결

IAM 자격 증명을 사용하여 세밀한 액세스 제어를 사용하는 경우 고급 검색 설정의 AWS OpenSearch IAM 자격 증명 섹션에 자격 증명을 제공할 수 있습니다.

세밀한 액세스 제어의 권한

고급 검색에는 다음 권한이 필요합니다. 자세한 내용은 역할 생성을 참조하십시오.

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

패턴 *은 고급 검색에 필요한 몇 가지 권한이 필요합니다.

네임스페이스 및 프로젝트 데이터를 색인화할 양 제한

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

고급 검색은 모든 네임스페이스가 색인화된 경우에만 크로스 그룹 코드/커밋 검색(전역)을 제공합니다. 여기서 모든 네임스페이스가 색인화된 경우에만 코드 또는 커밋 범위를 제공합니다. 이것은 색인화된 네임스페이스의 범위에서만 가능합니다. 색인화된 네임스페이스의 범위에서만 코드/커밋 검색이 가능합니다(일부 네임스페이스만 색인화된 경우). 예를 들어, 두 그룹이 색인화된 경우 단일 코드 검색을 실행할 방법이 없습니다. 첫 번째 그룹에서만 코드 검색을 실행한 후 두 번째 그룹에서만 실행할 수 있습니다.

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

모든 프로젝트 레코드가 색인화됩니다

• GitLab 16.7에 도입되었습니다 플래그인 search_index_all_projects는 기본으로 비활성화됩니다.
• GitLab 16.9에서 GitLab.com에서 활성화됩니다.
• GitLab 16.10에서 자체 호스팅된 환경에서 활성화됩니다.

플래그: 자체 호스팅된 GitLab에서는 기본적으로 이 기능을 사용할 수 있습니다. 관리자는 플래그를 비활성화하여 기능을 숨길 수 있습니다. GitLab.com에서는 이 기능을 사용할 수 있습니다. GitLab Dedicated에서는 이 기능을 사용할 수 없습니다.

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

• 모든 프로젝트 레코드가 색인화됩니다.
• 연결된 데이터(이슈, Merge 리퀘스트 또는 코드)가 색인화되지 않습니다.

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

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

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

언어 지원을 활성화하려면:

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

설치할 내용에 대한 지침은 다음과 같습니다:

고급 검색 비활성화

Elasticsearch 통합을 비활성화하려면:

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 인덱스에 대한 쓰기를 일시적으로 중지합니다. 그런 다음, 또 다른 인덱스를 생성하고 Reindex API를 호출하여 인덱스 데이터를 새 인덱스로 이관합니다. 재색인 작업이 완료되면 인덱스 별칭을 새 인덱스에 연결하여 새 primary 인덱스가 되게 합니다. 마지막으로 쓰기를 재개하고 일반적인 작업을 다시 시작합니다.

제로 다운타임 재색인 사용

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

고급 검색 관리를 통한 재색인 트리거

재색인 프로세스를 트리거하려면:

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

색인 재설정은 Elasticsearch 클러스터의 크기에 따라 시간이 오래 걸릴 수 있습니다.

이 프로세스가 완료되면 원래의 인덱스는 14일 후에 삭제 예정입니다. 이 작업을 취소하려면 동일한 페이지에서 취소 버튼을 누르면 됩니다.

재색인이 진행 중일 때, 해당 섹션에서 진행 상황을 확인할 수 있습니다.

Elasticsearch 제로 다운타임 재색인

1. 왼쪽 사이드바에서 맨 아래에서 관리 영역을 선택합니다.
2. 설정 > 고급 검색을 선택합니다.
3. Elasticsearch 제로 다운타임 재색인을 확장하면 다음 옵션을 찾을 수 있습니다:

• 분할 배수
• 최대 실행 분할

분할 배수

분할 배수는 재색인 중의 분할 수를 계산합니다.

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. 왼쪽 사이드바에서 맨 아래에서 관리 영역을 선택합니다.
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?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 파일을 확인하고 마이그레이션을 다시 시도하기 전에 변경 사항을 적용해야 합니다. 실패한 원인을 해결했다고 생각되면 “마이그레이션 재시도”를 선택하고, 마이그레이션이 백그라운드에서 다시 시도되도록 예약됩니다.

마이그레이션을 성공시키지 못하는 경우 처음부터 인덱스를 다시 만드는 마지막 수단을 고려해보세요. 이렇게 하면 올바른 최신 스키마로 인덱스가 다시 생성되기 때문에 문제점을 건너뛸 수 있습니다.

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

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

삭제된 마이그레이션은 사용되지 않는 것으로 표시됩니다. 새 버전에서 제거된 보류 중인 고급 검색 마이그레이션을 완료하지 않은 채 GitLab을 업그레이드하는 경우, 해당 버전에서 제거된 보류 중인 마이그레이션은 실행되거나 다시 시도될 수 없습니다. 이 경우 처음부터 인덱스를 다시 생성해야 합니다.

GitLab 고급 검색 Rake 작업

다음과 같은 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
프로젝트 리포지터리 색인화 중...I, [2019-03-04T21:27:03.083410 #3384]  INFO -- : GitLab 사용자 / test (ID=33) 색인화 중...
I, [2019-03-04T21:27:05.215266 #3384]  INFO -- : GitLab 사용자 / test (ID=33) 색인화 완료!

고급 검색 색인 범위

검색을 수행할 때 GitLab 색인은 다음과 같은 범위를 사용합니다:

튜닝

적절한 클러스터 구성 선택 안내

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

• 일반적으로 적어도 2-노드 클러스터 구성 및 레플리카 1개를 사용하는 것이 좋으며, 이를 통해 복구 기능을 확보할 수 있습니다. 저장 공간 사용량이 빠르게 증가하는 경우, 가로 스케일링(추가 노드 추가)을 미리 계획하는 것이 좋습니다.
• 검색 클러스터에서 HDD 리포지터리 사용을 권장하지 않습니다. 성능에 영향을 미칩니다. 대신 SSD 리포지터리(NVMe 또는 SATA SSD 드라이브 등)를 사용하는 것이 좋습니다.
• 대형 인스턴스에는 coordinating-only 노드를 사용하는 것이 좋지 않습니다. Coordinating-only 노드는 data node보다 작아서 성능과 고급 검색 마이그레이션에 영향을 줄 수 있습니다.
• GitLab 성능 도구를 사용하여 다양한 검색 클러스터 크기 및 구성으로 검색 성능을 벤치마킹할 수 있습니다.
• Heap 크기는 물리적 RAM의 50%를 넘지 않도록 설정해야 합니다. 추가로 zero-based compressed oops에 넘지 않도록 설정해야 합니다. 정확한 임계값은 다양하지만 대부분의 시스템에서 26GB는 안전하며 일부 시스템에서 30GB까지 커질 수도 있습니다. 자세한 내용은 Heap 크기 설정 및 JVM 옵션 설정을 참조하십시오.
• 노드 당 CPU(코어) 수는 일반적으로 아래에 설명된 Elasticsearch 샤드 수와 일치해야 합니다.
• 좋은 가이드라인은 노드 당 샤드 수를 설정한 힙 크기당 20개 이하로 유지하는 것입니다. 따라서 30GB 힙이 구성된 노드는 최대 600개의 샤드를 가질 수 있지만, 이 한도보다 낮은 수치로 설정할수록 클러스터가 좋은 상태를 유지하는 데 도움이 됩니다.
• Elasticsearch 샤드 수:
  • 작은 샤드는 작은 세그먼트로 이어지는 오버헤드를 증가시킵니다. 평균 샤드 크기를 몇 기가바이트에서 수십 기가바이트로 유지하는 것이 좋습니다.
  • 다른 고려 사항은 문서 수입니다. 사용할 샤드 수를 결정하려면 대시보드 > 통계(인덱싱할 문서 수)에서 숫자를 합산하고 5 백만으로 나누고 5를 더하면 됩니다. 예:
    • 2,000,000개 미만의 문서가 있는 경우 기본값인 5개의 샤드를 사용합니다.
    • 10,000,000개의 문서: 10000000/5000000 + 5 = 7개의 샤드
    • 100,000,000개의 문서: 100000000/5000000 + 5 = 25개의 샤드
• refresh_interval은 색인당 설정되는 값입니다. 데이터가 실시간이 아닌 경우 기본 1초에서 더 큰 값으로 조정할 수 있습니다. 이것은 신선한 결과를 얼마나 빨리 볼 수 있는지를 변경합니다. 중요하다면 가능한 한 기본값에 가깝게 유지해야 합니다.
• 만약 많은 양의 인덱싱 작업이 있는 경우 indices.memory.index_buffer_size를 30% 또는 40%로 높이는 것이 좋을 수 있습니다.

고급 검색 통합 설정 안내

• Elasticsearch 샤드 수 설정은 일반적으로 클러스터에서 사용 가능한 CPU 수와 일치합니다. 예를 들어 4코어가 있는 3-노드 클러스터의 경우 클러스터에서 적어도 3*4=12개의 샤드를 가져오는 것이 좋습니다. 샤드 수를 변경하려면 Split index API를 사용하거나 샤드 수를 변경한 다른 인덱스로 다시 색인화해야 합니다.
• Elasticsearch 레플리카 수 설정은 대부분의 경우 1과 같아야 합니다 (각 샤드에 1개의 복제본이 있습니다). 0을 사용하는 것은 권장되지 않으며, 하나의 노드를 잃는 것은 인덱스를 손상시킬 수 있기 때문입니다.

대형 인스턴스를 효율적으로 색인하는 방법

이 섹션은 다른 기본 지침이 데이터 양에 따른 문제로 인해 문제를 일으킬 경우 도움이 될 수 있습니다.

1. Elasticsearch 호스트 및 포트를 구성합니다.

2. 빈 색인을 생성합니다:

   # Omnibus 설치
   sudo gitlab-rake gitlab:elastic:create_empty_index
      
   # 소스에서 설치
   bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production
   

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

   # Omnibus 설치
   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. 프로젝트 및 해당 데이터를 색인화합니다:

   # Omnibus 설치
   sudo gitlab-rake gitlab:elastic:index_projects
      
   # 소스에서 설치
   bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production
   

   이는 색인화가 필요한 각 프로젝트에 대해 Sidekiq 작업을 대기열에 넣습니다. ‘관리자 영역 > 모니터링 > 백그라운드 작업 > 대기열 탭’에서 작업을 볼 수 있으며, elastic_commit_indexer를 선택하거나 Rake 작업을 사용하여 색인 상태를 조회할 수 있습니다:

   # Omnibus 설치
   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 매개변수를 제공할 수 있습니다:

   # Omnibus 설치
   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. 에픽, 그룹 위키, 개인 스니펫 및 사용자는 프로젝트와 연결되어 있지 않으므로 별도로 색인화해야 합니다:

   # Omnibus 설치
   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"
          } }'
   

   위의 새로 고침을 활성화한 후 강제 Merge을 호출해야 합니다.

   Elasticsearch 6.x 이상의 경우 강제 Merge을 진행하기 전에 인덱스가 읽기 전용 모드에 있는지 확인하십시오:

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

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

   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 객체에 변경이나 삭제가 발생할 때마다(Merge Request 설명 변경, 리포지터리의 기본 브랜치에서 파일 삭제, 프로젝트 삭제 등) 해당 인덱스의 문서가 삭제됩니다. 그러나 이러한 삭제는 “소프트” 삭제이기 때문에 “삭제된 문서”의 전체 수와 따라서 낭비되는 공간이 늘어납니다. Elasticsearch는 지능적으로 세그먼트를 Merge하여 이러한 삭제된 문서를 제거합니다. 그러나 GitLab 설치에서의 활동량과 유형에 따라 인덱스에서 최대 50%의 낭비 공간이 발생할 수 있습니다.

일반적으로 우리는 기본 설정으로 Elasticsearch의 Merge과 공간 회수를 자동으로 수행하는 것을 권장합니다. 삭제된 문서 처리에서는 “전반적으로, 최대 세그먼트 크기를 줄이는 것을 제외하고는 Lucene의 기본 값을 그대로 두고 삭제가 언제 회수되는지에 대해 너무 걱정하지 말아야 합니다.” 라고 설명하고 있습니다.

그러나 일부 대규모 설치에서는 Merge 정책 설정을 조정하고자 할 수 있습니다:

• 기본 설정인 5GB에서 2GB 또는 3GB로 index.merge.policy.max_merged_segment 크기를 줄이는 것을 고려해보세요. Merge은 세그먼트가 최소 50%의 삭제를 가졌을 때에만 발생합니다. 작은 세그먼트 크기는 더 자주 Merge이 일어나도록 합니다.

  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를 조정할 수 있습니다. 그러나 이렇게 하면 비용이 많이 드는 Merge 결정으로 이어질 수 있으므로 깊이 이해하지 않는 이상 이를 변경하지 말 것을 권장합니다.

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

• 삭제된 문서를 제거하기 위해 강제 Merge을 수행하지 마세요. 문서에는 이로 인해 회수되지 않을 수 있는 매우 큰 세그먼트가 생성되고, 중요한 성능이나 가용성 문제를 일으킬 수 있다는 경고가 있습니다.

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

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

GitLab은 여러 Sidekiq 프로세스를 시작할 수 있기 때문에 색인 큐에 항상 전용 워커가 있고, 다른 큐는 충돌을 피하기 위해 다른 전용 워커가 있는지를 확인할 수 있습니다.

이를 위해 라우팅 규칙 옵션을 사용하여 Sidekiq가 작업 일치 쿼리에 따라 특정 큐로 작업을 라우팅할 수 있습니다.

이에 대응하기 위해 일반적으로 다음 두 가지 옵션 중 하나를 권장합니다:

• 단일 노드에서 두 개의 프로세스 사용.
• 각각의 노드에 두 개의 큐 그룹 사용.

아래 단계에는 sidekiq['routing_rules'] 항목을 고려하세요:

• 모든 색인 작업은 global_search 큐로 라우팅되기 때문에 ["feature_category=global_search", "global_search"].
• 다른 비색인 작업은 default 큐로 라우팅되기 때문에 ["*", "default"].

최소한 sidekiq['queue_groups'] 중 하나의 프로세스에는 mailers 큐가 포함되어야 합니다. 그렇지 않으면 메일러 작업을 처리하지 않습니다.

단일 노드의 두 프로세스

하나의 노드에서 색인 및 비색인 Sidekiq 프로세스를 모두 만들려면 다음과 같이 수행하세요:

1. Sidekiq 노드에서 /etc/gitlab/gitlab.rb 파일을 변경하여:

   sidekiq['enable'] = true
   sidekiq['queue_selector'] = false
      
   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
   

2. 파일을 저장하고 GitLab 다시 구성하여 변경 사항이 적용되도록 합니다.
3. 나머지 모든 Rails 및 Sidekiq 노드에서 sidekiq['routing_rules']가 위와 같은지 확인합니다.
4. 기존 작업을 이동하려면 레일스 작업을 실행하세요.

두 개의 노드마다 하나의 프로세스

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

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

   sidekiq['enable'] = true
   sidekiq['queue_selector'] = false
      
   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
   

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

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

   sidekiq['enable'] = true
   sidekiq['queue_selector'] = false
      
   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
   

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의 사용은 항상 보조 데이터 리포지터리로만 사용됩니다. 즉, Elasticsearch에 저장된 모든 데이터는 언제든지 다른 데이터 소스(구체적으로 PostgreSQL 및 Gitaly)에서 다시 생성할 수 있습니다. 따라서 Elasticsearch 데이터 리포지터리가 어떤 이유로든 손상된 경우 모든 것을 처음부터 다시 색인화할 수 있습니다.