lander.log

AWS OpenSearch Nori Plugin Management

4 min read

AWS OpenSearch Nori Plugin Management

정의 (Definition)

AWS OpenSearch Nori Plugin Management는 Amazon OpenSearch Service의 ‘Optional Plugin Package’인 analysis-nori(한국어 형태소 분석기)를 Terraform의 aws_opensearch_package_association 리소스를 사용하여 도메인에 연결하고 관리하는 IaC 패턴입니다.

문제가 되는 배경 (Problem Context)

  1. 플러그인 설치 방식: analysis-nori는 기본 설치되어 있지 않으며, “S3 업로드” 방식이 아니라 AWS가 제공하는 Pre-packaged Plugin을 도메인에 Associate 하는 방식으로 활성화해야 합니다.
  2. 배포 지연 및 타임아웃: 패키지 연결(Association) 시 OpenSearch 도메인에서 Blue/Green 배포가 트리거될 수 있으며, 이 과정은 10분 이상(종종 30~60분) 소요됩니다. Terraform의 기본 타임아웃(10분)으로는 실패(Error: timeout)하기 쉽습니다.
  3. 상태 불일치(Drift/Taint): 타임아웃으로 Terraform이 종료되면, 실제 AWS 리소스는 백그라운드에서 성공하더라도 Terraform State에는 tainted 로 기록되어 다음 배포 시 불필요한 재생성(삭제 후 생성)을 시도하게 됩니다.

핵심 메커니즘 (How it Works)

1. Terraform 구성 (Package Association)

패키지 ID를 변수로 받아 연결합니다. 핵심은 timeouts 설정입니다.

variable "opensearch_analysis_nori_package_id" {
  description = "Package ID for analysis-nori (e.g., pkg-xxxx or FG-xxxx)"
  type        = string
  default     = "" # 비어있으면 연결 안 함
}
 
resource "aws_opensearch_package_association" "analysis_nori" {
  count = var.opensearch_analysis_nori_package_id != "" ? 1 : 0
 
  package_id  = var.opensearch_analysis_nori_package_id
  domain_name = module.opensearch.domain_name
 
  # 중요: Blue/Green 배포 시간을 고려하여 타임아웃을 충분히 늘려야 함
  timeouts {
    create = "60m"
  }
 
  depends_on = [module.opensearch]
}

2. Package ID 확인 방법

AWS CLI를 통해 리전 내 analysis-nori 패키지의 ID를 조회할 수 있습니다.

aws opensearch describe-packages \
  --region ap-northeast-2 \
  --query "PackageDetailsList[?PackageName=='analysis-nori'].[PackageID,PackageName,PackageStatus,EngineVersion]" \
  --output table

불변 조건과 보장 범위 (Invariants & Guarantees)

  • 보장: Association이 완료(ACTIVE)되면 해당 도메인에서 nori_tokenizer를 사용할 수 있습니다.
  • 제약: 패키지 연결/해제(Associate/Dissociate)는 동시에 진행될 수 없습니다. 진행 중 다른 작업을 시도하면 409 Conflict 에러가 발생합니다.

실무적 함의 (Operational Implications)

  • 타임아웃 설정 필수: aws_opensearch_package_association 리소스에는 반드시 create = "60m" 이상의 타임아웃을 설정해야 안정적인 파이프라인 운영이 가능합니다. (update 타임아웃은 지원하지 않음)
  • Taint 처리: 타임아웃으로 인해 실제로는 성공했으나 Terraform에서 실패로 처리된 경우, 재생성을 막기 위해 수동으로 untaint 해야 합니다.

트러블슈팅 가이드

상황 1: Terraform Timeout 발생 후 Taint 됨

증상: Terraform은 에러로 끝났으나, AWS 콘솔에서는 패키지가 Active 상태임. terraform plan 시 리소스를 교체(-/+)하려고 함. 해결:

  1. Taint 해제: terraform untaint 'aws_opensearch_package_association.analysis_nori[0]'
  2. 상태 동기화: terraform apply -refresh-only

상황 2: 409 Conflict (Dissociate 실패)

증상: 패키지 연결/해제 중 다른 작업 시도 시 실패. 해결: OpenSearch 도메인 상태가 Processing에서 Active로 돌아올 때까지(Blue/Green 완료 시까지) 대기 후 재시도해야 합니다.

References

Recent Posts