DEV: document Redis 8 breaking changes to ACL handling (#1669)

* DEV: document Redis 8 breaking changes to ACL handling

* Add more content.

Author: dwdougherty

content/operate/oss_and_stack/management/security/acl.md

@@ -289,19 +289,19 @@ The following is a list of command categories and their meanings:
 * **bitmap** - Data type: all bitmap related commands.
 * **blocking** - Potentially blocking the connection until released by another
   command.
-* **bloom** - Data type: all Bloom filter related commands.
-* **cms** - Data type: count-min sketch related commands.
+* **bloom** - Data type: all Bloom filter related commands. <sup>[1](#cmd-note-1)</sup>
+* **cms** - Data type: count-min sketch related commands. <sup>[1](#cmd-note-1)</sup>
 * **connection** - Commands affecting the connection or other connections.
   This includes [`AUTH`](/commands/auth), [`SELECT`](/commands/select), [`COMMAND`](/commands/command), [`CLIENT`](/commands/client), [`ECHO`](/commands/echo), [`PING`](/commands/ping), etc.
-* **cuckoo** - Data type: all Cuckoo filter related commands.
+* **cuckoo** - Data type: all Cuckoo filter related commands. <sup>[1](#cmd-note-1)</sup>
 * **dangerous** - Potentially dangerous commands (each should be considered with care for
   various reasons). This includes [`FLUSHALL`](/commands/flushall), [`MIGRATE`](/commands/migrate), [`RESTORE`](/commands/restore), [`SORT`](/commands/sort), [`KEYS`](/commands/keys),
   [`CLIENT`](/commands/client), [`DEBUG`](/commands/debug), [`INFO`](/commands/info), [`CONFIG`](/commands/config), [`SAVE`](/commands/save), [`REPLICAOF`](/commands/replicaof), etc.
 * **fast** - Fast O(1) commands. May loop on the number of arguments, but not the number of elements in the key.
 * **geo** - Data type: all geospatial index related commands.
 * **hash** - Data type: all hash related commands.
 * **hyperloglog** - Data type: all hyperloglog related commands.
-* **json** - Data type: all JSON related commands.
+* **json** - Data type: all JSON related commands. <sup>[1](#cmd-note-1)</sup>
 * **keyspace** - Writing or reading from keys, databases, or their metadata 
   in a type agnostic way. Includes [`DEL`](/commands/del), [`RESTORE`](/commands/restore), [`DUMP`](/commands/dump), [`RENAME`](/commands/rename), [`EXISTS`](/commands/exists), [`DBSIZE`](/commands/dbsize),
   [`KEYS`](/commands/keys), [`SCAN`](/commands/scan), [`EXPIRE`](/commands/expire), [`TTL`](/commands/ttl), [`FLUSHALL`](/commands/flushall), etc. Commands that may modify the keyspace,
@@ -311,18 +311,20 @@ The following is a list of command categories and their meanings:
 * **pubsub** - all pubsub related commands.
 * **read** - Reading from keys (values or metadata). Note that commands that don't interact with keys, will not have either `read` or `write`.
 * **scripting** - Scripting related.
-* **search** - All search related commands. Only ACL users with access to a superset of the key prefixes defined during index creation can create, modify, or read the index. For example, a user with the key ACL pattern `h:*` can create an index with keys prefixed by `h:*` or `h:p*`, but not keys prefixed by `h*`, `k:*`, or `k*`, because these prefixes may involve keys to which the user does not have access.
+* **search** - All search related commands. Only ACL users with access to a superset of the key prefixes defined during index creation can create, modify, or read the index. For example, a user with the key ACL pattern `h:*` can create an index with keys prefixed by `h:*` or `h:p*`, but not keys prefixed by `h*`, `k:*`, or `k*`, because these prefixes may involve keys to which the user does not have access. <sup>[1](#cmd-note-1)</sup>
 * **set** - Data type: all set related commands.
 * **sortedset** - Data type: all sorted set related commands.
 * **slow** - All commands that are not `fast`.
 * **stream** - Data type: all stream related commands.
 * **string** - Data type: all string related commands.
-* **tdigest** - Data type: all t-digest related commands.
-* **timeseries** - Data type: all time series related commands.
-* **topk** - Data type: all top-k related commands.
+* **tdigest** - Data type: all t-digest related commands. <sup>[1](#cmd-note-1)</sup>
+* **timeseries** - Data type: all time series related commands. <sup>[1](#cmd-note-1)</sup>
+* **topk** - Data type: all top-k related commands. <sup>[1](#cmd-note-1)</sup>
 * **transaction** - [`WATCH`](/commands/watch) / [`MULTI`](/commands/multi) / [`EXEC`](/commands/exec) related commands.
 * **write** - Writing to keys (values or metadata). Note that commands that don't interact with keys, will not have either `read` or `write`.
 
+1. <a name="cmd-note-1"></a> See the [Redis 8 release notes]({{< relref "/operate/oss_and_stack/stack-with-enterprise/release-notes/redisce/redisos-8.0-release-notes/#potentially-breaking-changes-to-acls" >}}) for more information about these command categories, which may introduce breaking changes to your Redis deployments.
+
 NOTE: Redis can also show you a list of all categories and the exact commands each category includes using the Redis [`ACL CAT`](/commands/acl-cat) command. 
 It can be used in two forms:
 

content/operate/oss_and_stack/stack-with-enterprise/release-notes/redisce/redisos-8.0-release-notes.md

@@ -71,10 +71,8 @@ Stand alone RediSearch, RedisJSON, RedisTimeSeries, and RedisBloom modules are n
 
   - See the [build instructions]({{< relref "/operate/oss_and_stack/install/build-stack" >}}) for information about building from source code.
   - New configuration file: `redis-full.conf`, loads Redis with all components, 
-    and contains new configuration parameters for Redis Query Engine and the new data structures .
-  - New ACL categories: `@search`, `@json`, `@timeseries`, `@bloom`, `@cuckoo`, `@cms`, `@topk`, and `@tdigest`.
-  - Commands are also included in the existing ACL categories such as `@read` and `@write`.
-
+    and contains new configuration parameters for Redis Query Engine and the new data structures.
+  - New ACL categories: `@search`, `@json`, `@timeseries`, `@bloom`, `@cuckoo`, `@cms`, `@topk`, and `@tdigest` commands are also included in the existing ACL categories such as `@read` and `@write`. See [below]({{< relref "/operate/oss_and_stack/stack-with-enterprise/release-notes/redisce/redisos-8.0-release-notes/#potentially-breaking-changes-to-acls" >}}) for information about potentially breaking changes.
 - More than 30 performance and resource utilization improvements.
 - A new I/O threading implementation, which enables throughput increase on multi-core environments
   (set with the `io-threads` configuration parameter).
@@ -113,3 +111,74 @@ For more details, see the release notes for the [8.0-M01](https://github.com/red
 - [#13966](https://github.com/redis/redis/pull/13966), [#13932](https://github.com/redis/redis/pull/13932) `CLUSTER SLOTS` - TLS port update not reflected.
 - [#13958](https://github.com/redis/redis/pull/13958) `XTRIM`, `XADD` - incorrect lag due to trimming stream.
 - [#13931](https://github.com/redis/redis/pull/13931) `HGETEX` - wrong order of keyspace notifications.
+
+### Potentially breaking changes to ACLs
+
+{{< note >}}
+The following content is relevant to all Redis distributions (RS, RC, and ROS).
+{{< /note >}}
+
+Redis 8 includes Redis Query Engine, as well as JSON, time series, Bloom filter, cuckoo filter, top-k, count-min sketch, and t-digest data types.
+The integration of these features into Redis also comes with improvements to Redis [ACL]({{< relref "/operate/oss_and_stack/management/security/acl" >}}) rules.
+
+{{< warning >}}
+These ACL changes may introduce breaking changes for some users, which must be analyzed carefully.
+{{< /warning >}}
+
+### Extension to the existing ACL categories
+
+Before Redis 8, the existing ACL categories @read, @write, @dangerous, @admin, @slow, and @fast did not include commands for the Redis Query Engine and the JSON, time series, and probabilistic data structures.
+
+Starting with Redis 8, Redis includes all Query Engine, JSON, time series, Bloom filter, cuckoo filter, top-k, count-min sketch, and t-digest commands in these existing ACL categories.
+
+As a result:
+
+- Existing ACL rules such as `+@read +@write` will allow access to more commands than in previous versions of Redis. Here are some examples:
+  - A user with `+@read` access will be able to execute `FT.SEARCH`.
+  - A user with `+@write` access will be able to execute `JSON.SET`. 
+
+- ACL rules such as `+@all -@write`  will allow access to fewer commands than previous versions of Redis. For example:
+  - A user with `+@all -@write` will not be able to execute `JSON.SET`.
+
+Note that the `@all` category did not change, as it always included all the commands.
+
+Additionally, ACL rules such as `+@read +JSON.GET` can now be simplified as `+@read` because `JSON.GET` is included in the `@read` category.
+
+### Who is affected by this change?
+
+Users who currently use the Redis Query Engine and/or the JSON, time series, or probabilistic data structures, and use custom ACL rules.
+
+You should reanalyze your ACL rules to make sure they are aligned with your security and access control requirements.
+
+### Redis 8 introduces the following data structure and processing engine ACL categories.
+
+| New ACL commands category names | Included commands               |
+| :----                           | :----                           |
+| `search`                        | All Redis Query Engine commands |
+| `json`                          | All JSON commands               |
+| `timeseries`                    | All time series commands        |
+| `bloom`                         | All Bloom filter commands       |
+| `cuckoo`                        | All cuckoo filter commands      |
+| `topk`                          | All top-k commands              |
+| `cms`                           | All count-min sketch commands   |
+| `tdigest`                       | All t-digest commands           |
+
+You can use these new categories in your ACL rules.
+
+### Time series notes
+
+The following time series commands retrieve data from all keys that match a given filter expression: `TS.MGET`, `TS.MRANGE`, and `TS.MREVRANGE`. 
+
+There can be a case where a user may have to only some of the matching keys. In such cases, the command’s result is an error message: “*current user doesn't have read permission to one or more keys that match the specified filter*”.
+
+On the other hand, `TS.QUERYINDEX` does not require `@read` access to the keys that match the specified filter, as it accesses only time series metadata (name and labels) and not content (measurements).
+
+### Redis Query Engine notes
+
+The following Redis Query Engine commands may retrieve data from all keys that match the prefixes defined in the index (that is, all indexed documents, per-index):
+
+- `FT.SEARCH`  
+- `FT.AGGREGATE` (may be followed by `FT.CURSOR`)  
+- `FT.PROFILE`
+
+Only ACL users with access to a superset of the key prefixes defined during index creation can create, modify, or read the index. For example, a user with the key ACL pattern `h:*` can create an index with keys prefixed by `h:*` or `h:p*`, but not keys prefixed by `h*`, `k:*`, or `k*`, because these prefixes may involve keys to which the user does not have access.