Set Up Pentaho to Connect to a Hortonworks Cluster
Overview
These instructions explain how to configure Pentaho's HDP shim, so Pentaho can connect to a working Hortonworks Data Platform (HDP) cluster.
Before You Begin
Before you begin, you'll need to do a few things.
- Verify Support
Check the Component Reference to verify that your Pentaho version supports your version of the HDP cluster.
- Set Up a HDP cluster
Pentaho can connect to secured and unsecured HDP Clusters:- Configure a HDP cluster. See Hortonwork's documentation if you need help.
- Install any required services and service client tools.
- Test the cluster.
- Get Connection Information
Get connection information for the cluster and services that you will use from your Hadoop Administrator, or from Ambari or other cluster management tools.
- Add a YARN User to Superuser Group
Add the YARN user on the cluster to the group defined by dfs.permissions.superusergroup property. The dfs.permissions.superusergroup property can be found in hdfs-site.xml file on your cluster or in the cluster management application.
- Review the Version-Specific Notes Section
Read the Version-Specific Notes section to review special configuration instructions for your version of HDP.
If you are connecting to a secured HDP cluster there are a few additional things you need to do.
- Secure the HDP with Kerberos
Pentaho supports Kerberos authentication. You will need to:- Configure Kerberos security on the cluster, including the Kerberos Realm, Kerberos KDC, and Kerberos Administrative Server.
- Configure the name, data, secondary name, job tracker, and task tracker nodes to accept remote connection requests.
- Set up Kerberos for name, data, secondary name, job tracker, and task tracker nodes if you are have deployed Hadoop using an enterprise-level program.
- Add the user account credential for each Spoon user that should have access to the Hadoop cluster to the Kerberos database. Make sure there is an operating system user account on each node in the Hadoop cluster for each user that you want to add to the Kerberos database. Add operating system user accounts if necessary. Note that the user account UIDs must be greater than the minimum user ID value (min.user.id). Usually, the minimum user ID value is set to 1000.
- Set up Kerberos on your Pentaho computers
Instructions for how to do this appear in Set Up Kerberos for Pentaho.
Edit Configuration Files on Clusters
Pentaho-specific edits to configuration files are the cluster are referenced in this section.
Oozie
By default, Oozie jobs are run by the Oozie user. But, if you use PDI to start an Oozie job, you must add the PDI user to the oozie-site.xml file on the cluster so that the PDI user can execute the program in proxy. If you plan to use the Oozie service complete these instructions:
- Open the oozie-site.xml file on the cluster.
- Add the following lines of the code to the oozie-site.xml file on cluster, substituting <your_pdi_user_name> with the PDI User username, such as jdoe.
1 <property> 2 <name>oozie.service.ProxyUserService.proxyuser.<your_pdi_user_name>.groups</name> 3 <value>*</value> 4 </property> 5 <property> 6 <name>oozie.service.ProxyUserService.proxyuser.<your_pdi_user_name>.hosts</name> 7 <value>*</value> 8 </property>
- Save and close the file
Configure Pentaho Component Shims
You must configure the shim in each of the following Pentaho components, on each computer from which Pentaho will be used to connect to the cluster:
- Spoon (PDI Client)
- Pentaho Server, including Analyzer and Pentaho Interactive Reporting.
- Pentaho Report Designer (PRD)
- Pentaho Metadata Editor (PME)
As a best practice, configure the shim in Spoon first. Spoon has features that will help you test your configuration. Then, copy the tested Spoon configuration files to other components, making changes if necessary.
You can also opt to go through these instructions for each Pentaho component, and not copy the shim files from Spoon. If you do not not plan to connect to the cluster from Spoon, you can configure the shim in another component first instead.
Step 1: Locate the Pentaho Big Data Plugin and Shim Directories
Shims and other parts of the Pentaho Adaptive Big Data Layer are in the Pentaho Big Data Plugin directory. The path to this directory differs by component. You need to know the locations of this directory, in each component, to complete shim configuration and testing tasks.
<pentaho home> is the directory where Pentaho is installed.
Components | Location of Pentaho Big Data Plugin Directory |
---|---|
Spoon | <pentaho home>/design-tools/data-integration/plugins/pentaho-big-data-plugin |
Pentaho Server | <pentaho home>/server/pentaho-server/pentaho-solutions/system/kettle/plugins/pentaho-big-data-plugin |
Pentaho Report Designer | <pentaho home>/design-tools/report-designer/plugins/pentaho-big-data-plugin |
Pentaho Metadata Editor | <pentaho home>/design-tools/metadata-editor/plugins/pentaho-big-data-plugin |
Shims are located in the pentaho-big-data-plugin/hadoop-configurations directory. Shim directory names consist of a three or four letter Hadoop Distribution abbreviation followed by the Hadoop Distribution's version number. The version number does not contain a decimal point. For example, the shim directory named cdh54 is the shim for the CDH (Cloudera Distribution for Hadoop), version 5.4. Here is a list of the shim directory abbreviations.
Abbreviation | Shim |
---|---|
cdh | Cloudera's Distribution of Apache Hadoop |
emr | Amazon Elastic Map Reduce |
hdp | Hortonworks Data Platform |
mapr | MapR |
Step 2: Select the Correct Shim
Although Pentaho often supports one or more versions of a Hadoop distribution, the download of the Pentaho Suite only contains the latest, supported, Pentaho-certified version of the shim. The other supported versions of shims can be downloaded from the Pentaho Customer Support Portal.
Before you begin, verify that the shim you want is supported by your version of Pentaho shown in the Components Reference.
- Navigate to the pentaho-big-data-plugin/hadoop-configurations directory to view the shim directories. If the shim you want to use is already there, you can go to Step 3: Copy the Configuration Files from Cluster to Shim.
- On the Customer Portal home page, sign in using the Pentaho support user name and password provided to you in your Pentaho Welcome Packet.
- In the search box, enter the name of the shim you want. Select the shim from the search results. Optionally, you can browse the shims by version on the Downloads page.
- Read all prerequisites, warnings, and instructions. On the bottom of the page in the Box widget, click the shim zip file to download it.
- Unzip the downloaded shim package to the pentaho-big-data-plugin/hadoop-configurations directory.
Step 3: Copy the Configuration Files from Cluster to Shim
Copying configuration files from the cluster to the shim helps keep key configuration settings in sync with the cluster and reduces configuration errors.
- Back up the existing HDP shim files in the pentaho-big-data-plugin/hadoop-configurations/hdpxx directory.
- Copy the following configuration files from the HDP cluster to pentaho-big-data-plugin/hadoop-configurations/hdpxx (overwriting the existing files):
- core-site.xml
- hbase-site.xml
- hdfs-site.xml
- hive-site.xml
- mapred-site.xml
- yarn-site.xml
Step 4: Edit the Shim Configuration Files
You need to verify or change authentication, Oozie, Hive, MapReduce, and YARN settings in these files:
- core-site.xml
- config.properties
- hbase-site.xml
- hive-site.xml
- mapred-site.xml
- yarn-site.xml
Verify or Edit config.properties (Unsecured Clusters)
If you are connecting to an unsecure cluster, verify that these values are properly set. Set the Oozie proxy user if needed.
- Navigate to the pentaho-big-data-plugin/hadoop-configurations/hdpxx directory and open config.properties.
- Add the following values:
Parameter | Values |
---|---|
authentication.superuser.provider | NO_AUTH |
pentaho.oozie.proxy.user | Add a proxy user's name to access the Oozie service through a proxy, otherwise, leave it set to oozie. |
java.system.hdp.version | HDP Version. For HDP 2.2, this is 2.2.0.0-2041 |
- Save and close the file.
Edit config.properties (Secured Clusters)
If you are connecting to a secure cluster, add Kerberos information to the config.properties file. Set the Oozie proxy user if needed.
- Navigate to the pentaho-big-data-plugin/hadoop-configurations/hdpxx directory and open the config.properties file.
- Add these values:
Parameter | Values |
---|---|
authentication.superuser.provider | hdp-kerberos (This should be the same as the authentication.kerberos.id .) |
authentication.kerberos.principal |
Set the Kerberos principal. |
authentication.kerberos.password |
Set the Kerberos password. You only need to set the password or the keytab, not both. |
authentication.kerberos.keytabLocation |
Set the Kerberos keytab. You only need to set the password or the keytab, not both. |
pentaho.oozie.proxy.user | Add the proxy user's name if you plan to access the Oozie service through a proxy. Otherwise, leave it set to oozie. |
java.system.hdp.version |
HDP Version. For HDP 2.2, this is 2.2.0.0-2041 |
- Save and close the file.
Edit hbase-site.xml
Edit the location of the temporary directory in the hbase-site.xml
file to create an HBase local storage directory.
- Navigate to the pentaho-big-data-plugin/hadoop-configurations/hdpxx directory and open the hbase-site.xml file.
- Add the following value:
Parameter | Value |
---|---|
hbase.tmp.dir |
/tmp/hadoop/hbase |
- Save and close the file.
Edit hive-site.xml
Verify that the following parameter is set in the hive-site.xml file:
- Navigate to the pentaho-big-data-plugin/hadoop-configurations/hdpxx directory and open the hive-site.xml file.
- Add the following value:
Parameter | Value |
---|---|
hive.metastore.uris | Set this to the location of your hive metastore. |
- Save and close the file.
Edit mapred-site.xml
Edit the mapred-site.xml file to indicate where the job history logs are stored and to allow MapReduce jobs to run across platforms.
- Navigate to the pentaho-big-data-plugin/hadoop-configurations/hdpxx directory and open the mapred-site.xml file .
- Add the following values:
Parameter | Value |
---|---|
mapreduce.jobhistory.address | Set this to the place where job history logs are stored. |
mapreduce.application.classpath |
Add classpath information. Here is an example: <property> <name>mapreduce.application.classpath</name> <value>$PWD/mr-framework/hadoop/share/hadoop/mapreduce/* :$PWD/mr-framework/hadoop/share/hadoop/mapreduce/lib/* :$PWD/mr-framework/hadoop/share/hadoop/common/*:$PWD/mr-framework/hadoop/share/hadoop/common/lib/* :$PWD/mr-framework/hadoop/share/hadoop/yarn/*:$PWD/mr-framework/hadoop/share/hadoop/yarn/lib/* :$PWD/mr-framework/hadoop/share/hadoop/hdfs/*:$PWD/mr-framework/hadoop/share/hadoop/hdfs/lib/* :/usr/hdp/${hdp.version}/hadoop/lib/hadoop-lzo-0.6.0.${hdp.version}.jar:/etc/hadoop/conf/secure </value> </property>
|
mapreduce.application.framework.path |
Set the framework path. Here is an example: <property> <name>mapreduce.application.framework.path</name> <value>/hdp/apps/${hdp.version}/mapreduce/mapreduce.tar.gz#mr-framework</value> </property> |
- Add the following:
Parameter | Value |
---|---|
mapreduce.app-submission.cross-platform | Add this property to allow MapReduce jobs to run on either Windows client or Linux server platforms .
<property> <name>mapreduce.app-submission.cross-platform</name> <value>true</value> </property> |
- Save and close the file.
Edit yarn-site.xml
Verify that the following parameters are set in the yarn-site.xml
file.
- Navigate to the pentaho-big-data-plugin/hadoop-configurations/hdpxx directory and open the
yarn-site.xml
file. - Add these values:
Parameter | Values |
---|---|
yarn.application.classpath | Add the classpaths needed to run YARN applications. Use commas to separate multiple paths. Example: <property> <name>yarn.application.classpath</name> <value>$HADOOP_CONF_DIR,/usr/hdp/current/hadoop-client/*, /usr/hdp/current/hadoop-client/lib/*,/usr/hdp/current/hadoop-hdfs-client/*, /usr/hdp/current/hadoop-hdfs-client/lib/*,/usr/hdp/current/hadoop-yarn-client/*, /usr/hdp/current/hadoop-yarn-client/lib/*</value> </property> |
yarn.resourcemanager.hostname | Update the hostname in your environment or use the default: sandbox.hortonworks.com |
yarn.resourcemanager.address | Update the hostname and port for your environment. |
yarn.resourcemanager.admin.address | Update the hostname and port for your environment. |
- Save and close the file.
Create a Connection to the HDP Cluster
Creating a connection to the cluster involves setting an active shim, then configuring and testing the connection to the cluster. Making a shim active means it is used by default when you access a cluster. When you initially install Pentaho, no shim is active by default. You must choose a shim to make active before you can connect to a cluster. Only one shim can be active at a time. The way you make a shim active, as well as the way you configure and test the cluster connection differs by Pentaho component.
Create and Test a Connection to the Cluster in Spoon
Creating and testing a connection to the HDP cluster from Spoon involves two tasks:
- Setting the active shim in Spoon
- Configuring and testing the cluster connection
Set the Active Shim in Spoon
Set the active shim when you want to connect to a Hadoop cluster the first time, or when you want to switch clusters. To set a shim as active, complete the following steps:
- Start Spoon.
- Select Hadoop Distribution... from the Tools menu.
- In the Hadoop Distribution window, select the Hadoop distribution you want.
- Click OK.
- Stop, then restart Spoon.
Configure and Test the Cluster Connection
You must provide connection details for the cluster and services you will use, such as the hostname for HDFS or the URL for Oozie. Then, you can use a built-in tool to test your configuration to find and troubleshoot common configuration issues, such as wrong hostnames and user permission errors.
Connection settings are set in the Hadoop cluster window. You can get to the settings from several places, but in these instructions, you will get the Hadoop cluster window from the View tab in a transformation or job. Complete the following steps to configure and test a connection:
- In Spoon, create a new job or transformation or open an existing one.
- Click the View tab.
- Right-click the Hadoop cluster folder, then click New. The Hadoop cluster window appears.
- Enter information in the Hadoop cluster window. You can get this information from your Hadoop Administrator.
As a best practice, use Kettle variables for each connection parameter value to mitigate risks associated with running jobs and transformations in environments that are disconnected from the repository.
Option | Definition |
---|---|
Cluster Name | Name that you assign the cluster connection. |
Use MapR Client | Indicates that this connection is for a MapR cluster. If this box is checked, the fields in the HDFS and JobTracker sections are disabled because those parameters are not needed to configure MapR. |
Hostname (in HDFS section) | Hostname for the HDFS node in your Hadoop cluster. |
Port (in HDFS section) | Port for the HDFS node in your Hadoop cluster. |
Username (in HDFS section) | Username for the HDFS node. |
Password (in HDFS section) | Password for the HDFS node. |
Hostname (in JobTracker section) | Hostname for the JobTracker node in your Hadoop cluster. If you have a separate job tracker node, type in the hostname here. Otherwise use the HDFS hostname. |
Port (in JobTracker section) | Port for the JobTracker in your Hadoop cluster. Job tracker port number; this cannot be the same as the HDFS port number. |
Hostname (in ZooKeeper section) | Hostname for the ZooKeeper node in your Hadoop cluster. Supply this only if you want to connect to a ZooKeeper service. |
Port (in ZooKeeper section) | Port for the ZooKeeper node in your Hadoop cluster. Supply this only if you want to connect to a ZooKeeper service. |
URL (in Oozie section) | Oozie client address. Supply this only if you want to connect to the Oozie service. |
- Click the Test button. Test results appear in the Hadoop Cluster Test window. If you have errors, see the Troubleshoot Cluster and Service Configuration Issues section below to resolve the issues, then test again.
- Click Close on the Hadoop Cluster Test window, then click OK to close the Hadoop cluster window.
Copy Spoon Shim Files to Other Pentaho Components
Once your connection has been properly configured on Spoon, copy configuration files to the shim directories in other Pentaho components. Copy the following configuration files from the pentaho-big-data-plugin/hadoop-configurations/hdpxx directory to pentaho-big-data-shim/hdpxx on the Pentaho Server, PRD, or PME:
- hbase-site.xml
- core-site.xml
- hdfs-site.xml
- hive-site.xml
- mapred-site.xml
- yarn-site.xml
Connect Other Pentaho Components to the Hortonworks Cluster
These instructions explain how to create and test a connection to the cluster in the Pentaho Server, PRD, and PME. Creating and testing a connection to the cluster in Spoon involves two tasks:
- Setting the active shim on PRD, PME, and the Pentaho Server
- Configuring and testing the cluster connections
Set the Active Shim on PRD, PME, and the Pentaho Server
Modify the plugin.properties file to set the active shim for the Pentaho Server, PRD, and PME.
- Stop the component.
- Locate the pentaho-big-data-plugin directory for your component.
- Navigate to the hadoop-configurations directory.
- Navigate to the pentaho-big-data-plugin directory and open the plugin.properties file.
- Set the active.hadoop.configuration property to the directory name of the shim you want to make active. Here is an example:
active.hadoop.configuation=hdp24
- Save and close the plugin.properties file.
- Restart the component.
Create and Test Connections
Connection tests appear in the following table.
Component | Test |
---|---|
Pentaho Server for DI |
Create a transformation in Spoon and run it remotely. |
Pentaho Server for BA | Create a connection to the cluster in the Data Source Wizard. |
PME | Create a connection to the cluster in PME. |
PRD | Create a connection to the cluster in PRD. |
Once you've connected to the cluster and its services properly, provide connection information to users who need access to the cluster and its services. Those users can only obtain access from computers that have been properly configured to connect to the cluster.
Here is what they need to connect:
- Hadoop Distribution and version of the cluster
- HDFS, JobTracker, ZooKeeper, and Hive2/Impala Hostnames, IP addresses and port numbers
- Oozie URL (if used)
- Users also require the appropriate permissions to access the directories they need on HDFS. This typically includes their home directory and any other required directories.
They might also need more information depending on the job entries, transformation steps, and services they use. Here's a more detailed list of information that your users might need from you.
General Notes
Set Hive Database Connection Parameters (Secured Clusters Only)
To access Hive, you need to set several database connection parameters from within Spoon.
-
Verify the valid Kerberos principal values have been set to Hive.metastore.kerberos.principal and hive.server2.authentication.kerberos.principal in hive-site.xml.
-
Start Spoon.
-
In Spoon, open the Database Connection window.
-
Click Options.
-
Add the principal parameter and set it to the values that you noted in the hive-site.xml file. The principal typically looks like
hive/HiveServer2.pentaho.com@mydomain
. -
Click OK to close the window.
Sqoop "Unsupported major.minor version" Error
If you are using Pentaho 6.0 and the Java version on your cluster is older than the Java version that Pentaho uses, you must change Pentaho's JDK so it is the same major version as the JDK on the cluster. The JDK that you install for Pentaho must meet the requirements in the Supported Components matrix. To learn how to download and install the JDK read this article.
Version-Specific Notes
The following notes are special topics for HDP.
HDP 2.5 Notes
The following note address issues with HDP 2.5.
Sqoop Support
If you receive an error message stating Generating splits for a textual index column allowed only in case of "-Dorg.apache.sqoop.splitter.allow_text_splitter=true" property passed as a parameter while trying to use the split-by option to the Sqoop Import job entry with the HDP 2.5 shim, perform the following steps to set the org.apache.sqoop.splitter.allow_text_splitter
property to true
:
-
Open your KJB file that contains a Sqoop Import entry in the PDI client (also known as Spoon).
-
Double-click the Sqoop Import entry to access the Sqoop Import property dialog box.
-
Click the Advanced Options link in the lower left corner of the dialog box.
-
In the Custom tab, add the
Dorg.apache.sqoop.splitter.allow_text_splitter
argument and set the value totrue
. -
Click OK and save your KJB file.
You should now be able to use the split-by option to the Sqoop Import entry.
HDP 2.4 Notes
The following notes address issues with HDP 2.4.
Simba Spark SQL Driver Support
If you are using Pentaho 7.0 or later, the HDP 2.4 shim supports the Simba Spark SQL driver. You will need to download, install, and configure the driver to use Simba Spark SQL with the HDP 2.4 shim.
- Download the Simba Spark SQL driver.
- Extract the ZIP file, and then copy the following 3 files into the
lib/
directory of the HDP shim:
SparkJDBC41.jar
TCLIServiceClient.jar
QI.jar
- In the Database Connection window, select SparkSQL option. The default port for the Spark thrift server is
10015
. -
For secure connections, set the following additional parameters on the JDBC URL through the Options tab:
- KrbServiceName
- KrbHostFQDN
- KrbRealm
-
For unsecure connections, if your Spark SQL configuration specifies
hive.server2.authentication=NONE
, then make sure to include an appropriate User Name in the Database Connection window. Otherwise, the connection is assumed to be NOSASL authentication, which will cause a connection failure after timeout. -
Stop and restart the component.
HDP 2.3 Notes
The following note addresses issues with HDP 2.3.
Pentaho can connect to HDP 2.3 cluster using the HDP 2.2 or HDP 2.3 shims
You can use either the HDP 2.2 or HDP 2.3 shims to connect to a HDP 2.3 clusters:
- If you use the HDP 2.2 shim to connect to an HDP 2.3 cluster, only HDP 2.2 functionality is supported.
- If you want to support HDP 2.3 functionality, use the HDP 2.3 shim to connect to the HDP 2.3 cluster instead.
Shims can be downloaded from the Pentaho Customer Support Portal.
Troubleshoot Cluster and Service Configuration Issues
The issues in this section explain how to resolve common configuration problems.
Shim and Configuration Issues
Symptoms | Common Causes | Common Resolutions |
---|---|---|
No shim |
|
|
Shim doesn't load |
|
|
The file system's URL does not match the URL in the configuration file. | Configuration files (*-site.xml files) were not configured properly. | Verify that the configuration files were configured correctly. Verify that the core-site.xml file is configured correctly. See the instructions for your Hadoop distribution in the Set Up Pentaho to Connect to an Apache Hadoop Cluster article for details. |
Connection Problems
Symptoms | Common Causes | Common Resolutions |
---|---|---|
Hostname incorrect or not resolving properly. |
|
|
Port name is incorrect. |
|
|
Can't connect. |
|
|
Directory Access or Permissions Issues
Symptoms | Common Causes | Common Resolutions |
---|---|---|
Can't access directory. |
|
|
Can't create, read, update, or delete files or directories |
Authorization and/or authentication issues. |
|
Test file cannot be overwritten. | Pentaho test file is already in the directory. |
|
Oozie Issues
Symptoms | Common Causes | Common Resolutions |
---|---|---|
Can't connect to Oozie. |
|
|
ZooKeeper Problems
Symptoms | Common Causes | Common Resolutions |
---|---|---|
Can't connect to ZooKeeper . |
|
|
ZooKeeper hostname or port not found or doesn't resolve properly. |
|
|