기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon OpenSearch Service에서 사용자 지정 플러그인 관리
OpenSearch Service용 사용자 지정 플러그인을 사용하면 언어 분석, 사용자 지정 필터링, 순위 등의 영역에서 OpenSearch 기능을 확장하여 맞춤형 검색 경험을 만들 수 있습니다. OpenSearch용 사용자 지정 플러그인은 `org.opensearch.plugins.Plugin` 클래스를 확장한 다음 `.zip` 파일에 패키징하여 개발할 수 있습니다.
다음 플러그인 확장은 현재 Amazon OpenSearch Service에서 지원됩니다.
+ **AnalysisPlugin** - 텍스트 처리를 위한 사용자 지정 분석기, 캐릭터 토크나이저 또는 필터를 추가하여 분석 기능을 확장합니다.
+ **SearchPlugin** - 사용자 지정 쿼리 유형, 유사성 알고리즘, 제안 옵션 및 집계를 사용하여 검색 기능을 개선합니다.
+ **MapperPlugin** - OpenSearch에서 사용자 지정 필드 유형 및 매핑 구성을 생성하여 다양한 유형의 데이터를 저장하고 인덱싱하는 방법을 정의할 수 있습니다.
+ **ScriptPlugin** – OpenSearch에 사용자 지정 스크립팅 기능을 추가할 수 있습니다. 예를 들어 검색 또는 인덱싱 중에 점수, 정렬 및 필드 값 변환과 같은 작업을 위한 사용자 지정 스크립트를 추가할 수 있습니다.
사용자 지정 패키지에 OpenSearch Service 콘솔 또는 기존 API 명령을 사용하여 플러그인을 업로드하고 Amazon OpenSearch Service 클러스터와 연결할 수 있습니다. [DescribePackages](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DescribePackages.html) 명령을 사용하여 계정의 모든 패키지를 설명하고 OpenSearch 버전 및 오류 세부 정보와 같은 세부 정보를 볼 수도 있습니다. OpenSearch Service는 플러그인 패키지의 버전 호환성, 보안 취약성 및 허용된 플러그인 작업을 검증합니다. 사용자 지정 패키지에 대한 자세한 내용은 [Amazon OpenSearch Service에서 패키지 가져오기 및 관리](custom-packages.md) 섹션을 참조하세요.
**OpenSearch 버전 및 AWS 리전 지원**
사용자 지정 플러그인은 다음 AWS 리전에서 OpenSearch 버전 2.15를 실행하는 OpenSearch Service 도메인에 대해 지원됩니다.
+ 미국 동부(오하이오)(us-east-2)
+ 미국 동부(버지니아 북부)(us-east-1)
+ 미국 서부(오레곤)(us-west-2)
+ 아시아 태평양(뭄바이)(ap-south-1)
+ 아시아 태평양(서울)(ap-northeast-2)
+ 아시아 태평양(싱가포르)(ap-southeast-1)
+ 아시아 태평양(시드니)(ap-southeast-2)
+ 아시아 태평양(도쿄)(ap-northeast-1)
+ 캐나다(중부)(ca-central-1)
+ 유럽(프랑크푸르트)(eu-central-1)
+ 유럽(아일랜드)(eu-west-1)
+ 유럽(런던) (eu-west-2)
+ 유럽(파리)(eu-west-3)
+ 남아메리카(상파울루)(sa-east-1)
**참고**
사용자 지정 플러그인에는 사용자 개발 코드가 포함되어 있습니다. 사용자 개발 코드로 인한 SLA 위반을 비롯한 모든 문제에는 SLA 크레딧이 적용되지 않습니다. 자세한 내용은 [Amazon OpenSearch Service - 서비스 수준 계약](https://aws.amazon.com/opensearch-service/sla/)을 참조하세요.
**Topics**
+ [플러그인 할당량](#plugin-limits)
+ [사전 조건](#custom-plugin-prerequisites)
+ [문제 해결](#custom-plugin-troubleshooting)
+ [콘솔을 사용하여 사용자 지정 플러그인 설치](#custom-plugin-install-console)
+ [를 사용하여 사용자 지정 플러그인 관리 AWS CLI](#managing-custom-plugins-cli)
+ [Amazon OpenSearch Service 사용자 지정 패키지 AWS KMS 통합](custom-package-kms-integration.md)
## 플러그인 할당량
+ 계정마다 리전당 최대 25개까지 사용자 지정 플러그인을 생성할 수 있습니다.
+ 플러그인의 최대 비압축 크기는 1GB입니다.
+ 단일 도메인에 연결할 수 있는 최대 플러그인 수는 20개입니다. 이 할당량은 선택적, 서드 파티, 사용자 지정 등 결합된 모든 플러그인 유형에 적용됩니다.
+ 사용자 지정 플러그인은 OpenSearch 버전 2.15 이상을 실행하는 도메인에 대해 지원됩니다.
+ 플러그인의 `descriptor.properties` 파일은 패치 버전이 0으로 설정된 2.15.0 또는 2.x.x 버전과 유사한 엔진 버전을 지원해야 합니다.
## 사전 조건
사용자 지정 플러그인을 설치하고 도메인에 연결하려면 먼저 다음 요구 사항을 충족해야 합니다.
+ `descriptor.properties` 파일의 플러그인에 대해 지원되는 엔진 버전은 `2.15.0` 또는 `2.x.0`과 유사해야 합니다. 즉, 패치 버전이 0이어야 합니다.
+ 도메인에 대해 다음 기능을 활성화해야 합니다.
+ [노드 간 암호화](ntn.md)
+ [저장된 데이터 암호화](encryption-at-rest.md)
+ [`EnforceHTTPS`가 'true'로 설정됨](createupdatedomains.md)
*AWS Config 개발자 가이드*의 [opensearch-https-required](https://docs.aws.amazon.com/config/latest/developerguide/opensearch-https-required.html)도 참조하세요.
+ 클라이언트는 **Policy-Min-TLS-1-2-PFS-2023-10**을 지원해야 합니다. 다음 명령을 사용하여 이 지원을 지정할 수 있습니다. *자리 표시자 값*을 자신의 정보로 바꿉니다.
```
aws opensearch update-domain-config \
--domain-name domain-name \
--domain-endpoint-options '{"TLSSecurityPolicy":"Policy-Min-TLS-1-2-PFS-2023-10" }'
```
자세한 내용은 *Amazon OpenSearch Service API 참조*의 [DomainEndpointOptions](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DomainEndpointOptions.html)를 참조하세요.
## 문제 해결
시스템에서 `PluginValidationFailureReason : The provided plugin could not be loaded` 오류가 반환되는 경우 [버전 호환성으로 인한 사용자 지정 플러그인 설치 실패](handling-errors.md#troubleshooting-custom-plugins)에서 문제 해결 정보를 참조하세요.
## 콘솔을 사용하여 사용자 지정 플러그인 설치
서드 파티 플러그인을 도메인에 연결하려면 먼저 플러그인 라이선스 및 구성을 패키지로 가져옵니다.
**사용자 지정 플러그인을 설치하려면**
1. [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home) Amazon OpenSearch Service 콘솔에 로그인합니다.
1. 왼쪽 탐색 창에서 **패키지**를 선택합니다.
1. [**패키지 가져오기(Import package)**]를 선택합니다.
1. **이름**에 플러그인의 알아보기 쉽고 고유한 이름을 입력합니다.
1. (선택 사항) **설명**에 패키지 또는 용도에 대한 유용한 세부 정보를 제공합니다.
1. **패키지 유형**에서 **플러그인**을 선택합니다.
1. **패키지 소스**에 경로를 입력하거나 Amazon S3에서 플러그인 ZIP 파일을 찾습니다.
1. **OpenSearch 엔진 버전**에서 플러그인이 지원하는 OpenSearch 버전을 선택합니다.
1. **패키지 암호화**에서 패키지의 암호화 키를 사용자 지정할지 여부를 선택합니다. 기본적으로 OpenSearch Service는 AWS 소유 키를 사용하여 플러그인 패키지를 암호화합니다. 대신 고객 관리형 키를 사용할 수 있습니다.
1. **가져오기**를 선택합니다.
플러그인 패키지를 가져온 후 도메인과 연결합니다. 지침은 [패키지를 가져오고 도메인에 연결](custom-packages.md#associate-console) 섹션을 참조하세요.
## 를 사용하여 사용자 지정 플러그인 관리 AWS CLI
AWS CLI 를 사용하여 여러 사용자 지정 플러그인 작업을 관리할 수 있습니다.
**Topics**
+ [를 사용하여 사용자 지정 플러그인 설치 AWS CLI](#custom-plugin-install-cli)
+ [를 사용하여 사용자 지정 플러그인 업데이트 AWS CLI](#custom-plugin-update-cli)
+ [AWS KMS 키 보안으로 사용자 지정 플러그인 생성 또는 업데이트](#custom-plugin-kms-key-security-cli)
+ [를 사용하여 사용자 지정 플러그인이 있는 OpenSearch Service 도메인을 최신 버전의 OpenSearch로 업그레이드 AWS CLI](#custom-plugin-domain-upgrade-cli)
+ [사용자 지정 플러그인 제거 및 연결 해제 상태 보기](#custom-plugin-uninstall-cli)
### 를 사용하여 사용자 지정 플러그인 설치 AWS CLI
**시작하기 전 준비 사항**
사용자 지정 플러그인을 도메인에 연결하려면 먼저 Amazon Simple Storage Service(Amazon S3) 버킷에 패키지를 업로드해야 합니다. 버킷은 플러그인을 사용하려는 AWS 리전 동일한에 있어야 합니다. S3 버킷에 객체를 추가하는 데 대한 자세한 내용은 *Amazon Simple Storage Service 사용 설명서*의 [객체 업로드](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html)를 참조하세요.
플러그인에 민감한 정보가 포함되어 있는 경우 업로드할 때 S3 관리형 키를 사용한 서버 측 암호화를 지정합니다. 파일을 업로드한 후 S3 경로를 기록해 둡니다. 경로 형식은 `s3://amzn-s3-demo-bucket/file-path/file-name`입니다.
**참고**
( AWS Key Management Service AWS KMS) 키를 지정하여 플러그인을 생성할 때 선택적으로 사용자 지정 플러그인을 보호할 수 있습니다. 자세한 내용은 [AWS KMS 키 보안으로 사용자 지정 플러그인 생성 또는 업데이트](#custom-plugin-kms-key-security-cli) 단원을 참조하세요.
**를 사용하여 사용자 지정 플러그인을 설치하려면 AWS CLI**
1. 다음 [create-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/create-package.html) 명령을 실행하여 사용자 지정 플러그인의 새 패키지를 생성하고 다음 요구 사항을 충족하는지 확인합니다.
+ 버킷과 키 위치는 명령을 실행 중인 계정의 S3 버킷에 있는 플러그인 `.zip` 파일을 가리켜야 합니다.
+ S3 버킷은 패키지가 생성되는 리전과 동일한 리전에 있어야 합니다.
+ `ZIP-PLUGIN` 패키지에는 `.zip` 파일만 지원됩니다.
+ `.zip` 파일의 내용은 플러그인에서 예상한 디렉토리 구조를 따라야 합니다.
+ `--engine-version`의 값은 `OpenSearch_{MAJOR}.{MINOR}` 형식이어야 합니다. 예를 들어 **OpenSearch\$12.17**입니다.
*자리 표시자 값*을 자신의 정보로 바꿉니다.
```
aws opensearch create-package \
--package-name package-name \
--region region \
--package-type ZIP-PLUGIN \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=s3-key \
--engine-version opensearch-version
```
1. (선택 사항) [describe-packages](https://docs.aws.amazon.com/cli/latest/reference/es/describe-packages.html) 명령을 사용하여 검증 및 보안 취약성 조사 결과를 비롯한 `create-package` 작업의 상태를 봅니다. *자리 표시자 값*을 자신의 정보로 바꿉니다.
```
aws opensearch describe-packages \
--region region \
--filters '[{"Name": "PackageType","Value": ["ZIP-PLUGIN"]}, {"Name": "PackageName","Value": ["package-name"]}]'
```
이 명령은 다음과 유사한 정보를 반환합니다.
```
{
"PackageDetailsList": [{
"PackageID": "pkg-identifier",
"PackageName": "package-name",
"PackageType": "ZIP-PLUGIN",
"PackageStatus": "VALIDATION_FAILED",
"CreatedAt": "2024-11-11T13:07:18.297000-08:00",
"LastUpdatedAt": "2024-11-11T13:10:13.843000-08:00",
"ErrorDetails": {
"ErrorType": "",
"ErrorMessage": "PluginValidationFailureReason : Dependency Scan reported 3 vulnerabilities for the plugin: CVE-2022-23307, CVE-2019-17571, CVE-2022-23305"
},
"EngineVersion": "OpenSearch_2.15",
"AllowListedUserList": [],
"PackageOwner": "OWNER-XXXX"
}]
}
```
**참고**
`create-package` 작업 중에 Amazon OpenSearch Service는 `ZIP-PLUGIN` 값에서 버전 호환성, 지원되는 플러그인 확장 및 보안 취약성을 확인합니다. 보안 취약성은 [Amazon Inspector](https://aws.amazon.com/inspector/getting-started/) 서비스를 사용하여 검사됩니다. 이러한 검사의 결과는 API 응답의 `ErrorDetails` 필드에 표시됩니다.
1. [associate-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-package.html) 명령을 사용하여 이전 단계에서 생성한 패키지의 패키지 ID로, 선택한 OpenSearch Service 도메인과 플러그인을 연결합니다.
**작은 정보**
플러그인이 여러 개 있는 경우 [associate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-packages.html) 명령을 사용하여 단일 작업에서 여러 패키지를 도메인에 연결할 수 있습니다.
*자리 표시자 값*을 자신의 정보로 바꿉니다.
```
aws opensearch associate-package \
--domain-name domain-name \
--region region \
--package-id package-id
```
**참고**
플러그인은 [블루/그린 배포 프로세스](managedomains-configuration-changes.md)를 사용하여 설치 및 제거합니다.
1. (선택 사항) [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/opensearch/list-packages-for-domain.html) 명령을 사용하여 연결 상태를 봅니다. 워크플로가 진행됨에 따라 연결 상태가 `ASSOCIATING`에서 `ACTIVE`로 바뀝니다. 플러그인 설치가 완료되고 플러그인을 사용할 준비가 되면 연결 상태가 ACTIVE로 바뀝니다.
*자리 표시자*를 자신의 정보로 바꿉니다.
```
aws opensearch list-packages-for-domain \
--region region \
--domain-name domain-name
```
### 를 사용하여 사용자 지정 플러그인 업데이트 AWS CLI
[update-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/update-package.html) 명령을 사용하여 플러그인을 변경합니다.
**참고**
( AWS Key Management Service AWS KMS) 키를 지정하여 플러그인을 업데이트할 때 선택적으로 사용자 지정 플러그인을 보호할 수 있습니다. 자세한 내용은 [AWS KMS 키 보안으로 사용자 지정 플러그인 생성 또는 업데이트](#custom-plugin-kms-key-security-cli) 단원을 참조하세요.
**를 사용하여 사용자 지정 플러그인을 업데이트하려면 AWS CLI**
+ 다음 명령을 실행합니다. *자리 표시자*를 자신의 정보로 바꿉니다.
```
aws opensearch update-package \
--region region \
--package-id package-id \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=s3-key \
--package-description description
```
패키지를 업데이트한 후 [associate-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-package.html) 또는 [associate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-packages.html) 명령을 사용하여 도메인에 패키지 업데이트를 적용할 수 있습니다.
**참고**
를 사용하여 플러그인에 대한 작업을 감사, 생성, 업데이트, 연결 및 연결 해제할 수 있습니다 AWS CloudTrail. 자세한 내용은 [를 사용하여 Amazon OpenSearch Service API 호출 모니터링 AWS CloudTrail](managedomains-cloudtrailauditing.md) 단원을 참조하십시오.
### AWS KMS 키 보안으로 사용자 지정 플러그인 생성 또는 업데이트
AWS KMS 키를 지정하여 플러그인을 생성하거나 업데이트할 때 사용자 지정 플러그인을 보호할 수 있습니다. 이렇게 하려면 다음 예와 같이 `PackageEncryptionOptions`를 `true`로 설정하고 키의 Amazon 리소스 이름(ARN)을 지정합니다.
**예: AWS KMS 키 보안으로 사용자 지정 플러그인 생성**
```
aws opensearch create-package \
--region us-east-2 --package-name my-custom-package \
--package-type ZIP-PLUGIN \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=my-s3-key
--engine-version OpenSearch_2.15
"PackageConfigOptions": {
...
}
"PackageEncryptionOptions": {
"Enabled": true,
"KmsKeyId":"arn:aws:kms:us-east-2:111222333444:key/2ba228d5-1d09-456c-ash9-daf42EXAMPLE"
}
```
**예: AWS KMS 키 보안으로 사용자 지정 플러그인 업데이트**
```
aws opensearch update-package \
--region us-east-2 --package-name my-custom-package \
--package-type ZIP-PLUGIN \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=my-s3-key
--engine-version OpenSearch_2.15
"PackageConfigOptions": {
...
}
"PackageEncryptionOptions": {
"Enabled": true,
"KmsKeyId":"arn:aws:kms:us-east-2:111222333444:key/2ba228d5-1d09-456c-ash9-daf42EXAMPLE"
}
```
**중요**
지정한 AWS KMS 키가 비활성화되거나 삭제되면 연결된 클러스터가 작동하지 않을 수 있습니다.
사용자 지정 패키지와의 AWS KMS 통합에 대한 자세한 내용은 단원을 참조하십시오[Amazon OpenSearch Service 사용자 지정 패키지 AWS KMS 통합](custom-package-kms-integration.md).
### 를 사용하여 사용자 지정 플러그인이 있는 OpenSearch Service 도메인을 최신 버전의 OpenSearch로 업그레이드 AWS CLI
사용자 지정 플러그인을 사용하는 OpenSearch Service 도메인을 최신 버전의 OpenSearch로 업그레이드해야 하는 경우 다음 프로세스를 완료합니다.
**를 사용하여 사용자 지정 플러그인이 있는 OpenSearch Service 도메인을 최신 버전의 OpenSearch로 업그레이드하려면 AWS CLI**
1. create-package 명령을 사용하여 새 OpenSearch 버전을 지정하는 플러그인에 대한 새 패키지를 생성합니다.
모든 엔진 버전의 플러그인의 패키지 이름이 동일한지 확인합니다. 패키지 이름을 변경하면 블루/그린 배포 중에 도메인 업그레이드 프로세스가 실패합니다.
1. [Amazon OpenSearch Service 도메인 업그레이드](version-migration.md)의 단계에 따라 도메인을 상위 버전으로 업그레이드합니다.
이 프로세스 중에 Amazon OpenSearch Service는 플러그인 패키지의 이전 버전을 연결 해제하고 블루/그린 배포를 사용하여 새 버전을 설치합니다.
### 사용자 지정 플러그인 제거 및 연결 해제 상태 보기
도메인에서 플러그인을 제거하려면 [dissociate-package](https://docs.aws.amazon.com/cli/latest/reference/es/dissociate-package.html) 명령을 사용합니다. 이 명령을 실행하면 관련 구성 또는 라이선스 패키지도 제거됩니다. 그런 다음 [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/es/list-packages-for-domain.html) 명령을 사용하여 연결 해제 상태를 확인할 수 있습니다.
**작은 정보**
[dissociate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/dissociate-packages.html) 명령을 사용하여 단일 작업으로 도메인에서 여러 플러그인을 제거할 수도 있습니다.
**사용자 지정 플러그인을 제거하고 연결 해제 상태를 보려면**
1. 모든 인덱스에서 플러그인을 비활성화합니다. 플러그인 패키지를 연결 해제하기 전에 이 작업을 수행해야 합니다.
모든 인덱스에서 비활성화하기 전에 플러그인을 제거하려고 하면 블루/그린 배포 프로세스가 `Processing` 상태로 유지됩니다.
1. 다음 명령을 실행하여 플러그인를 제거합니다. *자리 표시자*를 자신의 정보로 바꿉니다.
```
aws opensearch dissociate-package \
--region region \
--package-id plugin-package-id \
--domain-name domain name
```
1. (선택 사항) [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/opensearch/list-packages-for-domain.html) 명령을 실행하여 연결 해제 상태를 확인합니다.