AWS.OpenSearchServerless reference

AccessPolicy

Source: src/AWS/OpenSearchServerless/AccessPolicy.ts

An Amazon OpenSearch Serverless data access policy. Data access policies grant IAM principals fine-grained permissions on collections and their indexes (create/read/write/delete documents, create indexes, etc.) — they are the data-plane authorization layer that complements the network and encryption security policies.

A Bedrock Knowledge Base backed by an OpenSearch Serverless collection requires a data access policy granting the Knowledge Base’s service role aoss:APIAccessAll on the collection and its indexes.

AccessPolicy: Creating Access Policies

import * as AWS from "alchemy/AWS";

const access = yield* AWS.OpenSearchServerless.AccessPolicy("Access", {
  policyName: "my-collection-access",
  policy: [
    {
      Rules: [
        {
          ResourceType: "collection",
          Resource: ["collection/my-collection"],
          Permission: ["aoss:*"],
        },
        {
          ResourceType: "index",
          Resource: ["index/my-collection/*"],
          Permission: ["aoss:*"],
        },
      ],
      Principal: ["arn:aws:iam::123456789012:role/my-role"],
    },
  ],
});

BatchGetEffectiveLifecyclePolicy

Source: src/AWS/OpenSearchServerless/BatchGetEffectiveLifecyclePolicy.ts

Runtime binding for the BatchGetEffectiveLifecyclePolicy operation (IAM action aoss:BatchGetEffectiveLifecyclePolicy; the action does not support resource-level scoping, so the grant is on *).

Resolves which retention LifecyclePolicy is in effect for specific indexes (identified as index/{collection}/{index}). Indexes with no effective policy are reported in effectiveLifecyclePolicyErrorDetails. Provide the implementation with Effect.provide(AWS.OpenSearchServerless.BatchGetEffectiveLifecyclePolicyHttp).

BatchGetEffectiveLifecyclePolicy: Account Settings

const batchGetEffectiveLifecyclePolicy =
  yield* AWS.OpenSearchServerless.BatchGetEffectiveLifecyclePolicy();

const response = yield* batchGetEffectiveLifecyclePolicy({
  resourceIdentifiers: [
    { type: "retention", resource: "index/logs/app-logs" },
  ],
});
const effective = response.effectiveLifecyclePolicyDetails?.[0];
yield* Effect.log(`retention: ${effective?.retentionPeriod}`);

Collection

Source: src/AWS/OpenSearchServerless/Collection.ts

An Amazon OpenSearch Serverless collection — a group of OpenSearch indexes that scales OpenSearch Compute Units (OCUs) automatically. A collection of type VECTORSEARCH is the vector store required to back an Amazon Bedrock Knowledge Base.

A collection requires a matching encryption SecurityPolicy to exist before creation, plus a network security policy and a data AccessPolicy to be reachable and usable. Creation is asynchronous — the provider polls (bounded, ~5 minutes) until the collection reaches ACTIVE.

Collection: Creating Collections

import * as AWS from "alchemy/AWS";

const encryption = yield* AWS.OpenSearchServerless.SecurityPolicy("Enc", {
  policyName: "kb-enc",
  type: "encryption",
  policy: {
    Rules: [{ ResourceType: "collection", Resource: ["collection/kb"] }],
    AWSOwnedKey: true,
  },
});
const network = yield* AWS.OpenSearchServerless.SecurityPolicy("Net", {
  policyName: "kb-net",
  type: "network",
  policy: [
    {
      Rules: [
        { ResourceType: "collection", Resource: ["collection/kb"] },
        { ResourceType: "dashboard", Resource: ["collection/kb"] },
      ],
      AllowFromPublic: true,
    },
  ],
});
const collection = yield* AWS.OpenSearchServerless.Collection("KB", {
  collectionName: "kb",
  type: "VECTORSEARCH",
});
// collection.collectionEndpoint is the aoss data-plane endpoint

Collection: Search Collections

