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

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

版本：1\.204\.0
npm 元数据更新时间：2023-11-21T10:16:32.527Z
中文译文更新时间：2026-11-07T14:48:17.441Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk/aws-opensearchservice
原文对照：https://npmcn.com/package/%40aws-cdk/aws-opensearchservice/?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.2 MB，23 个文件
- 模块格式：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
- 首次发布：2021-09-17T02:34:25.759Z
- 最新版本发布：2023-06-19T21:09:35.606Z
- 近 30 天下载量：14496（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：93（近 12 个月 0 个）

## 中文简介

AWS 的 CDK 构建库: OpenSearch Service

## 安装

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

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

## README

# 亚马逊 OpenSearch 服务构建库

* * *

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

> AWS CDK v1在2023-06-01上达到了支持结束. 此软件包不再更新,用户应该迁移到 AWS CDK v2.
> 
> 关于如何移徙的更多信息,请参见: [_移动到 AWS CDK v2_ 指南](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html)。 。 。 .

* * *

| 特征 | 稳定 |
| --- | --- |
| CFN 资源 | ![Stable](https://img.shields.io/badge/stable-success.svg?style=for-the-badge) |
| 域名更高层次的构造 | ![Stable](https://img.shields.io/badge/stable-success.svg?style=for-the-badge) |

> **CFN 资源:** 所有课程与 `Cfn` 此模块中的前缀( n)[CFN 资源](https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib)总是 稳定安全使用.

> **稳定 :** 本单元中标出稳定的更高层次的构造将不进行任何 打破更改。 他们将严格遵循 [语义版本](https://semver.org/) 型号.

* * *

见 [移动到 OpenSearch](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-elasticsearch-readme.html#migrating-to-opensearch) 移民指令 `@aws-cdk/aws-elasticsearch` 至本单元, `@aws-cdk/aws-opensearchservice`。 。 。 .

## 快开始

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

```ts
const devDomain = new opensearch.Domain(this, 'Domain', {
  version: opensearch.EngineVersion.OPENSEARCH_1_0,
});
```

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

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

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

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

这创建了 Amazon OpenSearch 服务集群,并自动设置日志组 记录域日志并慢取搜索日志.

## 关于 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 OpenSearch Service...
```

为了解决这个问题,你需要 [创建](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, 'Service Linked Role', {
  awsServiceName: 'es.amazonaws.com',
});
```

## 导入已存在的域

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

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

## 权限

### 行政会议

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

```ts
declare const fn: lambda.Function;
declare const domain: opensearch.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 opensearch.Domain(this, 'Domain', {
  version: opensearch.EngineVersion.OPENSEARCH_1_0,
  ebs: {
    volumeSize: 100,
    volumeType: ec2.EbsDeviceVolumeType.GENERAL_PURPOSE_SSD,
  },
  nodeToNodeEncryption: true,
  encryptionAtRest: {
    enabled: true,
  },
});
```

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

## VPC 支持

域可以放入VPC内,提供亚马逊OpenSearch Service与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: opensearch.DomainProps = {
  version: opensearch.EngineVersion.OPENSEARCH_1_0,
  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 opensearch.Domain(this, 'Domain', domainProps);
```

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

## 计量

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

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

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

## 精细的谷物出入控制

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

```ts
const domain = new opensearch.Domain(this, 'Domain', {
  version: opensearch.EngineVersion.OPENSEARCH_1_0,
  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 opensearch.Domain(this, 'Domain', {
  version: opensearch.EngineVersion.OPENSEARCH_1_0,
  useUnsignedBasicAuth: true,
});

const masterUserPassword = domain.masterUserPassword;
```

## 自定义准入政策

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

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

```ts
const domain = new opensearch.Domain(this, 'Domain', {
  version: opensearch.EngineVersion.OPENSEARCH_1_0,
  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 opensearch.Domain(this, 'Domain', {
  version: opensearch.EngineVersion.OPENSEARCH_1_0,
});
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 opensearch.Domain(this, 'Domain', {
  version: opensearch.EngineVersion.OPENSEARCH_1_0,
  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 opensearch.Domain(this, 'Domain', {
  version: opensearch.EngineVersion.OPENSEARCH_1_0,
  capacity: {
    masterNodes: 2,
    warmNodes: 2,
    warmInstanceType: 'ultrawarm1.medium.search',
  },
});
```

## 自定义终点

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

```ts
new opensearch.Domain(this, 'Domain', {
  version: opensearch.EngineVersion.OPENSEARCH_1_0,
  customEndpoint: {
    domainName: 'search.example.com',
  },
});
```

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

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

## 高级选项

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

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

## 常见问题

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

AWS 的 CDK 构建库: OpenSearch Service注意：该包已被作者标记为弃用——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-opensearchservice？

在项目目录运行 npm install @aws-cdk/aws-opensearchservice，或使用 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-opensearchservice 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

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

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