Katran

Katran is a C++ library and BPF program intended for use in building a high-performance layer 4 load balancing forwarding plane. It is currently being evaluated by the Traffic Team as a replacement for PyBal in a project code named Liberica.
== Notes ==
=== Vagrant lab environment ===
An Example Vagrantfile for a lab environment could be:
Vagrant.configure("2") do |config|
 config.vm.define "client" do |client|
 client.vm.box = "debian/bookworm64"
 client.vm.hostname = "client"
 client.vm.provision "shell", inline: <<-SHELL
 apt update
 apt install -y vim curl tcpdump
 SHELL
 end
 
 config.vm.define "backend1" do |backend1|
 backend1.vm.box = "debian/bookworm64"
 backend1.vm.hostname = "backend1"
 backend1.vm.provision "shell", inline: <<-SHELL
 apt-get update
 apt-get install -y nginx
 SHELL
 end
 config.vm.define "lb" do |lb|
 lb.vm.box = "debian/bookworm64"
 lb.vm.hostname = "lb"
 # If you want to experiment with katran multiple cpu mapping uncomment the followin lines
 # This is supposed to work with the libvirt vagrant provider
 #lb.vm.network :private_network,
 # :type => "dhcp",
 # :libvirt__driver_queues => 4
 lb.vm.provider "libvirt" do |v|
 v.memory = 4096
 v.cpus = 4
 end
 lb.vm.provision "shell", inline: <<-SHELL
 apt-get update
 apt-get install -y build-essential git pkg-config vim
 SHELL
 end
end
== Compile Katran lib (gRPC example) ==
* Install dependencies
apt update
apt install build-essential git pkg-config libiberty-dev cmake
* Compile GRPC libs
cd /tmp
# GRPC server requires gRPC and it isn't currently handled by build.sh
git clone --recurse-submodules https://github.com/grpc/grpc.git --depth=1 --branch=v1.49.1
cd grpc
cmake .
make && make install
=== Compile katran libs in debian bullseye (deprecated, preferred distribution will be bookworm) ===
mkdir -p /katran
cd /katran
git clone --depth=1 https://github.com/facebookincubator/katran
cd katran
export CMAKE_BUILD_EXAMPLE_GRPC=1
# These steps are needed due to deprecated use of build_katran.sh
mkdir -p /grpc/_build
ln -s /usr/local/bin/grpc_cpp_plugin /grpc/_build
./build.sh install
./build.sh
=== Compile katran libs in debian bookworm ===
For Debian Bookworm a patch is needed to use a custom repository until this PR won't be merged:
mkdir -p /katran
cd /katran
git clone --depth=1 https://github.com/facebookincubator/katran
cd katran
* In build/fbcode_builder/manifests/katran replace
 repo_url = https://github.com/facebookincubator/katran.git
with
 repo_url = https://github.com/jvgutierrez/katran.git
* Then the steps are the same as Debian Bullseye:
export CMAKE_BUILD_EXAMPLE_GRPC=1
# These steps are needed due to deprecated use of build_katran.sh
mkdir -p /grpc/_build
ln -s /usr/local/bin/grpc_cpp_plugin /grpc/_build
./build.sh install
./build.sh # pass the --num-jobs N options to specify the number of simultaneous build jobs
=== Compiling the gRPC client ===
From the official Example file:
apt install -y ethtool
apt install -y golang
apt install -y protoc-gen-go
export GO111MODULE=on
export GOPATH=/katran/katran/example_grpc/goclient
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2
cp /katran/katran/example_grpc/goclient/bin/protoc-gen-go-grpc /katran/katran/example_grpc/goclient/bin/protoc-gen-go_grpc
* Edit build_grpc_client.sh to fix /dev/null at L65 this has been fixed upstream
export PATH=$PATH:/katran/katran/example_grpc/goclient/bin
cd /katran/katran/example_grpc/
./build_grpc_client.sh
=== Compiling BPF modules ===
BPF modules are built using the script /katran/katran/build_bpf_modules_opensource.sh but it needs a tiny patch to work on Bullseye against clang-13:
index 2227aca7..fbd33a03 100755
--- a/build_bpf_modules_opensource.sh
+++ b/build_bpf_modules_opensource.sh
@@ -65,11 +65,7 @@ if [ -z "${SRC_DIR-}" ] ; then
 SRC_DIR="$(pwd)"
 fi
 
-# Use the clang version based on the one fetched in 'build_katran.sh'
-CLANG_PATH="${BUILD_DIR}/deps/clang/clang+llvm-12.0.0-x86_64-linux-gnu-ubuntu-20.04"
-if [ -f /etc/redhat-release ]; then
- CLANG_PATH=/usr
-fi
+CLANG_PATH=/usr
 
 rm -rf "${BUILD_DIR}/deps/bpfprog"
 mkdir -p "${BUILD_DIR}/deps/bpfprog/include"
@@ -81,5 +77,5 @@ cp -r "${SRC_DIR}/katran/decap/bpf" "${BUILD_DIR}/deps/bpfprog/"
 cp "${SRC_DIR}"/katran/lib/linux_includes/* "${BUILD_DIR}/deps/bpfprog/include/"
 cd "${BUILD_DIR}/deps/bpfprog" && LD_LIBRARY_PATH="${CLANG_PATH}/lib" make \
 EXTRA_CFLAGS="${DEFINES}" \
- LLC="${CLANG_PATH}/bin/llc" CLANG="${CLANG_PATH}/bin/clang"
+ LLC="${CLANG_PATH}/bin/llc-13" CLANG="${CLANG_PATH}/bin/clang-13"
 echo "BPF BUILD COMPLETED"
Then we are ready to compile
apt install clang-13
./build_bpf_modules_opensource.sh
== Cleanup ==
If a cleanup is necessary to repeat some steps/restart from a pristine situation:
rm -fr /katran/katran/_build
rm -fr /tmp/xdproot*
rm -fr /tmp/fbcode_builder*
rm -fr /grpc/
rm -fr /tmp/grpc # optional if you want to recompile grpc too
== DOCS & stuff ==
* https://github.com/facebookincubator/katran
* https://github.com/facebookincubator/katran/issues/188 - Issue for missing dependency when building gRPC example
* https://github.com/facebookincubator/katran/pull/193 - PR to compile on Debian Bookworm
* https://engineering.fb.com/2018/05/22/open-source/open-sourcing-katran-a-scalable-network-load-balancer/
* https://news.ycombinator.com/item?id=17199921 - The HN discussion
== TODO ==
Category:SRE Traffic