const collection = yield* AWS.OpenSearchServerless.Collection("Search", {
  collectionName: "logs",
  type: "SEARCH",
  description: "application logs",
});

CollectionGroup

Source: src/AWS/OpenSearchServerless/CollectionGroup.ts

An Amazon OpenSearch Serverless collection group. Collection groups manage OpenSearch Compute Units (OCUs) at a group level — multiple collections share the group’s capacity limits instead of each collection scaling independently.

CollectionGroup: Creating Collection Groups

import * as AWS from "alchemy/AWS";

const group = yield* AWS.OpenSearchServerless.CollectionGroup("Group", {
  groupName: "analytics",
  standbyReplicas: "DISABLED",
  capacityLimits: {
    maxIndexingCapacityInOCU: 4,
    maxSearchCapacityInOCU: 4,
  },
});

CreateIndex

Source: src/AWS/OpenSearchServerless/CreateIndex.ts

Runtime binding for the CreateIndex operation scoped to one collection (IAM action aoss:APIAccessAll on the collection ARN).

Creates an index in the bound Collection from inside a function runtime — the control-plane path for the multi-tenant pattern where each tenant gets its own (vector) index. The calling principal must also be granted aoss:CreateIndex on the index pattern by a data AccessPolicy. Provide the implementation with Effect.provide(AWS.OpenSearchServerless.CreateIndexHttp).

CreateIndex: Managing Indexes at Runtime

// init — bind the operation to the collection
const createIndex = yield* AWS.OpenSearchServerless.CreateIndex(collection);

// runtime
yield* createIndex({
  indexName: `tenant-${tenantId}`,
  indexSchema: {
    mappings: {
      properties: {
        embedding: { type: "knn_vector", dimension: 1536 },
      },
    },
  },
});

DeleteIndex

Source: src/AWS/OpenSearchServerless/DeleteIndex.ts

Runtime binding for the DeleteIndex operation scoped to one collection (IAM action aoss:APIAccessAll on the collection ARN).

Deletes an index from the bound Collection — the teardown half of the runtime multi-tenant pattern built with CreateIndex. Deleting an already-deleted index surfaces the typed ResourceNotFoundException. The calling principal must also be granted aoss:DeleteIndex on the index pattern by a data AccessPolicy. Provide the implementation with Effect.provide(AWS.OpenSearchServerless.DeleteIndexHttp).

DeleteIndex: Managing Indexes at Runtime

const deleteIndex = yield* AWS.OpenSearchServerless.DeleteIndex(collection);

yield* deleteIndex({ indexName: "tenant-42" }).pipe(
  Effect.catchTag("ResourceNotFoundException", () => Effect.void),
);

GetAccountSettings

Source: src/AWS/OpenSearchServerless/GetAccountSettings.ts

Runtime binding for the GetAccountSettings operation (IAM action aoss:GetAccountSettings; the action does not support resource-level scoping, so the grant is on *).

Reads the account-level OpenSearch Serverless settings — the OCU capacity limits that cap the account’s spend. Provide the implementation with Effect.provide(AWS.OpenSearchServerless.GetAccountSettingsHttp).

GetAccountSettings: Account Settings

const getAccountSettings = yield* AWS.OpenSearchServerless.GetAccountSettings();

const settings = yield* getAccountSettings();
const limits = settings.accountSettingsDetail?.capacityLimits;
yield* Effect.log(`max indexing OCUs: ${limits?.maxIndexingCapacityInOCU}`);

GetCollection

Source: src/AWS/OpenSearchServerless/GetCollection.ts

Runtime binding for the BatchGetCollection operation scoped to one collection (IAM action aoss:BatchGetCollection on the collection ARN).

Reads the bound Collection’s live detail — status, endpoints, KMS key — from inside a function runtime. Useful for discovering the data-plane collectionEndpoint at runtime. Provide the implementation with Effect.provide(AWS.OpenSearchServerless.GetCollectionHttp).

GetCollection: Inspecting Collections

