# @aws-cdk/aws-elasticsearch 中文文档

规范地址：https://npmcn.com/package/%40aws-cdk/aws-elasticsearch/

版本：1\.204\.0
npm 元数据更新时间：2023-11-21T10:15:22.379Z
中文译文更新时间：2026-11-07T12:44:41.937Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk/aws-elasticsearch
原文对照：https://npmcn.com/package/%40aws-cdk/aws-elasticsearch/?lang=original
项目主页：https://github.com/aws/aws-cdk
源码仓库：https://github.com/aws/aws-cdk

弃用说明：AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，22 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 14\.15\.0
- 运行依赖：11 个
- peer 依赖：@aws-cdk/aws-certificatemanager 1\.204\.0，@aws-cdk/aws-cloudwatch 1\.204\.0，@aws-cdk/aws-ec2 1\.204\.0，@aws-cdk/aws-iam 1\.204\.0，@aws-cdk/aws-kms 1\.204\.0，@aws-cdk/aws-logs 1\.204\.0，@aws-cdk/aws-route53 1\.204\.0，@aws-cdk/aws-secretsmanager 1\.204\.0，@aws-cdk/core 1\.204\.0，@aws-cdk/custom-resources 1\.204\.0，constructs ^3\.3\.69
- 首次发布：2018-07-31T13:34:16.070Z
- 最新版本发布：2023-06-19T21:09:32.059Z
- 近 30 天下载量：73441（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：288（近 12 个月 0 个）

## 中文简介

AWS: 弹性搜索的 CDK 构造库

## 安装

```sh
npm install @aws-cdk/aws-elasticsearch
```

也可以使用：`pnpm add @aws-cdk/aws-elasticsearch`、`yarn add @aws-cdk/aws-elasticsearch`、`bun add @aws-cdk/aws-elasticsearch`

## README

# 亚马逊 OpenSearch 服务构建库

* * *

