Installing Kudu

You can deploy Kudu on a cluster using packages or you can build Kudu from source. To run Kudu without installing anything, use the Kudu Quickstart VM.

Kudu is currently easier to install and manage with Cloudera Manager, version 5.4.7 or newer. If you use Cloudera Manager, see also Cloudera’s Kudu documentation.
Upgrading Kudu

To upgrade Kudu from a previous version, see Upgrade from 0.5.0 to 0.6.0.

Prerequisites and Requirements

Hardware

  • A host to run the Kudu master.

  • One or more hosts to run Kudu tablet servers. When using replication, a minimum of three tablet servers is necessary.

Operating System Requirements
Linux

  • RHEL 6 or Ubuntu 14.04 Trusty.

  • A kernel and fileystem that support hole punching. Hole punching is the use of the fallocate(2) system call with the FALLOC_FL_PUNCH_HOLE option set. See troubleshooting hole punching for more information.

  • ntp.

OS X

  • OS X 10.10 Yosemite or OS X 10.11 El Capitan.

  • Prebuilt OS X packages are not provided.

Windows

  • Microsoft Windows is unsupported.

Storage

  • If solid state storage is available, storing Kudu WALs on such high-performance media may significantly improve latency when Kudu is configured for its highest durability levels.

Management

  • If you use Cloudera Manager and CDH, Cloudera Manager 5.4.3 or newer is required. Cloudera Manager 5.4.7 and newer provide better monitoring and administration options.

Install Using Packages

You can install Kudu using packages managed by the operating system.

Table 1. Kudu Package Locations
OS Repository Individual Packages

RHEL

RHEL 6

RHEL 6

Ubuntu

Trusty

Trusty
For later versions of Ubuntu, the Ubuntu Trusty packages are reported to install, though they have not been extensively tested.

Install On RHEL Hosts

  1. Download and configure the Kudu repositories for your operating system, or manually download individual RPMs, the appropriate link from Kudu Package Locations.

  2. If using a Yum repository, use the following commands to install Kudu packages on each host.

    sudo yum install kudu                         # Base Kudu files
sudo yum install kudu-master                  # Kudu master init.d service script and default configuration
sudo yum install kudu-tserver                 # Kudu tablet server init.d service script and default configuration
sudo yum install kudu-client0                 # Kudu C++ client shared library
sudo yum install kudu-client-devel            # Kudu C++ client SDK

  3. To manually install the Kudu RPMs, first download them, then use the command sudo rpm -ivh <RPM to install> and install the kudu-master and kudu-tserver packages on the appropriate hosts. These packages provide the operating system commands to start and stop Kudu.

Install On Ubuntu or Debian Hosts

  1. If using an Ubuntu or Debian repository, use the following commands to install Kudu packages on each host.

    sudo apt-get install kudu                     # Base Kudu files
sudo apt-get install kudu-master              # Service scripts for managing kudu-master
sudo apt-get install kudu-tserver             # Service scripts for managing kudu-tserver
sudo apt-get install libkuduclient0           # Kudu C++ client shared library
sudo apt-get install libkuduclient-dev       # Kudu C++ client SDK

  2. To manually install individual DEBs, first download them, then use the command sudo dpkg -i <DEB to install> to install them.

Verify the Installation

  1. Verify that services are running using one of the following methods:

    • Examine the output of the ps command on servers to verify one or both of kudu-master or kudu-tserver processes is running.

    • Access the Master or Tablet Server web UI by opening http://<_host_name_>:8051/ for masters or http://<_host_name_>:8050/ for tablet servers.

  2. If Kudu isn’t running, have a look at the log files in '/var/log/kudu', and if there’s a file ending with '.FATAL' then it means Kudu wasn’t able to start.

    • If the error is 'Error during hole punch test', it might be a problem with your OS.

    • If the error is 'Couldn’t get the current time', it’s a problem with ntp.

    • If it’s something else that doesn’t seem obvious or if you’ve tried the above solutions without luck, you can ask for help on the user mailing list.

Required Configuration

