Azkaban 4. 插件安装与开发

1. 插件介绍

Azkaban 本身是一个工作流调度系统，核心能力是项目管理、任务依赖、任务执行、定时调度、执行日志和权限控制。

但是实际使用中，仅靠内置能力通常不够。例如：

• 需要支持 Hadoop、Hive、Pig、Spark 等不同类型任务
• 需要在 Web 页面中查看 HDFS 文件
• 需要生成任务执行摘要
• 需要自定义报表页面
• 需要对接 LDAP、Kerberos、Hadoop Token
• 需要扩展告警方式

这些能力通常通过插件方式扩展。

Azkaban 官方文档中也说明，Azkaban 设计上是模块化的，可以通过插件增加 viewer 页面，也可以通过插件自定义 job 执行方式。

2. 常见插件类型

Azkaban 插件大致可以分成几类：

插件类型	运行位置	作用
JobType Plugin	Executor Server	扩展任务类型，例如 java、hive、spark、pig
Viewer Plugin	Web Server	扩展 Web 页面，例如 HDFS Viewer、JobSummary、Reportal
User Manager Plugin	Web Server	扩展用户认证，例如 LDAP
Trigger Plugin	Web Server	扩展触发方式
Alerter Plugin	Web Server / Executor	扩展告警方式

其中最常见的是两类：

JobType Plugin：让 Azkaban 能执行更多类型的任务
Viewer Plugin：让 Azkaban Web 页面能展示更多内容

腾讯云文章中介绍的 JobSummary、Jobtypes、Reportal，也基本对应这两类插件。

3. 插件目录结构

3.1 Executor 端插件目录

JobType 插件放在 Executor Server 端。

常见目录结构如下：

azkaban-exec-server/
  plugins/
    jobtypes/
      java/
        plugin.properties
        private.properties
        lib/
      command/
        plugin.properties
      hive/
        plugin.properties
        lib/

同时需要在 azkaban.properties 中配置：

azkaban.jobtype.plugin.dir=plugins/jobtypes

azkaban-plugins 的 INSTALL 文档中也说明，JobType 插件需要组织成平铺结构，每一种 job type 一个目录。

3.2 Web 端插件目录

Viewer 插件放在 Web Server 端。

常见目录结构如下：

azkaban-web-server/
  plugins/
    viewer/
      jobsummary/
        conf/
          plugin.properties
        lib/
      reportal/
        conf/
          plugin.properties
        lib/

Web 端插件通常用于扩展页面。例如：

• JobSummary：查看任务执行摘要
• Reportal：报表相关页面
• HDFS Viewer：查看 HDFS 文件

安装完成后通常需要重启 Azkaban Web Server。

4. JobType 插件安装

以 JobType 插件为例，安装流程一般是：

1. 编译或下载插件包。
2. 解压到 Executor Server 的 plugins/jobtypes 目录。
3. 检查 plugin.properties。
4. 检查依赖 jar。
5. 重启 Executor Server。
6. 查看日志确认插件是否加载成功。

示例：

cd /opt/azkaban/azkaban-exec-server/plugins
tar -zxvf azkaban-jobtype-3.0.0.tar.gz
mv azkaban-jobtype-3.0.0 jobtypes

然后重启 Executor：

cd /opt/azkaban/azkaban-exec-server
sh bin/azkaban-executor-shutdown.sh
sh bin/start-exec.sh

查看是否加载成功：

grep 'Loaded jobtype' logs/executorServerLog*.out

如果日志中能看到对应 job type，说明插件已经被加载。

5. JobType 插件配置

每个 job type 目录中通常会有 plugin.properties。

一个简化示例：

