Cslb is a client-side load-balancer for Go HTTP/HTTPS applications. Cslb is an alternative to
server-side load-balancers which add deployment and diagnostic complexity, cost, throughput
constraints and which also create an additional point of possible failure. Cslb puts load-balancer
intelligence into your Go clients so you can simplify your deployment and potentially eliminate
server-side load-balancers.
In many cases the only action needed to take advantage of cslb is to import the package and add an
SRV entry to your DNS. At that point, on behalf of your application, cslb automatically deals with
failed servers and spreads load across serving targets according to your load-distribution rules. In
addition, once you have cslb in place you can also run a "canary" alerting service which can
notify you when clients are failing to reach their correct services.
The primary goal of cslb is to make client-side load-balancing a no-brainer for your Go application.
Cslb is a standard Go package thus if your program is go-module aware (which is to say
you've run "go mod init") then cslb is pulled in when you run "go mod tidy" or you can
specifically pull it in with:
$ go get -u github.com/markdingo/cslbAt this stage cslb has no package dependencies beyond the standard packages shipped with the Go
compiler. Cslb requires Go 1.12.x or greater.
To take advantage of cslb a program simply imports the package at which point cslb automatically
starts performing client-side load-balancing by over-riding the DialContext of the
http.DefaultTransport. If the program uses its own http.Transport then its DialContext needs to
be similarly replaced. Here is the before and after code which shows the application changes needed:
import (
"net/http"
)
func main() {
resp, err := http.Get("http://example.net/resource")
... import (
"net/http"
_ "github.com/markdingo/cslb"
)
func main() {
resp, err := http.Get("http://example.net/resource")
...and that's it!
One line of import code and no changes to application code fetching HTTP resources. The package
documentation describes what to do if your applications use its own http.Transport. Essentially
you have to enable cslb for that Transport.
Cslb processing is activated by the presence of SRV Resource Records (RRs) matching the requested
hostname using the prescribed RFC2782 formulation. If no
SRV RR exists, cslb is completely transparent and passive. Cslb caches the presence or otherwise of
SRVs to minimize its impact in a non-SRV environment. This means you can deploy with cslb at any
time and activate the functionality at a later stage.
Cslb intercepts DialContext Requests made by net/http and makes internal DialContext Requests
to the SRV targets. The first successful connection is returned to the calling application. In
effect this provides a fail-over capability.
Cslb achieves load-balancing by implementing the SRV selection algorithm which provides a lot of
flexibility in terms of preferring targets by priority and distributing connections by weight within
priority. The package documentation shows how this works.
No server-side changes are required to use cslb - apart for possibly dispensing with your
server-side load-balancers! You can even use cslb-enabled applications on third-party services with
appropriate DNS finagling. It's also possible to use cslb in conjunction with an existing
server-side load-balancer deployment by placing the load-balancers targets in an SRV RR.
In addition to the passive collection of fail-over data based on DialContext results, cslb has an
optional "active mode" where a per-target health-check URL is periodically polled to determine the
health of a target. If a health-check URL fails, that target is removed from the target candidate
list for a configured time period. The health-check URL is defined by a TXT RR in the DNS. The
package documentation describes the naming convention and syntax.
Insights into the behaviour of cslb within your application are available via an optional status
page. When activated via an environment variable the web page provides statistics on intercepted
DialContext Requests, information on cached SRV and healthcheck results.
If you have any problems using cslb or suggestions on how it can do a better job, don't hesitate to
create an issue or email the
authors directly. This package can only
improve with your feedback.
Cslb is Copyright ©️ 2019,2020,2021 Mark Delany. This software is licensed under the BSD 2-Clause "Simplified" License.