Skip to main content

【2】Pingora Getting Started: Command Line Options, Configuration, and Graceful Service Upgrade

Preface​

Continuing from the previous article: 【1】Pingora Getting Started: Load Balancing and Health Checks

If you haven't read the previous article, I recommend checking it out first.

Similarly, this blog's content comes from: quick_start

Command Line Options​

The Pingora Server provides many built-in features that we can use with just a single line change:

fn main() {
    let mut my_server = Server::new(Some(Opt::parse_args())).unwrap();
    ...
}

After making this change, Pingora will consume command line arguments passed to the load balancer. We can run:

cargo run -- -h

We should see a help menu listing the arguments we can now use. In the following sections, we'll leverage these arguments to do more with the load balancer.

Running in Background​

Use the -d or --daemon argument to run the program in the background.

cargo run -- -d

To stop the service, send it a SIGTERM signal for graceful shutdown. In this case, the service will stop accepting new requests but will try to complete all ongoing requests before exiting.

pkill -SIGTERM load_balancer

(SIGTERM is the default signal for pkill).

Configuration​

A Pingora configuration file helps define how to run the service. Below is an example configuration file that defines how many threads the service can have, the location of the pid file, error log file, and upgrade coordination socket (which we'll explain later).

Copy the content below and place it in a file named conf.yaml in your project directory.

---
version: 1
threads: 2
pid_file: /tmp/load_balancer.pid
error_log: /tmp/load_balancer_err.log
upgrade_sock: /tmp/load_balancer.sock

To use this conf file:

RUST_LOG=INFO cargo run -- -c conf.yaml -d

RUST_LOG=INFO is here so the service populates the error log.

Now you can find the service's pid:

cat /tmp/load_balancer.pid

Graceful Service Upgrade (Linux only)​

Suppose we changed the load balancer code and recompiled the binary. Now we want to upgrade the background-running service to this updated version.

If we simply stop the old service and start the new one, some requests arriving in between might be lost. Fortunately, Pingora provides a graceful way to upgrade the service.

The approach is to first send a SIGQUIT signal to the running server, then start the new server with the -u \ --upgrade argument.

pkill -SIGQUIT load_balancer && \
RUST_LOG=INFO cargo run -- -c conf.yaml -d -u

During this process, the running old server will wait and hand over its listening sockets to the new server. Then the old server continues running until all ongoing requests are completed.

From the client's perspective, the service is always running because the listening sockets are never closed.