Elasticsearch

티어: 프리미엄, 얼티밋 오퍼링: GitLab.com, Self-managed, GitLab Dedicated

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

버전 요구 사항

Elasticsearch 버전 요구 사항

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

GitLab 버전 Elasticsearch 버전
GitLab 15.0 이상 Elasticsearch 7.x 이상
GitLab 14.0에서 14.10 Elasticsearch 6.8에서 7.x

고급 검색은 Elasticsearch 지원 종료 정책을 따릅니다. GitLab에서 Elasticsearch 지원 버전을 변경하면 월간 릴리스 게시물의 중요 사항에서 알립니다.

OpenSearch 버전 요구 사항

GitLab 버전 OpenSearch 버전
GitLab 15.5.3 이상 OpenSearch 1.x 이상
GitLab 15.0에서 15.5.2 OpenSearch 1.x

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

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

시스템 요구 사항

Elasticsearch는 GitLab 시스템 요구 사항에 기술된 자원 이외의 추가 자원이 필요합니다.

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

Elasticsearch 설치

Elasticsearch는 Linux 패키지나 자체 컴파일 설치에 포함되어 있지 않습니다. 별도로 설치해야하며 특정 버전을 선택해야 합니다. Elasticsearch 설치 방법에 대한 자세한 정보는 이 페이지의 범위를 벗어납니다.

Elasticsearch를 직접 설치하거나 AWS, GCP 또는 Azure에서 제공하는 Elasticsearch Service나 Amazon OpenSearch와 같은 클라우드 호스팅 오퍼링을 사용할 수 있습니다.

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

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

검색 색인은 다음 작업 후 업데이트됩니다: - 데이터베이스나 저장소에 데이터 추가 - 관리 영역에서 Elasticsearch 활성화

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

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

Elasticsearch 업그레이드 중에는 색인 일시 중지를 해야 변경 사항을 계속 추적할 수 있습니다. Elasticsearch 클러스터가 완전히 업그레이드되어 활성 상태인 경우 색인 재개를 해야 합니다.

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

Elasticsearch 저장소 인덱서

Git 저장소 데이터를 색인하려면 GitLab에서 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

참고: 먼저 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. 왼쪽 사이드바에서 관리 영역을 선택합니다.

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

    참고: 고급 검색 섹션을 보려면 활성 GitLab 프리미엄 라이선스가 필요합니다.

  3. Elasticsearch 클러스터에 대한 고급 검색 설정을 구성합니다. 아직 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 검색 사용 확인란을 선택한 후 변경 사항 저장을 선택합니다.