![Deprecated](https://img.shields.io/badge/deprecated-critical.svg?style=for-the-badge)

> 此API 可能会发出警告 。 后向兼容性没有保证 .

* * *

> 我们建议使用本单元,而不是本单元 [@aws-cdk/aws-opensearch服务](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-opensearchservice-readme.html) 模块。 见 [亚马逊 OpenSearch 服务 FAQs](https://aws.amazon.com/opensearch-service/faqs/#Name_change) 详细情况。 见 [移动到 OpenSearch](https://npmcn.com/package/%40aws-cdk/aws-elasticsearch/#readme-migrating-to-opensearch) 移民指示.

## 快开始

通过简单指定版本创建开发集群:

```ts
const devDomain = new es.Domain(this, 'Domain', {
  version: es.ElasticsearchVersion.V7_1,
});
```

要进行版本升级而不替换整个域,请指定 `enableVersionUpgrade` 属性.

```ts
const devDomain = new es.Domain(this, 'Domain', {
  version: es.ElasticsearchVersion.V7_10,
  enableVersionUpgrade: true, // defaults to false
});
```

通过同时指定容量和 az 分布等事项来创建生产级组

```ts
const prodDomain = new es.Domain(this, 'Domain', {
  version: es.ElasticsearchVersion.V7_1,
  capacity: {
    masterNodes: 5,
    dataNodes: 20,
  },
  ebs: {
    volumeSize: 20,
  },
  zoneAwareness: {
    availabilityZoneCount: 3,
  },
  logging: {
    slowSearchLogEnabled: true,
    appLogEnabled: true,
    slowIndexLogEnabled: true,
  },
});
```

这将创建一个弹性搜索集群,并自动设置日志组 记录域日志并慢取搜索日志.

## 关于 SLR 的说明

一些集群配置(例如VPC访问)需要存在 [`AWSServiceRoleForAmazonElasticsearchService`](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/slr.html) 与服务相关的角色.

在通过 AWS 控制台进行此类操作时,此 SLR 在需要时会被自动创建 。 然而,使用CloudFormation时,这不是行为. 如果需要SLR,但不存在,您将会遇到一个失败消息 simlar:

```console
Before you can proceed, you must enable a service-linked role to give Amazon ES...
```

为了解决这个问题,你需要 [创建](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#create-service-linked-role) sLR号 我们建议使用AWS CLI:

```console
aws iam create-service-linked-role --aws-service-name es.amazonaws.com
```

您也可以使用 CDK 创建它, **但请注意,只有第一个应用软件才会成功**数字 :

```ts
const slr = new iam.CfnServiceLinkedRole(this, 'ElasticSLR', {
  awsServiceName: 'es.amazonaws.com',
});
```

## 导入已存在的域

要将已有域导入您的 CDK 应用程序, 请使用 `Domain.fromDomainEndpoint` 工厂方法. 此方法接受一个已经存在的域的域端点 :

```ts
const domainEndpoint = 'https://my-domain-jcjotrt6f7otem4sqcwbch3c4u.us-east-1.es.amazonaws.com';
const domain = es.Domain.fromDomainEndpoint(this, 'ImportedDomain', domainEndpoint);
```

## 权限

### 行政会议

管理访问域的帮助方法也存在.

```ts
declare const fn: lambda.Function;
declare const domain: es.Domain;

// Grant write access to the app-search index
domain.grantIndexWrite('app-search', fn);

// Grant read access to the 'app-search/_search' path
domain.grantPathRead('app-search/_search', fn);
```

## 加密

也可以通过加密创建域 :

```ts
const domain = new es.Domain(this, 'Domain', {
  version: es.ElasticsearchVersion.V7_4,
  ebs: {
    volumeSize: 100,
    volumeType: ec2.EbsDeviceVolumeType.GENERAL_PURPOSE_SSD,
  },
  nodeToNodeEncryption: true,
  encryptionAtRest: {
    enabled: true,
  },
});
```

此设置有节点可加密的域名 休养. 您也可以选择提供用于加密的 KMS 密钥 休养.

## VPC 支持

弹性搜索域可以被放入VPC内,提供亚马逊ES与VPC内其他服务之间的安全通信,而不需要互联网网关,NAT设备,或VPN连接.

> 见 [在 VPC 内启动您的 Amazon OpenSearch 服务域](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/vpc.html) 更多细节.

```ts
const vpc = new ec2.Vpc(this, 'Vpc');
const domainProps: es.DomainProps = {
  version: es.ElasticsearchVersion.V7_1,
  removalPolicy: RemovalPolicy.DESTROY,
  vpc,
  // must be enabled since our VPC contains multiple private subnets.
  zoneAwareness: {
    enabled: true,
  },
  capacity: {
    // must be an even number since the default az count is 2.
    dataNodes: 2,
  },
};
new es.Domain(this, 'Domain', domainProps);
```

此外,您还可以使用 `vpcSubnets` 属性以控制将使用哪些子网,以及 `securityGroups` 要控制的属性 哪些安全小组将附属于域。 默认情况下, CDK 将选择全部 _私营_ vPC中的子网,并创建一个专用的安全组.

## 计量

存在帮助方法来访问共同域度量衡,例如:

```ts
declare const domain: es.Domain;
const freeStorageSpace = domain.metricFreeStorageSpace();
const masterSysMemoryUtilization = domain.metric('MasterSysMemoryUtilization');
```

这个模块是 [AWS 云开发套件](https://github.com/aws/aws-cdk) 项目.

## 精细的谷物出入控制

也可以通过配置主用户来创建域. 密码可以 如果不提供则提供或动态创建.

```ts
const domain = new es.Domain(this, 'Domain', {
  version: es.ElasticsearchVersion.V7_1,
  enforceHttps: true,
  nodeToNodeEncryption: true,
  encryptionAtRest: {
    enabled: true,
  },
  fineGrainedAccessControl: {
    masterUserName: 'master-user',
  },
});

const masterUserPassword = domain.masterUserPassword;
```

## 使用未签名的基本认证

为方便起见,可以配置域允许未签名的 HTTP 请求 使用基本的认证。 除非域配置为 VPC 的一部分 表示任何人可以使用所配置的主用户名访问域并 密码.

要启用未签名的基本认证访问, 域名配置为访问 策略允许任意请求, HTTPS 需要,节点到节点加密, 在休息时加密 和精细的进取控制.

如果以上设置没有设定, 将配置为启用的一部分 未签名的基本认证 。 如果它们设置为相冲突值,则错误是 抛出.

如果没有配置主用户,则创建默认主用户 用户名 `admin`。 。 。 .

如果没有配置密码,将创建默认主用户密码 存储在 AWS 机密管理器中作为秘密 。 秘密有前缀 `<domain id>MasterUser`。 。 。 .

```ts
const domain = new es.Domain(this, 'Domain', {
  version: es.ElasticsearchVersion.V7_1,
  useUnsignedBasicAuth: true,
});

const masterUserPassword = domain.masterUserPassword;
```

## 自定义准入政策

如果域名需要自定义访问控制,则可以配置为 建造者财产,或后来通过帮助方法.

对于简单的权限 `accessPolicies` 构造器可能足以:

```ts
const domain = new es.Domain(this, 'Domain', {
  version: es.ElasticsearchVersion.V7_1,
  accessPolicies: [
    new iam.PolicyStatement({
      actions: ['es:*ESHttpPost', 'es:ESHttpPut*'],
      effect: iam.Effect.ALLOW,
      principals: [new iam.AccountPrincipal('123456789012')],
      resources: ['*'],
    }),
  ]
});
```

例如,对于更为复杂的使用大小写,设置域名以接收来自 a [交叉账户 Kinesis Firehose](https://aws.amazon.com/premiumsupport/knowledge-center/kinesis-firehose-cross-account-streaming/) 页:1 `addAccessPolicies` 帮助方法 允许包含明确域 ARN 的政策.

```ts
const domain = new es.Domain(this, 'Domain', {
  version: es.ElasticsearchVersion.V7_1,
});

domain.addAccessPolicies(
  new iam.PolicyStatement({
    actions: ['es:ESHttpPost', 'es:ESHttpPut'],
    effect: iam.Effect.ALLOW,
    principals: [new iam.AccountPrincipal('123456789012')],
    resources: [domain.domainArn, `${domain.domainArn}/*`],
  }),
  new iam.PolicyStatement({
    actions: ['es:ESHttpGet'],
    effect: iam.Effect.ALLOW,
    principals: [new iam.AccountPrincipal('123456789012')],
    resources: [
      `${domain.domainArn}/_all/_settings`,
      `${domain.domainArn}/_cluster/stats`,
      `${domain.domainArn}/index-name*/_mapping/type-name`,
      `${domain.domainArn}/roletest*/_mapping/roletest`,
      `${domain.domainArn}/_nodes`,
      `${domain.domainArn}/_nodes/stats`,
      `${domain.domainArn}/_nodes/*/stats`,
      `${domain.domainArn}/_stats`,
      `${domain.domainArn}/index-name*/_stats`,
      `${domain.domainArn}/roletest*/_stat`,
    ],
  }),
);
```

## 审计记录

可以启用一个域的审计日志,但只有在启用了精细的访问控制后才能启用.

```ts
const domain = new es.Domain(this, 'Domain', {
  version: es.ElasticsearchVersion.V7_1,
  enforceHttps: true,
  nodeToNodeEncryption: true,
  encryptionAtRest: {
    enabled: true,
  },
  fineGrainedAccessControl: {
    masterUserName: 'master-user',
  },
  logging: {
    auditLogEnabled: true,
    slowSearchLogEnabled: true,
    appLogEnabled: true,
    slowIndexLogEnabled: true,
  },
});
```

## 超温

可以启用UltraWarm节点,提供成本效益高的方法来存储大量只读数据.

```ts
const domain = new es.Domain(this, 'Domain', {
  version: es.ElasticsearchVersion.V7_10,
  capacity: {
    masterNodes: 2,
    warmNodes: 2,
    warmInstanceType: 'ultrawarm1.medium.elasticsearch',
  },
});
```

## 自定义终点

自定义端点可以被配置到自定义域名下的ES域.

```ts
new es.Domain(this, 'Domain', {
  version: es.ElasticsearchVersion.V7_7,
  customEndpoint: {
    domainName: 'search.example.com',
  },
});
```

还可能指定一个自定义证书,而不是自动生成的证书.

此外,如果为自定义终点提供了主机区,则创建自动的 CNAME 记录

## 高级选项

[高级集群设置](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/createupdatedomains.html#createdomain-configure-advanced-options) 可用于配置额外选项.

```ts
new es.Domain(this, 'Domain', {
  version: es.ElasticsearchVersion.V7_7,
  advancedOptions: {
    'rest.action.multi.allow_explicit_index': 'false',
    'indices.fielddata.cache.size': '25',
    'indices.query.bool.max_clause_count': '2048',
  },
});
```

## 移动到 OpenSearch

从本单元迁移( E)`@aws-cdk/aws-elasticsearch`) 改为: `@aws-cdk/aws-opensearchservice` 模块,您必须修改您的 CDK 应用程序以引用新模块(包括一些相关的修改),然后执行 CloudFormation 资源删除/导入.

### 必要的 CDK 修改

对您的 CDK 应用程序作以下修改以迁移到 `@aws-cdk/aws-opensearchservice` 模块.

-   重写要使用的模块导入 `'@aws-cdk/aws-opensearchservice` 改为 `'@aws-cdk/aws-elasticsearch`。 。 。 . 例如:
    
    ```ts
    import * as es from '@aws-cdk/aws-elasticsearch';
    import { Domain } from '@aws-cdk/aws-elasticsearch';
    ```
    
    ...会...
    
    ```ts
    import * as opensearch from '@aws-cdk/aws-opensearchservice';
    import { Domain } from '@aws-cdk/aws-opensearchservice';
    ```
    
-   替换实例 `es.ElasticsearchVersion` 与 `opensearch.EngineVersion`。 。 。 . 例如:
    
    ```ts
    const version = es.ElasticsearchVersion.V7_1;
    ```
    
    ...会...
    
    ```ts
    const version = opensearch.EngineVersion.ELASTICSEARCH_7_1;
    ```
    
-   替换 `cognitoKibanaAuth` 财产 `DomainProps` 与 `cognitoDashboardsAuth`。 。 。 . 例如:
    
    ```ts
    new es.Domain(this, 'Domain', {
      cognitoKibanaAuth: {
        identityPoolId: 'test-identity-pool-id',
        userPoolId: 'test-user-pool-id',
        role: role,
      },
      version: elasticsearchVersion,
    });
    ```
    
    ...会...
    
    ```ts
    new opensearch.Domain(this, 'Domain', {
      cognitoDashboardsAuth: {
        identityPoolId: 'test-identity-pool-id',
        userPoolId: 'test-user-pool-id',
        role: role,
      },
      version: openSearchVersion,
    });
    ```
    
-   重写实例类型后缀 `.elasticsearch` 改为 `.search`。 。 。 . 例如:
    
    ```ts
    new es.Domain(this, 'Domain', {
      capacity: {
        masterNodeInstanceType: 'r5.large.elasticsearch',
      },
      version: elasticsearchVersion,
    });
    ```
    
    ...会...
    
    ```ts
    new opensearch.Domain(this, 'Domain', {
      capacity: {
        masterNodeInstanceType: 'r5.large.search',
      },
      version: openSearchVersion,
    });
    ```
    
-   任意 `CfnInclude`'d'域需要重新写入其原始模板 命令以成功方式列入 `opensearch.CfnDomain`
    

### 云层迁移

执行这些步骤以迁移您的应用程序而不丢失数据 :

-   确保 [删除政策](https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_core.RemovalPolicy.html) 设置为 `RemovalPolicy.RETAIN`。这是域建构的默认值,因此不需要任何内容,除非您已经将删除策略设置为其它的值.
-   通过手动修改用于创建 CloudFormation 堆栈的已合成模板,从您的 CloudFormation 堆栈中删除域资源 。 这也可能涉及修改或删除所依赖的资源,例如CDK为管理域的访问政策而创建的自定义资源,或者您已经连接到域上的任何其他资源. 您需要搜索每个域的逻辑ID的引用,以确定哪些其它资源引用,并替换或删除这些引用. 不删除属于域依赖性的资源,或在导入域前必须重新创建或导入. 修改后,通过AWS管理控制台或使用AWS CLI来部署堆栈.
-   移动您的 CDK 应用程序以使用新 `@aws-cdk/aws-opensearchservice` 模块,采用上述必要修改。 合成您的应用程序并获取由此产生的堆栈模板.
-   仅将域名定义从"移出"模板复制到您在上面部署的相应"被抽出"模板. [导入](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resource-import-existing-stack.html) 使用这些模板将孤儿域输入您的 CloudFormation 堆栈.
-   合成并部署您的 CDK 应用程序, 以重新配置/ 重建修改的依赖资源 。 CloudFormation堆栈现在应该包含与迁移前相同的资源.
-   继续正常发展!

## 常见问题

### @aws-cdk/aws-elasticsearch 是什么？

AWS: 弹性搜索的 CDK 构造库注意：该包已被作者标记为弃用——AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

### 如何安装 @aws-cdk/aws-elasticsearch？

在项目目录运行 npm install @aws-cdk/aws-elasticsearch，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@aws-cdk/aws-certificatemanager（1\.204\.0）、@aws-cdk/aws-cloudwatch（1\.204\.0）、@aws-cdk/aws-ec2（1\.204\.0）、@aws-cdk/aws-iam（1\.204\.0）、@aws-cdk/aws-kms（1\.204\.0）、@aws-cdk/aws-logs（1\.204\.0）、@aws-cdk/aws-route53（1\.204\.0）、@aws-cdk/aws-secretsmanager（1\.204\.0）、@aws-cdk/core（1\.204\.0）、@aws-cdk/custom-resources（1\.204\.0）、constructs（^3\.3\.69）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-cdk/aws-elasticsearch 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws-cdk/aws-elasticsearch 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws-cdk/aws-elasticsearch 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 14\.15\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aws-cdk/aws-elasticsearch 可以商用吗？

@aws-cdk/aws-elasticsearch 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-cdk/aws-elasticsearch 的下载量有多少？

根据 npm 官方下载统计，@aws-cdk/aws-elasticsearch 在 2026/10/07 – 2026/11/05 这 30 天内被下载 73,441 次，日均约 2,448 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws-cdk/aws-elasticsearch 还在维护吗？

最新版本 1\.204\.0 发布于 2023/06/20（3 年前）；至今共发布 288 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/07/31。作者已将其标记为弃用，新项目建议寻找替代方案。