# Prerequisites and permissions required for using OpenSearch Managed Clusters with Amazon Bedrock Knowledge Bases Prerequisites for OpenSearch Managed Clusters This section shows you how to configure permissions if you're creating your own vector database with Amazon OpenSearch Service Managed Clusters. This configuration must be performed before you create the knowledge base. The steps assume that you've already created a domain and vector index in Amazon OpenSearch Service. For more information, see [Creating and managing OpenSearch Service domains](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/createupdatedomains.html) in the *Amazon OpenSearch Service developer guide*. ## Key considerations Following are some key considerations for using Amazon Bedrock Knowledge Bases with Amazon OpenSearch Service Managed Clusters. + Before using any domain resources in OpenSearch Managed clusters, you need to configure certain IAM access permissions and policies. For Knowledge Bases integration with Managed clusters, before you perform the steps in this section, if your domain has a restrictive access policy, you must grant the required IAM access and configure the resource-based policies. We also recommend that you configure fine-grained access control to scope down the permissions. + When ingesting the data for your knowledge base, if you encounter failures, it might indicate an insufficient OpenSearch domain capacity to handle the speed of ingestion. To resolve this issue, increase your domain's capacity by provisioning higher IOPS (Input/Output Operations Per Second) and by increasing the throughput settings. Wait for several minutes for the new capacity to be provisioned and then retry the ingestion process. To verify that the issue has been resolved, you can monitor the performance during the retry process. If throttling still persists, you may need to further adjust capacity for improved efficiency. For more information, see [Operational best practices for Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/bp.html). ## Overview of permissions configuration For Knowledge Bases integration with managed clusters, you need to configure the following IAM access permissions and resource-based policies. We recommend that you enable fine-grained access policies to further control the user access and the granularity at which it must be scoped down to the property level. The following steps provide a high-level overview for how to configure permissions. 1. **Create and use Knowledge base service role** For the permissions that you want to configure, while you can still provide your own custom role, we recommend that you specify the option for Amazon Bedrock Knowledge Bases to create the Knowledge base service role for you. 1. **Configure the resource-based policy** The OpenSearch domain supports resource-based policies, that determine which principals can access and act on the domain. To use with Knowledge Bases, ensure proper configuration of the resource-based policy for your domain. 1. ***(Strongly Recommended)* Provide role mapping for fine-grained access control** While fine-grained access control is optional, we recommend that you have it enabled for controlling the granularity at which the permissions must be scoped down at the property level. ## Configuring IAM policies Your domain's access policy must grant the permissions to perform the required OpenSearch API actions by the roles in your account. If your domain has a restrictive access policy, then it might need to be updated as follows: + It should grant access to Amazon Bedrock service and include the required HTTP actions: `GET`, `POST`, `PUT`, and `DELETE`. + It must also grant Amazon Bedrock permissions to perform the `es:DescribeDomain` action on your index resource. This allows Amazon Bedrock Knowledge Bases to perform the required validations when configuring a knowledge base. ## (Optional) Fine-grained access control Fine-grained access control can control the granularity at which the permissions must be scoped down at the property levelYou can configure the fine-grained access policies, to grant the read-write permissions required to the service role created by Knowledge Bases. To configure fine-grained access control and provide the role mapping: 1. Make sure that the OpenSearch domain that you created has fine-grained access control enabled. 1. Create an OpenSearch UI (Dashboards), if you haven't already. This will be used to configure the role mapping 1. In your OpenSearch Dashboards, create an OpenSearch role and specify the vector index name, and the cluster and index permissions. To add the permissions, you must create permission groups and then add the required permissions that grant access to perform a set of operations including `delete`, `search`, `get`, and `index` for the role. 1. After you've added the required permissions, you must enter the ARN of your Knowledge base service role for the OpenSearch back-end role. Performing this step will complete the mapping between your Knowledge Base Service role and the OpenSearch role, which then grants Amazon Bedrock Knowledge Bases permissions to access the vector index in the OpenSearch domain and perform the required operations. **Topics** + [ ## Key considerations ](#kb-osm-permissions-prereq-considerations) + [ ## Overview of permissions configuration ](#kb-osm-permissions-prereq-overview) + [ ## Configuring IAM policies ](#kb-osm-permissions-iam) + [ ## (Optional) Fine-grained access control ](#kb-osm-permissions-console-fgap) + [ # Configuring resource-based policies for OpenSearch Managed clusters ](kb-osm-permissions-slr-rbp.md) + [ # Configuring OpenSearch permissions with fine-grained access control ](kb-osm-permissions-console-fgap.md) # Configuring resource-based policies for OpenSearch Managed clusters When creating your knowledge base, you can either create your own custom role or let Amazon Bedrock create one for you. How you configure the permissions depend on whether you're creating a new role or using an existing role. If you already have an existing IAM role, you must ensure that your domain's access policy does not prevent the roles in your account from performing the necessary OpenSearch API actions. If you are choosing to let Amazon Bedrock Knowledge Bases create the IAM role for you, you must ensure that your domain's access policy grants the permissions to perform the required OpenSearch API actions by the roles in your account. If your domain has a restrictive access policy, it can prevent your role from performing these actions. Following shows an example of a restrictive resource-based policy. In this case, you can either: + Create your knowledge base using an existing IAM role that your OpenSearch domain can grant access to this role for performing the necessary operations. + Alternatively, you can let Amazon Bedrock create a new role for you. In this case, you must ensure that the domain's access policy must grant the permissions to perform the necessary OpenSearch API actions by the roles in your account. The following sections show a sample IAM policy that grants the necessary permissions and how you can update the domain's access policy so that it grants permissions to perform the necessary OpenSearch API operations. **Topics** + [ ## Sample IAM identity-based and resource-based policies ](#kb-osm-permissions-iam) + [ ## Creating the Amazon Bedrock Knowledge Bases service role ](#kb-osm-permissions-slr) + [ ## Updating the resource-based policies ](#kb-osm-permissions-console-rbp) ## Sample IAM identity-based and resource-based policies This section provides a sample identity policy and a resource-based policy that you can configure for your OpenSearch domain when integrating with Amazon Bedrock Knowledge Bases. You must grant Amazon Bedrock permissions to perform these actions on the index that you provide your Knowledge Base. **** | Action | Resource | Description | | --- | --- | --- | | es:ESHttpPost | arn::es:::domain// | For inserting information to the index | | es:ESHttpGet | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/bedrock/latest/userguide/kb-osm-permissions-slr-rbp.html) | For searching information from the index. This action is configured at both the at both the domain/index level and the domain/index/\$1 level. At the domain/index level, it can get high level details about the index, such as the engine type. To retrieve details stored within the index, permissions are required at the domain/index/\$1 level. | | es:ESHttpHead | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/bedrock/latest/userguide/kb-osm-permissions-slr-rbp.html) | For getting information from the index. This action is configured at both the at both the domain/index level and the domain/index/\$1 level, in case information needs to be obtained at a higher level, such as whether a particular index exists. | | es:ESHttpDelete | arn::es:::domain// | For deleting information to the index | | es:DescribeDomain | arn::es:::domain/ | For performing validations on the domain, such as the engine version used. | ### Sample identity-based policy ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "OpenSearchIndexAccess", "Effect": "Allow", "Action": [ "es:ESHttpGet", "es:ESHttpPost", "es:ESHttpPut", "es:ESHttpDelete" ], "Resource": [ "arn:aws:es:us-east-1:123456789012:domain/domainName/indexName/*" ] }, { "Sid": "OpenSearchIndexGetAccess", "Effect": "Allow", "Action": [ "es:ESHttpGet", "es:ESHttpHead" ], "Resource": [ "arn:aws:es:us-east-1:123456789012:domain/domainName/indexName" ] }, { "Sid": "OpenSearchDomainValidation", "Effect": "Allow", "Action": [ "es:DescribeDomain" ], "Resource": [ "arn:aws:es:us-east-1:123456789012:domain/domainName" ] } ] } ``` ------ ### Sample resource-based policy **Note** Make sure that the service role has been created for it to be used in the resource-based policy. ## Creating the Amazon Bedrock Knowledge Bases service role When you create the knowledge base, you can choose the option to create and use a new service role. This section walks you through creating the Amazon Bedrock Knowledge Bases service role. By mapping the resource-based policies and the fine-grained access policies to this role, it will grant Amazon Bedrock the permissions to make requests to the OpenSearch domain. **To specify the Amazon Bedrock Knowledge Bases service role:** 1. In the Amazon Bedrock console, go to [Knowledge Bases](https://console.aws.amazon.com/bedrock/home#/knowledge-bases). 1. Choose **Create** and then choose **Knowledge base with vector store**. 1. Choose **Create and use a new service role**. You can either use the default, or provide a custom role name, and Amazon Bedrock will automatically create the Knowledge Base service role for you. 1. Continue going through the console to configure your data source and parsing and chunking strategies. 1. Choose an Embeddings model and then, under **Choose an existing vector store**, choose **Amazon OpenSearch Managed Cluster**. **Important** Before you proceed to create the knowledge base, complete the following steps to configure the resource-based policies and fine-grained access policies. For detailed steps on creating the knowledge base, see [Create a knowledge base by connecting to a data source in Amazon Bedrock Knowledge Bases](knowledge-base-create.md). ## Updating the resource-based policies If your OpenSearch domain has a restrictive access policy, you can follow the instructions on this page to update the resource-based policy. These permissions allow Knowledge Bases to make use of the index that you provide, and to retrieve the OpenSearch domain definition to perform the required validation on the domain. **To configure the resource-based policies from the AWS Management Console** 1. Go to the [Amazon OpenSearch Service console](https://console.aws.amazon.com/aos/home?region=us-east-1#opensearch/dashboard). 1. Go to the domain that you had created, and then go to **Security Configurations** where the resource-based policy is configured. 1. Edit the policy in the **JSON** tab and then update the policy similar to the [Sample resource-based policy](#kb-osm-permissions-rbp). 1. You can now go back to the Amazon Bedrock console and provide the details for your OpenSearch domain and index as described in [Knowledge base setup for Managed Clusters](knowledge-base-setup.md#knowledge-base-setup-osm). # Configuring OpenSearch permissions with fine-grained access control While optional, we strongly recommend that you enable fine-grained access control for your OpenSearch domain. Using fine-grained access control, you can use role-based access control, which enables you to create an OpenSearch role with specific permissions and map it to the Knowledge Base service role. The mapping grants your knowledge base the minimum required permissions that allows it to access and perform operations on the OpenSearch domain and index. To configure and use fine-access control: 1. Make sure that the OpenSearch domain that you're using has fine-grained access control enabled. 1. For your domain that uses fine-grained access control, configure permissions with scoped-down policies in the form of an OpenSearch role. 1. For the domain that you create a role for, add a role mapping to the Knowledge Base Service role. The following steps show how how to configure your OpenSearch role and ensure the correct mapping between the OpenSearch role and the Knowledge Base service role. **To create an OpenSearch role and configure permissions** After you have enabled fine-grained access control and configured Amazon Bedrock to connect to the OpenSearch Service, you can configure permissions using the OpenSearch Dashboards link for each OpenSearch domain. **To configure permissions for a domain to allow access to Amazon Bedrock:** 1. Open the OpenSearch Dashboard for the OpenSearch domain that you want to work with. To find the link to Dashboards, go to the domain that you created in the OpenSearch Service console. For domains running OpenSearch, the URL is of the format, `domain-endpoint/_dashboards/`. For more information, see [Dashboards](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/dashboards.html) in the *Amazon OpenSearch Service developer guide*. 1. In the OpenSearch Dashboard, choose **Security** and then choose **Roles**. 1. Choose **Create role**. 1. Provide any name for the role, for example, **kb\$1opensearch\$1role**. 1. Under **Cluster permissions**, add the following permissions. + `indices:data/read/msearch` + `indices:data/write/bulk*` + `indices:data/read/mget*` 1. Under **Index permissions**, provide a name for the vector index. Choose **Create new permission group**, and then choose **Create new action group**. Add the following permissions to an action group, such as `KnowledgeBasesActionGroup`. Add the following permissions to an action group. + `indices:admin/get` + `indices:data/read/msearch` + `indices:data/read/search` + `indices:data/write/index` + `indices:data/write/update` + `indices:data/write/delete` + `indices:data/write/delete/byquery` + `indices:data/write/bulk*` + `indices:admin/mapping/put` + `indices:data/read/mget*` ![\[The action groups to create in OpenSearch Dashboards for adding cluster and index permissions.\]](http://docs.aws.amazon.com/bedrock/latest/userguide/images/kb/kb-test-os-action-groups.png) 1. Choose **Create** to create the OpenSearch role. The following shows a sample OpenSearch role with the permissions added. ![\[A sample OpenSearch role in OpenSearch Dashboards with the permissions added.\]](http://docs.aws.amazon.com/bedrock/latest/userguide/images/kb/kb-test-os-dashboards-permissions.png) **To create a role mapping to your Knowledge Base service role** 1. Identify the IAM role that will need to be mapped. + If you created your own custom IAM role, you can copy the role ARN for this role from the IAM console. + If you are allowing Knowledge Bases to create the role for you, you can make note of the role ARN when creating your knowledge base, and then copy this role ARN. 1. Open the OpenSearch Dashboard for the OpenSearch domain that you want to work with. The URL is of the format, `domain-endpoint/_dashboards/`. 1. Choose **Security** from the navigation pane. 1. Search for the role that you just created from the list, for example, **kb\$1opensearch\$1role**, and open it. 1. On the **Mapped Users** tab, choose **Manage mapping** 1. In the **Backend roles** section, enter the ARN of the AWS managed IAM role for Knowledge Bases. Depending on whether you created your own custom role or let Knowledge Bases create the role for you, copy the role ARN information from the IAM console or the Amazon Bedrock console, and then enter that information for the **Backend roles** in the OpenSearch console. Following is an example. ``` arn:aws:iam:::role/service-role/ ``` 1. Choose **Map**. The Knowledge Base Service role can now connect to the OpenSearch role and perform the required operations on the domain and index.