AWS OpenSearch 서버 설정

AWS OpenSearch Service는 게시물 데이터의 인덱스를 생성·관리하여 대용량 데이터를 거의 실시간으로 빠르게 검색할 수 있게 해 줍니다. OpenSearch 서버를 설정하고 연결한 뒤에는 시스템 콘솔에서 인덱싱 과정을 관리할 수 있습니다. 게시물 인덱스는 OpenSearch 서버에 저장되며 새 게시물이 작성될 때마다 지속적으로 갱신됩니다. 기존 게시물을 인덱싱하려면 전체 게시물 데이터베이스에 대한 대량 인덱스를 생성해야 합니다.

AWS OpenSearch 배포는 AWS OpenSearch 설정과 Mattermost 구성의 두 단계로 이루어집니다.

AWS OpenSearch 설정

Mattermost v9.11부터 AWS OpenSearch v1.x 및 v2.x에 대한 베타 지원이 제공됩니다. 이 문서는 수동 설정 단계와 Terraform 예시를 포함해 온프레미스와 AWS OpenSearch 설정을 모두 다룹니다.

AWS OpenSearch 서버는 Mattermost 서버와 별도의 머신에 설정할 것을 강력히 권장합니다.

On-Premises OpenSearch

1. 온프레미스 OpenSearch를 설치하려면 전용 서버를 준비합니다(예: Ubuntu 22.04 LTS).

2. Java를 설치합니다(OpenSearch에는 Java 11 이상이 필요합니다).

   sudo apt update
   sudo apt install -y openjdk-11-jdk
   java -version
   

3. OpenSearch 2.x를 다운로드해 압축을 풉니다.

   wget https://artifacts.opensearch.org/releases/bundle/opensearch/2.9.0/opensearch-2.9.0-linux-x64.tar.gz
   tar -xzf opensearch-2.9.0-linux-x64.tar.gz
   sudo mv opensearch-2.9.0 /usr/share/opensearch
   

4. 전용 사용자를 만들고 권한을 설정합니다.

   sudo useradd --no-create-home --shell /bin/false opensearch
   sudo chown -R opensearch:opensearch /usr/share/opensearch
   

5. systemd를 구성합니다.

   [Unit]
     Description=OpenSearch
     Wants=network-online.target
     After=network-online.target
   
   [Service]
     Type=notify
     User=opensearch
     Group=opensearch
     ExecStart=/usr/share/opensearch/bin/opensearch
     Restart=on-failure
     LimitNOFILE=65536
     LimitNPROC=4096
   
   [Install]
     WantedBy=multi-user.target
   

6. opensearch.yml을 편집해 다음 내용을 포함시킵니다.

   cluster.name: mattermost-cluster
   node.name: node-1
   path.data: /var/lib/opensearch
   path.logs: /var/log/opensearch
   network.host: 0.0.0.0
   discovery.seed_hosts: ["<other-node-ip>"]
   cluster.initial_master_nodes: ["node-1", "node-2"]
   

   참고

   서비스를 시작하기 전에 path.data와 path.logs 디렉터리가 존재하고 opensearch 사용자 소유인지 확인하세요.

   sudo mkdir -p /var/lib/opensearch /var/log/opensearch
   sudo chown -R opensearch:opensearch /var/lib/opensearch /var/log/opensearch
   

7. OpenSearch를 활성화하고 시작합니다.

   sudo systemctl daemon-reload
   sudo systemctl enable opensearch
   sudo systemctl start opensearch
   sudo systemctl status opensearch
   

