Building and Deploying Gloo Edge from Source
You can build and deploy Gloo Edge Open Source from the source code.
Before you begin
- Follow the setup guide to clone the Gloo Edge repository and install the project dependencies.
- In your terminal, navigate to the Gloo Edge project.
- Continue with this guide to learn how you can build Gloo Edge from the top-level Makefile.
Set up build dependencies and code generation
From the Gloo Edge project directory, run:
make -B install-go-tools generated-code
install-go-tools target installs the dependencies to build Gloo Edge in
generated-code target does multiple things:
It generates the Go source code from the
.protofiles in the
apidirectories. For example,
projects/gloo/apiwill be generated in
It generates the custom resource definitions (CRDs) so that Gloo Edge can interact with Kubernetes. These CRDs can be found in
solo-kitresources, event loops, emitters, snapshots, and resource clients. These tools are denoted by
.sk.go, and are built using
Build Gloo Edge and Docker Images
The Gloo Edge project has several products. The code for
gloo itself can be found in
projects/gloo. Each product has its own set of build targets.
Gloo Edge binary
To compile the
gloo binary to the
_output/projects/gloo/ directory, run:
make -B gloo
To build the Docker image, run the following command. Review the following table to understand the command options.
VERSION=0.0.1 make gloo-docker -B
|An optional version number for the Docker image tag, such as
0.0.1. The format must be valid semantic versioning.
|The image registry for the image, such as the local host. This value is required on
|The name for the Docker image.
Successfully tagged quay.io/solo-io/gloo:0.0.1
Deploy Gloo Edge
You can choose from several Gloo Edge installation options. This guide assumes you deploy Gloo Edge into a Kubernetes cluster that runs locally in kind.
gloointo the cluster, if not already present.
glooctl install gateway
- Make the image accessible to the kind cluster.
- Update the kind cluster to use the new image as the template. Note that the image tag varies depending on your machine and the image registry and tag version that you previously used.
- Verify that Kubernetes removes the old pod and spins up a new pod.
Tip: You might find it easier to observe the update in real time by using a live monitoring tool like k9s.
$ kubectl -n gloo-system get pods NAME READY STATUS RESTARTS AGE discovery-77d7cd499d-vg2rl 1/1 Running 0 82s gateway-proxy-5b88d8995-hzt27 1/1 Running 0 82s gloo-6578f95696-4fdth 1/1 Running 0 82s gloo-bdd7ddb9d-l977c 0/1 Running 0 9s
After a few seconds, the old pod is deleted:
$ kubectl -n gloo-system get pods NAME READY STATUS RESTARTS AGE discovery-77d7cd499d-vg2rl 1/1 Running 0 89s gateway-proxy-5b88d8995-hzt27 1/1 Running 0 89s gloo-bdd7ddb9d-l977c 1/1 Running 0 16s
Make and debug changes
Now that you can build and deploy your own builds, you can start editing Gloo Edge itself. An in-depth discussion on making code changes is outside the scope of this guide. However, a brief overview of Gloo’s software architecture will make things easier to understand.
Gloo Edge is primarily composed of plugins. You can find the code for these plugins in
projects/gloo/pkg/plugins. Gloo Edge has a lot of them! Generally speaking, these plugins take Gloo Edge configuration as input, and translate Envoy configuration as output. You can test any changes you make to plugins by following two main steps:
- Unit tests, including dynamic and static breakpoints
- Deploying the code
The fastest way to test and debug changes is by using the unit tests in these directories. The unit tests are fast to recompile and re-execute, and integrate smoothly with the debugger of your choice. You can find the unit tests for a plugin in its directory.
- Navigate to the directory of a plugin, such as cross-site request forgery (CSRF).
- Run the plugin unit tests. You might use
Dynamic breakpoints can be added via gdb without having to rebuild the unit tests.
- List the available source files. The
plugin.goargument is optional but helpful to filter down all the source files available.
info sources plugin.go
- Specify the breakpoint by copying the full path of the filename, followed by the line on which to place it. For example:
Breakpoints can be added statically by editing the source code and adding
runtime.Breakpoint() at the desired point in the code. Then rebuild and re-run in
gdb breaks when it reaches that line. Then from that line, you can go up the stack to inspect variables.
Note that adding
runtime.Breakpoint() in the code will likely cause the Go runtime to abort, because Go does not know how to handle the break signal. Therefore, you can only run the binary in
gbd, not Go or
Testing in deployment
Testing in deployment can take time to set up and run. Make sure that you get the unit tests updated and passing before deploying.
- Rebuild the Docker image.
- Update the cluster.
- Check any output to stdout by viewing the logs.
kubectl -n gloo-system logs deployments/gloo