Installing Apache Kudu (incubating)

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.8.0 to 0.9.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, RHEL 7, Ubuntu 14.04 (Trusty), or SLES 12.

  • 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 7

RHEL 6, RHEL 7

Ubuntu

Trusty

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

Install On RHEL Hosts

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

  2. If using a Yum repository, use the following commands to install Kudu packages on each host, after saving the cloudera-kudu.repo file to /etc/yum.repos.d/.

    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 after saving the cloudera.list file to /etc/apt/sources.list.d/.

    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.

  • A C+11 capable compiler (GCC 4.8) is required.

RHEL or CentOS

RHEL or CentOS 6.6 or later is required to build Kudu from source. To build on a version older than 7.0, the Red Hat Developer Toolset must be installed (in order to have access to a C++11 capable compiler).

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

    $ sudo yum install gcc gcc-c++ autoconf automake libtool \
  boost-static boost-devel cyrus-sasl-devel \
  cyrus-sasl-plain patch pkgconfig make rsync vim-common gdb git

  2. If building on RHEL or CentOS older than 7.0, install the Red Hat Developer Toolset.

    $ DTLS_RPM=rhscl-devtoolset-3-epel-6-x86_64.noarch.rpm
$ DTLS_RPM_URL=https://www.softwarecollections.org/en/scls/rhscl/devtoolset-3/epel-6-x86_64/download/${DTLS_RPM}
$ wget ${DTLS_RPM_URL} -O ${DTLS_RPM}
$ sudo yum install -y scl-utils ${DTLS_RPM}
$ sudo yum install -y devtoolset-3-toolchain

  3. Optional: Install some additional packages, including ruby, if you plan to build documentation.

    $ sudo yum install gem ruby-devel zlib-devel

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

    $ git clone https://github.com/apache/incubator-kudu kudu
$ cd kudu

  5. Build any missing third-party requirements using the build-if-necessary.sh script. Not using the devtoolset will result in Host compiler appears to require libatomic, but cannot find it.

    $ build-support/enable_devtoolset.sh thirdparty/build-if-necessary.sh

  6. Build Kudu, using the utilities installed in the previous step. Choose a build directory for the intermediate output, which can be anywhere in your filesystem except for the kudu directory itself. Notice that the devtoolset must still be specified, else you’ll get cc1plus: error: unrecognized command line option "-std=c++11".

    mkdir -p build/release
cd build/release
../../build-support/enable_devtoolset.sh \
  ../../thirdparty/installed/bin/cmake \
  -DCMAKE_BUILD_TYPE=release \
  ../..
make -j4

  7. Optional: Install Kudu binaries, libraries, and headers. If you do not specify an installation directory through the DESTDIR environment variable, /usr/local/ is the default.

    sudo make DESTDIR=/opt/kudu install

  8. 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 gcc gcc-c++ autoconf automake libtool \
  boost-static boost-devel cyrus-sasl-devel \
  cyrus-sasl-plain patch pkgconfig make rsync vim-common gdb git
DTLS_RPM=rhscl-devtoolset-3-epel-6-x86_64.noarch.rpm
DTLS_RPM_URL=https://www.softwarecollections.org/en/scls/rhscl/devtoolset-3/epel-6-x86_64/download/${DTLS_RPM}
wget ${DTLS_RPM_URL} -O ${DTLS_RPM}
sudo yum install -y scl-utils ${DTLS_RPM}
sudo yum install -y devtoolset-3-toolchain
cd kudu
build-support/enable_devtoolset.sh thirdparty/build-if-necessary.sh
mkdir -p build/release
cd build/release
../../build-support/enable_devtoolset.sh \
  ../../thirdparty/installed/bin/cmake \
  -DCMAKE_BUILD_TYPE=release \
  ../..
make -j4

Ubuntu or Debian

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

    $ sudo apt-get install git autoconf automake libboost-thread-dev \
  libboost-system-dev curl gcc g++ libsasl2-dev libsasl2-modules \
  libtool ntp patch pkg-config make rsync unzip vim-common gdb python

  2. Optional: Install additional packages to build the documentation

    $ sudo apt-get install xsltproc zlib1g-dev

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

    $ git clone https://github.com/apache/incubator-kudu 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. Choose a build directory for the intermediate output, which can be anywhere in your filesystem except for the kudu directory itself.

    mkdir -p build/release
cd build/release
../../thirdparty/installed/bin/cmake -DCMAKE_BUILD_TYPE=release ../..
make -j4

  6. Optional: Install Kudu binaries, libraries, and headers. If you do not specify an installation directory through the DESTDIR environment variable, /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 2. Ubuntu / Debian Build Script