참고: Elasticsearch 클러스터가 작동 중이지 않을 때 Elasticsearch가 활성화된 상태에서 문제가 발생할 수 있습니다. 인스턴스에서는 변경 사항을 인덱싱하기 위해 작업을 대기시키지만 유효한 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 indexing Elasticsearch 색인을 활성화하거나 비활성화하고 이미 존재하지 않는 경우 빈 인덱스를 생성합니다. 색인을 활성화하지만 검색을 비활성화하여 색인이 완전히 완료될 때까지 기다릴 수 있습니다. 또한, 이 옵션이 기존 데이터에는 영향을 주지 않으며, 이 옵션은 데이터 변경을 추적하고 새 데이터가 색인되도록 하는 백그라운드 색인자를 활성화/비활성화하는 데만 사용됩니다.
Pause Elasticsearch indexing 일시적으로 인덱싱을 일시 중지하거나 다시 시작합니다. 클러스터 마이그레이션/재색인에 유용합니다. 모든 변경 사항은 여전히 추적되지만 재개할 때까지 Elasticsearch 인덱스에 커밋되지 않습니다.
Search with Elasticsearch enabled Elasticsearch를 검색에 사용하거나 사용하지 않도록 설정합니다.
Requeue indexing workers 색인 작업을 자동으로 다시 대기열에 넣도록 설정합니다. 이는 모든 문서가 처리될 때까지 Sidekiq 작업을 큐잉함으로써 비코드 색인 처리량을 향상시킵니다. 색인 작업 다시 대기열 설정은 작은 인스턴스나 Sidekiq 프로세스가 적은 인스턴스에는 권장되지 않습니다.
URL Elasticsearch 인스턴스의 URL입니다. 클러스터링을 지원하려면 쉼표로 구분된 목록을 사용하세요(예: http://host1, https://host2:9200). Elasticsearch 인스턴스에 암호가 설정된 경우 사용자 이름 및 비밀번호 필드를 사용하세요. 또는 http://<username>:<password>@<elastic_host>:9200/와 같이 인라인 자격 증명을 사용하세요. OpenSearch를 사용하는 경우 80 및 443 포트를 통한 연결만 허용됩니다.
Username Elasticsearch 인스턴스의 사용자 이름입니다.
Password Elasticsearch 인스턴스의 비밀번호입니다.
Number of Elasticsearch shards and replicas per index Elasticsearch 인덱스는 성능상의 이유로 여러 개의 샤드로 분할됩니다. 일반적으로 최소 다섯 개의 샤드를 사용해야 합니다. 수천만 개의 문서가 있는 인덱스는 샤드를 더 많이 가져야 합니다 (가이드 참조). 이 값에 대한 변경은 인덱스를 다시 생성하기 전까지 적용되지 않습니다. 확장성 및 내구성에 대한 자세한 내용은 Elasticsearch 문서를 참조하세요. 각 Elasticsearch 샤드에는 여러 개의 복제본이 있을 수 있습니다. 이러한 복제본은 샤드의 완전한 사본이며, 쿼리 성능을 증가시키거나 하드웨어 장애에 대한 내구성을 제공할 수 있습니다. 이 값을 증가시키면 인덱스에서 필요로 하는 총 디스크 공간도 증가합니다. 각각의 인덱스에 대해 샤드 및 복제본 수를 설정할 수 있습니다.
Limit the amount of namespace and project data to index 이 설정을 활성화하면 색인할 네임스페이스 및 프로젝트를 지정할 수 있습니다. 다른 모든 네임스페이스 및 프로젝트는 데이터베이스 검색을 사용합니다. 이 설정을 활성화하지만 네임스페이스 또는 프로젝트를 지정하지 않는 경우 프로젝트 레코드만 색인됩니다. 더 자세한 정보는 네임스페이스 및 프로젝트 데이터 양 제한을 참조하세요.
Using AWS OpenSearch Service with IAM credentials AWS IAM 권한 부여, AWS EC2 인스턴스 프로필 자격 증명, 또는 AWS ECS 작업 자격 증명을 사용하여 OpenSearch 요청에 서명하세요. AWS 호스팅 OpenSearch 도메인 액세스 정책 구성에 대한 자세한 내용은 아마존 OpenSearch Service에서 Identity and Access Management을 참조하세요.
AWS Region OpenSearch Service가 위치한 AWS 지역입니다.
AWS Access Key AWS 액세스 키입니다.
AWS Secret Access Key AWS 비밀 액세스 키입니다.
Maximum file size indexed 인스턴스 제한의 설명을 참조하세요.
Maximum field length 인스턴스 제한의 설명을 참조하세요.
Number of shards for non-code indexing 비코드 색인 작업의 샤드 수입니다. 이것은 병렬 Sidekiq 작업을 더 많이 큐잉함으로써 비코드 색인 처리량을 향상시킵니다. 샤드 수를 증가시키는 것은 작은 인스턴스나 Sidekiq 프로세스가 적은 인스턴스에는 권장되지 않습니다. 기본값은 2입니다.
Maximum bulk request size (MiB) GitLab Ruby 및 Go 기반 색인 프로세스에서 사용됩니다. 이 설정은 인덱싱 프로세스에서 페이로드를 Elasticsearch Bulk API에 제출하기 전에 수집해야 하는 데이터의 양(및 메모리에 저장해야 하는 데이터의 양)을 나타냅니다. GitLab Go 기반 색인기의 경우, 이 설정을 Bulk request concurrency와 함께 사용해야 합니다. Maximum bulk request size (MiB)은 Elasticsearch 호스트 및 gitlab-rake 명령 또는 Sidekiq 작업에서 실행 중인 GitLab Go 기반 색인기 호스트의 자원 제약 조건을 고려해야 합니다.
Bulk request concurrency GitLab Go 기반 색인기 프로세스(또는 스레드)가 Elasticsearch Bulk API에 후속으로 제출하기 위해 병렬로 실행될 수 있는 횟수를 나타냅니다. 이는 인덱싱 성능을 향상시키지만 Elasticsearch 대량 요청 대기열을 빠르게 채웁니다. 이 설정은 앞서 언급한 Maximum bulk request size 설정과 함께 사용되어야 하며, Elasticsearch 호스트 및 gitlab-rake 명령이나 Sidekiq 작업에서 실행 중인 GitLab Go 기반 색인기 호스트의 자원 제약 조건을 고려해야 합니다.
Client request timeout Elasticsearch HTTP 클라이언트 요청 제한 시간 값을 초 단위로 나타냅니다. 0은 시스템 기본 제한 시간 값을 사용함을 의미하며, 이 값은 GitLab 응용 프로그램이 구축된 라이브러리에 따라 다릅니다.
Code indexing concurrency 동시에 실행되는 최대 Elasticsearch 코드 색인 백그라운드 작업 수입니다. 이는 리포지토리 색인 작업에만 적용됩니다.

경고: Maximum bulk request size (MiB) 및 Bulk request concurrency 값을 증가시키면 Sidekiq 성능에 부정적인 영향을 줄 수 있습니다. Sidekiq 로그에서 scheduling_latency_s 기간이 길어진 것을 확인하면 기본값으로 되돌려야 합니다. 자세한 내용은 이슈 322147을 참조하세요.

접근 요구 사항

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에서 식별 및 액세스 관리를 참조하십시오.

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

내부 데이터베이스의 사용자와 세밀한 액세스 제어를 사용할 때 OpenSearch에 연결하려면 HTTP 기본 인증을 사용해야 합니다. OpenSearch URL의 일부 또는 고급 검색 설정의 사용자 이름과 암호 텍스트 상자에 마스터 사용자 이름과 암호를 제공할 수 있습니다. 자세한 내용은 튜토리얼: 내부 사용자 데이터베이스 및 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"
      ]
    }
  ]
}

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