8. 다음 명령을 실행해 icu-analyzer 플러그인을 /usr/share/opensearch/plugins 디렉터리에 설치합니다.

   중요

   analysis-icu 플러그인은 선택 사항이 아니라 클러스터의 모든 노드에 필수입니다. Mattermost의 게시물·파일 인덱스 템플릿이 이 플러그인에 의존합니다. 플러그인이 없으면 Mattermost는 이 템플릿을 생성할 수 없습니다.

   sudo /usr/share/opensearch/bin/opensearch-plugin install analysis-icu
   

   새로 설치한 플러그인을 로드하려면 확인에 앞서 각 노드에서 OpenSearch를 재시작해야 합니다. _cat/plugins는 활성화된 플러그인만 보고하므로 재시작이 먼저 필요합니다. 프로덕션 클러스터에서는 모든 노드를 한꺼번에 재시작하지 말고 한 번에 한 노드씩(롤링 재시작) 진행하세요. 다음 확인 명령을 일반 HTTP로 실행하려면 opensearch.yml에서 OpenSearch Security 플러그인을 plugins.security.disabled: true로 설정해야 할 수도 있습니다(인증 플러그인을 비활성화하며, 테스트 용도입니다). 계속하기 전에 모든 노드에 플러그인이 설치되어 활성화되었는지 확인하고, <your-opensearch-host>는 클러스터 엔드포인트로 바꾸세요.

   curl --silent --show-error --fail-with-body 'http://<your-opensearch-host>:9200/_cat/plugins?v&h=name,component,version&s=name,component'
   

   이 명령을 실행하면 클러스터의 노드마다 analysis-icu가 한 번씩 표시되어야 합니다. 어느 노드에서든 analysis-icu 줄이 빠져 있다면 해당 노드에는 플러그인이 설치되지 않은 것입니다.

(선택) CJK 언어 분석기 플러그인: 한국어, 일본어, 중국어 콘텐츠의 검색을 개선하려면 다음 언어별 분석기 플러그인 중 하나 이상을 설치하세요. analysis-nori(한국어), analysis-kuromoji(일본어), analysis-smartcn(중국어)입니다.

sudo /usr/share/opensearch/bin/opensearch-plugin install analysis-nori
sudo /usr/share/opensearch/bin/opensearch-plugin install analysis-kuromoji
sudo /usr/share/opensearch/bin/opensearch-plugin install analysis-smartcn

CJK 플러그인을 설치한 뒤에는 이를 로드하도록 OpenSearch를 재시작합니다.

sudo systemctl restart opensearch

그런 다음 EnableCJKAnalyzers 설정을 활성화합니다. 추가적인 CJK 검색 구성 옵션은 중국어, 일본어, 한국어 검색 활성화를 참고하세요.

Terraform(Docker) 예시

provider "docker" {
  host = "unix:///var/run/docker.sock"
}

resource "docker_image" "opensearch" {
  name = "opensearchproject/opensearch:2.9.0"
}

resource "docker_container" "opensearch" {
  name = "opensearch"
  image = docker_image.opensearch.latest

  ports {
    internal = 9200
    external = 9200
  }
  ports {
    internal = 9600
    external = 9600
  }

  env = [
    "cluster.name=mattermost-cluster",
    "network.host=0.0.0.0",
    "discovery.type=single-node", # remove for multi-node
  ]

  restart = "unless-stopped"
}

resource "null_resource" "install_icu_plugin" {
  depends_on = [docker_container.opensearch]

  provisioner "local-exec" {
    command = "docker exec opensearch /usr/share/opensearch/bin/opensearch-plugin install analysis-icu && docker restart opensearch"
  }
}

AWS OpenSearch Console Setup

1. AWS OpenSearch를 설치하려면 AWS Console > OpenSearch Service를 엽니다.

2. 다음과 같이 도메인을 생성합니다.

   • 도메인 이름: mattermost-os
   • 엔진 버전: OpenSearch 2.x

3. 다음과 같이 클러스터를 구성합니다.

   • 인스턴스 유형: r6g.xlarge.search
   • 데이터 노드: 2
   • 마스터 노드: 2
   • 스토리지: EBS gp3(1536 GiB, 4608 IOPS, 250 MiB/s)

4. 네트워크를 지정합니다. 서브넷 2개를 가진 VPC와 443 포트에서 Mattermost IP를 허용하는 보안 그룹을 지정합니다.

   참고

   9200 포트는 로컬 또는 온프레미스 OpenSearch에서 흔히 사용됩니다. AWS OpenSearch 도메인은 443 포트의 HTTPS만 지원합니다.

