From 302d02256703cf97d962b44187db3a4ad863ee12 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Thu, 28 Oct 2021 15:49:13 -0700 Subject: [PATCH 1/6] Added exists and close index to REST API --- .../rest-api/index-apis/close-index.md | 53 +++++++++++++++++++ .../rest-api/index-apis/delete-index.md | 2 +- _opensearch/rest-api/index-apis/exists.md | 43 +++++++++++++++ _opensearch/rest-api/index-apis/get-index.md | 2 +- 4 files changed, 98 insertions(+), 2 deletions(-) create mode 100644 _opensearch/rest-api/index-apis/close-index.md create mode 100644 _opensearch/rest-api/index-apis/exists.md diff --git a/_opensearch/rest-api/index-apis/close-index.md b/_opensearch/rest-api/index-apis/close-index.md new file mode 100644 index 00000000..8c2d09a4 --- /dev/null +++ b/_opensearch/rest-api/index-apis/close-index.md @@ -0,0 +1,53 @@ +--- +layout: default +title: Close index +parent: Index APIs +grand_parent: REST API reference +nav_order: 30 +--- + +# Close index +Introduced 1.0 +{: .label .label-purple } + +The close index API operation closes an index. Once an index is closed, you cannot add data to it or search for any data within the index. + +## Example + +```json +POST /sample-index/_close +``` + +## Path and HTTP methods + +``` +POST //_close +``` + +## URL parameters + +All parameters are optional. + +Parameter | Type | Description +:--- | :--- | :--- +<index-name> | String | The index to close. Can be a comma-separated list of multiple index names. Use `_all` or * to close all indices. +allow_no_indices | Boolean | Whether to ignore wildcards that don't match any indices. Default is true. +expand_wildcards | String | Expands wildcard expressions to different indices. Combine multiple values with commas. Available values are all (match all indices), open (match open indices), closed (match closed indices), hidden (match hidden indices), and none (do not accept wildcard expressions). Default is open. +ignore_unavailable | Boolean | If true, OpenSearch does not search for missing or closed indices. Default is false. +wait_for_active_shards | String | Specifies the number of active shards that must be available before OpenSearch processes the request. Default is 1 (only the primary shard). Set to all or a positive integer. Values greater than 1 require replicas. For example, if you specify a value of 3, the index must have two replicas distributed across two additional nodes for the request to succeed. +master_timeout | Time | How long to wait for a connection to the master node. Default is `30s`. +timeout | Time | How long to wait for a response from the cluster. Default is `30s`. + + +## Response +```json +{ + "acknowledged": true, + "shards_acknowledged": true, + "indices": { + "sample-index1": { + "closed": true + } + } +} +``` diff --git a/_opensearch/rest-api/index-apis/delete-index.md b/_opensearch/rest-api/index-apis/delete-index.md index 953225e0..ab6377a0 100644 --- a/_opensearch/rest-api/index-apis/delete-index.md +++ b/_opensearch/rest-api/index-apis/delete-index.md @@ -3,7 +3,7 @@ layout: default title: Delete index parent: Index APIs grand_parent: REST API reference -nav_order: 5 +nav_order: 10 --- # Delete index diff --git a/_opensearch/rest-api/index-apis/exists.md b/_opensearch/rest-api/index-apis/exists.md new file mode 100644 index 00000000..3a156277 --- /dev/null +++ b/_opensearch/rest-api/index-apis/exists.md @@ -0,0 +1,43 @@ +--- +layout: default +title: Index exists +parent: Index APIs +grand_parent: REST API reference +nav_order: 5 +--- + +# Index exists +Introduced 1.0 +{: .label .label-purple } + +The index exists API operation returns whether or not an index already exists. + +## Example + +```json +HEAD /sample-index +``` + +## Path and HTTP methods + +``` +HEAD / +``` + +## URL parameters + +All parameters are optional. + +Parameter | Type | Description +:--- | :--- | :--- +allow_no_indices | Boolean | Whether to ignore wildcards that don't match any indices. Default is true. +expand_wildcards | String | Expands wildcard expressions to different indices. Combine multiple values with commas. Available values are all (match all indices), open (match open indices), closed (match closed indices), hidden (match hidden indices), and none (do not accept wildcard expressions). Default is open. +flat_settings | Boolean | Whether to return settings in the flat form, which can improve readability, especially for heavily nested settings. For example, the flat form of "index": { "creation_date": "123456789" } is "index.creation_date": "123456789". +include_defaults | Boolean | Whether to include default settings as part of the response. This parameter is useful for identifying the names and current values of settings you want to update. +ignore_unavailable | Boolean | If true, OpenSearch does not search for missing or closed indices. Default is false. +local | Boolean | Whether to return information from only the local node instead of from the master node. Default is false. + + +## Response + +The index exists API operation returns only one of two possible response codes: `200` -- the index exists, and `404` -- the index does not exist. diff --git a/_opensearch/rest-api/index-apis/get-index.md b/_opensearch/rest-api/index-apis/get-index.md index 3716b495..7e37a6ee 100644 --- a/_opensearch/rest-api/index-apis/get-index.md +++ b/_opensearch/rest-api/index-apis/get-index.md @@ -3,7 +3,7 @@ layout: default title: Get index parent: Index APIs grand_parent: REST API reference -nav_order: 10 +nav_order: 20 --- # Get index From d9b98fad1bc1da720db546bae932145fa6990922 Mon Sep 17 00:00:00 2001 From: bowenlan-amzn Date: Mon, 1 Nov 2021 09:58:51 -0700 Subject: [PATCH 2/6] ism doc changes 1. suggest setup error notification 2. mention rollover_skip index setting Signed-off-by: bowenlan-amzn --- _im-plugin/ism/index.md | 4 ++-- _im-plugin/ism/policies.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/_im-plugin/ism/index.md b/_im-plugin/ism/index.md index 8004146c..f8dabe06 100644 --- a/_im-plugin/ism/index.md +++ b/_im-plugin/ism/index.md @@ -39,7 +39,7 @@ You can use the visual editor or JSON editor to create policies. Compared to the 2. Choose **Create policy**. 3. Choose **Visual editor**. 4. In the **Policy info** section, enter a policy ID and an optional description. -5. In the **Error notification** section, set up an optional error notification that gets sent whenever a policy execution fails. For more information, see [Error notifications]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#error-notifications). +5. In the **Error notification** section, set up an optional error notification that gets sent whenever a policy execution fails. Please set up this if you are using ISM for auto rollover. This helps to prevent unexpected huge index when rollover action failed. For more information, see [Error notifications]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#error-notifications). 6. In **ISM templates**, enter any ISM template patterns to automatically apply this policy to existing and future indices. For example, if you specify a template of `sample-index*`, the ISM plugin automatically applies this policy to any indices whose names start with `sample-index`. 7. In **States**, add any states you want to include in the policy. Each state has [actions]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies/#actions) the plugin executes when the index enters a certain state, and [transitions]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies/#transitions), which have conditions that, when met, transition the index into a destination state. The first state you create in a policy is automatically set as the initial state. Each policy must have at least one state, but actions and transitions are optional. 8. Choose **Create**. @@ -76,7 +76,7 @@ PUT _plugins/_ism/policies/policy_id If you have more than one template that matches an index pattern, ISM uses the priority value to determine which template to apply. -For an example ISM template policy, see [Sample policy with ISM template]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#sample-policy-with-ism-template). +For an example ISM template policy, see [Sample policy with ISM template for auto rollover]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#sample-policy-with-ism-template-for-auto-rollover). Older versions of the plugin include the `policy_id` in an index template, so when an index is created that matches the index template pattern, the index will have the policy attached to it: diff --git a/_im-plugin/ism/policies.md b/_im-plugin/ism/policies.md index 1d8f44b1..b8d64a66 100644 --- a/_im-plugin/ism/policies.md +++ b/_im-plugin/ism/policies.md @@ -517,9 +517,9 @@ The destination system **must** return a response otherwise the `error_notificat You can use the same options for `ctx` variables as the [notification](#notification) operation. -## Sample policy with ISM template +## Sample policy with ISM template for auto rollover -The following sample template policy is for a rollover use case. +If you want to skip the rollover action for an index, you can set this index setting `index.plugins.index_state_management.rollover_skip` to true. 1. Create a policy with an `ism_template` field: From 7ded80ce113e2c70721195d80daaa332538a43cd Mon Sep 17 00:00:00 2001 From: Keith Chan <12404772+keithhc2@users.noreply.github.com> Date: Mon, 1 Nov 2021 14:34:04 -0700 Subject: [PATCH 3/6] Minor language tweaks --- _im-plugin/ism/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_im-plugin/ism/index.md b/_im-plugin/ism/index.md index f8dabe06..8fcf9d36 100644 --- a/_im-plugin/ism/index.md +++ b/_im-plugin/ism/index.md @@ -39,7 +39,7 @@ You can use the visual editor or JSON editor to create policies. Compared to the 2. Choose **Create policy**. 3. Choose **Visual editor**. 4. In the **Policy info** section, enter a policy ID and an optional description. -5. In the **Error notification** section, set up an optional error notification that gets sent whenever a policy execution fails. Please set up this if you are using ISM for auto rollover. This helps to prevent unexpected huge index when rollover action failed. For more information, see [Error notifications]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#error-notifications). +5. In the **Error notification** section, set up an optional error notification that gets sent whenever a policy execution fails. For more information, see [Error notifications]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#error-notifications). If you're using auto rollovers in your policy, we recommend setting up error notifications, which help prevent unexpectedly large indices if rollovers fail. 6. In **ISM templates**, enter any ISM template patterns to automatically apply this policy to existing and future indices. For example, if you specify a template of `sample-index*`, the ISM plugin automatically applies this policy to any indices whose names start with `sample-index`. 7. In **States**, add any states you want to include in the policy. Each state has [actions]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies/#actions) the plugin executes when the index enters a certain state, and [transitions]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies/#transitions), which have conditions that, when met, transition the index into a destination state. The first state you create in a policy is automatically set as the initial state. Each policy must have at least one state, but actions and transitions are optional. 8. Choose **Create**. @@ -76,7 +76,7 @@ PUT _plugins/_ism/policies/policy_id If you have more than one template that matches an index pattern, ISM uses the priority value to determine which template to apply. -For an example ISM template policy, see [Sample policy with ISM template for auto rollover]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#sample-policy-with-ism-template-for-auto-rollover). +For an example ISM template policy, see [Sample policy with ISM template with auto rollover]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#sample-policy-with-ism-template-with-auto-rollover). Older versions of the plugin include the `policy_id` in an index template, so when an index is created that matches the index template pattern, the index will have the policy attached to it: From a31f0efa72c8758cd577474190256ba2451dcff8 Mon Sep 17 00:00:00 2001 From: Keith Chan <12404772+keithhc2@users.noreply.github.com> Date: Mon, 1 Nov 2021 14:37:01 -0700 Subject: [PATCH 4/6] Minor language tweak again --- _im-plugin/ism/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/ism/index.md b/_im-plugin/ism/index.md index 8fcf9d36..4fb68ef4 100644 --- a/_im-plugin/ism/index.md +++ b/_im-plugin/ism/index.md @@ -76,7 +76,7 @@ PUT _plugins/_ism/policies/policy_id If you have more than one template that matches an index pattern, ISM uses the priority value to determine which template to apply. -For an example ISM template policy, see [Sample policy with ISM template with auto rollover]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#sample-policy-with-ism-template-with-auto-rollover). +For an example ISM template policy, see [Sample policy with ISM template for auto rollover]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#sample-policy-with-ism-template-for-auto-rollover). Older versions of the plugin include the `policy_id` in an index template, so when an index is created that matches the index template pattern, the index will have the policy attached to it: From 2f35a61805aae7f28411443d08fb16d65956ee35 Mon Sep 17 00:00:00 2001 From: Keith Chan <12404772+keithhc2@users.noreply.github.com> Date: Mon, 1 Nov 2021 14:39:26 -0700 Subject: [PATCH 5/6] Added a hyperlink to update cluster settings API --- _im-plugin/ism/policies.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/_im-plugin/ism/policies.md b/_im-plugin/ism/policies.md index b8d64a66..58918b5a 100644 --- a/_im-plugin/ism/policies.md +++ b/_im-plugin/ism/policies.md @@ -519,7 +519,9 @@ You can use the same options for `ctx` variables as the [notification](#notifica ## Sample policy with ISM template for auto rollover -If you want to skip the rollover action for an index, you can set this index setting `index.plugins.index_state_management.rollover_skip` to true. +The following sample template policy is for a rollover use case. + +If you want to skip rollovers for an index, use the [update cluster settings API]({{site.url}}{{site.baseurl}}/opensearch/configuration/#update-cluster-settings-using-the-api) to set `index.plugins.index_state_management.rollover_skip` to true. 1. Create a policy with an `ism_template` field: From 7f7f786d80270052f2cdfcb85c72fd4aaa93b7c5 Mon Sep 17 00:00:00 2001 From: Keith Chan <12404772+keithhc2@users.noreply.github.com> Date: Mon, 1 Nov 2021 14:47:55 -0700 Subject: [PATCH 6/6] Update index.md --- _im-plugin/ism/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/ism/index.md b/_im-plugin/ism/index.md index 4fb68ef4..62da2eb6 100644 --- a/_im-plugin/ism/index.md +++ b/_im-plugin/ism/index.md @@ -39,7 +39,7 @@ You can use the visual editor or JSON editor to create policies. Compared to the 2. Choose **Create policy**. 3. Choose **Visual editor**. 4. In the **Policy info** section, enter a policy ID and an optional description. -5. In the **Error notification** section, set up an optional error notification that gets sent whenever a policy execution fails. For more information, see [Error notifications]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#error-notifications). If you're using auto rollovers in your policy, we recommend setting up error notifications, which help prevent unexpectedly large indices if rollovers fail. +5. In the **Error notification** section, set up an optional error notification that gets sent whenever a policy execution fails. For more information, see [Error notifications]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#error-notifications). If you're using auto rollovers in your policy, we recommend setting up error notifications, which notify you of unexpectedly large indices if rollovers fail. 6. In **ISM templates**, enter any ISM template patterns to automatically apply this policy to existing and future indices. For example, if you specify a template of `sample-index*`, the ISM plugin automatically applies this policy to any indices whose names start with `sample-index`. 7. In **States**, add any states you want to include in the policy. Each state has [actions]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies/#actions) the plugin executes when the index enters a certain state, and [transitions]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies/#transitions), which have conditions that, when met, transition the index into a destination state. The first state you create in a policy is automatically set as the initial state. Each policy must have at least one state, but actions and transitions are optional. 8. Choose **Create**.