search

cerner / cerner_kafka

A Kafka Cookbook for Chef
Apache License 2.0
30 stars 25 forks source link
kafka kafka-cookbook kafka-installation

readme

Cerner Kafka

Cookbook Version Build Status

A Chef cookbook to install Apache's Kafka.

A recipe to install the KafkaOffsetMonitor application is also included.

View the Change Log to see what has changed.

Getting Started

To get setup you need to do the following,

Provide a value for node["kafka"]["zookeepers"] with an array of zookeeper host names (i.e. ['zk1.domain.com', 'zk2.domain.com', 'zk3.domain.com']).

With the defaults and the default recipe this will install and run a 0.9.0.0 Kafka broker using Kafka's defaults.

What this will setup

This will install Kafka at node["kafka"]["install_dir"]. In order to handle upgrades appropriately we use symbolic links and land the real installations elsewhere.

The true installations will land,

/opt (configurable with node["kafka"]["base_dir"])
| - kafka_0.9.0.0
| | - config
| | - bin
| | - kafka_0.9.0.0.jar
| | - ...

While we provide a symbolic link to the convenient location,

/opt/kafka (configurable with node["kafka"]["install_dir"])
| - config
| - bin
| - kafka_0.9.0.0.jar
| - ...

It will also create/setup an init service which can be used to start/stop/restart kafka,

service kafka [start|stop|restart|status]

We also link kafka's log directory to /var/log/kafka to make it easier to find kafka's logs.

Usage

Here are some common deployment options and tips

Deploying Kafka 0.8

This cookbook can be used to install/deploy Kafka 0.8.X but some additional configuration is required. In addition to setting the node["kafka"]["zookeepers"] attribute you will also need to set the node["kafka"]["brokers"] attribute with an array of Kafka broker host names.

You will also need to tweak node["kafka"]["version"] to the version that will be used and possibly node["kafka"]["scala_version"] as well which defaults to 2.11.

Kafka brokers and zookeepers attributes

The attributes,

Actually map to 'server.properties' settings,

We do this mapping for you when you provide the node["kafka"]["brokers"] and node["kafka"]["zookeepers"] attributes.

You can choose to provide the server.properties attribute instead of node["kafka"]["brokers"] or node["kafka"]["zookeepers"].

To map node["kafka"]["brokers"] to node["kafka"]["server.properties"]["broker.id"] correctly all Chef nodes running the kafka recipe (and are part of the same Kafka cluster) must have the same list of node["kafka"]["brokers"] and all broker hostnames must be in the same order. We determine the node["kafka"]["server.properties"]["broker.id"] by using the index of Chef node's fqdn/hostname/ip in the list as the node["kafka"]["server.properties"]["broker.id"].

Additionally if you want to use a Zookeeper chroot with your kafka installation you can provide it by setting node["kafka"]["zookeeper_chroot"].

Using node["kafka"]["brokers"], node["kafka"]["zookeepers"] and node["kafka"]["zookeeper_chroot"] attributes are the recommended way to setup your kafka cluster in Chef.

Updating from 1.X and 2.X of the Cookbook

There were some non-passive changes made during the upgrade to the 2.X version of the cookbook. Specifically,

Make sure to make the appropriate attribute changes if needed. Otherwise the cookbook should work just as it did before.

Additionally in Kafka 0.9 broker's can be auto assigned broker ids. The cookbook supports this feature. Make sure to keep the broker ids for existing nodes otherwise they may drop their data.

How to specify where to download kafka from and which version to install

This cookbook supports Kafka version 0.8.1.1 and above. The default attributes currently will install version 0.9.0.0 from 'https://archive.apache.org/dist/kafka'. This is configured using a number of different attributes in order to make it easier for you.

NOTE: If you are upgrading from 0.8.X to 0.9.X there are some additional steps to handle a rolling upgrade.

There are basically two ways to configure these settings. The first way is via 3 different attributes,

With these 3 attributes we build the full url of the form #{node["kafka"]["download_url"]}/#{node["kafka"]["version"]}/kafka_#{node["kafka"]["scala_version"]}-#{node["kafka"]["version"]}.tgz.

This makes it easy to specify just a single change while still maintaining the rest of the URL.

The other option is to just provide the full URL itself,

Configuring java for the server/broker

Currently the cookbook defaults to use the same java settings that Linkedin recommends.

