diff --git a/docs/reference/migration/migrate_8_0/security.asciidoc b/docs/reference/migration/migrate_8_0/security.asciidoc
index 9a91b4b503cbc..3bda161e49161 100644
--- a/docs/reference/migration/migrate_8_0/security.asciidoc
+++ b/docs/reference/migration/migrate_8_0/security.asciidoc
@@ -6,6 +6,25 @@
 //Installation and Upgrade Guide
 
 //tag::notable-breaking-changes[]
+[[deprecate-elasticsearch-setup-passwords]]
+.The `elasticsearch-setup-passwords` tool is deprecated.
+[%collapsible]
+====
+*Details* +
+In 8.0, we're deprecating the `elasticsearch-setup-passwords` tool. To
+manually reset the password for the `elastic` user, use the
+{ref}/reset-elastic-password.html[`elasticsearch-reset-elastic-password`] tool. To
+change passwords for other users, use either {kib} or the {es}
+{ref}/security-api-change-password.html[change passwords API]. We will remove the 
+`elasticsearch-setup-passwords` tool in a future release.
+
+*Impact* +
+When starting {es} for the first time, passwords are generated automatically for
+the `elastic` and `kibana_system` users. If you run the
+`elasticsearch-setup-passwords` tool after starting {es}, the command will fail
+because the password for the `elastic` user is already configured.
+====
+
 .The file and native realms are now enabled unless explicitly disabled.
 [%collapsible]
 ====