From da7580f73333489f6362cdc2672563b7f6890e29 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 26 Jun 2023 12:00:24 -0700 Subject: [PATCH 1/2] Add descriptions for component templates --- .../ClusterDeleteComponentTemplateRequest.ts | 16 ++++-- .../ClusterGetComponentTemplateRequest.ts | 27 ++++++++-- .../ClusterPutComponentTemplateRequest.ts | 50 +++++++++++++++---- specification/indices/_types/IndexState.ts | 2 +- 4 files changed, 76 insertions(+), 19 deletions(-) diff --git a/specification/cluster/delete_component_template/ClusterDeleteComponentTemplateRequest.ts b/specification/cluster/delete_component_template/ClusterDeleteComponentTemplateRequest.ts index 36dc7a3007..e2c40d219e 100644 --- a/specification/cluster/delete_component_template/ClusterDeleteComponentTemplateRequest.ts +++ b/specification/cluster/delete_component_template/ClusterDeleteComponentTemplateRequest.ts @@ -22,11 +22,13 @@ import { Names } from '@_types/common' import { Duration } from '@_types/Time' /** + * Deletes component templates. + * Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases. * @rest_spec_name cluster.delete_component_template * @availability stack since=7.8.0 stability=stable * @availability serverless stability=stable visibility=public * @doc_id indices-component-template - * @cluster_privileges manage_index_templates,manage + * @cluster_privileges manage_index_templates */ export interface Request extends RequestBase { path_parts: { @@ -36,9 +38,17 @@ export interface Request extends RequestBase { name: Names } query_parameters: { - /** @server_default 30s */ + /** + * Period to wait for a connection to the master node. + * If no response is received before the timeout expires, the request fails and returns an error. + * @server_default 30s + */ master_timeout?: Duration - /** @server_default 30s */ + /** + * Period to wait for a response. + * If no response is received before the timeout expires, the request fails and returns an error. + * @server_default 30s + */ timeout?: Duration } } diff --git a/specification/cluster/get_component_template/ClusterGetComponentTemplateRequest.ts b/specification/cluster/get_component_template/ClusterGetComponentTemplateRequest.ts index 866599e9c6..e0e8d588f0 100644 --- a/specification/cluster/get_component_template/ClusterGetComponentTemplateRequest.ts +++ b/specification/cluster/get_component_template/ClusterGetComponentTemplateRequest.ts @@ -22,27 +22,44 @@ import { Name } from '@_types/common' import { Duration } from '@_types/Time' /** + * Retrieves information about component templates. * @rest_spec_name cluster.get_component_template * @availability stack since=7.8.0 stability=stable * @availability serverless stability=stable visibility=public + * @cluster_privileges manage_index_templates * @doc_id indices-component-template */ export interface Request extends RequestBase { path_parts: { + /** + * Comma-separated list of component template names used to limit the request. + * Wildcard (`*`) expressions are supported. + */ name?: Name } query_parameters: { - /** @server_default false */ + /** + * If `true`, returns settings in flat format. + * @server_default false + */ flat_settings?: boolean - /** @server_default false */ - local?: boolean - /** @server_default 30s */ - master_timeout?: Duration /** * @server_default false * @availability stack since=8.8.0 stability=experimental * @availability serverless stability=experimental */ include_defaults?: boolean + /** + * If `true`, the request retrieves information from the local node only. + * If `false`, information is retrieved from the master node. + * @server_default false + */ + local?: boolean + /** + * Period to wait for a connection to the master node. + * If no response is received before the timeout expires, the request fails and returns an error. + * @server_default 30s + */ + master_timeout?: Duration } } diff --git a/specification/cluster/put_component_template/ClusterPutComponentTemplateRequest.ts b/specification/cluster/put_component_template/ClusterPutComponentTemplateRequest.ts index 9138c53f33..c69b8a72f9 100644 --- a/specification/cluster/put_component_template/ClusterPutComponentTemplateRequest.ts +++ b/specification/cluster/put_component_template/ClusterPutComponentTemplateRequest.ts @@ -27,22 +27,57 @@ import { TypeMapping } from '@_types/mapping/TypeMapping' import { Duration } from '@_types/Time' /** + * Creates or updates a component template. + * Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases. + * + * An index template can be composed of multiple component templates. + * To use a component template, specify it in an index template’s `composed_of` list. + * Component templates are only applied to new data streams and indices as part of a matching index template. + * + * Settings and mappings specified directly in the index template or the create index request override any settings or mappings specified in a component template. + * + * Component templates are only used during index creation. + * For data streams, this includes data stream creation and the creation of a stream’s backing indices. + * Changes to component templates do not affect existing indices, including a stream’s backing indices. + * + * You can use C-style `/* *\/` block comments in component templates. + * You can include comments anywhere in the request body except before the opening curly bracket. * @rest_spec_name cluster.put_component_template * @availability stack since=7.8.0 stability=stable * @availability serverless stability=stable visibility=public + * @cluster_privileges manage_index_templates * @doc_id indices-component-template */ export interface Request extends RequestBase { path_parts: { + /** + * Name of the component template to create. + * Elasticsearch includes the following built-in component templates: `logs-mappings`; 'logs-settings`; `metrics-mappings`; `metrics-settings`;`synthetics-mapping`; `synthetics-settings`. + * Elastic Agent uses these templates to configure backing indices for its data streams. + * If you use Elastic Agent and want to overwrite one of these templates, set the `version` for your replacement template higher than the current version. + * If you don’t use Elastic Agent and want to disable all built-in component and index templates, set `stack.templates.enabled` to `false` using the cluster update settings API. + */ name: Name } query_parameters: { - /** @server_default false */ + /** + * If `true`, this request cannot replace or update existing component templates. + * @server_default false */ create?: boolean - /** @server_default 30s */ + /** + * Period to wait for a connection to the master node. + * If no response is received before the timeout expires, the request fails and returns an error. + * @server_default 30s */ master_timeout?: Duration } body: { + /** + * This setting overrides the value of the `action.auto_create_index` cluster setting. + * If set to `true` in a template, then indices can be automatically created using that + * template even if auto-creation of indices is disabled via `actions.auto_create_index`. + * If set to `false` then data streams matching the template must always be explicitly created. + */ + allow_auto_create?: boolean /** * The template to be applied which includes mappings, settings, or aliases configuration. */ @@ -50,20 +85,15 @@ export interface Request extends RequestBase { /** * Version number used to manage component templates externally. * This number isn't automatically generated or incremented by Elasticsearch. + * To unset a version, replace the template without specifying a version. */ version?: VersionNumber /** * Optional user metadata about the component template. * May have any contents. This map is not automatically generated by Elasticsearch. - * @doc_id mapping-meta-field + * This information is stored in the cluster state, so keeping it short is preferable. + * To unset `_meta`, replace the template without specifying this information. */ _meta?: Metadata - /** - * This setting overrides the value of the `action.auto_create_index` cluster setting. - * If set to `true` in a template, then indices can be automatically created using that - * template even if auto-creation of indices is disabled via `actions.auto_create_index`. - * If set to `false` then data streams matching the template must always be explicitly created. - */ - allow_auto_create?: boolean } } diff --git a/specification/indices/_types/IndexState.ts b/specification/indices/_types/IndexState.ts index ac73e0d801..0d6e8de909 100644 --- a/specification/indices/_types/IndexState.ts +++ b/specification/indices/_types/IndexState.ts @@ -32,7 +32,7 @@ export class IndexState { defaults?: IndexSettings data_stream?: DataStreamName /** - * Data lifecycle applicable iff this is a data stream. + * Data lifecycle applicable if this is a data stream. * @availability stack since=8.8.0 stability=experimental * @availability serverless stability=experimental */ From fa38fd4b8a569f425ad3453cf562981dc37798e5 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 26 Jun 2023 12:01:46 -0700 Subject: [PATCH 2/2] Generate output --- output/schema/schema.json | 116 ++++++++++-------- output/typescript/types.ts | 4 +- .../ClusterDeleteComponentTemplateRequest.ts | 4 +- .../ClusterGetComponentTemplateRequest.ts | 2 +- .../ClusterPutComponentTemplateRequest.ts | 12 +- 5 files changed, 73 insertions(+), 65 deletions(-) diff --git a/output/schema/schema.json b/output/schema/schema.json index 30ebab4510..d0320087c3 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -2423,8 +2423,7 @@ "name": "cluster.delete_component_template", "privileges": { "cluster": [ - "manage_index_templates", - "manage" + "manage_index_templates" ] }, "request": { @@ -2540,6 +2539,11 @@ "docId": "indices-component-template", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-component-template.html", "name": "cluster.get_component_template", + "privileges": { + "cluster": [ + "manage_index_templates" + ] + }, "request": { "name": "Request", "namespace": "cluster.get_component_template" @@ -2793,6 +2797,11 @@ "docId": "indices-component-template", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/indices-component-template.html", "name": "cluster.put_component_template", + "privileges": { + "cluster": [ + "manage_index_templates" + ] + }, "request": { "name": "Request", "namespace": "cluster.put_component_template" @@ -95575,7 +95584,7 @@ "body": { "kind": "no_body" }, - "description": "Deletes a component template", + "description": "Deletes component templates.\nComponent templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.", "inherits": { "type": { "name": "RequestBase", @@ -95603,7 +95612,7 @@ ], "query": [ { - "description": "Specify timeout for connection to master", + "description": "Period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -95616,7 +95625,7 @@ } }, { - "description": "Explicit operation timeout", + "description": "Period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "timeout", "required": false, "serverDefault": "30s", @@ -95629,7 +95638,7 @@ } } ], - "specLocation": "cluster/delete_component_template/ClusterDeleteComponentTemplateRequest.ts#L24-L44" + "specLocation": "cluster/delete_component_template/ClusterDeleteComponentTemplateRequest.ts#L24-L54" }, { "body": { @@ -95778,7 +95787,7 @@ "body": { "kind": "no_body" }, - "description": "Returns one or more component templates", + "description": "Retrieves information about component templates.", "inherits": { "type": { "name": "RequestBase", @@ -95792,7 +95801,7 @@ }, "path": [ { - "description": "The comma separated names of the component templates", + "description": "Comma-separated list of component template names used to limit the request.\nWildcard (`*`) expressions are supported.", "name": "name", "required": false, "type": { @@ -95806,6 +95815,7 @@ ], "query": [ { + "description": "If `true`, returns settings in flat format.", "name": "flat_settings", "required": false, "serverDefault": false, @@ -95818,10 +95828,21 @@ } }, { - "description": "Return local information, do not retrieve the state from master node (default: false)", - "name": "local", + "availability": { + "serverless": { + "stability": "experimental" + }, + "stack": { + "since": "8.8.0", + "stability": "experimental" + } + }, + "description": "Return all default configurations for the component template (default: false)", + "name": "include_defaults", "required": false, "serverDefault": false, + "since": "8.8.0", + "stability": "experimental", "type": { "kind": "instance_of", "type": { @@ -95831,44 +95852,33 @@ } }, { - "description": "Explicit operation timeout for connection to master node", - "name": "master_timeout", + "description": "If `true`, the request retrieves information from the local node only.\nIf `false`, information is retrieved from the master node.", + "name": "local", "required": false, - "serverDefault": "30s", + "serverDefault": false, "type": { "kind": "instance_of", "type": { - "name": "Duration", - "namespace": "_types" + "name": "boolean", + "namespace": "_builtins" } } }, { - "availability": { - "serverless": { - "stability": "experimental" - }, - "stack": { - "since": "8.8.0", - "stability": "experimental" - } - }, - "description": "Return all default configurations for the component template (default: false)", - "name": "include_defaults", + "description": "Period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", + "name": "master_timeout", "required": false, - "serverDefault": false, - "since": "8.8.0", - "stability": "experimental", + "serverDefault": "30s", "type": { "kind": "instance_of", "type": { - "name": "boolean", - "namespace": "_builtins" + "name": "Duration", + "namespace": "_types" } } } ], - "specLocation": "cluster/get_component_template/ClusterGetComponentTemplateRequest.ts#L24-L48" + "specLocation": "cluster/get_component_template/ClusterGetComponentTemplateRequest.ts#L24-L65" }, { "body": { @@ -97049,6 +97059,18 @@ "body": { "kind": "properties", "properties": [ + { + "description": "This setting overrides the value of the `action.auto_create_index` cluster setting.\nIf set to `true` in a template, then indices can be automatically created using that\ntemplate even if auto-creation of indices is disabled via `actions.auto_create_index`.\nIf set to `false` then data streams matching the template must always be explicitly created.", + "name": "allow_auto_create", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" + } + } + }, { "description": "The template to be applied which includes mappings, settings, or aliases configuration.", "name": "template", @@ -97062,7 +97084,7 @@ } }, { - "description": "Version number used to manage component templates externally.\nThis number isn't automatically generated or incremented by Elasticsearch.", + "description": "Version number used to manage component templates externally.\nThis number isn't automatically generated or incremented by Elasticsearch.\nTo unset a version, replace the template without specifying a version.", "name": "version", "required": false, "type": { @@ -97074,9 +97096,7 @@ } }, { - "description": "Optional user metadata about the component template.\nMay have any contents. This map is not automatically generated by Elasticsearch.", - "docId": "mapping-meta-field", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-meta-field.html", + "description": "Optional user metadata about the component template.\nMay have any contents. This map is not automatically generated by Elasticsearch.\nThis information is stored in the cluster state, so keeping it short is preferable.\nTo unset `_meta`, replace the template without specifying this information.", "name": "_meta", "required": false, "type": { @@ -97086,22 +97106,10 @@ "namespace": "_types" } } - }, - { - "description": "This setting overrides the value of the `action.auto_create_index` cluster setting.\nIf set to `true` in a template, then indices can be automatically created using that\ntemplate even if auto-creation of indices is disabled via `actions.auto_create_index`.\nIf set to `false` then data streams matching the template must always be explicitly created.", - "name": "allow_auto_create", - "required": false, - "type": { - "kind": "instance_of", - "type": { - "name": "boolean", - "namespace": "_builtins" - } - } } ] }, - "description": "Creates or updates a component template", + "description": "Creates or updates a component template.\nComponent templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.\n\nAn index template can be composed of multiple component templates.\nTo use a component template, specify it in an index template’s `composed_of` list.\nComponent templates are only applied to new data streams and indices as part of a matching index template.\n\nSettings and mappings specified directly in the index template or the create index request override any settings or mappings specified in a component template.\n\nComponent templates are only used during index creation.\nFor data streams, this includes data stream creation and the creation of a stream’s backing indices.\nChanges to component templates do not affect existing indices, including a stream’s backing indices.\n\nYou can use C-style `/* *\\/` block comments in component templates.\nYou can include comments anywhere in the request body except before the opening curly bracket.", "inherits": { "type": { "name": "RequestBase", @@ -97115,7 +97123,7 @@ }, "path": [ { - "description": "The name of the template", + "description": "Name of the component template to create.\nElasticsearch includes the following built-in component templates: `logs-mappings`; 'logs-settings`; `metrics-mappings`; `metrics-settings`;`synthetics-mapping`; `synthetics-settings`.\nElastic Agent uses these templates to configure backing indices for its data streams.\nIf you use Elastic Agent and want to overwrite one of these templates, set the `version` for your replacement template higher than the current version.\nIf you don’t use Elastic Agent and want to disable all built-in component and index templates, set `stack.templates.enabled` to `false` using the cluster update settings API.", "name": "name", "required": true, "type": { @@ -97129,7 +97137,7 @@ ], "query": [ { - "description": "Whether the index template should only be added if new or can also replace an existing one", + "description": "If `true`, this request cannot replace or update existing component templates.", "name": "create", "required": false, "serverDefault": false, @@ -97142,7 +97150,7 @@ } }, { - "description": "Specify timeout for connection to master", + "description": "Period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -97155,7 +97163,7 @@ } } ], - "specLocation": "cluster/put_component_template/ClusterPutComponentTemplateRequest.ts#L29-L69" + "specLocation": "cluster/put_component_template/ClusterPutComponentTemplateRequest.ts#L29-L99" }, { "body": { @@ -108955,7 +108963,7 @@ "stability": "experimental" } }, - "description": "Data lifecycle applicable iff this is a data stream.", + "description": "Data lifecycle applicable if this is a data stream.", "name": "lifecycle", "required": false, "since": "8.8.0", diff --git a/output/typescript/types.ts b/output/typescript/types.ts index d34c94413e..bbdc0bbade 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -8437,9 +8437,9 @@ export type ClusterExistsComponentTemplateResponse = boolean export interface ClusterGetComponentTemplateRequest extends RequestBase { name?: Name flat_settings?: boolean + include_defaults?: boolean local?: boolean master_timeout?: Duration - include_defaults?: boolean } export interface ClusterGetComponentTemplateResponse { @@ -8560,10 +8560,10 @@ export interface ClusterPutComponentTemplateRequest extends RequestBase { create?: boolean master_timeout?: Duration body?: { + allow_auto_create?: boolean template: IndicesIndexState version?: VersionNumber _meta?: Metadata - allow_auto_create?: boolean } } diff --git a/specification/cluster/delete_component_template/ClusterDeleteComponentTemplateRequest.ts b/specification/cluster/delete_component_template/ClusterDeleteComponentTemplateRequest.ts index e2c40d219e..1d695916f8 100644 --- a/specification/cluster/delete_component_template/ClusterDeleteComponentTemplateRequest.ts +++ b/specification/cluster/delete_component_template/ClusterDeleteComponentTemplateRequest.ts @@ -38,7 +38,7 @@ export interface Request extends RequestBase { name: Names } query_parameters: { - /** + /** * Period to wait for a connection to the master node. * If no response is received before the timeout expires, the request fails and returns an error. * @server_default 30s @@ -46,7 +46,7 @@ export interface Request extends RequestBase { master_timeout?: Duration /** * Period to wait for a response. - * If no response is received before the timeout expires, the request fails and returns an error. + * If no response is received before the timeout expires, the request fails and returns an error. * @server_default 30s */ timeout?: Duration diff --git a/specification/cluster/get_component_template/ClusterGetComponentTemplateRequest.ts b/specification/cluster/get_component_template/ClusterGetComponentTemplateRequest.ts index e0e8d588f0..e7d2cdf80e 100644 --- a/specification/cluster/get_component_template/ClusterGetComponentTemplateRequest.ts +++ b/specification/cluster/get_component_template/ClusterGetComponentTemplateRequest.ts @@ -57,7 +57,7 @@ export interface Request extends RequestBase { local?: boolean /** * Period to wait for a connection to the master node. - * If no response is received before the timeout expires, the request fails and returns an error. + * If no response is received before the timeout expires, the request fails and returns an error. * @server_default 30s */ master_timeout?: Duration diff --git a/specification/cluster/put_component_template/ClusterPutComponentTemplateRequest.ts b/specification/cluster/put_component_template/ClusterPutComponentTemplateRequest.ts index c69b8a72f9..91545c4126 100644 --- a/specification/cluster/put_component_template/ClusterPutComponentTemplateRequest.ts +++ b/specification/cluster/put_component_template/ClusterPutComponentTemplateRequest.ts @@ -29,17 +29,17 @@ import { Duration } from '@_types/Time' /** * Creates or updates a component template. * Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases. - * + * * An index template can be composed of multiple component templates. * To use a component template, specify it in an index template’s `composed_of` list. * Component templates are only applied to new data streams and indices as part of a matching index template. - * + * * Settings and mappings specified directly in the index template or the create index request override any settings or mappings specified in a component template. - * + * * Component templates are only used during index creation. * For data streams, this includes data stream creation and the creation of a stream’s backing indices. * Changes to component templates do not affect existing indices, including a stream’s backing indices. - * + * * You can use C-style `/* *\/` block comments in component templates. * You can include comments anywhere in the request body except before the opening curly bracket. * @rest_spec_name cluster.put_component_template @@ -61,10 +61,10 @@ export interface Request extends RequestBase { } query_parameters: { /** - * If `true`, this request cannot replace or update existing component templates. + * If `true`, this request cannot replace or update existing component templates. * @server_default false */ create?: boolean - /** + /** * Period to wait for a connection to the master node. * If no response is received before the timeout expires, the request fails and returns an error. * @server_default 30s */