네임스페이스 및 프로젝트 데이터의 색인 제한

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

고급 검색은 모든 네임스페이스가 색인되어 있을 때에만 교차 그룹 코드/커밋 검색(글로벌)을 제공합니다. 이 특정 시나리오에서는 일부 네임스페이스만 색인되어 있는 경우 글로벌 검색에서 코드 또는 커밋 범위를 제공하지 않습니다. 이는 색인화된 네임스페이스의 범위 내에서만 가능합니다. 색인된 네임스페이스의 코드/커밋 검색이 여러 색인된 네임스페이스에서 불가능합니다(네임스페이스의 일부만 색인되어 있는 경우). 예를 들어 두 그룹이 색인된 경우 첫 번째 그룹에서만 코드 검색을 실행한 후 두 번째 그룹에서 실행해야 합니다.

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

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

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

플래그: self-managed GitLab의 경우 기본적으로 이 기능을 사용할 수 있습니다. 기능을 숨기려면 관리자가 검색_index_all_projects라는 기능 플래그를 비활성화할 수 있습니다. GitLab.com에서는 이 기능을 사용할 수 있습니다. GitLab Dedicated에서는 이 기능을 사용할 수 없습니다.

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

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

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

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

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

언어 지원을 활성화하려면 다음 단계를 따르세요:

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

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