// init — bind the operation to the collection
const getCollection = yield* AWS.OpenSearchServerless.GetCollection(collection);

// runtime
const detail = yield* getCollection();
yield* Effect.log(`${detail?.status}: ${detail?.collectionEndpoint}`);

GetIndex

Source: src/AWS/OpenSearchServerless/GetIndex.ts

Runtime binding for the GetIndex operation scoped to one collection (IAM action aoss:APIAccessAll on the collection ARN).

Reads an index’s schema definition from the bound Collection. A missing index surfaces the typed ResourceNotFoundException. The calling principal must also be granted aoss:DescribeIndex on the index pattern by a data AccessPolicy. Provide the implementation with Effect.provide(AWS.OpenSearchServerless.GetIndexHttp).

GetIndex: Managing Indexes at Runtime

const getIndex = yield* AWS.OpenSearchServerless.GetIndex(collection);

const { indexSchema } = yield* getIndex({ indexName: "tenant-42" });

GetPoliciesStats

Source: src/AWS/OpenSearchServerless/GetPoliciesStats.ts

Runtime binding for the GetPoliciesStats operation (IAM action aoss:GetPoliciesStats; the action does not support resource-level scoping, so the grant is on *).

Returns counts of the account’s access policies, security policies, security configurations, and lifecycle policies — useful for quota dashboards (each policy type has an account quota). Provide the implementation with Effect.provide(AWS.OpenSearchServerless.GetPoliciesStatsHttp).

GetPoliciesStats: Account Settings

const getPoliciesStats = yield* AWS.OpenSearchServerless.GetPoliciesStats();

const stats = yield* getPoliciesStats();
yield* Effect.log(`total policies: ${stats.TotalPolicyCount}`);

LifecyclePolicy

Source: src/AWS/OpenSearchServerless/LifecyclePolicy.ts

An Amazon OpenSearch Serverless data lifecycle policy. Retention lifecycle policies control how long documents are retained in the indexes matched by the policy’s resource patterns — OpenSearch Serverless automatically deletes documents older than the configured MinIndexRetention.

