# Creating and Managing Amazon CloudSearch Domains A search domain encapsulates the data you want to search, indexing options that control how you can search the data and what information you can retrieve from your search domain, and the search instances that index your data and process search requests. You can [create](creating-domains.md), [monitor](monitoring-domains.md), and [delete](deleting-domains.md) domains using the Amazon CloudSearch console, AWS CLI, or AWS SDKs. All domain management actions are implemented by the Amazon CloudSearch configuration service. For more information, see the [Configuration API Reference for Amazon CloudSearch](configuration-api.md). **Topics** + [Creating an Amazon CloudSearch Domain](creating-domains.md) + [configure access policies](configuring-access.md) + [Configuring Scaling Options in Amazon CloudSearch](configuring-scaling-options.md) + [Configuring Availability Options in Amazon CloudSearch](configuring-availability-options.md) + [Configuring Domain Endpoint Options in Amazon CloudSearch](configuring-domain-endpoint-options.md) + [Monitoring Amazon CloudSearch Domains](monitoring-domains.md) + [Deleting an Amazon CloudSearch Domain](deleting-domains.md) + [Tagging Amazon CloudSearch Domains](tagging-cloudsearch-domains.md) # Creating an Amazon CloudSearch Domain To search your data with Amazon CloudSearch, the first thing you need to do is create a search domain. If you have multiple collections of data that you want to make searchable, you can create multiple search domains. Before you can [send search requests](searching.md) to a new domain, you must also [configure access policies](configuring-access.md), [configure index fields](configuring-index-fields.md), and [upload the data you want to search](uploading-data.md). When you create a search domain, you must give it a unique name. Domain names must start with a letter or number and be at least 3 and no more than 28 characters long. The allowed characters are: a-z, 0-9, and hyphen (-). Upper case letters, underscores (\$1), and other special characters are not allowed in domain names. By default, all new domains are created using the 2013-01-01 API version. If you have previously created search domains with the 2011-02-01 API version, you can opt to use the old API for your new domain. However, we recommend using the 2013-01-01 API for all new use cases. All domains will need to migrate to the 2013-01-01 API when the 2011-02-01 API is retired. You can choose the AWS region where you want to create your search domain. Typically, you should choose the region closest to your operations. For example, if you reside in Europe, create your search domain in the Europe (Ireland) region (eu-west-1). For a current list of supported regions and endpoints, see [Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html). For more information about choosing a region, see [Regions and Endpoints for Amazon CloudSearch](what-is-cloudsearch.md#endpoints). **Note** Amazon CloudSearch domains in different regions are entirely independent. For example, if you create a search domain called *my-domain* in us-east-1, and another domain called *my-domain* in eu-west-1, they are completely independent and do not share any data. Each search domain has unique endpoints through which you upload data for indexing and submit search requests. A domain's document and search endpoints remain the same for the life of the domain. For example, the endpoints for a domain called imdb-movies might be: ``` doc-imdb-movies-nypdffbzrfkoudsurkxvgwbpi4.us-east-1.cloudsearch.amazonaws.com search-imdb-movies-nypdffbzrfkoudsurkxvgwbpi4.us-east-1.cloudsearch.amazonaws.com ``` **Important** By default, access to a new domain's document and search endpoints is blocked for all IP addresses. You must configure access policies for the domain to be able to submit search requests to the domain's search endpoint and upload data from the command line or through the domain's document endpoint. You can upload documents and search the domain through the Amazon CloudSearch console without configuring access policies. You can create a search domain from the [Amazon CloudSearch console](#create-domain-console), using the `aws cloudsearch create-domain` command, or using one of the AWS SDKs. **Topics** + [Amazon CloudSearch console](#create-domain-console) + [create-domain](#create-domain-clt) + [Creating an Amazon CloudSearch Domain Using the AWS SDKs](#create-domain-sdk) ## Creating a Domain Using the Amazon CloudSearch Console The Amazon CloudSearch console enables you to easily create new search domains and provides a variety of options for configuring indexing options. **To create a domain** 1. Sign in to the AWS Management Console and open the Amazon CloudSearch console at [https://console.aws.amazon.com/cloudsearch/home](https://console.aws.amazon.com/cloudsearch/home). 1. Choose **Create domain**. 1. Enter a name for your new domain. Domain names must start with a letter or number and be at least 3 and no more than 28 characters long. Domain names can contain the following characters: a-z (lower case), 0-9, and - (hyphen). Upper case letters, underscores (\$1), and other special characters are not allowed in domain names. Optionally, you can set the **Desired instance type** and **Desired replication count** to prescale your domain. For more information, see [Configuring Scaling Options in Amazon CloudSearch](configuring-scaling-options.md). 1. Choose **Next**. 1. In the configuring options, select **Manual configuration** and choose **Next**. 1. Configure the index fields for the domain. For instructions, see [Configuring Index Fields](configuring-index-fields.md). 1. Choose **Next**. 1. Configure the domain access policy. For instructions, see [Configuring Access for Amazon CloudSearch](configuring-access.md). **Note** Until you configure access policies, you will only be able to upload documents and submit search queries through the console. By default, the document and search endpoints are configured to block all IP addresses. 1. Choose **Next**. 1. Review the domain configuration and choose **Create**. The domain's document and search service endpoints are displayed on the domain dashboard when the domain becomes active. At that point, you can upload documents for indexing and start searching your data. ## Creating a Domain Using the AWS CLI You use the `aws cloudsearch create-domain` command to create search domains. For information about installing and setting up the AWS CLI, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/). **To create a domain** + Run the `aws cloudsearch create-domain` command and specify the name of the domain you want to create with the `--domain-name` option. For example, to create a domain called *movies*: **Example** ``` aws cloudsearch create-domain --domain-name movies { "DomainStatus": { "DomainId": "965407640801/movies", "Created": true, "Deleted": false, "SearchInstanceCount": 0, "DomainName": "movies", "SearchService": {}, "RequiresIndexDocuments": false, "Processing": false, "DocService": {}, "ARN": "arn:aws:cloudsearch:us-east-1:965407640801:domain/movies", "SearchPartitionCount": 0 } } ``` The `aws cloudsearch create-domain` command returns immediately. It takes about ten minutes to create endpoints for a new domain. You can use the `aws cloudsearch describe-domains` command to view a summary of the domain's status and configuration. For more information, see [Getting Information About an Amazon CloudSearch Domain](getting-domain-info.md). **Important** Once a domain's endpoints are active, they remain the same for the life of the domain. You should cache the endpoints—there's no need to query for the endpoint before submitting a document or search service request and doing so is likely to result in your requests being throttled. ## Creating an Amazon CloudSearch Domain Using the AWS SDKs The AWS SDKs (except the Android and iOS SDKs) support all of the Amazon CloudSearch actions defined in the Amazon CloudSearch Configuration API, including `CreateDomain`. For more information about installing and using the AWS SDKs, see [AWS Software Development Kits](http://aws.amazon.com/code). # Configuring Access for Amazon CloudSearch You use AWS Identity and Access Management (IAM) access policies to control access to the Amazon CloudSearch configuration service and each search domain's document, search, and suggest services. An IAM access policy is a JSON document that explicitly lists permissions that define what actions people or processes are allowed to perform. For an introduction to IAM access policies, see [Overview of AWS IAM Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/PoliciesOverview.html). You control access to the Amazon CloudSearch configuration service APIs and the domain services APIs independently. For example, you might choose to restrict who can modify the configuration of your production domain, but allow team members to create and manage their own domains for development and testing. Similarly, you might configure your development and test domains to accept anonymous requests to the upload, search, and suggest services, but lock down your production domain so that it accepts only authenticated requests from your application. When AWS receives a request, it authenticates that the request is from a known AWS user, and then checks relevant policies to determine whether the user is authorized to perform the requested actions using the requested resources. If a user has not been explicitly granted permission to perform an action, the request is denied. During policy evaluation, if AWS encounters an explicit deny, the deny effect takes precedence over any explicit allow effects that are in force. **Important** To enable authentication, Amazon CloudSearch requests must be signed with an access key. The only exception is if you allow anonymous access to a domain's upload, search, or suggest services. For more information, see [Signing RequestsFrequently asked questions](what-is-cloudsearch.md#signing-requests). **Topics** + [Writing Access Policies for Amazon CloudSearch](#cloudsearch-access-policies) + [Amazon CloudSearch Policy Examples](#policy-examples) + [Amazon CloudSearch console](#configuring-access-console) + [Configuring Access for Amazon CloudSearch with the AWS CLI](#configuring-access-clt) + [Configuring Access to a Domain's Endpoints Using the AWS SDKs](#configuring-access-sdk) ## Writing Access Policies for Amazon CloudSearch Amazon CloudSearch supports both *user-based policies* and *resource-based policies*: + **User-based policies** are attached to a particular IAM role, group, or user. A user-based policy specifies which of your account's search domains a person or process can access and what actions they can perform. To attach a user-based policy to a user, group, or role, you use the IAM console, AWS CLI, or AWS SDKs. **You must define user-based policies to control access to the Amazon CloudSearch configuration service actions.** (The *user* in this context isn't necessarily a person, it's just an identity with associated permissions. For example, you might create a user to represent an application that needs to have credentials to submit search requests to your domain.) + **Resource-based policies** for Amazon CloudSearch are attached to a particular search domain. A resource-based policy specifies who has access to the search domain and which domain services they can use. Resource-based policies control access only to a particular domain's document, search, and suggest services; they cannot be used to configure access to the Amazon CloudSearch configuration service actions. To attach a resource-based policy to a domain, you use the Amazon CloudSearch console, AWS CLI or AWS SDKs. In general, we recommend managing access to Amazon CloudSearch APIs by configuring user-based policies. This enables you to manage all of your permissions in one place and any changes you need to make take effect almost immediately. However, to allow public access to a domain's search service or restrict access based on IP addresses, you must configure a resource-based policy for the domain. (We recommend replacing your old IP based access policies with user-based policies at your earliest convenience.) You can also use resource-based policies to easily allow other accounts to access a domain. Keep in mind that processing changes to a domain's resource-based policies takes significantly longer than applying changes to user-based policies. The IAM console can help you write both user-based and resource-based policies for Amazon CloudSearch. For more information, see [Managing IAM Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingPolicies.html). ### Contents of an Access Policy for Amazon CloudSearch You specify the following information in your access policies for Amazon CloudSearch: + `Version` specifies the policy language version that the statement is compatible with. The version is always set to `2012-10-17 `. + `Resource` is the ARN (Amazon Resource Name) for the domain to which a user-based policy applies. `Resource` is not specified in resource-based policies configured through the Amazon CloudSearch configuration service, because the policy is attached directly to the resource. For more information about Amazon CloudSearch ARNs, see [Amazon CloudSearch ARNs](#cloudsearch-arns). + `Effect` specifies whether the statement authorizes or blocks access to the specified action(s). It must be `Allow` or `Deny` + `Sid` is an optional string that you can use to provide a descriptive name for the policy statement. + `Action` specifies which Amazon CloudSearch actions the statement applies to. For the supported actions, see [Amazon CloudSearch Actions](#cloudsearch-actions). You can use a wildcard (\$1) as the action to configure access for all actions when you need to grant administrative access to select users. (In this case, you might also want to enable multi-factor authorization for additional security. For more information, see [Configuring MFA-Protected API Access](https://docs.aws.amazon.com/IAM/latest/UserGuide/Using_ManagingMFA.html).) Wildcards are also supported within action names. For example, `"Action":["cloudsearch:Describe*]` matches all of the configuration service `Describe` actions, such as `DescribeDomains` and `DescribeServiceAccessPolicies`. + `Condition` specifies conditions for when the policy is in effect. When configuring anonymous, IP-based access, you would specify the IP addresses that the access rule applies to, for example `"IpAddress": {"aws:SourceIp": ["192.0.2.0/32"]}`. + `Principal` specifies who is allowed access to the domain in a resource-based policy. `Principal` is not specified in user-based policies configured through IAM. The `Principal` value for a resource-based policy can specify other AWS accounts or users in your own account. For example, to grant access to the account 555555555555, you would specify `"Principal":{"AWS":["arn:aws:iam::555555555555:root"]}`. Specifying a wildcard (\$1) enables anonymous access to the domain. Anonymous access is not recommended. If you enable anonymous access, you should at least specify a condition to restrict which IP addresses can submit requests to the domain. For more information, see [Granting Access to a Domain from Selected IP Addresses](#ip-based-policy). For examples of access policies for Amazon CloudSearch, see [Amazon CloudSearch Policy Examples](#policy-examples). #### Amazon CloudSearch ARNs A policy's Amazon Resource Name (ARN) uniquely specifies the domain that the policy applies to. The ARN is a standard format that AWS uses to identify resources. The 12-digit number in the ARN is your AWS account ID. Amazon CloudSearch ARNs are of the form `arn:aws:cloudsearch:REGION:ACCOUNT-ID:domain/DOMAIN-NAME`. The following list describes the variable elements in the ARN: + `REGION` is the AWS region where the Amazon CloudSearch domain for which you are configuring permissions resides. You can use a wildcard (\$1) for the `REGION` for all regions. + `ACCOUNT-ID` is your AWS account ID with no hyphens; for example, 111122223333. + `DOMAIN-NAME` identifies a specific search domain. You can use a wildcard (\$1) for the `DOMAIN-NAME` for all of your account's domains in the specified region. If you have multiple domains whose names start with the same prefix, you can use a wildcard to match all of those domains. For example, `dev-*` matches `dev-test`, `dev-movies`, `dev-sandbox`, and so on. Note that if you name new domains with the same prefix, the policy also applies to those new domains. For example, the following ARN identifies the `movies` domain in the `us-east-1` region owned by account 111122223333: ``` arn:aws:cloudsearch:us-east-1:111122223333:domain/movies ``` The following example shows how the ARN is used to specify the resource in a user-based policy. A domain's ARN is displayed on the domain dashboard in the Amazon CloudSearch console and is also available by calling `DescribeDomains`. **Important** When specifying an ARN for a domain created with the 2011-02-01 API, you must use the former Amazon CloudSearch service name, `cs`. For example, `arn:aws:cs:us-east-1:111122223333:domain/movies`. If you need to define policies that configure access for both 2011 and 2013 domains, make sure to specify the correct ARN format for each domain. For more information, see [Configuration Service Access Policies Not Working](troubleshooting.md#troubleshooting-configuration-access-policies). #### Amazon CloudSearch Actions The actions you specify control which Amazon CloudSearch APIs the statement applies to. All Amazon CloudSearch actions are prefixed with `cloudsearch:`, such as `cloudsearch:search`. The following list shows the supported actions: + `cloudsearch:document` allows access to the document service API. Permission to use the `document` action is required to upload documents to a search domain for indexing. + `cloudsearch:search` allows access to the search API. Permission to use the `search` action is required to submit search requests to a domain. + `cloudsearch:suggest` allows access to the suggest API. Permission to use the `suggest` action is required to get suggestions from a domain. + `cloudsearch:CONFIGURATION-ACTION` allows access to the specified configuration service action. Permission to use the `DescribeDomains` and `ListDomainNames` configuration actions is required to access the Amazon CloudSearch console. Configuration actions can be specified only in user-based policies. For the complete list of actions, see [Actions](API_Operations.md). ## Amazon CloudSearch Policy Examples This section presents a few examples of Amazon CloudSearch access policies. **Topics** + [Granting Read-only Access to the Amazon CloudSearch Configuration Service](#read-only-configuration-policy) + [Granting Access to All Amazon CloudSearch Configuration Service Actions](#full-configuration-policy) + [Granting Unrestricted Access to All Amazon CloudSearch Services](#universal-policy) + [Granting Permission to Upload Documents to an Amazon CloudSearch Domain](#document-upload-policy) + [Granting Amazon CloudSearch Access to Another AWS Account](#cross-account-policy) + [Granting Access to an Amazon CloudSearch Domain from Selected IP Addresses](#ip-based-policy) + [Granting Public Access to an Amazon CloudSearch Domain's Search Service](#public-access-policy) ### Granting Read-only Access to the Amazon CloudSearch Configuration Service You can grant read-only access to the configuration service by allowing only the following actions. This might be useful if you want to allow users to view the configuration of a production domain without being able to make changes. + `cloudsearch:DescribeAnalysisSchemes` + `cloudsearch:DescribeAvailabilityOptions` + `cloudsearch:DescribeDomains` + `cloudsearch:DescribeExpressions` + `cloudsearch:DescribeIndexFields` + `cloudsearch:DescribeScalingParameters` + `cloudsearch:DescribeServiceAccessPolicies` + `cloudsearch:DescribeSuggesters` + `cloudsearch:ListDomainNames` The following user-based policy grants read-only access to the configuration service for a `movies` domain owned by the account 555555555555. The policy uses wildcards for the actions, since it grants access to all actions that begin with *Describe* or *List*. Note that this will also grant access to any describe or list actions that might be added to the API in the future. ### Granting Access to All Amazon CloudSearch Configuration Service Actions You can grant access to all Amazon CloudSearch configuration service actions by including an `Allow` statement that grants access to all configuration service actions, but not the domain services actions. This enables you to grant administrative access without authorizing a user to upload or retrieve data from a domain. One way to do this is to use a wildcard to grant access to all Amazon CloudSearch actions, and then include a deny statement that blocks access to the domain services actions. The following user-based policy grants access to the configuration service for all domains owned by the 111122223333 account in the `us-west-2` region. ### Granting Unrestricted Access to All Amazon CloudSearch Services You can grant unrestricted access to all Amazon CloudSearch services, including all configuration service actions and all domain services with a user-based policy. To do this, you specify wildcards for the actions, region, and domain name. The following policy enables the user to access all Amazon CloudSearch actions for any domain in any region that's owned by the 111122223333 account. ### Granting Permission to Upload Documents to an Amazon CloudSearch Domain You can grant a user permission to upload documents to a search domain by specifying the `cloudsearch:document` action. For example, the following user-based policy enables the user to upload documents to the `movies` domain in `us-east-1` owned by the 111122223333 account. ### Granting Amazon CloudSearch Access to Another AWS Account You have two options to configure cross-account access for a CloudSearch domain: **** | Option | Description | | --- | --- | | Configure an IAM role for cross-account access. | Increased security, but requires complex request signing. For more information, see [Cross-Account API Access Using IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/cross-acct-access.html) in the IAM documentation. | | Attach a resource-based policy to the CloudSearch domain and attach a user-based managed policy to an IAM role. | Easier to implement. For more information, see [Creating a Role to Delegate Permissions to an IAM User](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html) and [Walkthrough: Delegating Access Across AWS Accounts For Accounts You Own Using IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/walkthru_cross-account-with-roles.html) in the IAM documentation. | This topic provides an example of the second option, adding a resource-based policy to the CloudSearch domain. Assume that account \$11 is owned by account id `111111111111` and account \$12 is owned by account id `999999999999`. Account \$11 wants to grant access to account \$12 to use the search service for the `movies` domain, which requires two steps: 1. Account \$11 attaches a resource-based policy to the domain using the Amazon CloudSearch console that grants access to account \$12. 1. Account \$12 attaches a user-based managed policy to an IAM role owned by that account using the IAM console. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["cloudsearch:search"], "Resource": "arn:aws:cloudsearch:us-east-1:111111111111:domain/movies" } ] } ``` ------ **Important** To configure resource-based policies for Amazon CloudSearch, you must have permission to use the `cloudsearch:UpdateServiceAccessPolicies` action. ### Granting Access to an Amazon CloudSearch Domain from Selected IP Addresses Resource-based access policies set through the Amazon CloudSearch configuration service support anonymous access, which enables you to submit unsigned requests to a search domain's services. To allow anonymous access from selected IP addresses, use a wildcard for the `Principal` value and specify the allowed IP addresses as a `Condition` element in the policy. **Important** Allowing anonymous access from selected IP addresses is inherently less secure than requiring user credentials to access your search domains. We recommend against allowing anonymous access even if it is permitted only from select IP addresses. If you currently allow anonymous access, you should upgrade your applications to submit signed requests and control access by configuring user-based or resource-based policies. If you are creating a resource-based policy that grants access to requests coming from an Amazon EC2 instance, you need to specify the instance's public IP address. IP addresses are specified in the standard Classless Inter-Domain Routing (CIDR) format. For example 10.24.34.0/24 specifies the range 10.24.34.0 - 10.24.34.255, while 10.24.34.0/32 specifies the single IP address 10.24.34.0. For more information about CIDR notation, see [RFC 4632](http://www.rfc-editor.org/rfc/rfc4632.txt). For example, the following policy grants access to the search action for the `movies` domain owned by AWS account 111122223333 from the IP address 192.0.2.0/32. ### Granting Public Access to an Amazon CloudSearch Domain's Search Service If you need to allow public access to your domain's search endpoint, you can configure a resource-based policy with no conditions. This enables unsigned requests to be sent from any IP address. **Important** Allowing public access to a search domain means you have no control over the volume of requests submitted to the domain. Malicious users could flood the domain with requests, impacting legitimate users as well as your operating costs. For example, the following policy grants public access to the search action for the `movies` domain owned by AWS account 111122223333. ## Configuring Access for Amazon CloudSearch Using the AWS Management Console **To configure user-based policies** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. Configure Amazon CloudSearch permissions by attaching a policy to a user, group, or role. For more information, see [Managing Policies (AWS Management Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingPolicies.html#AddingPermissions_Console). For more information about user-based policies for Amazon CloudSearch see [Writing Access Policies for Amazon CloudSearch](#cloudsearch-access-policies). **To configure resource-based policies** 1. Sign in to the AWS Management Console and open the Amazon CloudSearch console at [https://console.aws.amazon.com/cloudsearch/home](https://console.aws.amazon.com/cloudsearch/home). 1. Choose the name of the domain you want to configure. 1. On the **Domain configuration** tab, choose **Edit** next to **Access policy**. 1. When you're done making changes to the domain access policy, choose **Submit**. Your domain remains in a `Processing` state while Amazon CloudSearch updates the access policy. ## Configuring Access for Amazon CloudSearch with the AWS CLI You can configure both user-based policies and resource-based policies for Amazon CloudSearch with the AWS CLI. For information about installing and setting up the AWS CLI, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/). **To configure user-based policies** + Configure Amazon CloudSearch permissions by attaching a policy to a user, group, or role with the `aws put-user-policy`, `aws put-group-policy`, or `aws put-role-policy` command. For more information, see [Managing Policies (AWS Management Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingPolicies.html#AddingPermissions_Console). For more information about user-based policies for Amazon CloudSearch see [Writing Access Policies for Amazon CloudSearch](#cloudsearch-access-policies). **To configure resource-based policies** + Run the `aws cloudsearch update-service-access-policies` command and specify an access policy with the `--access-policies` option. The access policy must be enclosed in quotes and all quotes within the access policy must be escaped with a backslash. For more information about resource-based policies for Amazon CloudSearch see [Writing Access Policies for Amazon CloudSearch](#cloudsearch-access-policies). The following example configures the `movies` domain to accept search requests from the IP address `192.0.2.0`. ``` aws cloudsearch update-service-access-policies --domain-name movies --access-policies "{\"Version\":\"2012-10-17\", \"Statement\":[{ \"Sid\":\"search_only\", \"Effect\":\"Allow\", \"Principal\": \"*\", \"Action\":\"cloudsearch:search\", \"Condition\":{\"IpAddress\":{\"aws:SourceIp\":\"192.0.2.0/32\"}}} ]}" { "AccessPolicies": { "Status": { "PendingDeletion": false, "State": "Processing", "CreationDate": "2014-04-30T22:07:30Z", "UpdateVersion": 9, "UpdateDate": "2014-04-30T22:07:30Z" }, "Options": "{\"Version\":\"2012-10-17\", \"Statement\":[{\"Sid\":\"\", \"Effect\":\"Allow\",\"Principal\":\"*\", \"Action\":\"cloudsearch:search\", \"Condition\":{\"IpAddress\":{\"aws:SourceIp\": \"192.0.2.0/32\"}}}]}" } } ``` Updating resource-based access policies takes some time to complete. You can check the state of the policy with the `aws cloudsearch describe-service-access-policies` command. Once the policy has been applied, the state of the policy changes to `Active`. You can retrieve your domain's policies using the `aws cloudsearch describe-service-access-policies` command. ## Configuring Access to a Domain's Endpoints Using the AWS SDKs The AWS SDKs (except the Android and iOS SDKs) support all of the Amazon CloudSearch actions defined in the Amazon CloudSearch Configuration API, including `UpdateServiceAccessPolicies`. For more information about installing and using the AWS SDKs, see [AWS Software Development Kits](http://aws.amazon.com/code). # Configuring Scaling Options in Amazon CloudSearch A search domain has one or more search instances, each with a finite amount of RAM and CPU resources for indexing data and processing requests. You can configure scaling options to control the instance type that is used, the number of instances your search index is distributed across (partition count), and the number of replicas of each index partition (replication count). All instances for a domain are always of the same type. You can configure the desired instance type, partition count, or replication count for an Amazon CloudSearch domain to: + **Increase upload capacity** By default, all search domains start out on a `search.small` instance. You can increase your domain's document upload capacity by changing the desired instance type. If you have a large amount of data to upload—for example, when you are initially populating your search domain—you can choose a larger instance type to increase the number of updates that can be submitted in parallel and reduce how long it takes to index your data. If you are already using the largest instance type, you can increase the desired partition count to further increase upload capacity. For more information, see [Bulk Uploads](uploading-data.md#bulk-uploads). Note that increasing the desired replication count does *not* generally increase a domain's upload capacity. + **Speed up search requests.** Choosing a larger desired instance type can also speed up search requests. If you've tuned your requests and still aren't meeting your performance targets, try choosing a larger instance type. If you are already using the largest instance type, you can increase the desired partition count to further boost query performance. For more information, see [Tuning Search Request Performance in Amazon CloudSearch](tuning-search.md). + **Increase search capacity. **By default, Amazon CloudSearch uses one instance per index partition. When Amazon CloudSearch scales the domain automatically, it adds replicas based on the resources needed to process the query traffic. To increase a domain's search capacity, you set the desired replication count. However, deploying additional instances takes some time. If you know in advance that you will need additional capacity—for example, before a big launch or announcement—add replicas ahead of time to ensure that your search domain is ready to handle the load. + **Improve fault tolerance.** Increasing the desired replication count also improves the domain's fault-tolerance—if there's a problem with one of the replicas, the others will continue to handle requests while it is being recovered. However, note that the replicas reside in the same Availability Zone. If you need to ensure availability of your domain in the event of an Availability Zone service disruption, you should enable the MultiAZ option. For more information, see [Configuring Availability Options](configuring-availability-options.md). When you set the desired instance type, desired number of replicas, or desired partition count, Amazon CloudSearch scales your domain as necessary, but will never scale the domain to an instance type that's smaller than the desired type, use fewer replicas than the desired number of replicas, or reduce the partition count below the desired partition count. **Note** The automatic scaling progression is based on the instance type's available disk space. The `search.small` and `search.medium` instance types have the same amount of disk space, so both scale to `search.large`. You can change your scaling options at any time. If your need for additional capacity is temporary, you can prescale your domain by setting the scaling options and then revert the changes after your volume of uploads or queries returns to your domain's steady state. When you make changes, you need to re-index your domain, which can take some time for the changes to take effect. How long it takes to re-index depends on the amount of data in your index. You can monitor the domain status to determine when indexing is complete—the status changes from PROCESSING to ACTIVE. **Topics** + [Choosing Scaling Options in Amazon CloudSearch](#choosing-scaling-options) + [Configuring Scaling Options through the Amazon CloudSearch Console](#configuring-scaling-options-console) + [Configuring Scaling Options through the AWS CLI](#configuring-scaling-options-cli) + [Configuring Scaling Options through the AWS SDK](#configuring-scaling-options-sdk) ## Choosing Scaling Options in Amazon CloudSearch When you set scaling options for a domain, you make a trade-off between cost and performance—changing the desired instance type, replication count, and partition count can significantly impact the cost of running your domain. To determine which instance type to select to handle your upload traffic, monitor your upload performance as you increase the upload rate. If you start seeing a large number of 504 or 507 errors before you reach your desired upload rate, select a larger instance type. If you are already on the largest instance type, you can increase the number of partitions to further increase upload capacity. For datasets of less than 1 GB of data or fewer than one million 1 KB documents, a small search instance should be sufficient. To upload data sets between 1 GB and 8 GB, we recommend setting the desired instance type to `search.large` before you begin uploading. For datasets between 8 GB and 16 GB, start with a `search.xlarge`. For datasets between 16 GB and 32 GB, start with a `search.2xlarge`. If you have more than 32 GB to upload, select the `search.2xlarge` instance type and increase the desired partition count to accommodate your data set. Each partition can contain up to 32 GB of data. Submit a [Service Increase Limit Request](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase&limitType=service-code-cloudsearch-partitions-and-instances) if you need more upload capacity or have more than 500 GB to index. To determine how many replicas you need to handle a given query volume, do some testing using a sample of your expected queries at the rate you need to support. Keep in mind that query performance depends heavily on the type of queries being processed. In general, searches that return a large volume of hits and complex structured queries are more resource intensive than simple text queries that match a small percentage of the documents in your search domain. If you expect a high volume of complex queries, choose a larger desired instance type and increase the desired replication count. ## Configuring Scaling Options through the Amazon CloudSearch Console **To configure a search domain's scaling options** Note that changing the desired instance type and replication count can significantly increase the cost of running your domain. 1. On the Amazon CloudSearch console, choose the name of the domain you want to configure. 1. On the **Domain configuration** tab, choose **Edit** next to **Scaling options**. 1. Select an instance type from the **Desired instance type** menu. 1. Select the number of replicas you want to use from the **Desired replication count** menu. 1. If you selected the `search.2xlarge` instance type, configure the **Desired partition count**. Increase the partition count if you have more data to upload than will fit on a single `search.2xlarge` partition. For more information, see [Bulk Uploads](uploading-data.md#bulk-uploads). 1. Choose **Submit**. 1. After you finish making changes to your domain configuration, choose **Actions**, **Run indexing** to update and deploy your index to the new instances. ## Configuring Scaling Options through the AWS CLI You use the `aws cloudsearch update-scaling-parameters` command to configure scaling options for a search domain. For information about installing and setting up the AWS CLI, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/). **To configure a search domain's scaling options** + Run the `aws cloudsearch update-scaling-parameters` command. You can specify the desired instance type and desired replication count. If you choose the largest instance type (`search.2xlarge`), you can also set the desired partition count. For example, the following command sets the desired instance type to `search.xlarge` and the desired replication count to two. You must specify both the `--domain-name` and `--scaling-parameters` options. ``` aws cloudsearch update-scaling-parameters --domain-name movies --scaling-parameters DesiredInstanceType=search.xlarge,DesiredReplicationCount=2 { "ScalingParameters": { "Status": { "PendingDeletion": false, "State": "RequiresIndexDocuments", "CreationDate": "2014-06-25T21:41:21Z", "UpdateVersion": 10, "UpdateDate": "2014-06-25T21:41:21Z" }, "Options": { "DesiredInstanceType": "search.xlarge", "DesiredReplicationCount": 2 } } } ``` **Important** When you specify `--scaling-parameters`, Amazon CloudSearch treats unspecified options as "reset to default" rather than "leave as-is." For example, if you specify `--scaling-parameters DesiredInstanceType=search.xlarge` in a command and then `--scaling-parameters DesiredReplicationCount=2` in a subsequent command, Amazon CloudSearch resets `DesiredInstanceType` to its default value during the second command. If you want the change from the first command to persist, you must specify it again in all subsequent commands: `--scaling-parameters DesiredInstanceType=search.xlarge,DesiredReplicationCount=2`. For the changes to take effect, you must initiate an index build. You can rebuild the index by calling `aws cloudsearch index-documents`. ## Configuring Scaling Options through the AWS SDK The AWS SDKs (except the Android and iOS SDKs) support all of the Amazon CloudSearch actions defined in the Amazon CloudSearch Configuration API, including `UpdateScalingParameters`. For more information about installing and using the AWS SDKs, see [AWS Software Development Kits](http://aws.amazon.com/code). # Configuring Availability Options in Amazon CloudSearch You can expand an Amazon CloudSearch domain to an additional Availability Zone in the same region to increase fault tolerance in the event of a service disruption. Availability Zones are physically separate locations with independent infrastructure engineered to be insulated from failures in other Availability Zones. For more information, see [Regions and Availability Zones](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) in the Amazon EC2 User Guide. When you turn on the Multi-AZ option, Amazon CloudSearch provisions and maintains extra instances for your search domain in a second Availability Zone to ensure high availability. The maximum number of Availability Zones a domain can be deployed in is two. Turning on Multi-AZ does not affect a search domain's service endpoints or increase the volume of data or traffic your search domain can handle. Updates are automatically applied to the instances in both Availability Zones. Search traffic is distributed across all of the instances and the instances in either zone are capable of handling the full load in the event of a failure. If there's an Availability Zone service disruption or the instances in one zone become degraded, Amazon CloudSearch routes all traffic to the other Availability Zone. Redundant instances are restored in a separate Availability Zone without any administrative intervention or disruption in service. You expand an existing search domain to a second Availability Zone by turning on the Multi-AZ option. Similarly, you can turn off the Multi-AZ option to downgrade the domain to a single Availability Zone. Turning the Multi-AZ option on or off takes about half an hour. You can configure a domain's availability options through the Amazon CloudSearch console, using the `aws cloudsearch update-availability-options` command, or the AWS SDKs. **Important** If your domain is running on a single search instance, enabling the Multi-AZ option adds a second search instance in a different availability zone, which doubles the cost of running your domain. Similarly, if your index is split across multiple partitions, a new instance is deployed in the second Availability Zone for each partition. Additional replicas are added to ensure that either Availability Zone has enough capacity to handle all of your traffic—when Multi-AZ is enabled, your domain will have at least one replica of each index partition. If you set the desired number of replicas and enable the Multi-AZ option, Amazon CloudSearch ensures that you have at least that many replicas available in total across the two availability zones. You can monitor the number of instances being used for your domain from the domain dashboard. **Topics** + [Configuring Availability Options through the Amazon CloudSearch Console](#configuring-availability-options-console) + [Configuring Amazon CloudSearch Availability Options Using the AWS CLI](#configuring-availability-options-clt) + [Configuring Availability Options through the AWS SDK](#configuring-availability-options-sdk) ## Configuring Availability Options through the Amazon CloudSearch Console If your domain currently uses a single search instance, enabling Multi-AZ adds a second search instance, which can significantly increase the cost of running your domain. **To configure a search domain's availability options** 1. Within the Amazon CloudSearch console, choose the name of your domain. 1. In the **Domain configuration**, choose **Edit** next to **Availability options**. 1. Enable **Toggle Multi-AZ options**. 1. Choose **Submit**. ## Configuring Amazon CloudSearch Availability Options Using the AWS CLI You use the `aws cloudsearch update-availability-options` command to configure availability options for a search domain. For information about installing and setting up the AWS CLI, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/). **To configure a search domain's availability options** + Run the `aws cloudsearch update-availability-options` command and specify the `--multi-az` option to turn on MultiAZ for the domain, or `--no-multi-az` to turn MultiAZ off. For example, the following request enables MultiAZ for the `movies` domain: ``` aws cloudsearch update-availability-options --domain-name movies --multi-az { "AvailabilityOptions": { "Status": { "PendingDeletion": false, "State": "Processing", "CreationDate": "2014-04-30T20:42:57Z", "UpdateVersion": 13, "UpdateDate": "2014-05-01T00:17:45Z" }, "Options": true } } ``` ## Configuring Availability Options through the AWS SDK The AWS SDKs (except the Android and iOS SDKs) support all of the Amazon CloudSearch actions defined in the Amazon CloudSearch Configuration API, including `UpdateAvailabilityOptions`. For more information about installing and using the AWS SDKs, see [AWS Software Development Kits](http://aws.amazon.com/code). # Configuring Domain Endpoint Options in Amazon CloudSearch Amazon CloudSearch domains let you require that all traffic to the domain arrive over HTTPS. This security feature helps you block clients that send unencrypted requests to the domain. **Topics** + [Configuring Domain Endpoint Options Using the Amazon CloudSearch Console](#configuring-domain-endpoint-options-console) + [Configuring Domain Endpoint Options Using the AWS CLI](#configuring-domain-endpoint-options-cli) + [Configuring Domain Endpoint Options Using the AWS SDKs](#configuring-domain-endpoint-options-api) ## Configuring Domain Endpoint Options Using the Amazon CloudSearch Console **To configure a search domain's endpoint options** 1. Within the Amazon CloudSearch console, choose the name of your domain to open its settings. 1. Under **Domain configuration**, choose **Edit** next to **HTTPS options**. 1. Enable **Toggle HTTPS options**. 1. Choose **Submit**. ## Configuring Domain Endpoint Options Using the AWS CLI Use the `aws cloudsearch update-domain-endpoint-options` command. For more information, see the [AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/cloudsearch/). ## Configuring Domain Endpoint Options Using the AWS SDKs The AWS SDKs (except the Android and iOS SDKs) support all of the Amazon CloudSearch actions defined in the Amazon CloudSearch Configuration API, including [DescribeDomainEndpointOptions](API_DescribeDomainEndpointOptions.md) and [UpdateDomainEndpointOptions](API_UpdateDomainEndpointOptions.md). For more information about installing and using the AWS SDKs, see [AWS Software Development Kits](http://aws.amazon.com/code). # Monitoring Amazon CloudSearch Domains The AWS Management Console enables you to easily monitor the status and configuration of your search domains and view your Amazon CloudSearch usage. You can also get configuration information about particular domains with the AWS CLI and AWS SDKs. **Topics** + [Getting Information About an Amazon CloudSearch Domain](getting-domain-info.md) + [Monitoring an Amazon CloudSearch Domain with Amazon CloudWatch](cloudwatch-monitoring.md) + [Logging Amazon CloudSearch Configuration API Calls with AWS CloudTrail](logging-config-api-calls.md) + [Tracking your Amazon CloudSearch Usage and Charges](tracking-usage.md) # Getting Information About an Amazon CloudSearch Domain You can retrieve the following information about each of your search domains: + **Domain name**—The name of the domain. + **ARN**—The domain's Amazon Resource Name (ARN). + **Document endpoint**—The endpoint through which you can submit document updates. + **Search endpoint**—The endpoint through which you can submit search requests. + **Searchable documents**—The number of documents that have been indexed. + **Access policies**—The access policies configured for the domain's document and search endpoints. + **Analysis schemes**—The text analysis schemes that can be applied to the domain's index fields. + **Index fields**—The name and type of each configured index field. + **Expressions**—The expressions that can be used for sorting search results. + **Suggesters**—The suggesters that can be used to retrieve suggestions for incomplete queries. When a domain is first created, the domain status will indicate that the domain is currently being activated and no other information is available. Once your domain's document and search endpoints are available, the domain status shows the endpoint addresses that you can use to add data and submit search requests. If you haven't submitted any data for indexing, the number of searchable documents is zero. You can view all of the information about your domain through the [Amazon CloudSearch console](#getting-domain-info-console). When you use the `aws cloudsearch describe-domains` command or the AWS SDKs, the domain's ARN is shown within the domain's access policies. To get the number of searchable documents, use the console or submit a `matchall` request to your domain's search endpoint. ``` q=matchall&q.parser=structured&size=0 ``` **Topics** + [Amazon CloudSearch console](#getting-domain-info-console) + [Getting Amazon CloudSearch Domain Information Using the AWS CLI](#getting-domain-info-clt) + [DescribeDomains](#getting-domain-info-sdk) ## Getting Domain Information Using the Amazon CloudSearch Console You can use the Amazon CloudSearch console to view information about all of your domains. The dashboard of the console shows a summary of each domain that you have created, including the domain name, status, and number of searchable documents. To update the table with the latest information, click the **Refresh** button at the top of the page. A domain can be in one of five states: + **Loading**—The domain has just been created and is still being initialized. You must wait until the domain status changes to PROCESSING, NEEDS INDEXING, or ACTIVE before you can start uploading documents. + **Active**—The domain is running and all configured fields have been indexed. + **Needs Indexing**—You have made changes to the domain configuration that require rebuilding the index. If you search the domain, these changes won't be reflected in the results. When you are done making changes, choose **Actions**, **Run indexing** to rebuild your index. + **Processing**—Configuration changes are being applied to your domain. If you search the domain, the most recent configuration changes might not be reflected in the results. + **Being Deleted**—You chose to delete the domain and its contents, and the domain and all of its resources are in the process of being removed. When deletion is complete, the domain will be removed from the list of domains. From the Amazon CloudSearch dashboard, you can do the following: + View the status of your search domains + Access the dashboard for a particular domain + Access the Amazon CloudSearch documentation and other resources **To view detailed information about a particular domain** 1. Open the Amazon CloudSearch console at [https://console.aws.amazon.com/cloudsearch/home](https://console.aws.amazon.com/cloudsearch/home). 1. Choose **Domains** from the left navigation pane. The domain dashboard shows the status summary for the selected domain. From the domain dashboard, you can do the following: + View the status of the domain + Upload documents to the domain + Search the domain + Access the domain configuration pages + Delete the domain ## Getting Amazon CloudSearch Domain Information Using the AWS CLI You use the `aws cloudsearch describe-domains` command to get the status of your search domains. To get specific information such as the access policies, availability options, and scaling options configured for a domain, you use the separate `describe` commands for each option. For information about installing and setting up the AWS CLI, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/). **To get domain status information** + Run the `aws cloudsearch describe-domains` command to get information about all of your domains. To get information about specific domains, use the `--domain-names` option to specify the domains that you are interested in. For example, the following request gets the status of the `movies` domain: ``` aws cloudsearch describe-domains --domain-names movies { "DomainStatusList": [ { "SearchInstanceType": "search.small", "DomainId": "965407640801/movies", "Created": true, "Deleted": false, "SearchInstanceCount": 1, "DomainName": "movies", "SearchService": { "Endpoint": "search-movies-m4fcjhuxgj6i76smhyiz7pfxsu.us-east-1.cloudsearch.amazonaws.com" }, "RequiresIndexDocuments": false, "Processing": true, "DocService": { "Endpoint": "doc-movies-m4fcjhuxgj6i76smhyiz7pfxsu.us-east-1.cloudsearch.amazonaws.com" }, "ARN": "arn:aws:cloudsearch:us-east-1:965407640801:domain/movies", "SearchPartitionCount": 1 } ] } ``` The `describe-domains` command does not return the number of searchable documents in the domain. To get the number of searchable documents, use the console or submit a `matchall` request to your domain's search endpoint: ``` q=matchall&q.parser=structured&size=0 ``` **To get the analysis schemes configured for a domain** + Run the `aws cloudsearch describe-analysis-schemes` command. For example, the following request gets the analysis schemes configured for the `movies` domain: ``` aws cloudsearch describe-analysis-schemes --domain-name movies { "AnalysisSchemes": [ { "Status": { "PendingDeletion": false, "State": "Active", "CreationDate": "2014-03-28T19:27:30Z", "UpdateVersion": 31, "UpdateDate": "2014-03-28T19:27:30Z" }, "Options": { "AnalysisSchemeLanguage": "en", "AnalysisSchemeName": "samplescheme", "AnalysisOptions": { "AlgorithmicStemming": "none", "Synonyms": "{\"aliases\":{\"youth\":[\"young adult\"]},\"groups\":[[\"tool box\",\"toolbox\"],[\"band saw\",\"bandsaw\"],[\"drill press\",\"drillpress\"]]}", "StemmingDictionary": "{}", "Stopwords": "[]" } } } ] } ``` **To get the availability options configured for a domain** + Run the `aws cloudsearch describe-availability-options` command. For example, the following request gets the availability options configured for the `movies` domain. If Multi-AZ is enabled for the domain, the `Options` value is set to `true`: ``` aws cloudsearch describe-availability-options --domain-name movies { "AvailabilityOptions": { "Status": { "PendingDeletion": false, "State": "Processing", "CreationDate": "2014-04-30T20:42:57Z", "UpdateVersion": 13, "UpdateDate": "2014-05-01T00:17:45Z" }, "Options": true } } ``` **To get the expressions configured for a domain** + Run the `aws cloudsearch describe-expressions` command. For example, the following request gets the expressions configured for the `movies` domain: ``` aws cloudsearch describe-expressions --domain-name movies { "Expression": { "Status": { "PendingDeletion": false, "State": "Processing", "CreationDate": "2014-05-01T01:15:18Z", "UpdateVersion": 52, "UpdateDate": "2014-05-01T01:15:18Z" }, "Options": { "ExpressionName": "popularhits", "ExpressionValue": "((0.3*popularity)/10.0)+(0.7* _score)" } } } ``` ## Getting Domain Information Using the AWS SDKs The AWS SDKs (except the Android and iOS SDKs) support all of the Amazon CloudSearch actions defined in the Amazon CloudSearch Configuration API, including `DescribeDomains`. For more information about installing and using the AWS SDKs, see [AWS Software Development Kits](http://aws.amazon.com/code). The `DescribeDomains` action does not return the number of searchable documents in the domain. To get the number of searchable documents, use the console or submit a `matchall` request to your domain's search endpoint: ``` q=matchall&q.parser=structured&size=0 ``` # Monitoring an Amazon CloudSearch Domain with Amazon CloudWatch Amazon CloudSearch automatically sends metrics to Amazon CloudWatch so that you can gather and analyze performance statistics. You can monitor these metrics by using the Amazon CloudSearch console, or by using the CloudWatch console, AWS CLI, or AWS SDKs. Each of your domain's search instances sends metrics to CloudWatch at one-minute intervals. The metrics are archived for two weeks; after that period, the data is discarded. There is no charge for the Amazon CloudSearch metrics that are reported through CloudWatch. If you set alarms on the metrics, you will be billed at standard [CloudWatch rates](http://aws.amazon.com/cloudwatch/pricing/). You can use the metrics in all regions supported by Amazon CloudSearch. **Topics** + [Amazon CloudSearch Metrics](#cloudsearch-metrics) + [Dimensions for Amazon CloudSearch Metrics](#cloudsearch-metric-dimensions) + [Generating SDK for Java Metrics for Amazon CloudSearch](#java-sdk-metrics) + [Viewing CloudWatch Metrics for an Amazon CloudSearch Domain](#viewing-metrics) Not all statistics, such as *Average* or *Sum*, are applicable for every metric. However, all of these values are available through the Amazon CloudSearch console, or by using the CloudWatch console, AWS CLI, or AWS SDKs for all metrics. In the following table, each metric has a list of Valid Statistics that is applicable to that metric. ## Amazon CloudSearch Metrics The `AWS/CloudSearch` namespace includes the following metrics. | Metric | Description | | --- | --- | | `SuccessfulRequests` | The number of search requests successfully processed by a search instance. Units: Count Valid statistics: Maximum, Sum | | `SearchableDocuments` | The number of searchable documents in the domain's search index. Units: Count Valid statistics: Maximum | | `IndexUtilization` | The percentage of the search instance's index capacity that has been used. The Maximum value indicates the percentage of the domain's index capacity that has been used. Units: Percent Valid statistics: Average, Maximum | | `Partitions` | The number of partitions the index is distributed across. Units: Count Valid statistics: Minimum, Maximum | ## Dimensions for Amazon CloudSearch Metrics Amazon CloudSearch sends the ClientId and DomainName dimensions to CloudWatch. | Dimension | Description | | --- | --- | | `ClientId` | The AWS account ID. | | `DomainName` | The name of the search domain. | ## Generating SDK for Java Metrics for Amazon CloudSearch The AWS SDK for Java can generate performance metrics for your Amazon CloudSearch client and send them to CloudWatch for visualization. For the Java VM arguments that enable this feature, see [Enabling Metrics for the AWS SDK for Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/generating-sdk-metrics.html) in the *AWS SDK for Java Developer Guide*. You can use the following code to test metrics generation. The code creates a new CloudWatch client and performs 2,500 searches. Because the SDK only sends metrics once per minute, long-running clients work best. The code uses the [default credential provider chain](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials.html#credentials-default). ``` import com.amazonaws.client.builder.AwsClientBuilder; import com.amazonaws.services.cloudsearchdomain.AmazonCloudSearchDomain; import com.amazonaws.services.cloudsearchdomain.AmazonCloudSearchDomainClientBuilder; import com.amazonaws.services.cloudsearchdomain.model.SearchRequest; public class Metrics { public static void main(String[] args) { String search_endpoint = "https://search-domain-id.us-west-1.cloudsearch.amazonaws.com"; String region = "us-west-1"; AwsClientBuilder.EndpointConfiguration endpointConfig = new AwsClientBuilder .EndpointConfiguration(search_endpoint, region); AmazonCloudSearchDomainClientBuilder builder = AmazonCloudSearchDomainClientBuilder .standard() .withEndpointConfiguration(endpointConfig); AmazonCloudSearchDomain client = builder.build(); String query; SearchRequest request = new SearchRequest(); com.amazonaws.services.cloudsearchdomain.model.SearchResult test = client.search(request); for (int i = 0; i < 2500; i++) { query = "test"; request.setQuery(query); test = client.search(request); System.out.println(test.toString()); } } } ``` To verify that the SDK is sending metrics to CloudWatch, check the **Metrics** page of the CloudWatch console and look for **AWSSDK/Java** under the **Custom Namespaces** section. The metrics might take several minutes to display. ## Viewing CloudWatch Metrics for an Amazon CloudSearch Domain The Amazon CloudSearch console graphs the metrics reported to CloudWatch. You can also access the metrics through the [CloudWatch console](https://console.aws.amazon.com/cloudwatch), AWS CLI, and AWS SDKs. For more information, see [Viewing, Graphing, and Publishing Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/working_with_metrics.html) in the * Amazon CloudWatch Developer Guide*. **To view metrics for a search domain using the Amazon CloudSearch console** 1. Open the Amazon CloudSearch console at [https://console.aws.amazon.com/cloudsearch](https://console.aws.amazon.com/cloudsearch). 1. Choose **Domains** from the left navigation pane. 1. Click the name of the domain, and then go to the **Monitoring** tab. # Logging Amazon CloudSearch Configuration API Calls with AWS CloudTrail Amazon CloudSearch integrates with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in Amazon CloudSearch. CloudTrail captures all configuration API calls for Amazon CloudSearch as events. **Note** CloudTrail only captures calls to the [configuration API](configuration-api.md), such as `CreateDomain` and `UpdateServiceAccessPolicies`, not the [document service API](document-service-api.md) nor the [search API](search-api.md). The calls captured include calls from the Amazon CloudSearch console, CLI, or SDKs. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket, including events for Amazon CloudSearch. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in **Event history**. Using the information collected by CloudTrail, you can determine the request that was made to Amazon CloudSearch, the IP address from which the request was made, who made the request, when it was made, and additional details. To learn more about CloudTrail, see the [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/). ## Amazon CloudSearch Information in CloudTrail CloudTrail is enabled on your AWS account when you create the account. When activity occurs in Amazon CloudSearch, that activity is recorded in a CloudTrail event along with other AWS service events in **Event history**. You can view, search, and download recent events in your AWS account. For more information, see [Viewing Events with CloudTrail Event History](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html). For an ongoing record of events in your AWS account, including events for Amazon CloudSearch, create a trail. A *trail* enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all AWS Regions. The trail logs events from all Regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see the following: + [Overview for Creating a Trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) + [CloudTrail Supported Services and Integrations](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations) + [Configuring Amazon SNS Notifications for CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html) + [Receiving CloudTrail Log Files from Multiple Regions](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) and [Receiving CloudTrail Log Files from Multiple Accounts](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html) All Amazon CloudSearch configuration API actions are logged by CloudTrail and are documented in the [Configuration API Reference for Amazon CloudSearch](configuration-api.md). Every event or log entry contains information about who generated the request. The identity information helps you determine the following: + Whether the request was made with root or AWS Identity and Access Management (IAM) user credentials. + Whether the request was made with temporary security credentials for a role or federated user. + Whether the request was made by another AWS service. For more information, see the [CloudTrail userIdentity Element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html). ## Understanding Amazon CloudSearch Log File Entries A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on. CloudTrail log files aren't an ordered stack trace of the public API calls, so they don't appear in any specific order. The following example shows a CloudTrail log entry that demonstrates the `CreateDomain` action. ``` { "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "AIDACKCEVSQ6C2EXAMPLE", "arn": "arn:aws:iam::123456789012:user/test-user", "accountId": "123456789012", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "userName": "test-user", "sessionContext": { "attributes": { "mfaAuthenticated": "false", "creationDate": "2018-08-21T23:31:33Z" } }, "invokedBy": "signin.amazonaws.com" }, "eventTime": "2018-08-21T23:32:15Z", "eventSource": "cloudsearch.amazonaws.com", "eventName": "CreateDomain", "awsRegion": "us-west-1", "sourceIPAddress": "123.123.123.123", "userAgent": "signin.amazonaws.com", "requestParameters": { "domainName": "test-domain" }, "responseElements": { "domainStatus": { "aRN": "arn:aws:cloudsearch:us-west-1:123456789012:domain/test-domain", "searchInstanceCount": 0, "docService": {}, "requiresIndexDocuments": false, "deleted": false, "searchService": {}, "domainId": "123456789012/test-domain", "processing": false, "created": true, "searchPartitionCount": 0, "domainName": "test-domain" } }, "requestID": "12345678-1234-1234-1234-987654321098", "eventID": "87654321-4321-4321-4321-987654321098", "eventType": "AwsApiCall", "recipientAccountId": "123456789012" } ``` # Tracking your Amazon CloudSearch Usage and Charges The AWS account activity page enables you to track your Amazon CloudSearch usage and charges. **To get your Amazon CloudSearch usage information** 1. Go to [aws.amazon.com](http://aws.amazon.com) and choose **My Account**, **Billing & Cost Management**. 1. Choose **Cost & Usage Reports**, then choose **AWS Usage Report**. 1. Choose **Amazon CloudSearch** from the services dropdown. 1. Specify the information that you want to include in the report, then choose the download button for the data format that you want to download. Reports can be downloaded in XML or CSV format. # Deleting an Amazon CloudSearch Domain If you are no longer using a search domain, you must delete it to avoid incurring additional usage fees. You will still be charged for a domain even if it does not contain any documents—deleting all documents does not delete the domain. Deleting a domain deletes the index associated with the domain and takes the domain's document and search endpoints offline permanently. It can take some time to completely remove a domain and decommission all of its resources. Small domains are typically deleted in a short amount of time, while especially large domains may require an extended amount of time to be deleted. During this process, the domain status is `Being Deleted` and your account is not charged. You can delete a domain from the Amazon CloudSearch console, using the `aws cloudsearch delete-domain` command, or using the AWS SDKs. **Topics** + [Amazon CloudSearch console](#deleting-domains-console) + [Deleting a Domain Using the AWS CLI](#deleting-domains-clt) + [DeleteDomain](#deleting-domains-sdk) ## Deleting a Domain Using the Amazon CloudSearch Console You can easily delete a domain from the domain dashboard in the Amazon CloudSearch console. **To delete a domain** 1. Open the Amazon CloudSearch console at [https://console.aws.amazon.com/cloudsearch/home](https://console.aws.amazon.com/cloudsearch/home). 1. In left **Navigation** pane, choose **Domains**. 1. Select the checkbox next to the domain that you want to delete, then choose **Delete** and confirm deletion. ## Deleting a Domain Using the AWS CLI Run the `aws cloudsearch delete-domain` command and specify the name of the domain you want to delete. For example, to delete the *movies* domain, you specify `--domain-name movies`. ``` aws cloudsearch delete-domain --domain-name movies ``` For information about installing and setting up the AWS CLI, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/). ## Deleting Amazon CloudSearch Domains Using the AWS SDKs The AWS SDKs (except the Android and iOS SDKs) support all of the Amazon CloudSearch actions defined in the Amazon CloudSearch Configuration API, including `DeleteDomain`. For more information about installing and using the AWS SDKs, see [AWS Software Development Kits](http://aws.amazon.com/code). # Tagging Amazon CloudSearch Domains Use Amazon CloudSearch tags to attach metadata to your search domains. AWS does not apply any semantic meaning to your tags; tags are interpreted strictly as character strings. All tags contain the following elements. **** | Tag Element | Description | | --- | --- | | Tag key | The tag key is the required name of the tag. Tag keys must be unique for the domain to which they are attached. For a list of basic restrictions on tag keys and values, see [Tag Restrictions](http://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/allocation-tag-restrictions.html). | | Tag value | The tag value is an optional string value of the tag. Tag values can be null and do not have to be unique in a tag set. For example, you can have a key-value pair in a tag set of project/Trinity and cost-center/Trinity. For a list of basic restrictions on tag keys and values, see [Tag Restrictions](http://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/allocation-tag-restrictions.html). | Each Amazon CloudSearch domain has a tag set, which contains all the tags that are assigned to that domain. AWS does not automatically set any tags on Amazon CloudSearch domains. A tag set can contain as many as ten tags, or it can be empty. If you add a tag to an Amazon CloudSearch domain that has the same key as an existing tag for a resource, the new value overwrites the old value. You can use a tag key to define a category, and the tag value can be a item in that category. For example, you could define a tag key of `project` and a tag value of `Salix` indicating that the domain is assigned to the Salix project. You could also use tags to designate domains for test or production environments by using keys such as `environment=test` and `environment=production`. We recommend that you use a consistent set of tag keys to make it easier to track metadata associated with your search domains. You also can use tags to organize your AWS bill to reflect your own cost structure and to track costs by grouping expenses for similarly tagged resources. To do this, sign up to get your AWS account bill with tag key values included. Then, organize your billing information according to resources with the same tag key values to see the cost of combined resources. For example, you can tag several Amazon CloudSearch domains with key-value pairs, and then organize your billing information to see the total cost for each domain across several services. For more information, see [Cost Allocation and Tagging](http://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html) in the *AWS Billing and Cost Management* documentation. **Note** Tags are cached for authorization purposes. Because of this, additions and updates to tags on Amazon CloudSearch domains might take several minutes before they are available. ## Working with Tags (Console) Use the following procedure to create a resource tag with the Amazon CloudSearch console. **To create a tag** 1. Go to the Amazon CloudSearch console and choose the name of your domain to open its configuration panel. 1. Go to the **Tags** tab and choose **Manage**. 1. Enter a tag key and optional value, then choose **Submit**. For more information about using the console to work with tags, see [Working with the Tag Editor](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/tag-editor.html) in the *AWS Management Console Getting Started Guide*.