5. 접근 정책(JSON)을 구성합니다. Mattermost는 OpenSearch 요청에 AWS SigV4 서명을 하지 않으므로, 4단계의 VPC와 보안 그룹으로 네트워크 계층에서 접근을 제한하고 도메인 접근 정책에는 개방형 주체를 사용하세요.

   {
     "Version": "2012-10-17",
     "Statement": [{
       "Effect": "Allow",
       "Principal": { "AWS": "*" },
       "Action": "es:ESHttp*",
       "Resource": "arn:aws:es:us-east-1:123456789012:domain/mattermost-os/*" }]
   }
   

   주의

   IAM 주체 기반 접근 정책(예: "Principal": { "AWS": "arn:aws:iam::<account-id>:role/<role-name>" })은 지원되지 않습니다. Mattermost의 OpenSearch 클라이언트는 요청에 AWS SigV4 서명을 하지 않으므로 AWS가 요청을 익명으로 취급하고, IAM으로 제한된 정책은 User: anonymous is not authorized to perform: es:ESHttpGet 오류로 요청을 거부합니다. 네트워크 계층이 아니라 OpenSearch 계층에서 인증을 강제해야 한다면, 도메인에서 내부 마스터 사용자와 함께 세분화된 접근 제어를 활성화하고 해당 자격 증명을 Mattermost Elasticsearch 구성의 Server Username과 Server Password에 입력하세요.

6. 다음 고급 설정(JSON)을 구성합니다.

   {
     "action.destructive_requires_name": "false",
     "rest.action.multi.allow_explicit_index": "true",
     "indices.query.bool.max_clause_count": "1024",
     "indices.fielddata.cache.size": "20"
   }
   

7. 자동 스냅숏 시작 시각을 23시(UTC)로 구성하고 HTTPS를 강제한 다음, 검토하고 생성합니다.

8. 테스트하려면 다음 명령을 실행합니다.

   curl https://mattermost-os-xxxxxxxxxxx.us-east-1.es.amazonaws.com
   

AWS Terraform 예시

provider "aws" {
  region = "us-east-1"
}

resource "aws_iam_role" "os_service_role" {
  name = "OSServiceRole"
  assume_role_policy = <<EOF
{
  "Version": "2012-10-17",
  "Statement": [{
    "Action": "sts:AssumeRole",
    "Effect": "Allow",
    "Principal": { "Service": "es.amazonaws.com" }
  }]
}
EOF
}

resource "aws_opensearch_domain" "mattermost" {
  domain_name = "mattermost-os"
  engine_version = "OpenSearch_2.9"
  cluster_config {
    instance_type = "r6g.xlarge.search"
    instance_count = 2
    dedicated_master_enabled = true
    dedicated_master_type = "r6g.xlarge.search"
    dedicated_master_count = 2
    zone_awareness_enabled = true
  }

  ebs_options {
    ebs_enabled = true
      volume_type = "gp3"
      volume_size = 1536
      iops = 4608
  }

  vpc_options {
    subnet_ids = ["subnet-blah1", "subnet-blah2"]
    security_group_ids = ["sg-1234567890"]
  }

  advanced_options = {
    "rest.action.multi.allow_explicit_index" = "true"
    "indices.query.bool.max_clause_count" = "1024"
    "indices.fielddata.cache.size" = "20"
    "action.destructive_requires_name" = "false"
  }

  access_policies = <<POLICY
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "AWS": "*"
    },
      "Action": "es:ESHttp*",
      "Resource": "arn:aws:es:us-east-1:123456789012:domain/mattermost-os/*"
    }]
  }
  POLICY
    service_software_options {
      automated_snapshot_start_hour = 23
    }

    domain_endpoint_options {
      enforce_https = true
    }
}

Mattermost 구성

Mattermost가 AWS OpenSearch 서버를 사용하고 게시물 인덱스를 생성하도록 구성하려면 다음 단계를 따르세요.

1. System Console > Environment > Elasticsearch(시스템 콘솔 > 환경 > Elasticsearch)로 이동합니다.
2. 페이지의 다른 설정을 활성화하려면 Enable Elasticsearch Indexing을 true로 설정합니다.
3. Backend type이 opensearch로 설정되어 있는지 확인합니다.
4. Server Connection Address를 Elasticsearch 또는 OpenSearch 클러스터 엔드포인트로 설정합니다.
5. 클러스터 상태를 모니터링합니다: curl https://mattermost-os-xxxxx.us-east-1.es.amazonaws.com/_cluster/health

