tableroll is a graceful upgrade process for network services. It allows zero-downtime upgrades (such that the listening socket never drops a connection) between multiple Go processes.
It is inspired heavily by cloudflare's tableflip library. The primary difference between 'tableflip' and 'tableroll' is that 'tableroll' does not require updates to re-use the existing executable binary nor does it enforce any process heirarchy between the old and new processes.
It is expected that the old and new processes in a tableroll upgrade will both be managed by an external service manager, such as a systemd template unit.
Instead of coordinating upgrades between a parent and child process, tableroll coordinates upgrades between a number of processes that agree on a well-known filesystem path ahead of time, and which all have access to that path.
tableroll's usage is similar to tableflip's usage.
In general, your process should do the following:
- Construct an upgrader using
tableroll.New
- Create or add all managed listeners / connections / files via
upgrader.Fds
. - Mark itself as ready to accept connections using
upgrader.Ready
- Wait for a request to exit using the
upgrader.UpgradeComplete
channel - Close all managed listeners and drain all connections (e.g. using
server.Shutdown
onhttp.Server
)
One example usage might be the following:
The following example shows a simple usage of tableroll.
package main
import (
"context"
"fmt"
"log"
"net"
"net/http"
"os"
"strconv"
"time"
"github.com/inconshreveable/log15"
"github.com/ngrok-oss/tableroll/v2"
)
func main() {
ctx := context.Background()
logger := log15.New()
if err := os.MkdirAll("/tmp/testroll", 0700); err != nil {
log.Fatalf("can't create coordination dir: %v", err)
}
tablerollID := strconv.Itoa(os.Getpid())
upg, err := tableroll.New(ctx, "/tmp/testroll", tablerollID, tableroll.WithLogger(logger))
if err != nil {
panic(err)
}
ln, err := upg.Fds.Listen(ctx, "port-8080", &net.ListenConfig{}, "tcp", "127.0.0.1:8080")
if err != nil {
log.Fatalf("can't listen: %v", err)
}
server := &http.Server{
Handler: http.HandlerFunc(func(r http.ResponseWriter, req *http.Request) {
logger.Info("got http connection")
time.Sleep(10 * time.Second)
r.Write([]byte(fmt.Sprintf("hello from %v!\n", os.Getpid())))
}),
}
go server.Serve(ln)
if err := upg.Ready(); err != nil {
panic(err)
}
<-upg.UpgradeComplete()
time.AfterFunc(30*time.Second, func() {
os.Exit(1)
})
_ = server.Shutdown(context.Background())
logger.Info("server shutdown")
}
When this program is run, it will listen on port 8080
for http connections.
If you start another copy of it, the newer copy will take over. If you have
pending http requests in-flight, they'll be handled by the old process before
it shuts down.