Jump to content

Katran

From Wikitech
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.
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=2248399"