Kafka uses different environment variables to configure the java settings for the server/broker,

You can customize these environment variables (as well as any environment variable for the kafka user) using the attribute,

Enabling Kerberos authentication

The cookbook supports enabling Kerberos authentication for the broker by setting node["kafka"]["kerberos"]["enable"] to true.

When enabled, two additional attributes are required,

The principal creation and keytab deployment are prerequisites not handled by this cookbook.

ZooKeeper client authentication can additionally be enabled by setting node["kafka"]["kerberos"]["enable_zk"] to true.

Custom Krb5LoginModule options can be set using the node["kafka"]["kerberos"]["krb5_properties"] attribute hash for Kafka, or node["kafka"]["kerberos"]["zk_krb5_properties"] for ZooKeeper (see attributes file for defaults).

The cookbook supports setting up both Kafka brokers and KafkaOffsetMonitor for kerberos.

Note that enabling Kerberos for a Kafka broker does not automatically set any configuration into server.properties. The following properties should be evaluated for relevance and configured separately as needed.

Dynamically Assigned Broker IDs

In Kafka 0.9 or higher a broker ID can be dynamically assigned using zookeeper. Kafka
likes to use these IDs in its log messages so its helpful to have something to translate. Previously the broker ids were provided as Chef attributes either setting it manually node['kafka']['server.properties']['broker.id'] or using the node['kafka']['brokers'] property which would set the broker id property.

We've added in logic to fetch the broker id from the meta file if the broker id is not provided by either of those methods so its possible to translate broker ids to host names using Chef. The broker id will be available in the node['kafka']['broker_id'] attribute.

Consumer Offset Monitor

The kafka::offset_monitor recipe will install the Kafka Consumer Offset Monitor application, which provides a web UI for monitoring various aspects of your Kafka cluster, including consumer processing lag.

This recipe shares several attributes with the default recipe:

The offset monitor application is installed to node["kafka"]["offset_monitor"]["install_dir"] (defaults to node["kafka]["base_dir"]/KafkaOffsetMonitor). The application download URL is controlled by the node["kafka"]["offset_monitor"]["url"] attribute.

The offset monitor maintains an SQLite database comparing the latest Kafka broker offset for each topic partition to the latest offset persisted in Zookeeper for each consumer group. The database file (node["kafka"]["offset_monitor"]["db_name"].db) is written to the kafka user's home directory. The monitoring refresh interval and retention period are configurable by the attributes node["kafka"]["offset_monitor"]["refresh"] and node["kafka"]["offset_monitor"]["retain"] using scala.concurrent.duration.Duration syntax (for example "60.seconds" or "30.days").

The offset monitor web application listens on port 8080 by default. The port is configurable by setting the node["kafka"]["offset_monitor"]["port"] attribute in the event that a conflicting service is already using port 8080.

This recipe is not included by the default recipe. It can be added to any or all of the Kafka broker nodes, or a separate node or VM. Each instance of the offset monitor will collect an identical complete data set for the entire Kafka cluster regardless of where it is installed, other than minor variances due to refresh interval asynchronicities.

This recipe creates a service which can be used to start/stop/restart the offset monitor java process,

service kafka-offset-monitor [start|stop|restart|status]

Log files are written to kafka-offset-monitor.log in node["kafka"]["log_dir"] (defaults to /var/log/kafka).

Attributes

Testing

We have provided some simple integration tests for testing the cookbook.

How to run tests

To run the tests for this cookbook you must install ChefDK.

The unit tests are written with rspec and chefspec. They can be run with rspec.

The lint testing uses Foodcritic and can be run with foodcritic . -f any.

The integration tests are written with test-kitchen and serverspec. They can be run with kitchen test.

Contributing

This project is licensed under the Apache License, Version 2.0.

When contributing to the project please add your name to the CONTRIBUTORS.txt file. Adding your name to the CONTRIBUTORS.txt file signifies agreement to all rights and reservations provided by the License.

To contribute to the project execute a pull request through github. The pull request will be reviewed by the community and merged by the project committers. Please attempt to conform to the test, code conventions, and code formatting standards if any are specified by the project before submitting a pull request.

Releases

Releases should happen regularly after most changes. Feel free to request a release by logging an issue.

Committers

For information related to being a committer check here.

LICENSE

Copyright 2013 Cerner Innovation, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.