매개변수 설명
중국어 (smartcn) 사용자 정의 분석기: 색인 새롭게 생성된 색인에 smartcn 사용자 정의 분석기를 사용하여 중국어 언어 지원을 활성화하거나 비활성화합니다.
중국어 (smartcn) 사용자 정의 분석기: 검색 고급 검색에 사용될 smartcn 필드를 사용하거나 비사용하려면 플러그인 설치, 사용자 정의 분석기 색인 활성화 및 색인 재생성 이후에만 활성화하세요.
일본어 (kuromoji) 사용자 정의 분석기: 색인 새롭게 생성된 색인에 kuromoji 사용자 정의 분석기를 사용하여 일본어 언어 지원을 활성화하거나 비활성화합니다.
일본어 (kuromoji) 사용자 정의 분석기: 검색 고급 검색에 사용될 kuromoji 필드를 사용하거나 비사용하려면 플러그인 설치, 사용자 정의 분석기 색인 활성화 및 색인 재생성 이후에만 활성화하세요.

고급 검색 비활성화

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이 읽기/쓰기에 사용하는 기본 색인에 연결하는데 사용됩니다. 재색인 프로세스를 시작하면 기본 색인에 대한 쓰기를 일시 중지합니다. 그런 다음 다른 색인을 생성하고 Reindex API를 호출하여 인덱스 데이터를 새 인덱스로 마이그레이션합니다. 재색인 작업이 완료되면 해당하는 색인 별칭을 새 색인에 연결하여 새 기본 색인이 됩니다. 마지막으로 쓰기를 재개하고 전형적인 운영이 재개됩니다.

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

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

고급 검색 관리를 통해 다시 인덱싱 트리거

다음을 실행하여 다시 인덱싱 프로세스를 트리거합니다:

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

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

이 프로세스가 완료되면 원래의 인덱스가 14일 후에 삭제 예정입니다. 이 작업을 취소하려면 다시 인덱싱 프로세스를 트리거한 동일한 페이지에서 취소 버튼을 누를 수 있습니다.

다시 인덱싱이 실행되는 동안 해당 섹션에서 진행 상황을 확인할 수 있습니다.

Elasticsearch 제로 다운타임 다시 인덱싱

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

Slice multiplier은 다시 인덱싱 중 슬라이스 수를 계산합니다.

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

Multiplier는 기본적으로 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 색인 확인란을 지웁니다.

색인 무결성

색인 무결성은 누락된 저장소 데이터를 감지하고 수정합니다. 이 기능은 코드 검색이 그룹 또는 프로젝트에 대해 결과가 없을 때 자동으로 사용됩니다.

고급 검색 마이그레이션

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

마이그레이션 사전 파일

매 마이그레이션에는 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 작업입니다:

