docs: how to setup/upgrade yarn and auth in hive (4paradigm#3120)

docs/zh/deploy/conf.md

@@ -255,7 +255,7 @@ zookeeper.max_connect_waitTime=30000
 
 # Spark Config
 spark.home=
-spark.master=local
+spark.master=local[*]
 spark.yarn.jars=
 spark.default.conf=
 spark.eventLog.dir=
@@ -267,5 +267,43 @@ hadoop.conf.dir=
 #enable.hive.support=false
 ```
 
-* 如果没有配置`spark.home`，则需要在TaskManager运行的环境变量配置`SPARK_HOME`。
-* `spark.master`默认配置为`local`，可以配置为`local[*]`、`yarn`、`yarn-cluster`、`yarn-client`等。如果配置为Yarn集群模式，则需要修改`offline.data.prefix`配置为HDFS路径，避免保存离线文件到Yarn容器本地，同时需要配置环境变量`HADOOP_CONF_DIR`为Hadoop配置文件所在目录。
+### Spark Config详解
+
+Spark Config中重点关注的配置如下：
+
+#### spark.home
+
+`spark.home`配置为Spark安装目录，TaskManager会使用该目录下的Spark执行离线任务。通常配置为下载的[OpenMLDB Spark 发行版](../../tutorial/openmldbspark_distribution.md)解压后的目录。
+
+如果TaskManager配置文件中`spark.home`为空，则会尝试读取TaskManager启动时的环境变量`SPARK_HOME`。如二者都未配置，TaskManager将会启动失败，并提示`spark.home`未配置。
+
+#### spark.master
+
+`spark.master`配置Spark的模式，Spark模式配置更详细的解释请参考[Spark Master URL](https://spark.apache.org/docs/latest/submitting-applications.html#master-urls)。
+
+TaskManager只接受`local`及其变种、`yarn`、`yarn-cluster`、`yarn-client`四种配置模式，默认配置为`local[*]`，即多线程本地模式（线程数为逻辑CPU数量）。Spark集群`spark://`、Mesos集群`mesos://`、Kubernetes集群`k8s://`等模式暂不支持。
+
+##### local模式
+
+local模式即Spark任务运行在本地（TaskManager所在主机），该模式下不需要太多配置，只需要注意两点：
+- 离线表的存储地址`offline.data.prefix`，默认为`file:///tmp/openmldb_offline_storage/`，即TaskManager所在主机的`/tmp`目录，你可以修改该配置为其他目录。
+  - 可以配置为HDFS路径，需要在**启动TaskManager前**配置环境变量`HADOOP_CONF_DIR`为Hadoop配置文件所在目录（注意是环境变量，不是TaskManager的配置项），文件目录中应包含Hadoop的`core-site.xml`、`hdfs-site.xml`等配置文件，更多见[Spark官方文档](https://spark.apache.org/docs/3.2.1/configuration.html#inheriting-hadoop-cluster-configuration)。
+  ```{note}
+  HDFS路径目前需要配置`namenode.uri`，删除离线表时会连接HDFS FileSystem`namenode.uri`，并删除离线表的存储目录（Offline Table Path）。未来将废弃此配置项。
+  ```
+- batchjob的路径`batchjob.jar.path`可自动获取，无需配置，如果你要使用别处的batchjob，可以配置该参数。
+
+```{seealso}
+如果Hadoop/Yarn需要Kerberos认证，参考[FAQ](../maintain/faq.md#4-如何配置taskmanager来访问开启kerberos的yarn集群)。
+```
+##### yarn/yarn-cluster模式
+
+"yarn"和"yarn-cluster"是同一个模式，即Spark任务运行在Yarn集群上，该模式下需要配置的参数较多，主要包括：
+- 在**启动TaskManager前**配置环境变量`HADOOP_CONF_DIR`为Hadoop和Yarn的配置文件所在目录，文件目录中应包含Hadoop的`core-site.xml`、`hdfs-site.xml`、Yarn的`yarn-site.xml`等配置文件，参考[Spark官方文档](https://spark.apache.org/docs/3.2.1/running-on-yarn.html#launching-spark-on-yarn)。
+- `spark.yarn.jars`配置Yarn需要读取的Spark运行jar包地址，必须是`hdfs://`地址。可以上传[OpenMLDB Spark 发行版](../../tutorial/openmldbspark_distribution.md)解压后的`jars`目录到HDFS上，并配置为`hdfs://<hdfs_path>/jars/*`（注意通配符）。[如果不配置该参数，Yarn会将`$SPARK_HOME/jars`打包上传分发，并且每次离线任务都要分发](https://spark.apache.org/docs/3.2.1/running-on-yarn.html#preparations)，效率较低，所以推荐配置。
+- `batchjob.jar.path`必须是HDFS路径，上传batchjob jar包到HDFS上，并配置为对应地址，保证Yarn集群上所有Worker可以获得batchjob包。
+- `offline.data.prefix`必须是HDFS路径，保证Yarn集群上所有Worker可读写数据。应使用前面配置的环境变量`HADOOP_CONF_DIR`中的Hadoop集群地址。
+
+##### yarn-client模式
+
+"yarn-client"模式，[driver运行在本地](https://spark.apache.org/docs/3.2.1/running-on-yarn.html#launching-spark-on-yarn)，executor运行在Yarn集群上，配置与yarn-cluster模式相同。

docs/zh/integration/offline_data_sources/hive.md

@@ -26,14 +26,14 @@
 
 ### 配置
 
-目前 OpenMLDB 只支持使用 metastore 服务来连接Hive。你需要进行以下相关配置以正确访问 Hive 数据源。
+目前 OpenMLDB 只支持使用 metastore 服务来连接Hive。你可以在以下两种配置方式中选择一种，来访问 Hive 数据源。
 
 - spark.conf：你可以在 spark conf 中配置 `spark.hadoop.hive.metastore.uris`。有两种方式：
 
   - taskmanager.properties: 在配置项 `spark.default.conf` 中加入`spark.hadoop.hive.metastore.uris=thrift://...` ，随后重启taskmanager。
   - CLI: 在 ini conf 中加入此配置项，并使用`--spark_conf`启动CLI，参考[客户端Spark配置文件](../../reference/client_config/client_spark_config.md)。
 
-- hive-site.xml：你可以配置 `hive-site.xml` 中的 `hive.metastore.uris`，并将配置文件放入 Spark home的`conf/`。`hive-site.xml` 样例：
+- hive-site.xml：你可以配置 `hive-site.xml` 中的 `hive.metastore.uris`，并将配置文件放入 Spark home的`conf/`（如果已配置`HADOOP_CONF_DIR`环境变量，也可以将配置文件放入`HADOOP_CONF_DIR`中）。`hive-site.xml` 样例：
 
   ```xml
   <configuration>
@@ -46,6 +46,18 @@
   </configuration>
   ```
 
+除了Hive连接配置，还需要在Hive中给TaskMananger的启动用户（OS用户和组）授予创建/读/写等权限，以及Hive表的HDFS路径的Read/Write/Execute权限。
+
+如果权限不够，可能出现如下错误：
+```
+org.apache.hadoop.security.AccessControlException: Permission denied: user=xx, access=xxx, inode="xxx":xxx:supergroup:drwxr-xr-x
+```
+这个错误是指用户没有权限访问Hive表的HDFS路径，需要给用户授予HDFS路径的Read/Write/Execute权限。
+
+```{seealso}
+如有疑问，请确认你的Hive集群使用了哪种权限管理方式，参考[权限管理](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Authorization#LanguageManualAuthorization-OverviewofAuthorizationModes)。
+```
+
 ### 调试信息
 
 确认任务是否连接到正确的 Hive 集群，可以通过任务日志来查看。
@@ -105,7 +117,7 @@ LOAD DATA INFILE 'hive://db1.t1' INTO TABLE t1 OPTIONS(deep_copy=false);
 
 - 如果不指定数据库名字，则会使用默认数据库名字 `default_db`
 - 如果指定数据库名字，则该数据库必须已经存在，目前不支持对于不存在的数据库进行自动创建
-- 如果不指定表格名字，则会在 Hive 内自动创建对应名字的表格
+- 如果指定的Hive表名不存在，则会在 Hive 内自动创建对应名字的表
 - `OPTIONS` 参数只有导出模式`mode`生效，其他参数均不生效
 
 举例：

docs/zh/maintain/upgrade.md

@@ -89,6 +89,12 @@
     bash bin/start.sh start taskmanager
     ```
 
+### Yarn模式下的升级
+
+Yarn模式下，第一步替换Spark时，还需要注意`spark.yarn.jars`和`batchjob.jar.path`的配置，如果指向HDFS路径，那么HDFS路径上的包也需要更新。这种情况下，更新TaskMananger的本地`$SPARK_HOME`目录不会影响到Yarn模式下的Spark。
+
+剩下的TaskManager升级步骤和上文的步骤一致。
+
 ## 5. 升级SDK
 
 ### 升级Java SDK