This script provides an overview of the procedure to build Kudu on Ubuntu, 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 \
  libboost-system-dev curl gcc g++ libsasl2-dev libsasl2-modules \
  libtool ntp patch pkg-config make rsync unzip vim-common gdb python
git clone https://github.com/apache/incubator-kudu kudu
cd kudu
thirdparty/build-if-necessary.sh
mkdir -p build/release
cd build/release
../../thirdparty/installed/bin/cmake \
  -DCMAKE_BUILD_TYPE=release \
  ../..
make -j4

SUSE Linux Enterprise Server

Building Kudu on SLES requires building Boost from source, since SLES does not have system packages containing Boost static libraries. Boost may be built anywhere, provided that the BOOST_ROOT environment variable is set to the location while invoking CMake to build Kudu. In the instructions below, Boost is built alongside Kudu.

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

    $ sudo zypper install autoconf automake curl cyrus-sasl-devel gcc gcc-c++ \
  gdb git libtool make ntp patch pkg-config python rsync unzip vim

  2. Install Boost.

    wget https://downloads.sourceforge.net/project/boost/boost/1.59.0/boost_1_59_0.tar.gz
tar xzf boost_1_59_0.tar.gz
pushd boost_1_59_0
./bootstrap.sh
./b2 --with-system --with-thread
popd

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

    $ git clone https://github.com/apache/incubator-kudu 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. Choose a build directory for the intermediate output, which can be anywhere in your filesystem except for the kudu directory itself.

    mkdir -p build/release
cd build/release
BOOST_ROOT=../../../boost_1_59_0 \
  ../../thirdparty/installed/bin/cmake \
  -DCMAKE_BUILD_TYPE=release \
  ../..
make -j4

  6. Optional: Install Kudu binaries, libraries, and headers. If you do not specify an installation directory through the DESTDIR environment variable, /usr/local/ is the default.

    sudo make DESTDIR=/opt/kudu install
Example 3. SLES Build Script

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

#!/bin/bash

sudo zypper install autoconf automake curl cyrus-sasl-devel gcc gcc-c++ \
  gdb git libtool make ntp patch pkg-config python rsync unzip vim
wget https://downloads.sourceforge.net/project/boost/boost/1.59.0/boost_1_59_0.tar.gz
tar xzf boost_1_59_0.tar.gz
pushd boost_1_59_0
./bootstrap.sh
./b2 --with-system --with-thread
popd
git clone https://github.com/apache/incubator-kudu kudu
cd kudu
thirdparty/build-if-necessary.sh
mkdir -p build/release
cd build/release
BOOST_ROOT=../../../boost_1_59_0 \
  ../../thirdparty/installed/bin/cmake \
  -DCMAKE_BUILD_TYPE=release \
  ../..
make -j4

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. Clone the Git repository and change to the new kudu directory.

    $ git clone https://github.com/apache/incubator-kudu kudu
$ cd kudu

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

    $ thirdparty/build-if-necessary.sh

  4. Build Kudu. Choose a build directory for the intermediate output, which can be anywhere in your filesystem except for the kudu directory itself.

    mkdir -p build/release
cd build/release
../../thirdparty/installed/bin/cmake -DCMAKE_BUILD_TYPE=release ../..
make -j4
Example 4. OSX Build Script

This script provides an overview of the procedure to build Kudu on OSX, and can be used as the basis for an automated deployment scenario. It assumes Xcode and Homebrew are installed.

#!/bin/bash

brew install autoconf automake cmake libtool pkg-config boost pstree
git clone https://github.com/apache/incubator-kudu kudu
cd kudu
thirdparty/build-if-necessary.sh
mkdir -p build/release
cd build/release
../../thirdparty/installed/bin/cmake -DCMAKE_BUILD_TYPE=release ../..
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.8.0 to 0.9.0

Before upgrading, see Client compatibility and API Compatibility. To upgrade from Kudu 0.8.0 to 0.9.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.9.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.

For the duration of the Kudu Beta, upgrade instructions are only given for going from the previous latest version to the newest.

Client compatibility

Masters and tablet servers should be upgraded before clients are upgraded. For specific information about client compatibility, see the Incompatible Changes section of the release notes.

API Compatibility

In Kudu 0.9 and higher, you must set partitioning options explicitly when creating a new table. If you do not specify partitioning options, the table creation will fail. This behavior change does not affect existing tables.

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 or CentOS 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