작업 설명
sudo gitlab-rake gitlab:elastic:info 고급 검색 통합에 대한 디버깅 정보를 출력합니다.
sudo gitlab-rake gitlab:elastic:index Elasticsearch 색인을 활성화하고 gitlab:elastic:recreate_index, gitlab:elastic:clear_index_status, gitlab:elastic:index_group_entities, gitlab:elastic:index_projects, gitlab:elastic:index_snippets, 및 gitlab:elastic:index_users를 실행합니다.
sudo gitlab-rake gitlab:elastic:pause_indexing Elasticsearch 색인을 일시 중지합니다. 변경 사항은 계속 추적됩니다. 클러스터/인덱스 마이그레이션에 유용합니다.
sudo gitlab-rake gitlab:elastic:resume_indexing Elasticsearch 색인을 재개합니다.
sudo gitlab-rake gitlab:elastic:index_projects 모든 프로젝트를 반복하고, 백그라운드에서 인덱싱하기 위해 Sidekiq 작업을 대기열에 넣습니다. 인덱스 생성 후에만 사용할 수 있습니다.
sudo gitlab-rake gitlab:elastic:index_group_entities gitlab:elastic:index_epics 및 gitlab:elastic:index_group_wikis를 호출합니다.
sudo gitlab-rake gitlab:elastic:index_epics Elasticsearch가 활성화된 그룹의 모든 epics를 색인합니다.
sudo gitlab-rake gitlab:elastic:index_group_wikis Elasticsearch가 활성화된 그룹의 모든 위키를 색인합니다.
sudo gitlab-rake gitlab:elastic:index_projects_status 모든 프로젝트 저장소 데이터 (코드, 커밋, 및 위키)의 전반적인 인덱싱 상태를 결정합니다. 상태는 인덱싱된 프로젝트 수를 총 프로젝트 수로 나누고 100을 곱하여 계산됩니다. 이 작업은 이슈, 병합 요청, 또는 마일스톤과 같은 저장소가 아닌 데이터를 포함하지 않습니다.
sudo gitlab-rake gitlab:elastic:clear_index_status 모든 프로젝트의 IndexStatus 인스턴스를 삭제합니다. 이 명령은 인덱스를 완전히 삭제하므로 주의해서 사용해야 합니다.
sudo gitlab-rake gitlab:elastic:create_empty_index 빈 인덱스(기본 인덱스 및 별도의 이슈 인덱스)를 생성하고, Elasticsearch 쪽에 이미 존재하지 않는 경우 각각에 별칭을 할당합니다.
sudo gitlab-rake gitlab:elastic:delete_index Elasticsearch 인스턴스에서 GitLab 인덱스와 별칭(있는 경우)을 제거합니다.
sudo gitlab-rake gitlab:elastic:recreate_index gitlab:elastic:delete_index 및 gitlab:elastic:create_empty_index의 래퍼 작업입니다.
sudo gitlab-rake gitlab:elastic:index_snippets 스니펫 데이터를 색인하는 Elasticsearch 가져오기를 수행합니다.
sudo gitlab-rake gitlab:elastic:index_users 모든 사용자를 Elasticsearch로 가져옵니다.
sudo gitlab-rake gitlab:elastic:projects_not_indexed 인덱싱되지 않은 프로젝트를 표시합니다.
sudo gitlab-rake gitlab:elastic:reindex_cluster 제로 다운타임 클러스터 재색인 작업을 예약합니다.
sudo gitlab-rake gitlab:elastic:mark_reindex_failed 가장 최근의 재색인 작업을 실패로 표시합니다.
sudo gitlab-rake gitlab:elastic:list_pending_migrations 보류 중인 마이그레이션을 나열합니다. 보류 중인 마이그레이션에는 아직 시작되지 않은 마이그레이션, 시작되었지만 완료되지 않은 마이그레이션, 중단된 마이그레이션이 포함됩니다.
sudo gitlab-rake gitlab:elastic:estimate_cluster_size 총 저장소 크기를 기반으로 클러스터 크기를 예상합니다.
sudo gitlab-rake gitlab:elastic:enable_search_with_elasticsearch Elasticsearch로 고급 검색을 활성화합니다.
sudo gitlab-rake gitlab:elastic:disable_search_with_elasticsearch Elasticsearch로 고급 검색을 비활성화합니다.

환경 변수

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

환경 변수 데이터 유형 작동 원리
ID_TO 정수 인덱서에게 값 이하의 프로젝트만 인덱싱하도록 지시합니다.
ID_FROM 정수 인덱서에게 값 이상의 프로젝트만 인덱싱하도록 지시합니다.

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

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 사용자 / test(ID=33) 색인화 중...
I, [2019-03-04T21:27:05.215266 #3384]  INFO -- : GitLab 사용자 / test(ID=33) 색인화가 완료되었습니다!

고급 검색 인덱스 범위

검색 수행 시 GitLab 인덱스는 다음 범위를 사용합니다.

범위 이름 검색 대상
commits 커밋 데이터
projects 프로젝트 데이터 (기본)
blobs 코드
issues 이슈 데이터
merge_requests 병합 요청 데이터
milestones 마일스톤 데이터
notes 노트 데이터
snippets 스니펫 데이터
wiki_blobs 위키 내용
users 사용자
epics 에픽 데이터

튜닝

최적 클러스터 구성 선택에 대한 지침

클러스터 구성 선택에 대한 기본 지침은 Elastic Cloud Calculator를 참조하시기 바랍니다. 아래에서 자세한 정보를 찾을 수 있습니다.

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

고급 검색 통합 설정 안내

  • Number of Elasticsearch shards 설정은 일반적으로 클러스터에서 사용 가능한 CPU 개수와 대응됩니다. 예를 들어, 각각 4개의 코어를 갖춘 3-노드 클러스터가 있다면, 클러스터 내에서 최소 3*4=12개의 샤드를 사용하는 것이 좋습니다. 샤드 수를 바꾸려면 분할 인덱스 API를 사용하거나 샤드 수를 변경한 다른 인덱스로 재색인해야 합니다.
  • Number of Elasticsearch replicas 설정은 대부분의 경우 1과 같아야 합니다 (각 샤드에는 1개의 복제본이 있습니다). 0을 사용하는 것은 권장되지 않습니다. 왜냐하면 노드 하나가 손상되면 인덱스가 손상될 수 있기 때문입니다.

대규모 인스턴스 효율적으로 인덱싱하는 방법

이 섹션은 다른 기본 지침이 큰 양의 데이터를 인덱싱하는 동안 문제를 발생시킬 경우 도움이 될 수 있습니다.

경고: 대규모 인스턴스를 인덱싱하면 많은 Sidekiq 작업이 생성됩니다. 확장 가능한 설정을 갖추거나 추가 Sidekiq 프로세스를 생성하여 이 작업에 대비해야 합니다.

  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" : "30초",
           "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" : "1초"
       } }'

    상기한 새로 고침을 활성화한 후 강제 병합을 호출해야 합니다.

    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 기본 설정을 그대로 두고 삭제가 되었을 때에 대해 너무 걱정할 필요가 없습니다.”

