Katran

From Wikitech
This documentation is a stub. Please expand it.
Tracked in Phabricator
Task T332027

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

TODO

Retrieved from "https://wikitech.wikimedia.org/w/index.php?title=Katran&oldid=2163794"