Elasticsearch 고급 검색

요약

- Offering: GitLab Self-Managed, GitLab Dedicated 이 페이지에서는 고급 검색을 활성화하는 방법을 설명합니다. 고급 검색을 활성화하려면 다음을 수행해야 합니다. Elasticsearch 또는 AWS OpenSearch 클러스터 설치.

  - 
  Tier: Premium, Ultimate

- Offering: GitLab Self-Managed, GitLab Dedicated

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

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

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

고급 검색은 모든 프로젝트를 동일한 Elasticsearch 인덱스에 저장합니다. 단, 비공개 프로젝트는 접근 권한이 있는 사용자에게만 검색 결과에 표시됩니다.

Elasticsearch 용어 설명#

이 용어 설명은 Elasticsearch 관련 용어의 정의를 제공합니다.

Lucene: Java로 작성된 전체 텍스트 검색 라이브러리입니다.
근실시간(NRT, Near Real Time): 문서를 인덱싱한 시점부터 검색 가능해지기까지의 약간의 지연을 의미합니다.
클러스터(Cluster): 모든 데이터를 보유하고 인덱싱 및 검색 기능을 제공하기 위해 함께 작동하는 하나 이상의 노드 모음입니다.
노드(Node): 클러스터의 일부로 작동하는 단일 서버입니다.
인덱스(Index): 유사한 특성을 가진 문서들의 모음입니다.
문서(Document): 인덱싱할 수 있는 기본 정보 단위입니다.
샤드(Shards): 인덱스의 완전히 기능하는 독립적인 하위 분할입니다. 각 샤드는 실제로 Lucene 인덱스입니다.
레플리카(Replicas): 인덱스를 복제하는 장애 조치 메커니즘입니다.

Elasticsearch 또는 AWS OpenSearch 클러스터 설치#

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

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

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

단일 노드 검색 클러스터의 경우, 기본 샤드가 할당되어 있으므로 클러스터 상태는 항상 yellow입니다. 클러스터는 기본 샤드와 동일한 노드에 레플리카 샤드를 할당할 수 없습니다.

새 Elasticsearch 클러스터를 운영 환경에서 사용하기 전에

중요한 Elasticsearch 구성을 참고하세요.

버전 호환성#

Elasticsearch#

History

Support for Elasticsearch 6.8 removed in GitLab 15.0.

Elasticsearch 7.x 지원은 GitLab 18.10에서 지원 중단되었으며 19.1에서 제거될 예정입니다.

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

GitLab 버전	Elasticsearch 버전
18.1 and later	7.x and later
15.0 to 18.0	7.x and 8.x
14.0 to 14.10	6.8 to 7.x

GitLab.com은 Elasticsearch 8.x를 사용합니다. GitLab Self-Managed에서는 최적의 성능과 향후 호환성을 위해 Elasticsearch 9.x를 사용해야 합니다.

고급 검색은 Elasticsearch 지원 종료 정책을 따릅니다.

OpenSearch#

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

GitLab 버전	OpenSearch 버전
18.1 and later	1.x and later
17.6.3 to 18.0	1.x and 2.x
15.5.3 to 17.6.2	1.x, 2.0 to 2.17
15.0 to 15.5.2	1.x

고급 검색은 OpenSearch 유지관리 정책을 따릅니다.

시스템 요구 사항#

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 Service 접근 제어#

사전 요구 사항:

OpenSearch 도메인을 생성할 때 AWS 계정에 AWSServiceRoleForAmazonOpenSearchService라는 이름의 서비스 연결 역할이 있어야 합니다.
AWS OpenSearch의 도메인 접근 정책에서 es:ESHttp* 액션을 허용해야 합니다.

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

AWS OpenSearch Service에는 세 가지 주요 보안 계층이 있습니다.

네트워크#

이 보안 계층을 사용하면 도메인을 생성할 때 **퍼블릭 접근(Public access)**을 선택하여 모든 클라이언트의 요청이 도메인 엔드포인트에 도달할 수 있도록 할 수 있습니다. **VPC 접근(VPC access)**을 선택하면 클라이언트는 요청이 엔드포인트에 도달하도록 VPC에 연결해야 합니다.

자세한 내용은 AWS 설명서를 참고하세요.

도메인 접근 정책#

GitLab은 AWS OpenSearch에 대한 다음 도메인 접근 제어 방법을 지원합니다.