서버 연결 정보 설정

1. (선택) 엔터프라이즈 검색 서버에 접근할 때 사용하는 Server Username을 입력합니다.
2. (선택) 해당 사용자 이름에 연결된 Server Password를 입력합니다.
3. (선택) Enable Cluster Sniffing을 설정합니다. 스니핑은 클러스터의 모든 데이터 노드를 자동으로 찾아 연결합니다.

4. 기본 인증 자격 증명과 함께 사용하거나 이를 대체할 수 있는 선택적 CA 및 클라이언트 인증서 설정도 제공됩니다. 자세한 내용은 엔터프라이즈 검색 설정 문서를 참고하세요.
5. Test Connection을 선택한 다음 Save를 선택합니다. 서버 연결에 실패하면 구성을 저장할 수 없고 Elasticsearch나 AWS OpenSearch를 사용하는 검색도 활성화할 수 없습니다.

기존 메시지의 게시물 인덱스 구축

Index Now를 선택합니다. 이 작업은 게시물 데이터베이스의 크기와 메시지 수에 따라 최대 몇 시간이 걸릴 수 있습니다. 인덱스가 생성되는 동안 진행률을 확인할 수 있습니다. 다운타임을 피하려면 Enable Elasticsearch for search queries를 false로 설정해 인덱싱 과정에서도 데이터베이스 검색을 사용할 수 있도록 하세요.

엔터프라이즈 검색 활성화

엔터프라이즈 검색을 활성화하기 전에 대량 인덱싱이 완료되었는지 확인하세요. 그렇지 않으면 검색 결과가 불완전해집니다.

Enable Elasticsearch for search queries를 true로 설정하고, Enable Elasticsearch for autocomplete도 true로 설정합니다. 구성 변경 사항을 저장하고 Mattermost 서버를 재시작하세요.

구성을 저장하면 데이터베이스에 작성되는 새 게시물이 Elasticsearch 또는 AWS OpenSearch 서버에 자동으로 인덱싱됩니다.

엔터프라이즈 검색 제한 사항

1. Elasticsearch와 AWS OpenSearch는 검색 결과의 관련성을 유지하기 위해 표준 "불용어(stop words)" 집합을 사용합니다. 다음 단어에 대한 결과는 반환되지 않습니다: "a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with".
2. 불용어를 따옴표로 묶어 검색하면 검색어에 해당하는 것보다 더 많은 결과가 반환됩니다(티켓).
3. 기본적으로 검색 결과는 사용자가 속한 팀과 채널로 제한됩니다. 이는 Mattermost 서버가 강제합니다. 엔터티는 조회 시 Mattermost가 필터링할 수 있는 방식으로 Elasticsearch 또는 AWS OpenSearch에 인덱싱되므로, Mattermost 서버는 Elasticsearch 또는 AWS OpenSearch 요청마다 해당 필터를 적용해 결과 범위를 좁힙니다. Mattermost v11.6부터 관리자는 멤버가 아니어도 공개 채널을 검색하도록 허용할 수 있어, 사용자가 속한 팀 범위 안에서 가입하지 않은 공개 채널의 메시지도 찾을 수 있습니다.
4. Elasticsearch 또는 AWS OpenSearch가 처리하는 사용자 검색과 자동 완성은 사용자 이름, 닉네임, 이름과 성만 일치시킵니다. 이메일 주소는 인덱싱되지 않으므로 시스템 관리자를 포함해 어떤 사용자도 이메일 주소로는 찾을 수 없습니다. 데이터베이스에서 처리하는 사용자 검색은 이메일 주소도 계속 일치시킵니다. 채널·팀 멤버 검색에서 시스템 관리자는 항상 이메일 주소로 일치되며, 다른 모든 사용자는 Show email address가 활성화되어 있어야 합니다. System Console > User Management > Users(시스템 콘솔 > 사용자 관리 > 사용자) 목록은 이 설정과 무관하게 항상 이메일 주소로 일치시킵니다.