Borgorg

Welcome to the Borgorg monorepo.

This repo is for the fictional organization Borgorg. It aims to model a large organization’s full technical estate using cloud native tooling in a monorepo format.

More doco coming at some point…

Working with this Repository

One of the aims of this repository is that every Kubernetes cluster can be run locally on k3d using a few simple commands. The source code for all “business” services is also maintained and built out of this repository.

The only requirement for working with this repository is Bazelisk. It will download the appropriate version of Bazel and Bazel will do its Bazel thing and download everything else.

Running Kubernetes Clusters Locally

The following series of commands creates a local container registry, builds the source code for the services defined in this repository and publishes the images to the local registry, creates the k3d Kubernetes cluster, and then applies the Kubernetes manifests to the cluster. Following these commands you should have a working local Kubernetes environment that is running all of the applications defined in the Kustomize configuration.

bazel run //kube:create_registry
bazel run //src:push_local_images
bazel run //kube:create_cluster_cust_xxx_loc_xxxxx_kapp
bazel run //kube:apply_manifests_cust_xxx_loc_xxxxx_kapp

Managing Source Code

This repository demonstrates a multi-service, multi-language setup. Services are written in either Go or Rust and are built and published as container images using Bazel.

Go

All Go source code is stored under src/go with a single src/go/go.mod file. This allows the Go code to work as normal with the Go CLI and IDEs.

Go binaries should be managed under src/go/cmd and libraries should be managed under src/go/pkg as normal. When you add a new binary, library, or dependency, get the Go code working first using the Go CLI by changing directory into src/go and running go mod tidy to sort out dependencies and then go build cmd/... to make sure everything compiles.

You then need to tell Bazel to update its understanding of all the Go depdencencies using the following Gazelle command.

bazel run //src/go:gazelle_update_repos

If you are adding a new binary or library, you’ll likely want to use Gazelle to generate the go_binary, go_library, and go_test targets using the following commands. It will generate and update existing target definitions. It should be smart enough to assign the appropriate Bazel dependencies (which were generated using the command above) to these targets.

bazel run //src/go/cmd/hello:gazelle_generate_targets
bazel run //src/go/pkg/farewell:gazelle_generate_targets

Rust

All Rust source code is stored under src/rust with a single src/rust/Cargo.toml Cargo workspace file. As with the Go code, this allows the Rust code to work well with the Cargo CLI and IDEs.

Both binary and library crates are stored under src/rust/crates in a flat structure as seems to becoming a semi-standard (see this article). Add new crates as you normally would with any Cargo workspace and follow the existing examples for defining rust_binary, rust_library, etc, targets. Be sure to add the new crate as a workspace member in src/rust/Cargo.toml.

As with the Go code, it’s generally best to get the Rust code building with Cargo first to ensure that the dependencies are in order and the src/rust/Cargo.lock file has been updated. You’ll then likely need to refresh the Cargo dependencies as below.

To refresh Cargo dependencies into src/rust/Cargo.bazel.lock (which is read by crate_universe) run the following command.

CARGO_BAZEL_REPIN=1 bazel sync --only=crate_index

The command above can also be used to drive other Cargo commands - see here.