[incubator-kyuubi] 01/03: [KYUUBI #3217] [DOCS] Doc for using Marcos in row-level filter in Authz

[ch...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

chengpan pushed a commit to branch branch-1.6
in repository https://gitbox.apache.org/repos/asf/incubator-kyuubi.git

commit e76f8f7b39faeb74ce4c9b39de97652c747d97ba
Author: liangbowen <li...@gf.com.cn>
AuthorDate: Fri Aug 19 09:55:56 2022 +0800

    [KYUUBI #3217] [DOCS] Doc for using Marcos in row-level filter in Authz
    
    ### _Why are the changes needed?_
    
    Support macros in Row-filter condition expression, introduced in Ranger 2.3 ([release notes](https://cwiki.apache.org/confluence/display/RANGER/Apache+Ranger+2.3.0+-+Release+Notes)), is an major feature to significantly simplify the row-filter condition expression in practice by replacing explicit condition query by using user/group's attributes.
    
    - [RANGER-3605](https://issues.apache.org/jira/browse/RANGER-3605) : Support macros in row-filter/condition expressions
    - [RANGER-3550](https://issues.apache.org/jira/browse/RANGER-3550) : support for using user/tag attributes in row-filter expressions and conditions
    Consider user liangtiancheng with attribute born_city = guangzhou, we can define the row filter condition with city='${{USER.born_city}}' with the macro feature.
    
    However, This feature implicit relies on an config named `ranger.plugin.spark.enable.implicit.userstore.enricher` and the default value false will prevent RangerUserStoreEnricher fetching user/group and their attributes. Macros in row-filter condition will fallback to null value (as lack of user attributes value in UserStore of auth context) in script transformation unexpectedly and imperceptibly.
    
    Improving doc of ranger-spark-security.xml to aware of this feature and related config.
    
    ### _How was this patch tested?_
    - [ ] Add some test cases that check the changes thoroughly including negative and positive cases if possible
    
    - [ ] Add screenshots for manual tests if appropriate
    
    - [x] [Run test](https://kyuubi.apache.org/docs/latest/develop_tools/testing.html#running-tests) locally before make a pull request
    
    Closes #3267 from bowenliang123/doc-ranger-macros.
    
    Closes #3217
    
    aee4b201 [liangbowen] plain text
    a7ec3bc9 [liangbowen] update docs and clearify difference between ranger.plugin.hive.policy.cache.dir and ranger.plugin.spark.policy.cache.dir configs
    4887bd1f [liangbowen] simplify with "row filter expressions"
    fa62402f [liangbowen] skip list items
    9dd1cd4c [liangbowen] h5. Using Marcos in Row Level Filters
    849bed5b [liangbowen] add docs for Additional configs for using Marcos in row-level filter
    
    Authored-by: liangbowen <li...@gf.com.cn>
    Signed-off-by: Kent Yao <ya...@apache.org>
---
 docs/security/authorization/spark/install.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/security/authorization/spark/install.md b/docs/security/authorization/spark/install.md
index e04b34680..ec2892230 100644
--- a/docs/security/authorization/spark/install.md
+++ b/docs/security/authorization/spark/install.md
@@ -74,6 +74,23 @@ for pointing to the right Ranger admin server.
 
 </configuration>
 ```
+##### Using Macros in Row Level Filters
+
+Macros are now supported for using user/group/tag in row filter expressions, introduced in [Ranger 2.3](https://cwiki.apache.org/confluence/display/RANGER/Apache+Ranger+2.3.0+-+Release+Notes). This feature helps significantly simplify row filter expressions by using user/group/tag's attributes instead of explicit conditions. Considering a user with an attribute `born_city` of value `Guangzhou `, the row filter condition as `city='${{USER.born_city}}'` will be transformed to `city='Guangz [...]
+   
+```xml
+    <property>
+        <name>ranger.plugin.spark.enable.implicit.userstore.enricher</name>
+        <value>true</value>
+        <description>Enable UserStoreEnricher for fetching user and group attributes if using macros or scripts in row-filters since Ranger 2.3</description>
+    </property>
+
+    <property>
+        <name>ranger.plugin.hive.policy.cache.dir</name>
+        <value>./a ranger hive service name/policycache</value>
+        <description>As Authz plugin reuses hive service def, a policy cache path is required for caching UserStore and Tags for "hive" service def, while "ranger.plugin.spark.policy.cache.dir config" is the path for caching policies in service. </description>
+    </property>    
+```
 
 #### ranger-spark-audit.xml