그러나 어떤 큰 규모의 설치는 병합 정책 설정을 조정하기를 원할 수 있습니다:

  • index.merge.policy.max_merged_segment 크기를 기본 설정인 5GB에서 2GB나 3GB로 줄이는 것을 고려해 보세요. 병합은 삭제가 적어도 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 대기열을 포함시켜야만 mailers 작업이 전혀 처리되지 않습니다.

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

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

단일 노드, 두 프로세스

하나의 노드에서 색인 및 비색인화 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. 기존 작업을 마이그레이션하기 위해 레이크 작업을 실행하세요.
note
GitLab을 다시 구성한 후에 바로 레이크 작업을 실행하는 것이 중요합니다. GitLab을 다시 구성한 후에는 기존 작업이 작업을 마이그레이션하기 시작하기 전까지 처리되지 않습니다.

두 노드에서 각각 한 프로세스 처리

이러한 큐 그룹을 두 노드에서 처리하려면 다음을 수행하세요:

  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. 기존 작업을 마이그레이션하기 위해 레이크 작업을 실행하세요. 

    sudo gitlab-rake gitlab:sidekiq:migrate_jobs:retry gitlab:sidekiq:migrate_jobs:schedule gitlab:sidekiq:migrate_jobs:queued
note
GitLab을 다시 구성한 후에 바로 레이크 작업을 실행하는 것이 중요합니다. GitLab을 다시 구성한 후에는 기존 작업이 작업을 마이그레이션하기 시작하기 전까지 처리되지 않습니다.

기본 검색으로 되돌리기

가끔은 Elasticsearch 색인 데이터에 문제가 발생할 수 있습니다. 따라서 GitLab은 검색 결과가 없을 때 “기본 검색”으로 되돌릴 수 있도록 허용합니다. 또한 해당 범위에서 기본 검색을 지원하는 경우입니다. 이 “기본 검색”은 인스턴스에 대해 고급 검색이 전혀 활성화되지 않은 것처럼 작동하며 다른 데이터 원본(예: PostgreSQL 데이터 및 Git 데이터)을 사용하여 검색합니다.

데이터 복구: Elasticsearch는 보조 데이터 저장소로만 사용됨

GitLab에서의 Elasticsearch 사용은 언제나 보조 데이터 저장소로만 사용됩니다. 즉, Elasticsearch에 저장된 모든 데이터는 항상 다른 데이터 원본인 PostgreSQL 및 Gitaly에서 다시 파생될 수 있습니다. 따라서 Elasticsearch 데이터 저장소가 어떤 이유로 손상된 경우 모든 것을 처음부터 다시 인덱싱할 수 있습니다.