Additional configuration steps are required on each host before you can start Kudu services.

  1. The packages create a kudu-conf entry in the operating system’s alternatives database, and they ship the built-in conf.dist alternative. To adjust your configuration, you can either edit the files in /etc/kudu/conf/ directly, or create a new alternative using the operating system utilities, make sure it is the link pointed to by /etc/kudu/conf/, and create custom configuration files there. Some parts of the configuration are configured in /etc/default/kudu-master and /etc/default/kudu-tserver files as well. You should include or duplicate these configuration options if you create custom configuration files.

    Review the configuration, including the default WAL and data directory locations, and adjust them according to your requirements.

  1. Start Kudu services using the following commands:

    $ sudo service kudu-master start
$ sudo service kudu-tserver start

  2. To stop Kudu services, use the following commands:

    $ sudo service kudu-master stop
$ sudo service kudu-tserver stop

  3. Configure the Kudu services to start automatically when the server starts, by adding them to the default runlevel.

    $ sudo chkconfig kudu-master on                # RHEL / CentOS
$ sudo chkconfig kudu-tserver on               # RHEL / CentOS

$ sudo update-rc.d kudu-master defaults        # Debian / Ubuntu
$ sudo update-rc.d kudu-tserver defaults       # Debian / Ubuntu

  4. For additional configuration of Kudu services, see Configuring Kudu.

Build From Source

If installing Kudu using parcels or packages does not provide the flexibility you need, you can build Kudu from source. You can build from source on any supported operating system.

Known Build Issues

  • It is not possible to build Kudu on Microsoft Windows.

  • Do not build Kudu using gcc 4.6. It is known to cause runtime and test failures.

RHEL or CentOS

  1. Install the prerequisite libraries, if they are not installed:

    $ sudo yum install boost-static boost-devel openssl-devel cyrus-sasl-devel

  2. Optional: Install the asciidoctor gem if you plan to build documentation.

    $ sudo gem install asciidoctor

  3. Clone the Git repository and change to the new kudu directory.

    $ git clone http://github.com/cloudera/kudu
$ cd kudu

  4. Build any missing third-party requirements using the build-if-necessary.sh script.

    $ thirdparty/build-if-necessary.sh

  5. Build Kudu, using the utilities installed in the previous step. Edit the install prefix to the location where you would like the Kudu binaries, libraries, and headers installed during the make install step. The default value is /usr/local/.

    thirdparty/installed/bin/cmake . -DCMAKE_BUILD_TYPE=release -DCMAKE_INSTALL_PREFIX=/opt/kudu
make -j4

  6. Optional: Install Kudu binaries, libraries, and headers. If you do not specify a DESTDIR, /usr/local/ is the default.

    sudo make DESTDIR=/opt/kudu install

  7. Optional: Build the documentation. NOTE: This command builds local documentation that is not appropriate for uploading to the Kudu website.

    $ make docs
Example 1. RHEL / CentOS Build Script

This script provides an overview of the procedure to build Kudu on a newly-installed RHEL or CentOS host, and can be used as the basis for an automated deployment scenario. It skips the steps marked Optional above.

#!/bin/bash

sudo yum -y install boost-static boost-devel openssl-devel cyrus-sasl-devel
git clone http://github.com/cloudera/kudu
cd kudu
thirdparty/build-if-necessary.sh
thirdparty/installed/bin/cmake . -DCMAKE_BUILD_TYPE=release
make -j4
make install

Ubuntu or Debian

  1. Install the prerequisite libraries, if they are not installed:

    $ sudo apt-get -y install git autoconf automake libboost-thread-dev curl gcc g++ \
  libssl-dev libsasl2-dev libtool ntp

  2. Optional: Install the asciidoctor gem and xsltproc if you plan to build documentation.

    $ sudo apt-get -y install asciidoctor xsltproc

  3. Clone the Git repository and change to the new kudu directory.

    $ git clone http://github.com/cloudera/kudu
$ cd kudu

  4. Build any missing third-party requirements using the build-if-necessary.sh script.

    $ thirdparty/build-if-necessary.sh

  5. Build Kudu.

    thirdparty/installed/bin/cmake . -DCMAKE_BUILD_TYPE=release
make -j4

  6. Optional: Build the documentation. NOTE: This command builds local documentation that is not appropriate for uploading to the Kudu website.

    $ make docs
Example 2. Ubuntu / Debian Build Script

This script provides an overview of the procedure to build Kudu on RHEL or CentOS, and can be used as the basis for an automated deployment scenario. It skips the steps marked Optional above.

#!/bin/bash

