[DOCS] Add transform nodes (#53698)

docs/reference/cat/nodes.asciidoc

@@ -44,7 +44,7 @@ Valid columns are:
 `node.role`, `r`, `role`, `nodeRole`::
 (Default) Roles of the node. Returned values include `d` (data node), `i`
 (ingest node), `m` (master-eligible node), `l` (machine learning node), `v`
-(voting-only node), and `-` (coordinating node only).
+(voting-only node), `t` ({transform} node), and `-` (coordinating node only).
 +
 For example, `dim` indicates a master-eligible data and ingest node. See
 <<modules-node>>.

docs/reference/modules/node.asciidoc

@@ -50,6 +50,13 @@ there must be at least one {ml} node in your cluster. For more information about
 IMPORTANT: If you use the {oss-dist}, do not set `node.ml`. Otherwise, the node
 fails to start.
 
+<<transform-node,{transform-cap} node>>::
+
+A node that has `xpack.transform.enabled` and `node.transform` set to `true`. If
+you want to use {transforms}, there must be at least one {transform} node in
+your cluster. For more information, see <<transform-settings>> and
+<<transforms>>.
+
 [NOTE]
 [[coordinating-node]]
 .Coordinating node
@@ -96,7 +103,7 @@ restarts.
 ==== Dedicated master-eligible node
 
 It is important for the health of the cluster that the elected master node has 
-the resources it needs to fulfil its responsibilities. If the elected master 
+the resources it needs to fulfill its responsibilities. If the elected master 
 node is overloaded with other tasks then the cluster may not operate well. In 
 particular, indexing and searching your data can be very resource-intensive, so 
 in large or high-throughput clusters it is a good idea to avoid using the 
@@ -118,7 +125,9 @@ node.data: false <3>
 node.ingest: false <4>
 node.ml: false <5>
 xpack.ml.enabled: true <6>
-cluster.remote.connect: false <7>
+node.transform: false <7>
+xpack.transform.enabled: true <8>
+cluster.remote.connect: false <9>
 -------------------
 <1> The `node.master` role is enabled by default.
 <2> The `node.voting_only` role is disabled by default.
@@ -126,7 +135,9 @@ cluster.remote.connect: false <7>
 <4> Disable the `node.ingest` role (enabled by default).
 <5> Disable the `node.ml` role (enabled by default).
 <6> The `xpack.ml.enabled` setting is enabled by default.
-<7> Disable remote cluster connections (enabled by default).
+<7> Disable the `node.transform` role.
+<8> The `xpack.transform.enabled` setting is enabled by default.
+<9> Disable remote cluster connections (enabled by default).
 
 To create a dedicated master-eligible node in the {oss-dist}, set:
 
@@ -197,7 +208,9 @@ node.data: false <3>
 node.ingest: false <4>
 node.ml: false <5>
 xpack.ml.enabled: true <6>
-cluster.remote.connect: false <7>
+node.transform: false <7>
+xpack.transform.enabled: true <8>
+cluster.remote.connect: false <9>
 -------------------
 <1> The `node.master` role is enabled by default.
 <2> Enable the `node.voting_only` role (disabled by default).
@@ -205,11 +218,13 @@ cluster.remote.connect: false <7>
 <4> Disable the `node.ingest` role (enabled by default).
 <5> Disable the `node.ml` role (enabled by default).
 <6> The `xpack.ml.enabled` setting is enabled by default.
-<7> Disable remote cluster connections (enabled by default).
+<7> Disable the `node.transform` role.
+<8> The `xpack.transform.enabled` setting is enabled by default.
+<9> Disable remote cluster connections (enabled by default).
 
 [float]
 [[data-node]]
-=== Data Node
+=== Data node
 
 Data nodes hold the shards that contain the documents you have indexed. Data
 nodes handle data related operations like CRUD, search, and aggregations.
@@ -227,14 +242,16 @@ node.voting_only: false <2>
 node.data: true <3>
 node.ingest: false <4>
 node.ml: false <5>
-cluster.remote.connect: false <6>
+node.transform: false <6>
+cluster.remote.connect: false <7>
 -------------------
 <1> Disable the `node.master` role (enabled by default).
 <2> The `node.voting_only` role is disabled by default.
 <3> The `node.data` role is enabled by default.
 <4> Disable the `node.ingest` role (enabled by default).
 <5> Disable the `node.ml` role (enabled by default).
-<6> Disable remote cluster connections (enabled by default).
+<6> Disable the `node.transform` role.
+<7> Disable remote cluster connections (enabled by default).
 
 To create a dedicated data node in the {oss-dist}, set:
 [source,yaml]
@@ -251,7 +268,7 @@ cluster.remote.connect: false <4>
 
 [float]
 [[node-ingest-node]]
-=== Ingest Node
+=== Ingest node
 
 Ingest nodes can execute pre-processing pipelines, composed of one or more
 ingest processors. Depending on the type of operations performed by the ingest
@@ -267,14 +284,16 @@ node.voting_only: false <2>
 node.data: false <3>
 node.ingest: true <4>
 node.ml: false <5>
-cluster.remote.connect: false <6>
+node.transform: false <6>
+cluster.remote.connect: false <7>
 -------------------
 <1> Disable the `node.master` role (enabled by default).
 <2> The `node.voting_only` role is disabled by default.
 <3> Disable the `node.data` role (enabled by default).
 <4> The `node.ingest` role is enabled by default.
 <5> Disable the `node.ml` role (enabled by default).
-<6> Disable remote cluster connections (enabled by default).
+<6> Disable the `node.transform` role.
+<7> Disable remote cluster connections (enabled by default).
 
 To create a dedicated ingest node in the {oss-dist}, set:
 
@@ -320,14 +339,16 @@ node.voting_only: false <2>
 node.data: false <3>
 node.ingest: false <4>
 node.ml: false <5>
-cluster.remote.connect: false <6>
+node.transform: false <6>
+cluster.remote.connect: false <7>
 -------------------
 <1> Disable the `node.master` role (enabled by default).
 <2> The `node.voting_only` role is disabled by default.
 <3> Disable the `node.data` role (enabled by default).
 <4> Disable the `node.ingest` role (enabled by default).
 <5> Disable the `node.ml` role (enabled by default).
-<6> Disable remote cluster connections (enabled by default).
+<6> Disable the `node.transform` role.
+<7> Disable remote cluster connections (enabled by default).
 
 To create a dedicated coordinating node in the {oss-dist}, set:
 
@@ -348,7 +369,7 @@ cluster.remote.connect: false <4>
 === [xpack]#Machine learning node#
 
 The {ml-features} provide {ml} nodes, which run jobs and handle {ml} API
-requests. If `xpack.ml.enabled` is set to true and `node.ml` is set to `false`,
+requests. If `xpack.ml.enabled` is set to `true` and `node.ml` is set to `false`,
 the node can service API requests but it cannot run jobs.
 
 If you want to use {ml-features} in your cluster, you must enable {ml}
@@ -367,7 +388,9 @@ node.data: false <3>
 node.ingest: false <4>
 node.ml: true <5>
 xpack.ml.enabled: true <6>
-cluster.remote.connect: false <7>
+node.transform: false <7>
+xpack.transform.enabled: true <8>
+cluster.remote.connect: false <9>
 -------------------
 <1> Disable the `node.master` role (enabled by default).
 <2> The `node.voting_only` role is disabled by default.
@@ -375,7 +398,42 @@ cluster.remote.connect: false <7>
 <4> Disable the `node.ingest` role (enabled by default).
 <5> The `node.ml` role is enabled by default.
 <6> The `xpack.ml.enabled` setting is enabled by default.
-<7> Disable remote cluster connections (enabled by default).
+<7> Disable the `node.transform` role.
+<8> The `xpack.transform.enabled` setting is enabled by default.
+<9> Disable remote cluster connections (enabled by default).
+
+[discrete]
+[[transform-node]]
+=== [xpack]#{transform-cap} node#
+
+{transform-cap} nodes run {transforms} and handle {transform} API requests.
+
+If you want to use {transforms} in your cluster, you must have
+`xpack.transform.enabled` set to `true` on all master-eligible nodes and all
+data nodes. You must also have `node.transform` set to `true` on at least one
+node. This is the default behavior. If you have the {oss-dist}, do not use these
+settings. For more information, see <<transform-settings>>.
+
+To create a dedicated {transform} node in the {default-dist}, set:
+
+[source,yaml]
+-------------------
+node.master: false <1>
+node.voting_only: false <2>
+node.data: false <3>
+node.ingest: false <4>
+node.ml: false <5>
+node.transform: true <6>
+xpack.transform.enabled: true <7>
+cluster.remote.connect: false <8>
+-------------------
+<1> Disable the `node.master` role.
+<2> Disable the `node.voting_only`.
+<3> Disable the `node.data` role.
+<4> Disable the `node.ingest` role.
+<5> Enable the `node.ml` role.
+<6> Enable the `xpack.ml.enabled` setting.
+<7> Disable remote cluster connections.
 
 [float]
 [[change-node-role]]

docs/reference/transform/ecommerce-tutorial.asciidoc

@@ -8,21 +8,11 @@ from an {es} index, transform it, and store it in another index. Let's use the
 {kibana-ref}/add-sample-data.html[{kib} sample data] to demonstrate how you can
 pivot and summarize your data with {transforms}.
 
-
+. Verify that your environment is set up properly to use {transforms}. If the
-. If the {es} {security-features} are enabled, obtain a user ID with sufficient
+{es} {security-features} are enabled, to complete this tutorial you need a user
-privileges to complete these steps. 
+that has authority to preview and create {transforms}. You must also have
-+
+specific index privileges for the source and destination indices. See
---
+<<transform-setup>>.
-You need `manage_transform` cluster privileges to preview and create 
-{transforms}. Members of the built-in `transform_admin` role have these 
-privileges.
-
-You also need `read` and `view_index_metadata` index privileges on the source
-index and `read`, `create_index`, and `index` privileges on the destination
-index. 
-
-For more information, see <<security-privileges>> and <<built-in-roles>>.
---
 
 . Choose your _source index_.
 +

docs/reference/transform/index.asciidoc

@@ -11,6 +11,7 @@ indices that summarize the behavior of users or sessions or other entities in
 your data.
 
 * <<transform-overview>>
+* <<transform-setup>>
 * <<transform-usage>>
 * <<transform-api-quickref>>
 * <<ecommerce-transforms>>
@@ -19,6 +20,7 @@ your data.
 * <<transform-limitations>>
 
 include::overview.asciidoc[]
+include::setup.asciidoc[]
 include::usage.asciidoc[]
 include::checkpoints.asciidoc[]
 include::api-quickref.asciidoc[]

docs/reference/transform/limitations.asciidoc

@@ -46,17 +46,6 @@ A single cluster will support up to 1,000 {transforms}. When using the
 is returned. Use the `size` and `from` parameters to enumerate through the full 
 list.
 
-
-[float]
-[[transform-node-assignment-limitations]]
-==== {transforms-cap} node assignment not configurable
-
-{transforms-cap} persistent tasks are assigned to the data node running
-fewest persistent tasks at the time of assignment. This cannot be customized.
-It means that if {transforms} are being used then `xpack.transform.enabled`
-must be set to `true` (which is the default) on every data node in the cluster.
-
-
 [float]
 [[transform-aggresponse-limitations]]
 ==== Aggregation responses may be incompatible with destination index mappings

docs/reference/transform/setup.asciidoc

@@ -0,0 +1,40 @@
+[role="xpack"]
+[[transform-setup]]
+=== Set up {transforms}
+++++
+<titleabbrev>Setup</titleabbrev>
+++++
+
+To use the {transforms}, you must have the
+{subscriptions}[appropriate license] and at least one
+<<transform-setup-nodes,{transform} node>> in your {es} cluster. If {stack}
+{security-features} are enabled, you must also ensure your users have the
+<<transform-privileges,necessary privileges>>.
+
+[discrete]
+[[transform-setup-nodes]]
+==== {transform-cap} nodes
+
+To use {transforms}, there must be at least one node in your cluster with
+`xpack.transform.enabled` and `node.transform` set to `true`. By default, all
+nodes are {transform} nodes unless you explicitly change these settings or set 
+`node.data` to `false`.
+
+If you want to control which nodes run {transforms}, set `node.transform` to
+`false` on some nodes.
+
+For more information, see <<transform-settings>> and <<modules-node>>.
+
+[discrete]
+[[transform-privileges]]
+==== Security privileges
+
+The {es} {security-features} provide <<built-in-roles,built-in roles>>
+and <<security-privileges,privileges>> that make it easier to control
+which users can manage or view {transforms}. 
+
+For example, you need `manage_transform` cluster privileges to preview and
+create {transforms}. Members of the built-in `transform_admin` role have these 
+privileges. You also need `read` and `view_index_metadata` index privileges on
+the source index and `read`, `create_index`, and `index` privileges on the
+destination index.