AWS opensearch-service high security documentation change
Summary
Expanded documentation for managing custom plugins including supported plugin types, regional/version support, quotas, troubleshooting, CLI management, and KMS encryption integration. Added detailed prerequisites for TLS security policy requirements and HTTPS enforcement.
Security assessment
Added explicit requirements for TLS 1.2 with PFS (Policy-Min-TLS-1-2-PFS-2023-10) and HTTPS enforcement. Introduced security vulnerability scanning using Amazon Inspector during plugin validation. Added KMS encryption options for plugin packages, which directly addresses data protection security concerns.
Diff
diff --git a/opensearch-service/latest/developerguide/custom-plugins.md b/opensearch-service/latest/developerguide/custom-plugins.md index c6e5f89e6..519c5db59 100644 --- a//opensearch-service/latest/developerguide/custom-plugins.md +++ b//opensearch-service/latest/developerguide/custom-plugins.md @@ -5 +5 @@ -LimitationsPrerequisitesInstalling custom plugins +Plugin quotasPrerequisitesTroubleshootingInstalling a custom plugin using the consoleManaging custom plugins using the AWS CLI @@ -7 +7 @@ LimitationsPrerequisitesInstalling custom plugins -# Installing custom plugins in Amazon OpenSearch Service +# Managing custom plugins in Amazon OpenSearch Service @@ -9 +9,53 @@ LimitationsPrerequisitesInstalling custom plugins -Custom plugins for Amazon OpenSearch Service extend the functionality of OpenSearch by allowing you to add new features, modify existing behavior, or integrate with external systems. +Using custom plugins for OpenSearch Service, you can extend OpenSearch functionality in areas like language analysis, custom filtering, ranking and more, making it possible for you to craft personalized search experiences. Custom plugins for OpenSearch can be developed by extending the `org.opensearch.plugins.Plugin` class and then packaging it in a `.zip` file. + +The following plugin extensions are currently supported by Amazon OpenSearch Service: + + * **AnalysisPlugin** – Extends analysis functionality by adding, for example, custom analyzers, character tokenizers, or filters for text processing. + + * **SearchPlugin** – Enhances search capabilities with custom query types, similarity algorithms, suggestion options, and aggregations. + + * **MapperPlugin** – Allows you to create custom field types and their mapping configurations in OpenSearch, enabling you to define how different types of data should be stored and indexed. + + * **ScriptPlugin** – Allows you to add custom scripting capabilities to OpenSearch, for example, custom scripts for operations like scoring, sorting, and field value transformations during search or indexing. + + + + +You can use the OpenSearch Service console or existing API commands for custom packages to upload and associate the plugin with the Amazon OpenSearch Service cluster. You can also use the [DescribePackages](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DescribePackages.html) command to describe all the packages in your account and to view details such as OpenSearch version and error details. OpenSearch Service validates plugin package for version compatibility, security vulnerabilities, and permitted plugin operations. For more information about custom packages, see [Importing and managing packages in Amazon OpenSearch Service](./custom-packages.html). + +###### OpenSearch version and AWS Region support + +Custom plugins are supported on OpenSearch Service domains that are running OpenSearch version 2.15 in the following AWS Regions: + + * US East (Ohio) (us-east-2) + + * US East (N. Virginia) (us-east-1) + + * US West (Oregon) (us-west-2) + + * Asia Pacific (Mumbai) (ap-south-1) + + * Asia Pacific (Seoul) (ap-northeast-2) + + * Asia Pacific (Singapore) (ap-southeast-1) + + * Asia Pacific (Sydney) (ap-southeast-2) + + * Asia Pacific (Tokyo) (ap-northeast-1) + + * Canada (Central) (ca-central-1) + + * Europe (Frankfurt) (eu-central-1) + + * Europe (Ireland) (eu-west-1) + + * Europe (London) (eu-west-2) + + * Europe (Paris) (eu-west-3) + + * South America (São Paulo) (sa-east-1) + + + + +###### Note @@ -15 +67 @@ Custom plugins contain user-developed code. Any issues, including SLA breaches, - * Limitations + * Plugin quotas @@ -19 +71,3 @@ Custom plugins contain user-developed code. Any issues, including SLA breaches, - * Installing custom plugins + * Troubleshooting + + * Installing a custom plugin using the console @@ -20,0 +75 @@ Custom plugins contain user-developed code. Any issues, including SLA breaches, + * Managing custom plugins using the AWS CLI @@ -21,0 +77 @@ Custom plugins contain user-developed code. Any issues, including SLA breaches, + * [Amazon OpenSearch Service custom package AWS KMS integration](./custom-package-kms-integration.html) @@ -24 +79,0 @@ Custom plugins contain user-developed code. Any issues, including SLA breaches, -## Limitations @@ -26 +80,0 @@ Custom plugins contain user-developed code. Any issues, including SLA breaches, - * You can create up to 25 custom plugins per account. @@ -28 +82,7 @@ Custom plugins contain user-developed code. Any issues, including SLA breaches, - * The maximum allowed uncompressed size for a plugin is 1 GB. +## Plugin quotas + + * You can create up to 25 custom plugins per account per Region. + + * The maximum uncompressed size for a plugin is 1 GB. + + * The maximum number of plugins that can be associated with a single domain is 20. This quota applies to all plugin types combined: optional, third-party, and custom. @@ -34 +94 @@ Custom plugins contain user-developed code. Any issues, including SLA breaches, - * The following features are unavailable when your domain uses custom plugins: + * The following features are not available when your domain uses custom plugins: @@ -36 +96 @@ Custom plugins contain user-developed code. Any issues, including SLA breaches, - * Cross-cluster search + * [Cross-cluster search](./cross-cluster-search.html) @@ -38 +98 @@ Custom plugins contain user-developed code. Any issues, including SLA breaches, - * Cross-cluster replication + * [Cross-cluster replication](./replication.html) @@ -40 +100 @@ Custom plugins contain user-developed code. Any issues, including SLA breaches, - * Remote reindex + * [Remote reindexing](https://docs.aws.amazon.com/prescriptive-guidance/latest/opensearch-service-migration/remote-reindexing.html) @@ -42 +102 @@ Custom plugins contain user-developed code. Any issues, including SLA breaches, - * Auto-Tune + * [Auto-Tune](./auto-tune.html) @@ -44 +104 @@ Custom plugins contain user-developed code. Any issues, including SLA breaches, - * UltraWarm + * [Multi-AZ with Standby](./managedomains-multiaz.html#managedomains-za-standby) @@ -46 +106 @@ Custom plugins contain user-developed code. Any issues, including SLA breaches, - * Multi-AZ with Standby + * [Centralized OpenSearch user interface](./application.html) @@ -55 +115 @@ Before you install a custom plugin and associate it to a domain, make sure you m - * Your domain uses TLS policy **Policy-Min-TLS-1-2-PFS-2023-10**. For more information, see [DomainEndpointOptions](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DomainEndpointOptions.html). + * The supported engine version for the plugin in the `descriptor.properties` file should be similar to `2.15.0` or `2._x_.0`. That is, the patch version must be zero. @@ -57 +117 @@ Before you install a custom plugin and associate it to a domain, make sure you m - * You enabled the following features on your domain: + * The following features must be enabled on your domain: @@ -63 +123,3 @@ Before you install a custom plugin and associate it to a domain, make sure you m - * [Require HTTPS for all traffic to the domain](./createupdatedomains.html) + * [EnforceHTTPS is set to 'true'](./createupdatedomains.html) + +See also [opensearch-https-required](https://docs.aws.amazon.com/config/latest/developerguide/opensearch-https-required.html) in the _AWS Config Developer Guide_. @@ -64,0 +127 @@ Before you install a custom plugin and associate it to a domain, make sure you m + * Clients must support **Policy-Min-TLS-1-2-PFS-2023-10**. You can specify this support using the following command. Replace the `placeholder value` with your own information: @@ -65,0 +129,3 @@ Before you install a custom plugin and associate it to a domain, make sure you m + aws opensearch update-domain-config \ + --domain-name domain-name \ + --domain-endpoint-options '{"TLSSecurityPolicy":"Policy-Min-TLS-1-2-PFS-2023-10" }' @@ -66,0 +133 @@ Before you install a custom plugin and associate it to a domain, make sure you m +For more information, see [DomainEndpointOptions](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DomainEndpointOptions.html) in the _Amazon OpenSearch Service API Reference_. @@ -68 +135,8 @@ Before you install a custom plugin and associate it to a domain, make sure you m -## Installing custom plugins + + + +## Troubleshooting + +If the system returns the error `PluginValidationFailureReason : The provided plugin could not be loaded`, see [Custom plugin installation fails due to version compatibility](./handling-errors.html#troubleshooting-custom-plugins) for troubleshooting information. + +## Installing a custom plugin using the console @@ -80 +154,51 @@ To associate a third-party plugin to a domain, first import the plugin license a - 4. Enter a descriptive name for the plugin. + 4. For **Name** , enter a unique, easily identifiable name for the plugin. + + 5. (Optional) For **Description** , provide any useful details about the package or its purpose. + + 6. For **Package type** , choose **Plugin**. + + 7. For **Package source** , enter the path or browse to the plugin ZIP file in Amazon S3. + + 8. For **OpenSearch engine version** , choose the version of OpenSearch that the plugin supports. + + 9. For **Package encryption** , choose whether to customize the encryption key for the package. By default, OpenSearch Service encrypts the plugin package with an AWS owned key. You can use a customer managed key instead. + + 10. Choose **Import**. + + + + +After you import the plugin package, associate it with a domain. For instructions, see [Import and associate a package to a domain](./custom-packages.html#associate-console). + +## Managing custom plugins using the AWS CLI + +You can use the AWS CLI to manage a number of custom plugin tasks. + +###### Tasks + + * Installing a custom plugin using the AWS CLI + + * Updating a custom plugin using the AWS CLI + + * Create or update a custom plugin with an AWS KMS key security + + * Upgrading an OpenSearch Service domain with custom plugins to a later version of OpenSearch using the AWS CLI + + * Uninstalling and viewing the dissociation status of a custom plugin + + + + +### Installing a custom plugin using the AWS CLI + +###### Before you begin + +Before you can associate a custom plugin with your domain, you must upload it to an Amazon Simple Storage Service (Amazon S3) bucket. The bucket must be located in the same AWS Region where you intend to use the plugin. For information about adding an object to an S3 bucket, see [Uploading objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html) in the _Amazon Simple Storage Service User Guide_. + +If your plugin contains sensitive information, specify server-side encryption with S3-managed keys when you upload it. After you upload the file, make note of its S3 path. The path format is `s3://`amzn-s3-demo-bucket`/`file-path``/file-name``. + +###### Note + +You can optionally secure a custom plugin when you create the plugin by specifying an AWS Key Management Service (AWS KMS) key. For information, see Create or update a custom plugin with an AWS KMS key security. + +###### To install a custom plugin using the AWS CLI @@ -82 +206 @@ To associate a third-party plugin to a domain, first import the plugin license a - 5. For **Package type** , choose **Plugin**. + 1. Create a new package for your custom plugin by running the following [create-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/create-package.html) command, ensuring that the following requirements are met: @@ -84 +208 @@ To associate a third-party plugin to a domain, first import the plugin license a - 6. For **Package source** , enter the path to the plugin ZIP file in Amazon S3. + * The bucket and key location must point to the plugin `.zip` file in an S3 bucket in the account in which your are running the commands. @@ -86 +210 @@ To associate a third-party plugin to a domain, first import the plugin license a