Add documentation for context and ABC templates (opensearch-project#8197

) * Add documentation for context and ABC templates Signed-off-by: Mohit Godwani <[email protected]> * Add information in create index and template Signed-off-by: Mohit Godwani <[email protected]> * Apply suggestions from code review Co-authored-by: Prabhakar Sithanandam <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> * Update _api-reference/index-apis/create-index.md Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <[email protected]> * Add technical writer review. Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Co-authored-by: Mohit Godwani <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <[email protected]> * Update _im-plugin/index-context.md Co-authored-by: Prabhakar Sithanandam <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Co-authored-by: Prabhakar Sithanandam <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> * Apply suggestions from code review Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> --------- Signed-off-by: Mohit Godwani <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> Co-authored-by: Naarcha-AWS <[email protected]> Co-authored-by: Prabhakar Sithanandam <[email protected]> Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Noah Staveley <[email protected]>
noahstaveley · Sep 23, 2024 · 355e1f0 · 355e1f0
1 parent 66354a4
commit 355e1f0
Show file tree

Hide file tree

Showing 3 changed files with 177 additions and 2 deletions.
diff --git a/_api-reference/index-apis/create-index-template.md b/_api-reference/index-apis/create-index-template.md
@@ -45,7 +45,7 @@ Parameter | Type | Description
 `priority` | Integer | A number that determines which index templates take precedence during the creation of a new index or data stream. OpenSearch chooses the template with the highest priority. When no priority is given, the template is assigned a `0`, signifying the lowest priority. Optional.
 `template` | Object | The template that includes the `aliases`, `mappings`, or `settings` for the index. For more information, see [#template]. Optional.
 `version` | Integer | The version number used to manage index templates. Version numbers are not automatically set by OpenSearch. Optional.
-
+`context` | Object | (Experimental) The `context` parameter provides use-case-specific predefined templates that can be applied to an index. Among all settings and mappings declared for a template, context templates hold the highest priority. For more information, see [index-context]({{site.url}}{{site.baseurl}}/im-plugin/index-context/).
 
 ### Template
 

diff --git a/_api-reference/index-apis/create-index.md b/_api-reference/index-apis/create-index.md
@@ -50,7 +50,7 @@ timeout | Time | How long to wait for the request to return. Default is `30s`.
 
 ## Request body
 
-As part of your request, you can optionally specify [index settings]({{site.url}}{{site.baseurl}}/im-plugin/index-settings/), [mappings]({{site.url}}{{site.baseurl}}/field-types/index/), and [aliases]({{site.url}}{{site.baseurl}}/opensearch/index-alias/) for your newly created index. 
+As part of your request, you can optionally specify [index settings]({{site.url}}{{site.baseurl}}/im-plugin/index-settings/), [mappings]({{site.url}}{{site.baseurl}}/field-types/index/), [aliases]({{site.url}}{{site.baseurl}}/opensearch/index-alias/), and [index context]({{site.url}}{{site.baseurl}}/opensearch/index-context/). 
 
 ## Example request
 

diff --git a/_im-plugin/index-context.md b/_im-plugin/index-context.md
@@ -0,0 +1,175 @@
+---
+layout: default
+title: Index context
+nav_order: 14
+redirect_from:
+  - /opensearch/index-context/
+---
+
+# Index context
+
+This is an experimental feature and is not recommended for use in a production environment. For updates on the progress the feature or if you want to leave feedback, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/).    
+{: .warning}
+
+Index context declares the use case for an index. Using the context information, OpenSearch applies a predetermined set of settings and mappings, which provides the following benefits:
+
+- Optimized performance
+- Settings tuned to your specific use case
+- Accurate mappings and aliases based on [OpenSearch Integrations]({{site.url}}{{site.baseurl}}/integrations/)
+
+The settings and metadata configuration that are applied using component templates are automatically loaded when your cluster starts. Component templates that start with `@abc_template@` or Application-Based Configuration (ABC) templates can only be used through a `context` object declaration, in order to prevent configuration issues.
+{: .warning}
+
+
+## Installation
+
+To install the index context feature:
+
+1. Install the `opensearch-system-templates` plugin on all nodes in your cluster using one of the [installation methods]({{site.url}}{{site.baseurl}}/install-and-configure/plugins/#install).
+
+2. Set the feature flag `opensearch.experimental.feature.application_templates.enabled` to `true`. For more information about enabling and disabling feature flags, see [Enabling experimental features]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/experimental/).
+
+3. Set the `cluster.application_templates.enabled` setting to `true`. For instructions on how to configure OpenSearch, see [configuring settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index/#static-settings).
+
+## Using the `context` setting
+
+Use the `context` setting with the Index API to add use-case-specific context.
+
+### Considerations
+
+Consider the following when using the `context` parameter during index creation:
+
+1. If you use the `context` parameter to create an index, you cannot include any settings declared in the index context during index creation or dynamic settings updates.
+2. The index context becomes permanent when set on an index or index template.
+
+When you adhere to these limitations, suggested configurations or mappings are uniformly applied on indexed data within the specified context.
+
+### Examples
+
+The following examples show how to use index context.
+
+
+#### Create an index
+
+The following example request creates an index in which to store metric data by declaring a `metrics` mapping as the context:
+
+```json
+PUT /my-metrics-index
+{
+  "context": {
+    "name": "metrics"
+  }
+}
+```
+{% include copy-curl.html %}
+
+After creation, the context is added to the index and the corresponding settings are applied:
+
+
+**GET request**
+
+```json
+GET /my-metrics-index
+```
+{% include copy-curl.html %}
+
+
+**Response**
+
+```json
+{
+    "my-metrics-index": {
+        "aliases": {},
+        "mappings": {},
+        "settings": {
+            "index": {
+                "codec": "zstd_no_dict",
+                "refresh_interval": "60s",
+                "number_of_shards": "1",
+                "provided_name": "my-metrics-index",
+                "merge": {
+                    "policy": "log_byte_size"
+                },
+                "context": {
+                    "created_version": "1",
+                    "current_version": "1"
+                },
+                ...
+            }
+        },
+        "context": {
+            "name": "metrics",
+            "version": "_latest"
+        }
+    }
+}
+```
+
+
+#### Create an index template
+
+You can also use the `context` parameter when creating an index template. The following example request creates an index template with the context information as `logs`:
+
+```json
+PUT _index_template/my-logs
+{
+    "context": {
+        "name": "logs",
+        "version": "1"
+    },
+    "index_patterns": [
+        "my-logs-*"
+    ]
+}
+```
+{% include copy-curl.html %}
+
+All indexes created using this index template will get the metadata provided by the associated component template. The following request and response show how `context` is added to the template:
+
+**Get index template**
+
+```json
+GET _index_template/my-logs
+```
+{% include copy-curl.html %}
+
+**Response**
+
+```json
+{
+    "index_templates": [
+        {
+            "name": "my-logs2",
+            "index_template": {
+                "index_patterns": [
+                    "my-logs1-*"
+                ],
+                "context": {
+                    "name": "logs",
+                    "version": "1"
+                }
+            }
+        }
+    ]
+}
+```
+
+If there is any conflict between any settings, mappings, or aliases directly declared by your template and the backing component template for the context, the latter gets higher priority during index creation.
+
+
+## Available context templates
+
+The following templates are available to be used through the `context` parameter as of OpenSearch 2.17:
+
+- `logs`
+- `metrics`
+- `nginx-logs`
+- `amazon-cloudtrail-logs`
+- `amazon-elb-logs`
+- `amazon-s3-logs`
+- `apache-web-logs`
+- `k8s-logs`
+
+For more information about these templates, see the [OpenSearch system templates repository](https://github.com/opensearch-project/opensearch-system-templates/tree/main/src/main/resources/org/opensearch/system/applicationtemplates/v1).
+
+To view the current version of these templates on your cluster, use `GET /_component_template`.