sudo apt-get -y install git autoconf automake libboost-thread-dev curl \
  gcc g++ libssl-dev libsasl2-dev libtool ntp
git clone http://github.com/cloudera/kudu
cd kudu
thirdparty/build-if-necessary.sh
thirdparty/installed/bin/cmake . -DCMAKE_BUILD_TYPE=release
make -j4
make install

OS X

The Xcode toolchain is necessary for compiling Kudu. Use xcode-select --install to install the Xcode Command Line Tools if Xcode is not already installed. These instructions use Homebrew to install dependencies, but manual dependency installation is possible.

OS X Known Issues

Kudu support for OS X is experimental, and should only be used for development. See OS X Limitations & Known Issues for more information.

  1. Install the prerequisite libraries, if they are not installed:

    $ brew install autoconf automake cmake libtool pkg-config boost pstree

  2. OS X 10.11 El Capitan only: install OpenSSL.

    $ brew install openssl
$ brew link -f openssl

  3. Clone the Git repository and change to the new kudu directory.

    $ git clone http://github.com/cloudera/kudu
$ cd kudu

  4. Build any missing third-party requirements using the build-if-necessary.sh script.

    $ thirdparty/build-if-necessary.sh

  5. Build Kudu.

    thirdparty/installed/bin/cmake .
make -j4

Installing the C++ Client Libraries

If you need access to the Kudu client libraries for development, install the kudu-client and kudu-client-devel package for your platform. See Install Using Packages.

Only build against the client libraries and headers (kudu_client.so and client.h). Other libraries and headers are internal to Kudu and have no stability guarantees.

Build the Java Client

Requirements

  • JDK 7

  • Apache Maven 3.x

  • protoc 2.6 or newer installed in your path, or built from the thirdparty/ directory. You can run the following commands to build protoc from the third-party dependencies:

$ thirdparty/download-thirdparty.sh
$ thirdparty/build-thirdparty.sh protobuf

To build the Java client, clone the Kudu Git repository, change to the java directory, and issue the following command:

$ mvn install -DskipTests

For more information about building the Java API, as well as Eclipse integration, see java/README.md.

View API Documentation

C++ API Documentation

The documentation for the C++ client APIs is included in the header files in /usr/include/kudu/ if you installed Kudu using packages or subdirectories of src/kudu/client/ if you built Kudu from source. If you installed Kudu using parcels, no headers are included in your installation. and you will need to build Kudu from source in order to have access to the headers and shared libraries.

The following command is a naive approach to finding relevant header files. Use of any APIs other than the client APIs is unsupported.

$ find /usr/include/kudu -type f -name *.h
Java API Documentation

You can view the Java API documentation online. Alternatively, after building the Java client, Java API documentation is available in java/kudu-client/target/apidocs/index.html.

Upgrade from 0.5.0 to 0.6.0

Before upgrading, see Client compatibility and API Compatibility. To upgrade from Kudu 0.5.0 to 0.6.0, perform the following high-level steps, which are detailed in Upgrade procedure:

  1. Shut down all Kudu services.

  2. Install the new Kudu packages or parcels, or install Kudu 0.6.0 from source.

  3. Restart all Kudu services.

It is technically possible to upgrade Kudu using rolling restarts, but it has not been tested and is not recommended.

Client compatibility

Kudu 0.6.0 maintains wire compatibility with Kudu 0.5.0. This means that a Kudu 0.6.0 client can communicate with a Kudu 0.5.0 cluster, and vice versa. For that reason, you do not need to upgrade client JARs at the same time the cluster is upgraded.

The same wire compatibility guarantees apply to the Impala_Kudu fork that was released with Kudu 0.5.0.

API Compatibility

The Kudu 0.6.0 client API is not compatible with the Kudu 0.5.0 client API. See the Kudu 0.6.0 release notes for details.

Upgrade procedure

  1. Stop the Kudu master and tablet server services:

    $ sudo service kudu-master stop
$ sudo service kudu-tserver stop

  2. Upgrade the packages.

    • On RHEL hosts:

      sudo yum clean all
sudo yum upgrade kudu

    • On Ubuntu or Debian hosts:

      sudo apt-get update
sudo apt-get install kudu

  3. Start the Kudu master and tablet server services:

    $ sudo service kudu-master start
$ sudo service kudu-tserver start

Next Steps