Lifecycle policies are free, provision instantly, and are matched to indexes by resource pattern (e.g. index/my-collection/*) — the collection does not need to exist when the policy is created.

LifecyclePolicy: Creating Lifecycle Policies

Retain Log Indexes for 30 Days

import * as AWS from "alchemy/AWS";

const retention = yield* AWS.OpenSearchServerless.LifecyclePolicy("Retention", {
  policyName: "logs-retention",
  policy: {
    Rules: [
      {
        ResourceType: "index",
        Resource: ["index/logs/*"],
        MinIndexRetention: "30d",
      },
    ],
  },
});

Unlimited Retention for Specific Indexes

const keepForever = yield* AWS.OpenSearchServerless.LifecyclePolicy("KeepForever", {
  policyName: "audit-retention",
  policy: {
    Rules: [
      {
        ResourceType: "index",
        Resource: ["index/audit/*"],
        NoMinIndexRetention: true,
      },
    ],
  },
});

SecurityConfig

Source: src/AWS/OpenSearchServerless/SecurityConfig.ts

An Amazon OpenSearch Serverless security configuration. Security configurations federate OpenSearch Dashboards sign-in with SAML identity providers, AWS IAM Identity Center, or IAM federation, so human users can access collections without IAM credentials.

The configuration’s configId (format saml/{accountId}/{name}) is what a data AccessPolicy references as a Principal to grant the federated identities index- and collection-level permissions.

SecurityConfig: SAML Authentication

import * as AWS from "alchemy/AWS";

const saml = yield* AWS.OpenSearchServerless.SecurityConfig("Saml", {
  configName: "my-idp",
  type: "saml",
  samlOptions: {
    metadata: idpMetadataXml,
    groupAttribute: "groups",
    sessionTimeout: "4 hours",
  },
});
// Reference saml.configId as a Principal in a data access policy

SecurityConfig: IAM Federation

const federation = yield* AWS.OpenSearchServerless.SecurityConfig("Federation", {
  configName: "my-federation",
  type: "iamfederation",
  iamFederationOptions: {
    userAttribute: "user",
    groupAttribute: "groups",
  },
});

SecurityPolicy

Source: src/AWS/OpenSearchServerless/SecurityPolicy.ts

An Amazon OpenSearch Serverless security policy. Security policies govern encryption at rest (encryption) and network access (network) for one or more collections, matched by a resource pattern such as collection/my-collection.

An encryption policy is a prerequisite for every collection — a collection whose name is not covered by an encryption policy fails to create. A network policy controls whether the collection’s data and OpenSearch Dashboards endpoints are reachable from public networks or only from specific VPC endpoints.

SecurityPolicy: Encryption Policies

import * as AWS from "alchemy/AWS";

const encryption = yield* AWS.OpenSearchServerless.SecurityPolicy("Encryption", {
  policyName: "my-collection-enc",
  type: "encryption",
  policy: {
    Rules: [{ ResourceType: "collection", Resource: ["collection/my-collection"] }],
    AWSOwnedKey: true,
  },
});

SecurityPolicy: Network Policies

const network = yield* AWS.OpenSearchServerless.SecurityPolicy("Network", {
  policyName: "my-collection-net",
  type: "network",
  policy: [
    {
      Rules: [
        { ResourceType: "collection", Resource: ["collection/my-collection"] },
        { ResourceType: "dashboard", Resource: ["collection/my-collection"] },
      ],
      AllowFromPublic: true,
    },
  ],
});

UpdateAccountSettings

Source: src/AWS/OpenSearchServerless/UpdateAccountSettings.ts

Runtime binding for the UpdateAccountSettings operation (IAM action aoss:UpdateAccountSettings; the action does not support resource-level scoping, so the grant is on *).

Updates the account-level OCU capacity limits — the cost-control automation path (e.g. a budget alarm handler capping search capacity). Provide the implementation with Effect.provide(AWS.OpenSearchServerless.UpdateAccountSettingsHttp).

UpdateAccountSettings: Account Settings

const updateAccountSettings = yield* AWS.OpenSearchServerless.UpdateAccountSettings();

yield* updateAccountSettings({
  capacityLimits: { maxSearchCapacityInOCU: 4 },
});

UpdateIndex

Source: src/AWS/OpenSearchServerless/UpdateIndex.ts

Runtime binding for the UpdateIndex operation scoped to one collection (IAM action aoss:APIAccessAll on the collection ARN).

Updates an index’s schema in the bound Collection — add new fields or change field mappings at runtime. The calling principal must also be granted aoss:UpdateIndex on the index pattern by a data AccessPolicy. Provide the implementation with Effect.provide(AWS.OpenSearchServerless.UpdateIndexHttp).

UpdateIndex: Managing Indexes at Runtime

const updateIndex = yield* AWS.OpenSearchServerless.UpdateIndex(collection);

yield* updateIndex({
  indexName: "tenant-42",
  indexSchema: {
    mappings: { properties: { title: { type: "text" } } },
  },
});

VpcEndpoint

Source: src/AWS/OpenSearchServerless/VpcEndpoint.ts

An Amazon OpenSearch Serverless-managed interface VPC endpoint. Creating one lets resources in a VPC reach a collection privately (without traversing the public internet), and lets a network SecurityPolicy restrict a collection’s access to only that endpoint. Creation is asynchronous — the provider polls (bounded) until the endpoint reaches ACTIVE.

VpcEndpoint: Creating VPC Endpoints

import * as AWS from "alchemy/AWS";

const endpoint = yield* AWS.OpenSearchServerless.VpcEndpoint("Endpoint", {
  endpointName: "my-endpoint",
  vpcId: vpc.vpcId,
  subnetIds: [subnet.subnetId],
  securityGroupIds: [securityGroup.groupId],
});