[Entitlements] Small docs fixes (#127323) (#127379)

(cherry picked from commit e9bedf1)

Co-authored-by: Lorenzo Dematté <[email protected]>

Author: leemthompo

docs/extend/creating-classic-plugins.md

@@ -80,8 +80,13 @@ The entitlements currently implemented and enforced in {{es}} that are available
 
 #### `manage_threads`
 
-Allows code to call methods that create or modify properties on Java Threads, for example `Thread#start` or `ThreadGroup#setMaxPriority`. In general, setting the name, priority, daemon state and context class loader are things no plugins should do when executing on
-{{es}} threadpools; however, many 3rd party libraries that support async operations (e.g. Apache HTTP client) need to manage their own threads. In this case it is justifiable to request this entitlement.
+Allows code to call methods that create or modify properties on Java Threads, for example `Thread#start` or `ThreadGroup#setMaxPriority`.
+
+:::{note}
+This entitlement is rarely necessary. Your plugin should use {{es}} thread pools and executors (see `Plugin#getExecutorBuilders`) instead of creating and managing its own threads. Plugins should avoid modifying thread name, priority, daemon state, and context class loader when executing on ES threadpools.
+
+However, many 3rd party libraries that support async operations, such as the Apache HTTP client, need to create and manage their own threads. In such cases, it makes sense to request this entitlement.
+:::
 
 Example:
 ```yaml

libs/entitlement/README.md

@@ -170,7 +170,7 @@ java.lang.IllegalStateException: Invalid module name in policy: layer [server] d
 
 IMPORTANT: this patching mechanism is intended to be used **only** for emergencies; once a missing entitlement is identified, the fix needs to be applied to the codebase, by raising a PR or submitting a bug via Github so that the bundled policies can be fixed.
 
-### How to migrate a from a Java Security Manager Policy to an entitlement policy
+### How to migrate from a Java Security Manager Policy to an entitlement policy
 
 Translating Java Security Permissions to Entitlements is usually not too difficult;
 - many permissions are not used anymore. The Entitlement system is targeting sensitive actions we identified as crucial to our code; any other permission is not checked anymore. Also, we do not have  any entitlement related to reflection or access checks: Elasticsearch runs modularized, and we leverage and trust the Java module mechanism to enforce access and visibility.