jobtype.class=azkaban.jobtype.HadoopJavaJob
jobtype.classpath=lib/*
jobtype.global.classpath=${hadoop.home}/*,${hadoop.home}/conf
jobtype.global.jvm.args=-Djava.library.path=${hadoop.home}/lib/native

常见配置说明：

配置	说明
jobtype.class	当前 job type 对应的 Java 类
jobtype.classpath	当前插件自己的依赖
jobtype.global.classpath	所有此类任务共用的 classpath
jobtype.global.jvm.args	任务启动时附加的 JVM 参数

如果是 Hadoop、Hive、Spark 类任务，还会涉及：

hadoop.home=/opt/cloudera/parcels/CDH/lib/hadoop
hive.home=/opt/cloudera/parcels/CDH/lib/hive
spark.home=/opt/cloudera/parcels/CDH/lib/spark

这些路径需要根据实际集群环境调整。

6. commonprivate.properties

JobType 插件中经常会有公共私有配置，例如 commonprivate.properties。

在腾讯云文章中，CDH + Kerberos 环境下有类似配置：

hadoop.security.manager.class=azkaban.security.HadoopSecurityManager_H_2_0
proxy.keytab.location=/opt/cloudera/azkaban/azkaban.keytab
proxy.user=azkaban/admin@FAYSON.COM
azkaban.should.proxy=true
obtain.binary.token=true
obtain.namenode.token=true
obtain.jobtracker.token=true

hadoop.home=/opt/cloudera/parcels/CDH/lib/hadoop
hadoop.classpath=/opt/cloudera/parcels/CDH/lib/hadoop
pig.home=/opt/cloudera/parcels/CDH/lib/pig
hive.home=/opt/cloudera/parcels/CDH/lib/hive
spark.home=/opt/cloudera/parcels/CDH/lib/spark

execute.as.user=true
azkaban.native.lib=/opt/cloudera/azkaban/

这里重点有几个：

配置	说明
hadoop.security.manager.class	Hadoop 安全管理类，Hadoop 2.x 通常使用 HadoopSecurityManager_H_2_0
proxy.keytab.location	Kerberos keytab 路径
proxy.user	用于代理的 Kerberos principal
azkaban.should.proxy	是否启用代理
execute.as.user	是否以用户身份执行任务
azkaban.native.lib	execute-as-user 所在目录

如果集群没有开启 Kerberos，可以先不配置 keytab 和 proxy 相关参数。

7. execute-as-user

在安全集群或者需要以提交用户身份执行任务时，Azkaban 会用到 execute-as-user。

常见操作如下：

gcc execute-as-user.c -o execute-as-user
chown root execute-as-user
chmod 6050 execute-as-user

配置中需要指定 native lib 路径：

execute.as.user=true
azkaban.native.lib=/opt/azkaban/

这里要注意权限问题。execute-as-user 通常需要 root 拥有，并设置特殊权限。如果权限不正确，任务可能无法切换用户执行。

排查时可以关注 Executor 日志中的：

execute-as-user
Permission denied
Cannot run program

8. Viewer 插件安装

Viewer 插件安装在 Web Server 端，以 JobSummary 为例：

cp azkaban-jobsummary-3.0.0.tar.gz /opt/azkaban/azkaban-web-server/plugins/viewer/
cd /opt/azkaban/azkaban-web-server/plugins/viewer/
tar -zxvf azkaban-jobsummary-3.0.0.tar.gz
mv azkaban-jobsummary-3.0.0 jobsummary

修改配置：

cd /opt/azkaban/azkaban-web-server/plugins/viewer/jobsummary/conf
vim plugin.properties

然后重启 Web Server：

cd /opt/azkaban/azkaban-web-server
sh bin/azkaban-web-shutdown.sh
sh bin/start-web.sh

登录 Web 页面后，如果能看到对应入口，就说明 Viewer 插件加载成功。

9. Viewer 插件配置示例

以 Reportal 为例，plugin.properties 中常见配置如下：

viewer.name=Reportal
viewer.path=reportal
viewer.order=1
viewer.hidden=false
viewer.external.classpaths=extlib
viewer.servlet.class=azkaban.viewer.reportal.ReportalServlet

azkaban.should.proxy=true
proxy.user=azkaban/admin@EXAMPLE.COM
proxy.keytab.location=/opt/azkaban/azkaban.keytab
allow.group.proxy=true

reportal.output.filesystem=hdfs
reportal.output.dir=/tmp/reportal
reportal.output.dir.retention.ms=604800000
reportal.mail.temp.dir=/tmp/reportal
reportal.mail.temp.dir.retention.ms=86400000
reportal.clean.interval.ms=86400000

hadoop.security.manager.class=azkaban.security.HadoopSecurityManager_H_2_0

主要配置含义：

配置	说明
viewer.name	页面显示名称
viewer.path	访问路径
viewer.order	页面入口排序
viewer.hidden	是否隐藏入口
viewer.servlet.class	插件 Servlet 类
viewer.external.classpaths	额外依赖目录
reportal.output.filesystem	报表输出位置，本地或 HDFS
reportal.output.dir	报表输出目录

Viewer 插件本质上是在 Azkaban Web 中挂载一个额外页面，因此主要关注 Servlet 类、依赖和页面路径。

10. 自定义 JobType 插件开发思路

如果要自己开发一个 JobType 插件，核心思路是：

1. 编写一个 Java 类，继承 Azkaban 的 Job 基类或实现对应接口。
2. 在类中实现任务初始化、执行、取消等逻辑。
3. 打包 jar。
4. 在 plugins/jobtypes/<type>/plugin.properties 中配置 jobtype.class。
5. 重启 Executor。
6. 编写 .job 文件使用新的 type。

假设自定义一个 myjava 类型：

plugins/jobtypes/myjava/
  plugin.properties
  lib/
    my-azkaban-jobtype.jar

plugin.properties：

jobtype.class=com.example.azkaban.MyJavaJob
jobtype.classpath=lib/*

使用时编写 job：

type=myjava
name=test_myjava
param1=hello

这样 Executor 在执行 type=myjava 的任务时，就会加载对应插件类执行。

11. 自定义插件开发注意点

11.1 依赖隔离

插件依赖尽量放在插件自己的 lib 目录中，不要随意放到全局 extlib。

如果多个插件依赖不同版本的 jar，放到全局目录容易产生冲突。

11.2 日志

插件中要尽量把关键参数和执行命令打印出来。

例如：

任务参数
执行用户
实际执行命令
工作目录
退出码

这样排查问题时不用反复修改代码。

11.3 取消任务

JobType 插件最好实现 cancel 逻辑。

如果只实现执行逻辑，不处理取消逻辑，用户在页面上点击 kill flow 后，底层进程可能还在继续运行。

11.4 安全认证

如果插件要访问 HDFS、Hive、YARN，并且集群开启 Kerberos，需要重点处理：

keytab
principal
delegation token
proxy user
execute-as-user

很多插件安装失败不是代码问题，而是安全认证和依赖 classpath 没配好。

12. 常见问题

12.1 插件没有加载

检查 Executor 或 Web 日志：

grep -i "plugin" logs/*.out
grep -i "Loaded jobtype" logs/*.out

常见原因：

1. 插件目录层级不对。
2. azkaban.jobtype.plugin.dir 配置错误。
3. plugin.properties 文件名或内容错误。
4. jar 包缺失。
5. 重启的是错误节点。

12.2 ClassNotFoundException

如果出现：

java.lang.ClassNotFoundException

优先检查：

jobtype.class
jobtype.classpath
lib 目录 jar 是否存在

如果是 Hadoop、Hive、Spark 相关类找不到，还要检查 extlib 和 commonprivate.properties。

12.3 Kerberos 认证失败

如果开启 Kerberos，常见错误包括：

GSSException
Failed to find any Kerberos tgt
LoginException

重点检查：

proxy.keytab.location
proxy.user
hadoop.security.manager.class
azkaban.should.proxy
obtain.namenode.token
obtain.jobtracker.token

12.4 execute-as-user 权限错误

检查：

ls -l /opt/azkaban/execute-as-user

一般需要：

-rws--x--- root ...

如果权限不对，重新设置：

chown root execute-as-user
chmod 6050 execute-as-user

13. 安装检查清单

安装插件后，可以按下面清单检查：

检查项	命令或位置
Executor 插件目录	azkaban-exec-server/plugins/jobtypes
Web 插件目录	azkaban-web-server/plugins/viewer
JobType 配置	plugin.properties
公共私有配置	commonprivate.properties
依赖包	lib、extlib
插件加载日志	grep 'Loaded jobtype' logs/*.out
安全认证	keytab、principal、proxy user
用户切换	execute-as-user 权限

14. 总结

Azkaban 插件可以分成两类重点理解：

Executor 端：JobType 插件，负责让任务跑起来
Web 端：Viewer 插件，负责扩展页面展示能力

安装插件时最容易出问题的地方通常不是业务代码，而是：

目录层级
plugin.properties
classpath
extlib
Kerberos
execute-as-user

如果是自己开发插件，建议先从最简单的 JobType 插件开始，只实现一个固定命令执行逻辑，确认插件加载、参数读取、日志输出都没有问题后，再逐步接入 Hadoop、Hive、Spark 或 Kerberos。