리소스 기반(도메인) 접근 정책: 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/*"
    }
  ]
}

다음은 특정 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/*"
    }
  ]
}

계정 간에 [AWS `AssumeRole`](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)을 사용하는 경우 `aws_role_arn`을 제공해야 합니다. ARN은 OpenSearch에 접근할 수 있는 권한이 있는 역할이어야 합니다.

자격 증명 기반 정책 예시 다음은 es:ESHttp* 액션이 허용된 IAM 주체에 연결된 자격 증명 기반 접근 정책의 예시입니다.

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

세분화된 접근 제어#

세분화된 접근 제어를 활성화하면 다음 방법 중 하나로 마스터 사용자를 설정해야 합니다.

IAM ARN을 마스터 사용자로 설정 IAM 주체를 마스터 사용자로 사용하면 클러스터에 대한 모든 요청이 AWS Signature Version 4로 서명되어야 합니다. EC2 인스턴스에 할당한 IAM 역할인 IAM ARN을 지정할 수도 있습니다. 자세한 내용은 AWS 설명서를 참고하세요.

사전 요구 사항:

관리자 접근 권한.

IAM ARN을 마스터 사용자로 설정하려면 GitLab 인스턴스에서 IAM 자격 증명과 함께 AWS OpenSearch Service를 사용해야 합니다.

오른쪽 상단 모서리에서 Admin을 선택합니다.

왼쪽 사이드바에서 Settings > Search를 선택합니다.

Advanced search를 펼칩니다.

AWS OpenSearch IAM credentials 섹션에서:

Use AWS OpenSearch Service with IAM credentials 체크박스를 선택합니다.

AWS region에 OpenSearch 도메인이 위치한 AWS 리전을 입력합니다(예: us-east-1).

AWS access key와 AWS secret access key에 인증을 위한 액세스 키를 입력합니다.

컨테이너가 아닌 EC2 인스턴스에서 직접 실행되는 GitLab 배포는

액세스 키를 입력할 필요가 없습니다. GitLab 인스턴스는 AWS Instance Metadata Service (IMDS)에서 자동으로 이 키를 가져옵니다.

Save changes를 선택합니다.

마스터 사용자 생성 내부 사용자 데이터베이스에서 마스터 사용자를 생성하면 HTTP 기본 인증을 사용하여 클러스터에 요청을 보낼 수 있습니다. 자세한 내용은 AWS 설명서를 참고하세요.

사전 요구 사항:

관리자 접근 권한.

마스터 사용자를 생성하려면 GitLab 인스턴스에서 OpenSearch 도메인 URL과 마스터 사용자 이름 및 비밀번호를 구성해야 합니다.

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Advanced search를 펼칩니다.
OpenSearch domain URL에 OpenSearch 도메인 엔드포인트 URL을 입력합니다.
Username에 마스터 사용자 이름을 입력합니다.
Password에 마스터 비밀번호를 입력합니다.
Save changes를 선택합니다.

새 Elasticsearch 버전으로 업그레이드#

History

Support for Elasticsearch 6.8 removed in GitLab 15.0.

사전 요구 사항:

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

Elasticsearch를 새 마이너 또는 메이저 버전으로 업그레이드할 때 GitLab 구성을 변경하지 않아도 됩니다. Elasticsearch 클러스터가 완전히 업그레이드되고 활성화되면:

클러스터 연결, 인덱스 및 검색 작업을 확인합니다.

sudo gitlab-rake gitlab:elastic:index_and_search_validation

인덱싱 재개.

선택 사항. 인덱싱 상태 확인. 올바른 검색 결과를 위해, 특히 Elasticsearch 인스턴스가 한동안 오프라인 상태였던 경우 인덱싱이 완료되었는지 확인합니다.

고급 검색으로 검색 활성화.

Elasticsearch 리포지터리 인덱서#

GitLab은 Git 리포지터리 데이터를 인덱싱하기 위해 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를 설치](https://brew.sh/)해야 합니다.

macOS에 설치하려면 다음을 실행합니다.

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

빌드 및 설치#

인덱서를 빌드하고 설치하려면 다음을 실행합니다.

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

# Run the installation task for 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 인덱서에서 발생한 오류는 json.exception.class가 Gitlab::Elastic::Indexer::Error인 형태로 elasticsearch.log 파일과 sidekiq.log 파일에 기록됩니다. 이러한 오류는 Git 리포지터리 데이터를 인덱싱할 때 발생할 수 있습니다.

고급 검색 활성화#

사전 요구 사항:

인스턴스에 대한 관리자 접근 권한이 있어야 합니다.
인덱스당 샤드 수를 구성합니다.
인덱스당 레플리카 수를 구성합니다.
선택 사항. 대규모 인스턴스 인덱싱을 준비합니다.

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

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Elasticsearch 클러스터에 대한 고급 검색 설정을 구성합니다. 아직 Search with advanced search 체크박스를 선택하지 마세요.
인스턴스를 인덱싱합니다.
선택 사항. 인덱싱 상태를 확인합니다.
인덱싱이 완료되면 Search with advanced search 체크박스를 선택한 후 Save changes를 선택합니다.

Elasticsearch가 활성화된 상태에서 Elasticsearch 클러스터가 다운되면, 인스턴스가 변경 사항을 인덱싱하는 작업을 큐에 추가하지만 유효한 Elasticsearch 클러스터를 찾을 수 없어 이슈와 같은 문서를 업데이트하는 데 문제가 생길 수 있습니다.

리포지터리 데이터가 50GB를 초과하는 GitLab 인스턴스의 경우 대규모 인스턴스를 효율적으로 인덱싱을 참고하세요.

인스턴스 인덱싱#

사용자 인터페이스에서#

History

Introduced in GitLab 17.3.

사전 요구 사항:

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

사용자 인터페이스에서 초기 인덱싱을 수행하거나 인덱스를 다시 생성할 수 있습니다.

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

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Turn on indexing for advanced search 체크박스를 선택한 후 Save changes를 선택합니다.
Index the instance를 선택합니다.

Rake 작업으로#

사전 요구 사항:

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

전체 인스턴스를 인덱싱하려면 다음 Rake 작업을 사용합니다.

# WARNING: This task deletes all existing indices
# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:index

# WARNING: This task deletes all existing indices
# For self-compiled installations
bundle exec rake gitlab:elastic:index RAILS_ENV=production

특정 데이터를 인덱싱하려면 다음 Rake 작업을 사용합니다.

# For installations that use the Linux package
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

# For self-compiled installations
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

인덱싱 상태 확인#

사전 요구 사항:

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

인덱싱 상태를 확인하려면:

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Advanced search indexing status를 펼칩니다.

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

사전 요구 사항:

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

인덱싱 진행 상황을 모니터링하려면 백그라운드 작업 상태를 확인할 수도 있습니다.

오른쪽 상단 모서리에서 Admin을 선택합니다.
Monitoring > Background jobs를 선택합니다.
Sidekiq 대시보드에서 Busy를 선택하고 다음 인덱싱 작업을 확인합니다.

코드 및 커밋의 경우 Search::Elastic::CommitIndexerWorker.

위키 데이터의 경우 ElasticWikiIndexerWorker.

고급 검색으로 검색 활성화#

사전 요구 사항:

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

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

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Search with advanced search 체크박스를 선택합니다.
Save changes를 선택합니다.

고급 검색으로 코드 검색 활성화#

사전 요구 사항:

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

GitLab에서 고급 검색으로 코드 검색을 활성화하려면:

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Code search with advanced search 체크박스를 선택합니다.
Save changes를 선택합니다.

고급 검색 구성#

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

Parameter	Description
Turn on indexing for advanced search	Turns on or turns off indexing and creates an empty index if one does not already exist. You may want to turn on indexing but turn off search to give the index time to be fully completed, for example. Also, keep in mind that this option doesn’t have any impact on existing data, this only enables/disables the background indexer which tracks data changes and ensures new data is indexed.
Pause indexing for advanced search	Pauses advanced search indexing. This is useful for cluster migration/reindexing. All changes are still tracked, but they are not committed to the index until resumed.
Search with advanced search	Turns on or turns off the advanced search capabilities in search and advanced vulnerability management.
Code search with advanced search	Turns on or turns off code search with advanced search. When this setting is turned off, all code is deleted from your Elasticsearch instance. To turn this setting back on, fully reindex your code. If exact code search is enabled, you should turn off this setting to save resources.
Requeue indexing workers	Turns on automatic requeuing of indexing workers. This improves non-code indexing throughput by enqueuing Sidekiq jobs until all documents are processed. Requeuing indexing workers is not recommended for smaller instances or instances with few Sidekiq processes.
URL	The URL of your Elasticsearch instance. Use a comma-separated list to support clustering (for example, http://host1, https://host2:9200). If your Elasticsearch instance is password-protected, use the Username and Password fields. Alternatively, use inline credentials such as http://:@<elastic_host>:9200/. If you use OpenSearch, only connections over ports 80 and 443 are accepted.
Username	The username of your Elasticsearch instance.
Password	The password of your Elasticsearch instance.
Number of Elasticsearch shards and replicas per index	Elasticsearch indices are split into multiple shards for performance reasons. In general, you should use at least five shards. Indices with tens of millions of documents should have more shards (see the guidance). Changes to this value do not take effect until you re-create the index. For more information about scalability and resilience, see the Elasticsearch documentation. Each Elasticsearch shard can have a number of replicas. These replicas are a complete copy of the shard and can provide increased query performance or resilience against hardware failure. Increasing this value increases the total disk space required by the index. You can set the number of shards and replicas for each of the indices.
Limit the amount of namespace and project data to index	When you enable this setting, you can specify namespaces and projects to index. All other namespaces and projects use database search instead. If you enable this setting but do not specify any namespace or project, only project records are indexed. For more information, see Limit the amount of namespace and project data to index.
Use AWS OpenSearch Service with IAM credentials	Sign your OpenSearch requests using AWS IAM authorization, AWS EC2 Instance Profile Credentials, or AWS ECS Tasks Credentials. Refer to Identity and Access Management in Amazon OpenSearch Service for details of AWS hosted OpenSearch domain access policy configuration.
AWS Region	The AWS region in which your OpenSearch Service is located.
AWS Access Key	The AWS access key.
AWS Secret Access Key	The AWS secret access key.
Maximum file size indexed	See the explanation in instance limits..
Maximum field length	See the explanation in instance limits..
Indexing timeout (minutes)	Indexing timeout in minutes per project.
Number of shards for non-code indexing	Number of indexing worker shards. This improves non-code indexing throughput by enqueuing more parallel Sidekiq jobs. Increasing the number of shards is not recommended for smaller instances or instances with few Sidekiq processes. Default is 2.
Maximum bulk request size (MiB)	Used by the GitLab Ruby and Go-based indexer processes. This setting indicates how much data must be collected (and stored in memory) in a given indexing process before submitting the payload to the Elasticsearch Bulk API. For the GitLab Go-based indexer, you should use this setting with Bulk request concurrency. Maximum bulk request size (MiB) must accommodate the resource constraints of both the Elasticsearch hosts and the hosts running the GitLab Go-based indexer from either the gitlab-rake command or the Sidekiq tasks.
Bulk request concurrency	The Bulk request concurrency indicates how many of the GitLab Go-based indexer processes (or threads) can run in parallel to collect data to subsequently submit to the Elasticsearch Bulk API. This increases indexing performance, but fills the Elasticsearch bulk requests queue faster. This setting should be used together with the Maximum bulk request size (MiB) setting and needs to accommodate the resource constraints of both the Elasticsearch hosts and the hosts running the GitLab Go-based indexer either from the gitlab-rake command or the Sidekiq tasks.
Client request timeout	Elasticsearch HTTP client request timeout value in seconds. 0 means using the system default timeout value, which depends on the libraries that GitLab application is built upon.
Code indexing concurrency	Maximum number of Elasticsearch code indexing background jobs allowed to run concurrently. This only applies to repository indexing operations.
Retry on failure	Maximum number of possible retries for Elasticsearch search requests. Introduced in GitLab 17.6.
Index prefix	Custom prefix for Elasticsearch index names. Defaults to gitlab. When changed, all indices will use this prefix instead of gitlab (for example, custom-production-issues instead of gitlab-production-issues). Must be 1-100 characters, contain only lowercase alphanumeric characters, hyphens, and underscores, and cannot start or end with a hyphen or underscore. Introduced in GitLab 18.2.

**Maximum bulk request size (MiB)**와 **Bulk request concurrency** 값을 높이면 Sidekiq 성능에 부정적인 영향을 줄 수 있습니다. Sidekiq 로그에서 `scheduling_latency_s` 지속 시간이 증가하는 경우 기본값으로 되돌리세요. 자세한 내용은 [이슈 322147](https://gitlab.com/gitlab-org/gitlab/-/issues/322147)을 참고하세요.

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

History

Indexing all project records introduced in GitLab 16.7 with a flag named search_index_all_projects. Disabled by default.
Generally available in GitLab 16.11. Feature flag search_index_all_projects removed.
Indexing vulnerability records introduced on GitLab.com and GitLab Dedicated in GitLab 18.1 with a flag named vulnerability_es_ingestion. Disabled by default.
Indexing vulnerability records is generally available on GitLab.com and GitLab Dedicated in GitLab 18.2. Feature flag vulnerability_es_ingestion removed.

이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 변경 이력을 참고하세요.

Limit the amount of namespace and project data to index 체크박스를 선택하면, 인덱싱할 네임스페이스와 프로젝트를 지정할 수 있습니다. 네임스페이스가 그룹인 경우 해당 그룹의 서브그룹과 프로젝트도 인덱싱됩니다.

이 설정을 활성화하면:

전체 인덱싱을 위해 네임스페이스 또는 프로젝트를 지정해야 합니다.
프로젝트 레코드(프로젝트 이름 및 설명과 같은 메타데이터)는 모든 프로젝트에 대해 항상 인덱싱됩니다.
보안 보고서의 필터링 지원을 위해 취약성 레코드는 모든 프로젝트 및 네임스페이스에 대해 항상 인덱싱됩니다.
연관 데이터는 지정한 네임스페이스 및 프로젝트에 대해서만 인덱싱됩니다.

이 설정을 활성화한 후 네임스페이스 또는 프로젝트를 지정하지 않으면, 프로젝트 레코드만 인덱싱되고 연관 데이터는 검색할 수 없습니다.

인덱싱된 네임스페이스#

History

Global search for limited indexing introduced in GitLab 13.4 with a flag named advanced_global_search_for_limited_indexing. Disabled by default.
Enabled on GitLab.com in GitLab 14.2.
Global search for limited indexing generally available in GitLab 17.11 as a UI option, instead of the advanced_global_search_for_limited_indexing flag.

모든 네임스페이스를 인덱싱하면 전역 코드 및 커밋 검색에 고급 검색을 사용할 수 있습니다. 일부 네임스페이스만 인덱싱하는 경우:

전역 검색에는 코드 또는 커밋 검색 범위가 포함되지 않습니다.
코드 및 커밋 검색은 단일 인덱싱된 네임스페이스에서만 사용 가능합니다.
여러 인덱싱된 네임스페이스에 걸친 단일 코드 또는 커밋 검색은 불가능합니다.
인덱싱된 네임스페이스에서는 크로스 프로젝트 검색을 사용할 수 있습니다.

예를 들어, 두 개의 별도 그룹을 인덱싱하는 경우 각 그룹에서 별도로 코드 검색을 실행해야 합니다.

제한된 인덱싱에 대한 전역 검색을 활성화하려면:

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Advanced search를 펼칩니다.
Enable global search for limited indexing를 선택합니다.
Save changes를 선택합니다.
인스턴스를 이미 인덱싱한 경우 인스턴스를 다시 인덱싱해야 합니다. 이렇게 하면 기존 검색 데이터가 삭제되어 필터링이 올바르게 작동하도록 합니다.

커스텀 언어 분석기 활성화#

사전 요구 사항:

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

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

커스텀 언어 분석기를 활성화하려면:

원하는 플러그인을 설치합니다. 플러그인 설치 지침은 Elasticsearch 설명서를 참고하세요. 플러그인은 클러스터의 모든 노드에 설치해야 하며 설치 후 각 노드를 재시작해야 합니다. 플러그인 목록은 이 섹션의 테이블을 참고하세요.
오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Custom analyzers: language support를 찾습니다.
Indexing에 대한 플러그인 지원을 활성화합니다.
변경 사항이 적용되도록 Save changes를 선택합니다.
무중단 재인덱싱을 실행하거나 처음부터 모두 재인덱싱하여 업데이트된 매핑으로 새 인덱스를 생성합니다.
이전 단계가 완료된 후 Searching에 대한 플러그인 지원을 활성화합니다.

설치할 항목에 대한 안내는 다음 Elasticsearch 언어 플러그인 옵션을 참고하세요.

Parameter	Description
Enable Chinese (smartcn) custom analyzer: Indexing	Enables or disables Chinese language support using smartcn custom analyzer for newly created indices.
Enable Chinese (smartcn) custom analyzer: Search	Enables or disables using smartcn fields for advanced search. Only enable this after installing the plugin, enabling custom analyzer indexing and recreating the index.
Enable Japanese (kuromoji) custom analyzer: Indexing	Enables or disables Japanese language support using kuromoji custom analyzer for newly created indices.
Enable Japanese (kuromoji) custom analyzer: Search	Enables or disables using kuromoji fields for advanced search. Only enable this after installing the plugin, enabling custom analyzer indexing and recreating the index.

고급 검색 비활성화#

사전 요구 사항:

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

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

오른쪽 상단 모서리에서 Admin을 선택합니다.

왼쪽 사이드바에서 Settings > Search를 선택합니다.

Turn on indexing for advanced search 및 Search with advanced search 체크박스를 해제합니다.

Save changes를 선택합니다.

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

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:delete_index

# For self-compiled installations
bundle exec rake gitlab:elastic:delete_index RAILS_ENV=production

고급 검색으로 검색 비활성화#

사전 요구 사항:

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

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

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Search with advanced search 체크박스를 해제합니다.
Save changes를 선택합니다.

고급 검색으로 코드 검색 비활성화#

사전 요구 사항:

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

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

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Code search with advanced search 체크박스를 해제합니다.
Save changes를 선택합니다.

인덱싱 일시 중지#

사전 요구 사항:

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

인덱싱을 일시 중지하려면:

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Advanced search를 펼칩니다.
Pause indexing for advanced search 체크박스를 선택합니다.
Save changes를 선택합니다.

인덱싱 재개#

사전 요구 사항:

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

인덱싱을 재개하려면:

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Advanced search를 펼칩니다.
Pause indexing for advanced search 체크박스를 해제합니다.
Save changes를 선택합니다.

무중단 재인덱싱#

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

무중단 재인덱싱 사용#

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

재인덱싱 실행#

사전 요구 사항:

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

재인덱싱을 실행하려면:

GitLab 인스턴스에 관리자로 로그인합니다.
오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Advanced search zero-downtime reindexing을 펼칩니다.
Trigger cluster reindexing을 선택합니다.

재인덱싱은 Elasticsearch 클러스터의 크기에 따라 오래 걸릴 수 있습니다.

이 프로세스가 완료된 후 원본 인덱스는 14일 후에 삭제 예약됩니다. 재인덱싱 프로세스를 실행한 동일 페이지에서 Cancel 버튼을 눌러 이 작업을 취소할 수 있습니다.

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

무중단 재인덱싱 실행#

사전 요구 사항:

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

무중단 재인덱싱을 실행하려면:

오른쪽 상단 모서리에서 Admin을 선택합니다.

왼쪽 사이드바에서 Settings > Search를 선택합니다.

Advanced search zero-downtime reindexing을 펼칩니다. 다음 설정을 사용할 수 있습니다.

슬라이스 배수

최대 실행 슬라이스

슬라이스 배수#

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

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

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

최대 실행 슬라이스#

최대 실행 슬라이스 파라미터의 기본값은 60이며, Elasticsearch 재인덱싱 중 동시에 실행할 수 있는 최대 슬라이스 수에 해당합니다.

이 값을 너무 높게 설정하면 클러스터가 검색 및 쓰기로 과부하될 수 있어 성능에 부정적인 영향을 줄 수 있습니다. 이 값을 너무 낮게 설정하면 재인덱싱 프로세스가 완료되는 데 매우 오랜 시간이 걸릴 수 있습니다.

이 값에 대한 최선의 설정은 클러스터 크기, 재인덱싱 중 일부 검색 성능 저하를 허용할 의향이 있는지 여부, 그리고 재인덱싱을 빠르게 완료하고 인덱싱을 재개하는 것이 얼마나 중요한지에 따라 달라집니다.

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

사전 요구 사항:

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

완료되지 않은 재인덱싱 작업을 포기하고 인덱싱을 재개하려면:

가장 최근 재인덱싱 작업을 실패로 표시합니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:mark_reindex_failed

# For self-compiled installations
bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production

오른쪽 상단 모서리에서 Admin을 선택합니다.

왼쪽 사이드바에서 Settings > Search를 선택합니다.

Advanced search를 펼칩니다.

Pause indexing for advanced search 체크박스를 해제합니다.

인덱스 무결성#

History

Introduced in GitLab 15.10 with a flag named search_index_integrity. Disabled by default.
Generally available in GitLab 16.4. Feature flag search_index_integrity removed.

인덱스 무결성은 누락된 리포지터리 데이터를 감지하고 수정합니다. 이 기능은 그룹 또는 프로젝트 범위의 코드 검색 결과가 없을 때 자동으로 사용됩니다.

고급 검색 마이그레이션#

재인덱스 마이그레이션은 백그라운드에서 실행되므로 인스턴스를 수동으로 재인덱싱할 필요가 없습니다.

GitLab 18.0 이상에서는 elastic_migration_worker_enabled 애플리케이션 설정을 사용하여 마이그레이션 워커를 활성화하거나 비활성화할 수 있습니다. 기본적으로 마이그레이션 워커는 활성화되어 있습니다.

마이그레이션 사전 파일#

History

Introduced in 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 파일을 확인하여 마이그레이션이 중단된 이유를 디버그하고 필요한 변경 사항을 적용하는 것이 좋습니다.

오류 원인을 수정했다고 판단되면:

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Advanced search를 펼칩니다.
Elasticsearch migration halted 경고 상자 내에서 Retry migration을 선택합니다. 마이그레이션이 백그라운드에서 재시도 예약됩니다.

마이그레이션이 성공하지 못하는 경우 처음부터 인덱스를 재생성하는 최후 수단을 고려할 수 있습니다. 새로 생성된 인덱스는 최신 스키마로 재생성되므로 모든 마이그레이션을 건너뛰어 문제를 회피할 수 있습니다.

메이저 업그레이드 전에 모든 마이그레이션을 완료해야 합니다#

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

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

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

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

건너뛸 수 있는 마이그레이션이 더 이상 사용되지 않는 것으로 표시될 때까지 실행되지 않은 경우, 변경 사항을 적용하려면 인덱스를 재생성해야 합니다.

GitLab 고급 검색 Rake 작업#

다음 용도로 Rake 작업을 사용할 수 있습니다.

인덱서를 빌드 및 설치합니다.
Elasticsearch를 비활성화할 때 인덱스를 삭제합니다.
GitLab 데이터를 인덱스에 추가합니다.

다음은 사용 가능한 Rake 작업들입니다.

Task	Description
sudo gitlab-rake gitlab:elastic:info	Outputs debugging information for the advanced search integration.
sudo gitlab-rake gitlab:elastic:index	In GitLab 17.0 and earlier, turns on indexing for advanced search and runs gitlab:elastic:recreate_index, gitlab:elastic:clear_index_status, gitlab:elastic:index_group_entities, gitlab:elastic:index_projects, gitlab:elastic:index_snippets, and gitlab:elastic:index_users.In GitLab 17.1 and later, queues a Sidekiq job in the background. First, the job turns on indexing for advanced search and pauses indexing to ensure all indices are created. Then, the job re-creates all indices, clears indexing status, and queues additional Sidekiq jobs to index project and group data, snippets, and users. Finally, indexing for advanced search is resumed to complete. Introduced in GitLab 17.1 with a flag named elastic_index_use_trigger_indexing. Enabled by default. Generally available in GitLab 17.3. Feature flag elastic_index_use_trigger_indexing removed.
sudo gitlab-rake gitlab:elastic:pause_indexing	Pauses indexing for advanced search. Changes are still tracked. Useful for cluster/index migrations.
sudo gitlab-rake gitlab:elastic:resume_indexing	Resumes indexing for advanced search.
sudo gitlab-rake gitlab:elastic:index_and_search_validation	Validates cluster connectivity, index, and search operations for all indices. Introduced in GitLab 18.3.
sudo gitlab-rake gitlab:elastic:index_projects	Iterates over all projects, and queues Sidekiq jobs to index them in the background. It can only be used after the index is created.
sudo gitlab-rake gitlab:elastic:index_group_entities	Invokes gitlab:elastic:index_work_items and gitlab:elastic:index_group_wikis.
sudo gitlab-rake gitlab:elastic:index_work_items	Indexes all work items from the groups where Elasticsearch is enabled.
sudo gitlab-rake gitlab:elastic:index_namespaces	Indexes all root namespaces.
sudo gitlab-rake gitlab:elastic:index_group_wikis	Indexes all wikis from the groups where Elasticsearch is enabled.
sudo gitlab-rake gitlab:elastic:index_snippets	Performs an Elasticsearch import that indexes the snippets data.
sudo gitlab-rake gitlab:elastic:index_users	Imports all users into Elasticsearch.
sudo gitlab-rake gitlab:elastic:index_vulnerabilities	Indexes all vulnerabilities.
sudo gitlab-rake gitlab:elastic:index_projects_status	Determines the overall indexing status of all project repository data (code, commits, and wikis). The status is calculated by dividing the number of indexed projects by the total number of projects and multiplying by 100. This task does not include non-repository data such as issues, merge requests, or milestones.
sudo gitlab-rake gitlab:elastic:index_groups_status	Determines the overall indexing status of all group repository data (group wikis). The status is calculated by dividing the number of indexed groups by the total number of groups and multiplying by 100. This task does not include non-repository data such as epics, merge requests, or milestones.
sudo gitlab-rake gitlab:elastic:clear_index_status	Deletes all instances of IndexStatus for all projects. This command results in a complete wipe of the index, and it should be used with caution.
sudo gitlab-rake gitlab:elastic:create_empty_index	Generates empty indices (the default index and a separate issues index) and assigns an alias for each on the Elasticsearch side only if it doesn’t already exist.
sudo gitlab-rake gitlab:elastic:delete_index	Removes the GitLab indices and aliases (if they exist) on the Elasticsearch instance.
sudo gitlab-rake gitlab:elastic:recreate_index	Wrapper task for gitlab:elastic:delete_index and gitlab:elastic:create_empty_index. Does not queue any indexing jobs.
sudo gitlab-rake gitlab:elastic:projects_not_indexed	Displays which projects do not have repository data indexed. This task does not include non-repository data such as issues, merge requests, or milestones.
sudo gitlab-rake gitlab:elastic:groups_not_indexed	Displays which groups do not have repository data indexed. This task does not include non-repository data such as issues, merge requests, or milestones.
sudo gitlab-rake gitlab:elastic:reindex_cluster	Schedules a zero-downtime cluster reindexing task.
sudo gitlab-rake gitlab:elastic:mark_reindex_failed	Mark the most recent reindex job as failed.
sudo gitlab-rake gitlab:elastic:list_pending_migrations	List pending migrations. Pending migrations include those that have not yet started, have started but not finished, and those that are halted.
sudo gitlab-rake gitlab:elastic:estimate_cluster_size	Get an estimate of code and wiki index sizes and total cluster size based on the total repository size.
sudo gitlab-rake gitlab:elastic:estimate_shard_sizes	Get an estimate of shard sizes for each index based on approximate database counts. This estimate does not include repository data (code, commits, and wikis). Introduced in GitLab 16.11.
sudo gitlab-rake gitlab:elastic:enable_search_with_elasticsearch	Enables advanced search with Elasticsearch.
sudo gitlab-rake gitlab:elastic:disable_search_with_elasticsearch	Disables advanced search with Elasticsearch.

환경 변수#

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

Environment Variable	Data Type	What it does
ID_TO	Integer	Tells the indexer to only index projects less than or equal to the value.
ID_FROM	Integer	Tells the indexer to only index projects greater than or equal to the value.

프로젝트 범위 또는 특정 프로젝트 인덱싱#

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
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 인덱스는 다음 범위를 사용합니다.

Scope Name	What it searches
commits	Commit data
projects	Project data (default)
blobs	Code
work_items	Work item data
merge_requests	Merge request data
milestones	Milestone data
notes	Note data
snippets	Snippet data
wiki_blobs	Wiki contents
users	Users

GitLab.com과 GitLab Dedicated에서는 검색 외의 기능을 지원하기 위해 모든 프로젝트 및 네임스페이스에 대한 취약성 레코드가 항상 인덱싱됩니다. GitLab Self-Managed에서의 취약성 레코드 인덱싱은 이슈 525484에서 제안되었습니다.

튜닝#

최적 클러스터 구성 선택 안내#

클러스터 구성 선택에 대한 기본 안내는 Elastic Cloud Calculator도 참고하세요.

일반적으로 레플리카 1개와 함께 최소 2노드 클러스터 구성을 사용하여 탄력성을 확보하는 것이 좋습니다. 스토리지 사용량이 빠르게 증가하고 있다면, 수평 확장(노드 추가)을 미리 계획하는 것이 좋습니다.
검색 클러스터에 HDD 스토리지를 사용하는 것은 성능에 영향을 주므로 권장하지 않습니다. SSD 스토리지(예: NVMe 또는 SATA SSD 드라이브)를 사용하는 것이 좋습니다.
대규모 인스턴스에서는 코디네이팅 전용 노드를 사용하지 않는 것이 좋습니다. 코디네이팅 전용 노드는 데이터 노드보다 작아, 성능과 고급 검색 마이그레이션에 영향을 줄 수 있습니다.
GitLab Performance Tool을 사용하여 다양한 검색 클러스터 크기 및 구성으로 검색 성능을 벤치마크할 수 있습니다.
Heap size는 물리적 RAM의 50% 이하로 설정해야 합니다. 또한 제로 기반 압축 oops(zero-based compressed oops)의 임계값을 초과하지 않아야 합니다. 정확한 임계값은 다르지만, 대부분의 시스템에서는 26GB가 안전하며 일부 시스템에서는 30GB까지 가능합니다. 자세한 내용은 Heap size settings와 Setting JVM options을 참고하세요.
refresh_interval은 인덱스별 설정입니다. 실시간 데이터가 필요하지 않은 경우 기본값 1s에서 더 큰 값으로 조정할 수 있습니다. 이 설정은 새로운 결과를 얼마나 빨리 볼 수 있는지에 영향을 줍니다. 실시간성이 중요하다면 기본값에 최대한 가깝게 유지하는 것이 좋습니다.
많은 무거운 인덱싱 작업이 있는 경우 indices.memory.index_buffer_size를 30% 또는 40%로 높이는 것이 좋습니다.

고급 검색 설정#

Elasticsearch 샤드 수#

History

gitlab:elastic:estimate_shard_sizes introduced in GitLab 16.11.
gitlab:elastic:estimate_shard_sizes changed in GitLab 18.3 to include sizing for indices that contain repository data.

단일 노드 클러스터의 경우, 인덱스당 Elasticsearch 샤드 수를 Elasticsearch 데이터 노드의 CPU 코어 수로 설정합니다.

다중 노드 클러스터의 경우, Rake 작업 gitlab:elastic:estimate_shard_sizes를 실행하여 각 인덱스의 샤드 수를 결정합니다. 이 작업은 샤드 및 레플리카 크기 권장 사항과 데이터베이스 데이터를 포함하는 인덱스의 예상 문서 수를 반환합니다.

평균 샤드 크기를 수 GB에서 30 GB 사이로 유지하세요. 평균 샤드 크기가 30 GB를 초과하면 해당 인덱스의 샤드 크기를 늘리고 무중단 재인덱싱을 실행합니다. 클러스터 상태를 유지하려면 노드당 샤드 수가 구성된 힙 크기의 20배를 초과하지 않아야 합니다. 예를 들어, 30GB 힙을 가진 노드는 최대 600개의 샤드를 가져야 합니다.

인덱스의 샤드 수를 업데이트하려면 설정을 변경하고 무중단 재인덱싱을 실행합니다.

Elasticsearch 레플리카 수#

단일 노드 클러스터의 경우, 인덱스당 Elasticsearch 레플리카 수를 0으로 설정합니다.

다중 노드 클러스터의 경우, 인덱스당 Elasticsearch 레플리카 수를 1(각 샤드에 레플리카 1개)로 설정합니다. 하나의 노드를 잃으면 인덱스가 손상되기 때문에 이 수는 0이어서는 안 됩니다.

샤드 할당 인식이 활성화된 경우, 샤드당 복사본의 총 수가 인식 속성(일반적으로 노드 또는 영역) 수로 균등하게 나누어져야 합니다. 모든 인식 속성에 걸쳐 샤드 복사본이 균등하게 분산되면 최적의 결함 허용성과 부하 분산이 보장됩니다.

(1 + `number_of_replicas`) / `number_of_awareness_attributes` = whole number

인덱스의 레플리카 수를 업데이트하려면 설정을 변경하고 무중단 재인덱싱을 실행합니다.

대규모 인스턴스를 효율적으로 인덱싱#

사전 요구 사항:

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

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

Geo 기본 노드와 보조 노드 모두 동일한 Elasticsearch 클러스터를 가리킵니다. 단, Elasticsearch 인덱싱 워커는 기본 사이트의 Sidekiq 노드에서만 실행됩니다.

이러한 이유로, 추가 Sidekiq 프로세스를 기본 사이트의 Sidekiq 노드에서 구성해야 합니다.

대용량 데이터 인덱싱으로 인해 고급 검색 활성화에 문제가 발생하는 경우:

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

빈 인덱스를 생성합니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:create_empty_index

# For self-compiled installations
bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production

GitLab 인스턴스를 재인덱싱하는 경우 인덱스 상태를 초기화합니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:clear_index_status

# For self-compiled installations
bundle exec rake gitlab:elastic:clear_index_status RAILS_ENV=production

Turn on indexing for advanced search 체크박스를 선택합니다.

대규모 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
       } }'

프로젝트와 관련 데이터를 인덱싱합니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:index_projects

# For self-compiled installations
bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production

이렇게 하면 인덱싱이 필요한 각 프로젝트에 대해 Sidekiq 작업이 큐에 추가됩니다. Rake 작업으로 인덱싱 상태를 조회할 수 있습니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:index_projects_status

# For self-compiled installations
bundle exec rake gitlab:elastic:index_projects_status RAILS_ENV=production

Indexing is 65.55% complete (6555/10000 projects). Considers only code, commits, and wikis.

인덱스를 프로젝트 범위로 제한하려면 ID_FROM 및 ID_TO 파라미터를 사용할 수 있습니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000

# For self-compiled installations
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 작업을 사용하여 인덱서가 모든 진행 상황을 "잊도록" 강제할 수도 있으며, 이렇게 하면 처음부터 인덱싱 프로세스를 재시도합니다.

작업 항목, 그룹 위키, 개인 스니펫, 사용자는 프로젝트와 연관되어 있지 않으므로 별도로 인덱싱해야 합니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:index_work_items
sudo gitlab-rake gitlab:elastic:index_group_wikis
sudo gitlab-rake gitlab:elastic:index_snippets
sudo gitlab-rake gitlab:elastic:index_users

# For self-compiled installations
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_snippets RAILS_ENV=production
bundle exec rake gitlab:elastic:index_users RAILS_ENV=production

인덱싱 후 복제 및 새로 고침을 다시 활성화합니다(이전에 refresh_interval을 증가시킨 경우에만).

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

새로 고침을 활성화한 후 강제 병합(force merge)을 호출해야 합니다.

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
       } }'

인덱싱이 완료되면 Search with advanced search 체크박스를 선택합니다.

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

대부분의 인스턴스에서는 전용 Sidekiq 노드나 프로세스를 구성할 필요가 없습니다.

다음 단계에서는 라우팅 규칙이라는 Sidekiq의 고급 설정을 사용합니다. 작업 손실을 방지하기 위해 라우팅 규칙 사용의 영향을 충분히 이해한 후 적용하세요.

대규모 인스턴스 인덱싱은 길고 리소스 집약적인 프로세스로 Sidekiq 노드와 프로세스에 과부하를 줄 수 있습니다. 이는 GitLab 성능과 가용성에 부정적인 영향을 미칩니다.

GitLab은 여러 Sidekiq 프로세스를 시작할 수 있으므로, 큐 세트(또는 큐 그룹)를 인덱싱 전용으로 추가 프로세스를 생성할 수 있습니다. 이를 통해 인덱싱 큐는 항상 전용 워커를 가지고, 나머지 큐는 경쟁을 피하기 위한 별도의 전용 워커를 갖도록 할 수 있습니다.

이 목적을 위해 워커 매칭 쿼리를 기반으로 Sidekiq가 특정 큐로 작업을 라우팅하도록 하는 라우팅 규칙 옵션을 사용합니다.

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

다음 두 가지 옵션 중 하나를 선택할 수 있습니다.

다음 단계에서 sidekiq['routing_rules']의 항목을 고려합니다.

모든 인덱싱 작업이 global_search 큐로 라우팅되도록 ["feature_category=global_search", "global_search"].
다른 모든 비인덱싱 작업이 default 큐로 라우팅되도록 ["*", "default"].

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

여러 프로세스를 시작할 때, 프로세스 수는 Sidekiq에 할당하려는 CPU 코어 수를 초과할 수 없습니다. 각 Sidekiq 프로세스는 사용 가능한 워크로드 및 동시성 설정에 따라 하나의 CPU 코어만 사용할 수 있습니다. 자세한 내용은 [여러 Sidekiq 프로세스 실행](/19.0/administration/sidekiq/extra_sidekiq_processes/) 방법을 참고하세요.

단일 노드, 두 개의 프로세스#

하나의 노드에서 인덱싱 및 비인덱싱 Sidekiq 프로세스를 모두 생성하려면:

Sidekiq 노드에서 /etc/gitlab/gitlab.rb 파일을 다음과 같이 변경합니다.

sidekiq['enable'] = true

sidekiq['routing_rules'] = [
   ["feature_category=global_search", "global_search"],
   ["*", "default"],
]

sidekiq['queue_groups'] = [
   "global_search", # process that listens to global_search queue
   "default,mailers" # process that listens to default and mailers queue
]

sidekiq['concurrency'] = 20

GitLab 16.11 이하를 사용 중인 경우 모든 큐 선택기를 명시적으로 비활성화합니다.

sidekiq['queue_selector'] = false

파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성합니다.

다른 모든 Rails 및 Sidekiq 노드에서 sidekiq['routing_rules']가 이전 구성과 동일한지 확인합니다.

기존 작업을 마이그레이션하는 Rake 작업을 실행합니다.

GitLab을 재구성한 직후 Rake 작업을 실행하는 것이 중요합니다.

GitLab을 재구성한 후 Rake 작업이 작업 마이그레이션을 시작할 때까지 기존 작업은 처리되지 않습니다.

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

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

인덱싱 Sidekiq 프로세스를 설정하려면, 인덱싱 Sidekiq 노드에서 /etc/gitlab/gitlab.rb 파일을 다음과 같이 변경합니다.

sidekiq['enable'] = true

sidekiq['routing_rules'] = [
   ["feature_category=global_search", "global_search"],
   ["*", "default"],
]

sidekiq['queue_groups'] = [
  "global_search", # process that listens to global_search queue
]

sidekiq['concurrency'] = 20

GitLab 16.11 이하를 사용 중인 경우 모든 큐 선택기를 명시적으로 비활성화합니다.

sidekiq['queue_selector'] = false

파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성합니다.

비인덱싱 Sidekiq 프로세스를 설정하려면, 비인덱싱 Sidekiq 노드에서 /etc/gitlab/gitlab.rb 파일을 다음과 같이 변경합니다.

sidekiq['enable'] = true

sidekiq['routing_rules'] = [
   ["feature_category=global_search", "global_search"],
   ["*", "default"],
]

sidekiq['queue_groups'] = [
   "default,mailers" # process that listens to default and mailers queue
]

sidekiq['concurrency'] = 20

GitLab 16.11 이하를 사용 중인 경우 모든 큐 선택기를 명시적으로 비활성화합니다.

sidekiq['queue_selector'] = false

다른 모든 Rails 및 Sidekiq 노드에서 sidekiq['routing_rules']가 이전 구성과 동일한지 확인합니다.

파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성합니다.

기존 작업을 마이그레이션하는 Rake 작업을 실행합니다.

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

GitLab을 재구성한 직후 Rake 작업을 실행하는 것이 중요합니다.

GitLab을 재구성한 후 Rake 작업이 작업 마이그레이션을 시작할 때까지 기존 작업은 처리되지 않습니다.

삭제된 문서#

인덱싱된 GitLab 객체(머지 리퀘스트 설명 변경, 리포지터리의 기본 브랜치에서 파일 삭제, 프로젝트 삭제 등)가 변경되거나 삭제될 때마다 인덱스의 문서가 삭제됩니다. 단, 이러한 삭제는 "소프트" 삭제이기 때문에 "삭제된 문서"의 전체 수와 낭비 공간이 증가합니다.

Elasticsearch는 세그먼트를 지능적으로 병합하여 이러한 삭제된 문서를 제거합니다. 단, GitLab 설치의 활동 양과 유형에 따라 인덱스에서 최대 50%의 낭비 공간이 발생할 수 있습니다.

일반적으로 기본 설정으로 Elasticsearch가 자동으로 공간을 병합하고 회수하도록 두는 것이 좋습니다. Lucene의 삭제된 문서 처리에서는 "전반적으로 최대 세그먼트 크기를 줄이는 것 외에는 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"
       }
     }'

삭제된 문서를 제거하기 위해 강제 병합을 수행하지 마세요. 문서의 경고에 따르면 이로 인해 회수되지 않을 수 있는 매우 큰 세그먼트가 생성될 수 있으며 심각한 성능 또는 가용성 문제를 일으킬 수 있습니다.

기본 검색으로 되돌리기#

Elasticsearch 인덱스 데이터에 문제가 있을 수 있으므로, GitLab은 검색 결과가 없고 해당 범위에서 기본 검색이 지원되는 경우 "기본 검색"으로 되돌릴 수 있습니다. 이 "기본 검색"은 인스턴스에서 고급 검색이 전혀 활성화되지 않은 것처럼 작동하며 다른 데이터 소스(예: PostgreSQL 데이터 및 Git 데이터)를 사용하여 검색합니다.

재해 복구#

Elasticsearch는 GitLab의 보조 데이터 저장소입니다. Elasticsearch에 저장된 모든 데이터는 다른 데이터 소스, 구체적으로 PostgreSQL과 Gitaly에서 다시 파생될 수 있습니다. Elasticsearch 데이터 저장소가 손상되면 처음부터 모든 것을 재인덱싱할 수 있습니다.

Elasticsearch 인덱스가 너무 큰 경우, 처음부터 모든 것을 재인덱싱하는 데 너무 많은 다운타임이 발생할 수 있습니다. Elasticsearch 인덱스의 불일치를 자동으로 찾아 재동기화할 수 없지만, 누락된 업데이트에 대해 로그를 검사할 수 있습니다. 데이터를 더 빠르게 복구하려면 다음을 재실행할 수 있습니다.

track_items를 검색하여 elasticsearch.log에서 동기화된 모든 비리포지터리 업데이트. 이 항목들을 ::Elastic::ProcessBookkeepingService.track!을 통해 다시 전송해야 합니다.
indexing_commit_range를 검색하여 elasticsearch.log에서 모든 리포지터리 업데이트. 로그에서 가장 오래된 from_sha로 IndexStatus#last_commit/last_wiki_commit를 설정한 후 Search::Elastic::CommitIndexerWorker와 ElasticWikiIndexerWorker로 프로젝트를 다시 인덱싱해야 합니다.
ElasticDeleteProjectWorker를 검색하여 sidekiq.log에서 모든 프로젝트 삭제. ElasticDeleteProjectWorker를 다시 실행해야 합니다.

처음부터 모든 것을 재인덱싱하지 않고도 데이터 손실에서 복구하는 시간을 줄이기 위해 정기적인 Elasticsearch 스냅샷을 찍을 수도 있습니다.

Elasticsearch 고급 검색

GitLab v19.2

원문 보기

번역일: 2026-05-22

요약

  - 
  Tier: Premium, Ultimate

- Offering: GitLab Self-Managed, GitLab Dedicated

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

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

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

고급 검색은 모든 프로젝트를 동일한 Elasticsearch 인덱스에 저장합니다. 단, 비공개 프로젝트는 접근 권한이 있는 사용자에게만 검색 결과에 표시됩니다.

Elasticsearch 용어 설명#

이 용어 설명은 Elasticsearch 관련 용어의 정의를 제공합니다.

Lucene: Java로 작성된 전체 텍스트 검색 라이브러리입니다.
근실시간(NRT, Near Real Time): 문서를 인덱싱한 시점부터 검색 가능해지기까지의 약간의 지연을 의미합니다.
클러스터(Cluster): 모든 데이터를 보유하고 인덱싱 및 검색 기능을 제공하기 위해 함께 작동하는 하나 이상의 노드 모음입니다.
노드(Node): 클러스터의 일부로 작동하는 단일 서버입니다.
인덱스(Index): 유사한 특성을 가진 문서들의 모음입니다.
문서(Document): 인덱싱할 수 있는 기본 정보 단위입니다.
샤드(Shards): 인덱스의 완전히 기능하는 독립적인 하위 분할입니다. 각 샤드는 실제로 Lucene 인덱스입니다.
레플리카(Replicas): 인덱스를 복제하는 장애 조치 메커니즘입니다.

Elasticsearch 또는 AWS OpenSearch 클러스터 설치#

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

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

새 Elasticsearch 클러스터를 운영 환경에서 사용하기 전에

중요한 Elasticsearch 구성을 참고하세요.

버전 호환성#

Elasticsearch#

History

Support for Elasticsearch 6.8 removed in GitLab 15.0.

Elasticsearch 7.x 지원은 GitLab 18.10에서 지원 중단되었으며 19.1에서 제거될 예정입니다.

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

GitLab 버전	Elasticsearch 버전
18.1 and later	7.x and later
15.0 to 18.0	7.x and 8.x
14.0 to 14.10	6.8 to 7.x

GitLab.com은 Elasticsearch 8.x를 사용합니다. GitLab Self-Managed에서는 최적의 성능과 향후 호환성을 위해 Elasticsearch 9.x를 사용해야 합니다.

고급 검색은 Elasticsearch 지원 종료 정책을 따릅니다.

OpenSearch#

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

GitLab 버전	OpenSearch 버전
18.1 and later	1.x and later
17.6.3 to 18.0	1.x and 2.x
15.5.3 to 17.6.2	1.x, 2.0 to 2.17
15.0 to 15.5.2	1.x

고급 검색은 OpenSearch 유지관리 정책을 따릅니다.

시스템 요구 사항#

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

접근 요구 사항#

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

Elasticsearch 역할 기반 접근 제어#

자세한 내용은 Elasticsearch 역할 기반 접근 제어와 Elasticsearch 보안 권한을 참고하세요.

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

AWS OpenSearch Service 접근 제어#

사전 요구 사항:

OpenSearch 도메인을 생성할 때 AWS 계정에 AWSServiceRoleForAmazonOpenSearchService라는 이름의 서비스 연결 역할이 있어야 합니다.
AWS OpenSearch의 도메인 접근 정책에서 es:ESHttp* 액션을 허용해야 합니다.

AWS OpenSearch Service에는 세 가지 주요 보안 계층이 있습니다.

네트워크#

자세한 내용은 AWS 설명서를 참고하세요.

도메인 접근 정책#

GitLab은 AWS OpenSearch에 대한 다음 도메인 접근 제어 방법을 지원합니다.

리소스 기반(도메인) 접근 정책: 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/*"
    }
  ]
}

다음은 특정 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/*"
    }
  ]
}

계정 간에 [AWS `AssumeRole`](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)을 사용하는 경우 `aws_role_arn`을 제공해야 합니다. ARN은 OpenSearch에 접근할 수 있는 권한이 있는 역할이어야 합니다.

자격 증명 기반 정책 예시 다음은 es:ESHttp* 액션이 허용된 IAM 주체에 연결된 자격 증명 기반 접근 정책의 예시입니다.

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

세분화된 접근 제어#

세분화된 접근 제어를 활성화하면 다음 방법 중 하나로 마스터 사용자를 설정해야 합니다.

사전 요구 사항:

관리자 접근 권한.

IAM ARN을 마스터 사용자로 설정하려면 GitLab 인스턴스에서 IAM 자격 증명과 함께 AWS OpenSearch Service를 사용해야 합니다.

오른쪽 상단 모서리에서 Admin을 선택합니다.

왼쪽 사이드바에서 Settings > Search를 선택합니다.

Advanced search를 펼칩니다.

AWS OpenSearch IAM credentials 섹션에서:

Use AWS OpenSearch Service with IAM credentials 체크박스를 선택합니다.

AWS region에 OpenSearch 도메인이 위치한 AWS 리전을 입력합니다(예: us-east-1).

AWS access key와 AWS secret access key에 인증을 위한 액세스 키를 입력합니다.

컨테이너가 아닌 EC2 인스턴스에서 직접 실행되는 GitLab 배포는

액세스 키를 입력할 필요가 없습니다. GitLab 인스턴스는 AWS Instance Metadata Service (IMDS)에서 자동으로 이 키를 가져옵니다.

Save changes를 선택합니다.

사전 요구 사항:

관리자 접근 권한.

마스터 사용자를 생성하려면 GitLab 인스턴스에서 OpenSearch 도메인 URL과 마스터 사용자 이름 및 비밀번호를 구성해야 합니다.

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Advanced search를 펼칩니다.
OpenSearch domain URL에 OpenSearch 도메인 엔드포인트 URL을 입력합니다.
Username에 마스터 사용자 이름을 입력합니다.
Password에 마스터 비밀번호를 입력합니다.
Save changes를 선택합니다.

새 Elasticsearch 버전으로 업그레이드#

History

Support for Elasticsearch 6.8 removed in GitLab 15.0.

사전 요구 사항:

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

클러스터 연결, 인덱스 및 검색 작업을 확인합니다.

sudo gitlab-rake gitlab:elastic:index_and_search_validation

인덱싱 재개.

고급 검색으로 검색 활성화.

Elasticsearch 리포지터리 인덱서#

인덱서 설치#

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

의존성 설치#

Debian / Ubuntu#

Debian 또는 Ubuntu에 설치하려면 다음을 실행합니다.

sudo apt install libicu-dev

CentOS / RHEL#

CentOS 또는 RHEL에 설치하려면 다음을 실행합니다.

sudo yum install libicu-devel

macOS#

먼저 [Homebrew를 설치](https://brew.sh/)해야 합니다.

macOS에 설치하려면 다음을 실행합니다.

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

빌드 및 설치#

인덱서를 빌드하고 설치하려면 다음을 실행합니다.

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

# Run the installation task for 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`로 설정해야 할 수 있습니다.

인덱싱 오류 확인#

고급 검색 활성화#

사전 요구 사항:

인스턴스에 대한 관리자 접근 권한이 있어야 합니다.
인덱스당 샤드 수를 구성합니다.
인덱스당 레플리카 수를 구성합니다.
선택 사항. 대규모 인스턴스 인덱싱을 준비합니다.

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

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Elasticsearch 클러스터에 대한 고급 검색 설정을 구성합니다. 아직 Search with advanced search 체크박스를 선택하지 마세요.
인스턴스를 인덱싱합니다.
선택 사항. 인덱싱 상태를 확인합니다.
인덱싱이 완료되면 Search with advanced search 체크박스를 선택한 후 Save changes를 선택합니다.

Elasticsearch가 활성화된 상태에서 Elasticsearch 클러스터가 다운되면, 인스턴스가 변경 사항을 인덱싱하는 작업을 큐에 추가하지만 유효한 Elasticsearch 클러스터를 찾을 수 없어 이슈와 같은 문서를 업데이트하는 데 문제가 생길 수 있습니다.

리포지터리 데이터가 50GB를 초과하는 GitLab 인스턴스의 경우 대규모 인스턴스를 효율적으로 인덱싱을 참고하세요.

인스턴스 인덱싱#

사용자 인터페이스에서#

History

Introduced in GitLab 17.3.

사전 요구 사항:

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

사용자 인터페이스에서 초기 인덱싱을 수행하거나 인덱스를 다시 생성할 수 있습니다.

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

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Turn on indexing for advanced search 체크박스를 선택한 후 Save changes를 선택합니다.
Index the instance를 선택합니다.

Rake 작업으로#

사전 요구 사항:

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

전체 인스턴스를 인덱싱하려면 다음 Rake 작업을 사용합니다.

# WARNING: This task deletes all existing indices
# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:index

# WARNING: This task deletes all existing indices
# For self-compiled installations
bundle exec rake gitlab:elastic:index RAILS_ENV=production

특정 데이터를 인덱싱하려면 다음 Rake 작업을 사용합니다.

# For installations that use the Linux package
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

# For self-compiled installations
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

인덱싱 상태 확인#

사전 요구 사항:

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

인덱싱 상태를 확인하려면:

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Advanced search indexing status를 펼칩니다.

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

사전 요구 사항:

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

인덱싱 진행 상황을 모니터링하려면 백그라운드 작업 상태를 확인할 수도 있습니다.

오른쪽 상단 모서리에서 Admin을 선택합니다.
Monitoring > Background jobs를 선택합니다.
Sidekiq 대시보드에서 Busy를 선택하고 다음 인덱싱 작업을 확인합니다.

코드 및 커밋의 경우 Search::Elastic::CommitIndexerWorker.

위키 데이터의 경우 ElasticWikiIndexerWorker.

고급 검색으로 검색 활성화#

사전 요구 사항:

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

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

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Search with advanced search 체크박스를 선택합니다.
Save changes를 선택합니다.

고급 검색으로 코드 검색 활성화#

사전 요구 사항:

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

GitLab에서 고급 검색으로 코드 검색을 활성화하려면:

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Code search with advanced search 체크박스를 선택합니다.
Save changes를 선택합니다.

고급 검색 구성#

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

Parameter	Description
Turn on indexing for advanced search	Turns on or turns off indexing and creates an empty index if one does not already exist. You may want to turn on indexing but turn off search to give the index time to be fully completed, for example. Also, keep in mind that this option doesn’t have any impact on existing data, this only enables/disables the background indexer which tracks data changes and ensures new data is indexed.
Pause indexing for advanced search	Pauses advanced search indexing. This is useful for cluster migration/reindexing. All changes are still tracked, but they are not committed to the index until resumed.
Search with advanced search	Turns on or turns off the advanced search capabilities in search and advanced vulnerability management.
Code search with advanced search	Turns on or turns off code search with advanced search. When this setting is turned off, all code is deleted from your Elasticsearch instance. To turn this setting back on, fully reindex your code. If exact code search is enabled, you should turn off this setting to save resources.
Requeue indexing workers	Turns on automatic requeuing of indexing workers. This improves non-code indexing throughput by enqueuing Sidekiq jobs until all documents are processed. Requeuing indexing workers is not recommended for smaller instances or instances with few Sidekiq processes.
URL	The URL of your Elasticsearch instance. Use a comma-separated list to support clustering (for example, http://host1, https://host2:9200). If your Elasticsearch instance is password-protected, use the Username and Password fields. Alternatively, use inline credentials such as http://:@<elastic_host>:9200/. If you use OpenSearch, only connections over ports 80 and 443 are accepted.
Username	The username of your Elasticsearch instance.
Password	The password of your Elasticsearch instance.
Number of Elasticsearch shards and replicas per index	Elasticsearch indices are split into multiple shards for performance reasons. In general, you should use at least five shards. Indices with tens of millions of documents should have more shards (see the guidance). Changes to this value do not take effect until you re-create the index. For more information about scalability and resilience, see the Elasticsearch documentation. Each Elasticsearch shard can have a number of replicas. These replicas are a complete copy of the shard and can provide increased query performance or resilience against hardware failure. Increasing this value increases the total disk space required by the index. You can set the number of shards and replicas for each of the indices.
Limit the amount of namespace and project data to index	When you enable this setting, you can specify namespaces and projects to index. All other namespaces and projects use database search instead. If you enable this setting but do not specify any namespace or project, only project records are indexed. For more information, see Limit the amount of namespace and project data to index.
Use AWS OpenSearch Service with IAM credentials	Sign your OpenSearch requests using AWS IAM authorization, AWS EC2 Instance Profile Credentials, or AWS ECS Tasks Credentials. Refer to Identity and Access Management in Amazon OpenSearch Service for details of AWS hosted OpenSearch domain access policy configuration.
AWS Region	The AWS region in which your OpenSearch Service is located.
AWS Access Key	The AWS access key.
AWS Secret Access Key	The AWS secret access key.
Maximum file size indexed	See the explanation in instance limits..
Maximum field length	See the explanation in instance limits..
Indexing timeout (minutes)	Indexing timeout in minutes per project.
Number of shards for non-code indexing	Number of indexing worker shards. This improves non-code indexing throughput by enqueuing more parallel Sidekiq jobs. Increasing the number of shards is not recommended for smaller instances or instances with few Sidekiq processes. Default is 2.
Maximum bulk request size (MiB)	Used by the GitLab Ruby and Go-based indexer processes. This setting indicates how much data must be collected (and stored in memory) in a given indexing process before submitting the payload to the Elasticsearch Bulk API. For the GitLab Go-based indexer, you should use this setting with Bulk request concurrency. Maximum bulk request size (MiB) must accommodate the resource constraints of both the Elasticsearch hosts and the hosts running the GitLab Go-based indexer from either the gitlab-rake command or the Sidekiq tasks.
Bulk request concurrency	The Bulk request concurrency indicates how many of the GitLab Go-based indexer processes (or threads) can run in parallel to collect data to subsequently submit to the Elasticsearch Bulk API. This increases indexing performance, but fills the Elasticsearch bulk requests queue faster. This setting should be used together with the Maximum bulk request size (MiB) setting and needs to accommodate the resource constraints of both the Elasticsearch hosts and the hosts running the GitLab Go-based indexer either from the gitlab-rake command or the Sidekiq tasks.
Client request timeout	Elasticsearch HTTP client request timeout value in seconds. 0 means using the system default timeout value, which depends on the libraries that GitLab application is built upon.
Code indexing concurrency	Maximum number of Elasticsearch code indexing background jobs allowed to run concurrently. This only applies to repository indexing operations.
Retry on failure	Maximum number of possible retries for Elasticsearch search requests. Introduced in GitLab 17.6.
Index prefix	Custom prefix for Elasticsearch index names. Defaults to gitlab. When changed, all indices will use this prefix instead of gitlab (for example, custom-production-issues instead of gitlab-production-issues). Must be 1-100 characters, contain only lowercase alphanumeric characters, hyphens, and underscores, and cannot start or end with a hyphen or underscore. Introduced in GitLab 18.2.

**Maximum bulk request size (MiB)**와 **Bulk request concurrency** 값을 높이면 Sidekiq 성능에 부정적인 영향을 줄 수 있습니다. Sidekiq 로그에서 `scheduling_latency_s` 지속 시간이 증가하는 경우 기본값으로 되돌리세요. 자세한 내용은 [이슈 322147](https://gitlab.com/gitlab-org/gitlab/-/issues/322147)을 참고하세요.

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

History

Indexing all project records introduced in GitLab 16.7 with a flag named search_index_all_projects. Disabled by default.
Generally available in GitLab 16.11. Feature flag search_index_all_projects removed.
Indexing vulnerability records introduced on GitLab.com and GitLab Dedicated in GitLab 18.1 with a flag named vulnerability_es_ingestion. Disabled by default.
Indexing vulnerability records is generally available on GitLab.com and GitLab Dedicated in GitLab 18.2. Feature flag vulnerability_es_ingestion removed.

이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 변경 이력을 참고하세요.

Limit the amount of namespace and project data to index 체크박스를 선택하면, 인덱싱할 네임스페이스와 프로젝트를 지정할 수 있습니다. 네임스페이스가 그룹인 경우 해당 그룹의 서브그룹과 프로젝트도 인덱싱됩니다.

이 설정을 활성화하면:

전체 인덱싱을 위해 네임스페이스 또는 프로젝트를 지정해야 합니다.
프로젝트 레코드(프로젝트 이름 및 설명과 같은 메타데이터)는 모든 프로젝트에 대해 항상 인덱싱됩니다.
보안 보고서의 필터링 지원을 위해 취약성 레코드는 모든 프로젝트 및 네임스페이스에 대해 항상 인덱싱됩니다.
연관 데이터는 지정한 네임스페이스 및 프로젝트에 대해서만 인덱싱됩니다.

이 설정을 활성화한 후 네임스페이스 또는 프로젝트를 지정하지 않으면, 프로젝트 레코드만 인덱싱되고 연관 데이터는 검색할 수 없습니다.

인덱싱된 네임스페이스#

History

Global search for limited indexing introduced in GitLab 13.4 with a flag named advanced_global_search_for_limited_indexing. Disabled by default.
Enabled on GitLab.com in GitLab 14.2.
Global search for limited indexing generally available in GitLab 17.11 as a UI option, instead of the advanced_global_search_for_limited_indexing flag.

모든 네임스페이스를 인덱싱하면 전역 코드 및 커밋 검색에 고급 검색을 사용할 수 있습니다. 일부 네임스페이스만 인덱싱하는 경우:

전역 검색에는 코드 또는 커밋 검색 범위가 포함되지 않습니다.
코드 및 커밋 검색은 단일 인덱싱된 네임스페이스에서만 사용 가능합니다.
여러 인덱싱된 네임스페이스에 걸친 단일 코드 또는 커밋 검색은 불가능합니다.
인덱싱된 네임스페이스에서는 크로스 프로젝트 검색을 사용할 수 있습니다.

예를 들어, 두 개의 별도 그룹을 인덱싱하는 경우 각 그룹에서 별도로 코드 검색을 실행해야 합니다.

제한된 인덱싱에 대한 전역 검색을 활성화하려면:

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Advanced search를 펼칩니다.
Enable global search for limited indexing를 선택합니다.
Save changes를 선택합니다.
인스턴스를 이미 인덱싱한 경우 인스턴스를 다시 인덱싱해야 합니다. 이렇게 하면 기존 검색 데이터가 삭제되어 필터링이 올바르게 작동하도록 합니다.

커스텀 언어 분석기 활성화#

사전 요구 사항:

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

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

커스텀 언어 분석기를 활성화하려면:

원하는 플러그인을 설치합니다. 플러그인 설치 지침은 Elasticsearch 설명서를 참고하세요. 플러그인은 클러스터의 모든 노드에 설치해야 하며 설치 후 각 노드를 재시작해야 합니다. 플러그인 목록은 이 섹션의 테이블을 참고하세요.
오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Custom analyzers: language support를 찾습니다.
Indexing에 대한 플러그인 지원을 활성화합니다.
변경 사항이 적용되도록 Save changes를 선택합니다.
무중단 재인덱싱을 실행하거나 처음부터 모두 재인덱싱하여 업데이트된 매핑으로 새 인덱스를 생성합니다.
이전 단계가 완료된 후 Searching에 대한 플러그인 지원을 활성화합니다.

설치할 항목에 대한 안내는 다음 Elasticsearch 언어 플러그인 옵션을 참고하세요.

Parameter	Description
Enable Chinese (smartcn) custom analyzer: Indexing	Enables or disables Chinese language support using smartcn custom analyzer for newly created indices.
Enable Chinese (smartcn) custom analyzer: Search	Enables or disables using smartcn fields for advanced search. Only enable this after installing the plugin, enabling custom analyzer indexing and recreating the index.
Enable Japanese (kuromoji) custom analyzer: Indexing	Enables or disables Japanese language support using kuromoji custom analyzer for newly created indices.
Enable Japanese (kuromoji) custom analyzer: Search	Enables or disables using kuromoji fields for advanced search. Only enable this after installing the plugin, enabling custom analyzer indexing and recreating the index.

고급 검색 비활성화#

사전 요구 사항:

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

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

오른쪽 상단 모서리에서 Admin을 선택합니다.

왼쪽 사이드바에서 Settings > Search를 선택합니다.

Turn on indexing for advanced search 및 Search with advanced search 체크박스를 해제합니다.

Save changes를 선택합니다.

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

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:delete_index

# For self-compiled installations
bundle exec rake gitlab:elastic:delete_index RAILS_ENV=production

고급 검색으로 검색 비활성화#

사전 요구 사항:

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

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

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Search with advanced search 체크박스를 해제합니다.
Save changes를 선택합니다.

고급 검색으로 코드 검색 비활성화#

사전 요구 사항:

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

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

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Code search with advanced search 체크박스를 해제합니다.
Save changes를 선택합니다.

인덱싱 일시 중지#

사전 요구 사항:

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

인덱싱을 일시 중지하려면:

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Advanced search를 펼칩니다.
Pause indexing for advanced search 체크박스를 선택합니다.
Save changes를 선택합니다.

인덱싱 재개#

사전 요구 사항:

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

인덱싱을 재개하려면:

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Advanced search를 펼칩니다.
Pause indexing for advanced search 체크박스를 해제합니다.
Save changes를 선택합니다.

무중단 재인덱싱#

무중단 재인덱싱 사용#

재인덱싱 실행#

사전 요구 사항:

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

재인덱싱을 실행하려면:

GitLab 인스턴스에 관리자로 로그인합니다.
오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Advanced search zero-downtime reindexing을 펼칩니다.
Trigger cluster reindexing을 선택합니다.

재인덱싱은 Elasticsearch 클러스터의 크기에 따라 오래 걸릴 수 있습니다.

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

무중단 재인덱싱 실행#

사전 요구 사항:

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

무중단 재인덱싱을 실행하려면:

오른쪽 상단 모서리에서 Admin을 선택합니다.

왼쪽 사이드바에서 Settings > Search를 선택합니다.

Advanced search zero-downtime reindexing을 펼칩니다. 다음 설정을 사용할 수 있습니다.

슬라이스 배수

최대 실행 슬라이스

슬라이스 배수#

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

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

최대 실행 슬라이스#

최대 실행 슬라이스 파라미터의 기본값은 60이며, Elasticsearch 재인덱싱 중 동시에 실행할 수 있는 최대 슬라이스 수에 해당합니다.

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

사전 요구 사항:

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

완료되지 않은 재인덱싱 작업을 포기하고 인덱싱을 재개하려면:

가장 최근 재인덱싱 작업을 실패로 표시합니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:mark_reindex_failed

# For self-compiled installations
bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production

오른쪽 상단 모서리에서 Admin을 선택합니다.

왼쪽 사이드바에서 Settings > Search를 선택합니다.

Advanced search를 펼칩니다.

Pause indexing for advanced search 체크박스를 해제합니다.

인덱스 무결성#

History

Introduced in GitLab 15.10 with a flag named search_index_integrity. Disabled by default.
Generally available in GitLab 16.4. Feature flag search_index_integrity removed.

고급 검색 마이그레이션#

재인덱스 마이그레이션은 백그라운드에서 실행되므로 인스턴스를 수동으로 재인덱싱할 필요가 없습니다.

마이그레이션 사전 파일#

History

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

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

오류 원인을 수정했다고 판단되면:

오른쪽 상단 모서리에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > Search를 선택합니다.
Advanced search를 펼칩니다.
Elasticsearch migration halted 경고 상자 내에서 Retry migration을 선택합니다. 마이그레이션이 백그라운드에서 재시도 예약됩니다.

메이저 업그레이드 전에 모든 마이그레이션을 완료해야 합니다#

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

GitLab 고급 검색 Rake 작업#

다음 용도로 Rake 작업을 사용할 수 있습니다.

인덱서를 빌드 및 설치합니다.
Elasticsearch를 비활성화할 때 인덱스를 삭제합니다.
GitLab 데이터를 인덱스에 추가합니다.

다음은 사용 가능한 Rake 작업들입니다.

Task	Description
sudo gitlab-rake gitlab:elastic:info	Outputs debugging information for the advanced search integration.
sudo gitlab-rake gitlab:elastic:index	In GitLab 17.0 and earlier, turns on indexing for advanced search and runs gitlab:elastic:recreate_index, gitlab:elastic:clear_index_status, gitlab:elastic:index_group_entities, gitlab:elastic:index_projects, gitlab:elastic:index_snippets, and gitlab:elastic:index_users.In GitLab 17.1 and later, queues a Sidekiq job in the background. First, the job turns on indexing for advanced search and pauses indexing to ensure all indices are created. Then, the job re-creates all indices, clears indexing status, and queues additional Sidekiq jobs to index project and group data, snippets, and users. Finally, indexing for advanced search is resumed to complete. Introduced in GitLab 17.1 with a flag named elastic_index_use_trigger_indexing. Enabled by default. Generally available in GitLab 17.3. Feature flag elastic_index_use_trigger_indexing removed.
sudo gitlab-rake gitlab:elastic:pause_indexing	Pauses indexing for advanced search. Changes are still tracked. Useful for cluster/index migrations.
sudo gitlab-rake gitlab:elastic:resume_indexing	Resumes indexing for advanced search.
sudo gitlab-rake gitlab:elastic:index_and_search_validation	Validates cluster connectivity, index, and search operations for all indices. Introduced in GitLab 18.3.
sudo gitlab-rake gitlab:elastic:index_projects	Iterates over all projects, and queues Sidekiq jobs to index them in the background. It can only be used after the index is created.
sudo gitlab-rake gitlab:elastic:index_group_entities	Invokes gitlab:elastic:index_work_items and gitlab:elastic:index_group_wikis.
sudo gitlab-rake gitlab:elastic:index_work_items	Indexes all work items from the groups where Elasticsearch is enabled.
sudo gitlab-rake gitlab:elastic:index_namespaces	Indexes all root namespaces.
sudo gitlab-rake gitlab:elastic:index_group_wikis	Indexes all wikis from the groups where Elasticsearch is enabled.
sudo gitlab-rake gitlab:elastic:index_snippets	Performs an Elasticsearch import that indexes the snippets data.
sudo gitlab-rake gitlab:elastic:index_users	Imports all users into Elasticsearch.
sudo gitlab-rake gitlab:elastic:index_vulnerabilities	Indexes all vulnerabilities.
sudo gitlab-rake gitlab:elastic:index_projects_status	Determines the overall indexing status of all project repository data (code, commits, and wikis). The status is calculated by dividing the number of indexed projects by the total number of projects and multiplying by 100. This task does not include non-repository data such as issues, merge requests, or milestones.
sudo gitlab-rake gitlab:elastic:index_groups_status	Determines the overall indexing status of all group repository data (group wikis). The status is calculated by dividing the number of indexed groups by the total number of groups and multiplying by 100. This task does not include non-repository data such as epics, merge requests, or milestones.
sudo gitlab-rake gitlab:elastic:clear_index_status	Deletes all instances of IndexStatus for all projects. This command results in a complete wipe of the index, and it should be used with caution.
sudo gitlab-rake gitlab:elastic:create_empty_index	Generates empty indices (the default index and a separate issues index) and assigns an alias for each on the Elasticsearch side only if it doesn’t already exist.
sudo gitlab-rake gitlab:elastic:delete_index	Removes the GitLab indices and aliases (if they exist) on the Elasticsearch instance.
sudo gitlab-rake gitlab:elastic:recreate_index	Wrapper task for gitlab:elastic:delete_index and gitlab:elastic:create_empty_index. Does not queue any indexing jobs.
sudo gitlab-rake gitlab:elastic:projects_not_indexed	Displays which projects do not have repository data indexed. This task does not include non-repository data such as issues, merge requests, or milestones.
sudo gitlab-rake gitlab:elastic:groups_not_indexed	Displays which groups do not have repository data indexed. This task does not include non-repository data such as issues, merge requests, or milestones.
sudo gitlab-rake gitlab:elastic:reindex_cluster	Schedules a zero-downtime cluster reindexing task.
sudo gitlab-rake gitlab:elastic:mark_reindex_failed	Mark the most recent reindex job as failed.
sudo gitlab-rake gitlab:elastic:list_pending_migrations	List pending migrations. Pending migrations include those that have not yet started, have started but not finished, and those that are halted.
sudo gitlab-rake gitlab:elastic:estimate_cluster_size	Get an estimate of code and wiki index sizes and total cluster size based on the total repository size.
sudo gitlab-rake gitlab:elastic:estimate_shard_sizes	Get an estimate of shard sizes for each index based on approximate database counts. This estimate does not include repository data (code, commits, and wikis). Introduced in GitLab 16.11.
sudo gitlab-rake gitlab:elastic:enable_search_with_elasticsearch	Enables advanced search with Elasticsearch.
sudo gitlab-rake gitlab:elastic:disable_search_with_elasticsearch	Disables advanced search with Elasticsearch.

환경 변수#

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

Environment Variable	Data Type	What it does
ID_TO	Integer	Tells the indexer to only index projects less than or equal to the value.
ID_FROM	Integer	Tells the indexer to only index projects greater than or equal to the value.

프로젝트 범위 또는 특정 프로젝트 인덱싱#

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
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 인덱스는 다음 범위를 사용합니다.

Scope Name	What it searches
commits	Commit data
projects	Project data (default)
blobs	Code
work_items	Work item data
merge_requests	Merge request data
milestones	Milestone data
notes	Note data
snippets	Snippet data
wiki_blobs	Wiki contents
users	Users

튜닝#

최적 클러스터 구성 선택 안내#

클러스터 구성 선택에 대한 기본 안내는 Elastic Cloud Calculator도 참고하세요.

일반적으로 레플리카 1개와 함께 최소 2노드 클러스터 구성을 사용하여 탄력성을 확보하는 것이 좋습니다. 스토리지 사용량이 빠르게 증가하고 있다면, 수평 확장(노드 추가)을 미리 계획하는 것이 좋습니다.
검색 클러스터에 HDD 스토리지를 사용하는 것은 성능에 영향을 주므로 권장하지 않습니다. SSD 스토리지(예: NVMe 또는 SATA SSD 드라이브)를 사용하는 것이 좋습니다.
대규모 인스턴스에서는 코디네이팅 전용 노드를 사용하지 않는 것이 좋습니다. 코디네이팅 전용 노드는 데이터 노드보다 작아, 성능과 고급 검색 마이그레이션에 영향을 줄 수 있습니다.
GitLab Performance Tool을 사용하여 다양한 검색 클러스터 크기 및 구성으로 검색 성능을 벤치마크할 수 있습니다.
Heap size는 물리적 RAM의 50% 이하로 설정해야 합니다. 또한 제로 기반 압축 oops(zero-based compressed oops)의 임계값을 초과하지 않아야 합니다. 정확한 임계값은 다르지만, 대부분의 시스템에서는 26GB가 안전하며 일부 시스템에서는 30GB까지 가능합니다. 자세한 내용은 Heap size settings와 Setting JVM options을 참고하세요.
refresh_interval은 인덱스별 설정입니다. 실시간 데이터가 필요하지 않은 경우 기본값 1s에서 더 큰 값으로 조정할 수 있습니다. 이 설정은 새로운 결과를 얼마나 빨리 볼 수 있는지에 영향을 줍니다. 실시간성이 중요하다면 기본값에 최대한 가깝게 유지하는 것이 좋습니다.
많은 무거운 인덱싱 작업이 있는 경우 indices.memory.index_buffer_size를 30% 또는 40%로 높이는 것이 좋습니다.

고급 검색 설정#

Elasticsearch 샤드 수#

History

gitlab:elastic:estimate_shard_sizes introduced in GitLab 16.11.
gitlab:elastic:estimate_shard_sizes changed in GitLab 18.3 to include sizing for indices that contain repository data.

단일 노드 클러스터의 경우, 인덱스당 Elasticsearch 샤드 수를 Elasticsearch 데이터 노드의 CPU 코어 수로 설정합니다.

인덱스의 샤드 수를 업데이트하려면 설정을 변경하고 무중단 재인덱싱을 실행합니다.

Elasticsearch 레플리카 수#

단일 노드 클러스터의 경우, 인덱스당 Elasticsearch 레플리카 수를 0으로 설정합니다.

(1 + `number_of_replicas`) / `number_of_awareness_attributes` = whole number

인덱스의 레플리카 수를 업데이트하려면 설정을 변경하고 무중단 재인덱싱을 실행합니다.

대규모 인스턴스를 효율적으로 인덱싱#

사전 요구 사항:

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

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

Geo 기본 노드와 보조 노드 모두 동일한 Elasticsearch 클러스터를 가리킵니다. 단, Elasticsearch 인덱싱 워커는 기본 사이트의 Sidekiq 노드에서만 실행됩니다.

이러한 이유로, 추가 Sidekiq 프로세스를 기본 사이트의 Sidekiq 노드에서 구성해야 합니다.

대용량 데이터 인덱싱으로 인해 고급 검색 활성화에 문제가 발생하는 경우:

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

빈 인덱스를 생성합니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:create_empty_index

# For self-compiled installations
bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production

GitLab 인스턴스를 재인덱싱하는 경우 인덱스 상태를 초기화합니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:clear_index_status

# For self-compiled installations
bundle exec rake gitlab:elastic:clear_index_status RAILS_ENV=production

Turn on indexing for advanced search 체크박스를 선택합니다.

대규모 Git 리포지터리 인덱싱은 시간이 걸릴 수 있습니다. 프로세스를 빠르게 하려면 인덱싱 속도를 위한 튜닝을 참고하세요.

refresh_interval을 일시적으로 늘릴 수 있습니다.

인덱싱 시간이 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
       } }'

프로젝트와 관련 데이터를 인덱싱합니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:index_projects

# For self-compiled installations
bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production

이렇게 하면 인덱싱이 필요한 각 프로젝트에 대해 Sidekiq 작업이 큐에 추가됩니다. Rake 작업으로 인덱싱 상태를 조회할 수 있습니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:index_projects_status

# For self-compiled installations
bundle exec rake gitlab:elastic:index_projects_status RAILS_ENV=production

Indexing is 65.55% complete (6555/10000 projects). Considers only code, commits, and wikis.

인덱스를 프로젝트 범위로 제한하려면 ID_FROM 및 ID_TO 파라미터를 사용할 수 있습니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000

# For self-compiled installations
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`에 의해 큐에 추가된 프로젝트 인덱싱 작업이 때로는 중단될 수 있습니다. 이는 여러 이유로 발생할 수 있지만, 인덱싱 작업을 다시 실행해도 항상 안전합니다.

작업 항목, 그룹 위키, 개인 스니펫, 사용자는 프로젝트와 연관되어 있지 않으므로 별도로 인덱싱해야 합니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:index_work_items
sudo gitlab-rake gitlab:elastic:index_group_wikis
sudo gitlab-rake gitlab:elastic:index_snippets
sudo gitlab-rake gitlab:elastic:index_users

# For self-compiled installations
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_snippets RAILS_ENV=production
bundle exec rake gitlab:elastic:index_users RAILS_ENV=production

인덱싱 후 복제 및 새로 고침을 다시 활성화합니다(이전에 refresh_interval을 증가시킨 경우에만).

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

새로 고침을 활성화한 후 강제 병합(force merge)을 호출해야 합니다.

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
       } }'

인덱싱이 완료되면 Search with advanced search 체크박스를 선택합니다.

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

대부분의 인스턴스에서는 전용 Sidekiq 노드나 프로세스를 구성할 필요가 없습니다.

이 목적을 위해 워커 매칭 쿼리를 기반으로 Sidekiq가 특정 큐로 작업을 라우팅하도록 하는 라우팅 규칙 옵션을 사용합니다.

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

다음 두 가지 옵션 중 하나를 선택할 수 있습니다.

다음 단계에서 sidekiq['routing_rules']의 항목을 고려합니다.

모든 인덱싱 작업이 global_search 큐로 라우팅되도록 ["feature_category=global_search", "global_search"].
다른 모든 비인덱싱 작업이 default 큐로 라우팅되도록 ["*", "default"].

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

여러 프로세스를 시작할 때, 프로세스 수는 Sidekiq에 할당하려는 CPU 코어 수를 초과할 수 없습니다. 각 Sidekiq 프로세스는 사용 가능한 워크로드 및 동시성 설정에 따라 하나의 CPU 코어만 사용할 수 있습니다. 자세한 내용은 [여러 Sidekiq 프로세스 실행](/19.0/administration/sidekiq/extra_sidekiq_processes/) 방법을 참고하세요.

단일 노드, 두 개의 프로세스#

하나의 노드에서 인덱싱 및 비인덱싱 Sidekiq 프로세스를 모두 생성하려면:

Sidekiq 노드에서 /etc/gitlab/gitlab.rb 파일을 다음과 같이 변경합니다.

sidekiq['enable'] = true

sidekiq['routing_rules'] = [
   ["feature_category=global_search", "global_search"],
   ["*", "default"],
]

sidekiq['queue_groups'] = [
   "global_search", # process that listens to global_search queue
   "default,mailers" # process that listens to default and mailers queue
]

sidekiq['concurrency'] = 20

GitLab 16.11 이하를 사용 중인 경우 모든 큐 선택기를 명시적으로 비활성화합니다.

sidekiq['queue_selector'] = false

파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성합니다.

다른 모든 Rails 및 Sidekiq 노드에서 sidekiq['routing_rules']가 이전 구성과 동일한지 확인합니다.

기존 작업을 마이그레이션하는 Rake 작업을 실행합니다.

GitLab을 재구성한 직후 Rake 작업을 실행하는 것이 중요합니다.

GitLab을 재구성한 후 Rake 작업이 작업 마이그레이션을 시작할 때까지 기존 작업은 처리되지 않습니다.

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

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

인덱싱 Sidekiq 프로세스를 설정하려면, 인덱싱 Sidekiq 노드에서 /etc/gitlab/gitlab.rb 파일을 다음과 같이 변경합니다.

sidekiq['enable'] = true

sidekiq['routing_rules'] = [
   ["feature_category=global_search", "global_search"],
   ["*", "default"],
]

sidekiq['queue_groups'] = [
  "global_search", # process that listens to global_search queue
]

sidekiq['concurrency'] = 20

GitLab 16.11 이하를 사용 중인 경우 모든 큐 선택기를 명시적으로 비활성화합니다.

sidekiq['queue_selector'] = false

파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성합니다.

비인덱싱 Sidekiq 프로세스를 설정하려면, 비인덱싱 Sidekiq 노드에서 /etc/gitlab/gitlab.rb 파일을 다음과 같이 변경합니다.

sidekiq['enable'] = true

sidekiq['routing_rules'] = [
   ["feature_category=global_search", "global_search"],
   ["*", "default"],
]

sidekiq['queue_groups'] = [
   "default,mailers" # process that listens to default and mailers queue
]

sidekiq['concurrency'] = 20

GitLab 16.11 이하를 사용 중인 경우 모든 큐 선택기를 명시적으로 비활성화합니다.

sidekiq['queue_selector'] = false

다른 모든 Rails 및 Sidekiq 노드에서 sidekiq['routing_rules']가 이전 구성과 동일한지 확인합니다.

파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성합니다.

기존 작업을 마이그레이션하는 Rake 작업을 실행합니다.

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

GitLab을 재구성한 직후 Rake 작업을 실행하는 것이 중요합니다.

GitLab을 재구성한 후 Rake 작업이 작업 마이그레이션을 시작할 때까지 기존 작업은 처리되지 않습니다.

삭제된 문서#

단, 일부 대규모 설치에서는 병합 정책 설정을 조정할 수 있습니다.

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

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

기본 검색으로 되돌리기#

재해 복구#

track_items를 검색하여 elasticsearch.log에서 동기화된 모든 비리포지터리 업데이트. 이 항목들을 ::Elastic::ProcessBookkeepingService.track!을 통해 다시 전송해야 합니다.
indexing_commit_range를 검색하여 elasticsearch.log에서 모든 리포지터리 업데이트. 로그에서 가장 오래된 from_sha로 IndexStatus#last_commit/last_wiki_commit를 설정한 후 Search::Elastic::CommitIndexerWorker와 ElasticWikiIndexerWorker로 프로젝트를 다시 인덱싱해야 합니다.
ElasticDeleteProjectWorker를 검색하여 sidekiq.log에서 모든 프로젝트 삭제. ElasticDeleteProjectWorker를 다시 실행해야 합니다.

처음부터 모든 것을 재인덱싱하지 않고도 데이터 손실에서 복구하는 시간을 줄이기 위해 정기적인 Elasticsearch 스냅샷을 찍을 수도 있습니다.