diff --git a/docs/reference/migration/migrate_5_0/cat.asciidoc b/docs/reference/migration/migrate_5_0/cat.asciidoc
index c3b1c84ee8d..5a38845e051 100644
--- a/docs/reference/migration/migrate_5_0/cat.asciidoc
+++ b/docs/reference/migration/migrate_5_0/cat.asciidoc
@@ -31,3 +31,10 @@ Additionally, the field `translog` has been renamed to
 `translog_ops_percent`. The short aliases for these fields are `tor`,
 `to`, and `top`, respectively.
 
+==== Changes to cat nodes API
+
+The cat nodes endpoint returns `m` for master eligible, `d` for data,
+and `i` for ingest. A node with no explicit roles will be a coordinating
+only node and marked with `-`. A node can have multiple roles. The
+master column has been adapted to return only whether a node is the
+current master (`*`) or not (`-`).
diff --git a/docs/reference/migration/migrate_5_0/rest.asciidoc b/docs/reference/migration/migrate_5_0/rest.asciidoc
index 0b8d76ea10f..46cb74b6289 100644
--- a/docs/reference/migration/migrate_5_0/rest.asciidoc
+++ b/docs/reference/migration/migrate_5_0/rest.asciidoc
@@ -20,3 +20,18 @@ The `GET` HTTP verb for `/_forcemerge` is no longer supported, please use the
 The `mem` section contained only one value, the total memory available
 throughout all nodes in the cluster. The section was removed as it didn't
 prove useful.
+
+==== Revised node roles aggregate returned by `/_cluster/stats`
+
+The `client`, `master_only`, `data_only` and `master_data` fields have been
+removed in favor of `master`, `data`, `ingest` and `coordinating_only`. A
+node can contribute to multiple counts as it can have multiple roles. Every
+node is implicitly a coordinating node, so whenever a node has no explicit
+roles, it will be counted as coordinating only.
+
+==== Node roles are not part of node attributes anymore
+
+Node roles are now returned in a specific section, called `roles`, as part of
+nodes stats and nodes info response. The new section is an array that holds all
+the different roles that each node fulfills. In case the array is returned
+empty, that means that the node is a coordinating only node.
diff --git a/docs/reference/migration/migrate_5_0/settings.asciidoc b/docs/reference/migration/migrate_5_0/settings.asciidoc
index 5e524a6a3cc..4342b422878 100644
--- a/docs/reference/migration/migrate_5_0/settings.asciidoc
+++ b/docs/reference/migration/migrate_5_0/settings.asciidoc
@@ -26,6 +26,12 @@ should be used instead.
 The `name` setting has been removed and is replaced by `node.name`. Usage of
 `-Dname=some_node_name` is not supported anymore.
 
+==== Node types settings
+
+The `node.client` setting has been removed. A node with such a setting set will not
+start up. Instead, each node role needs to be set separately using the existing
+`node.master`, `node.data` and `node.ingest` supported static settings.
+
 ==== Gateway settings
 
 The `gateway.format` setting for configuring global and index state serialization