Tooling for building and developing against Agones, with only dependencies being Make and Docker
Rather than installing all the dependencies locally, you can test and build Agones using the Docker image that is built from the Dockerfile in this directory. There is an accompanying Makefile for all the common tasks you may wish to accomplish.
- Table of Contents
- Building on Different Platforms
- GOPATH
- Testing and Building
- Make Variable Reference
- Make Target Reference
- Dependencies
- Install Make, either via
apt install makeoryum install makedepending on platform. - Install Docker for your Linux platform.
- (optional) Minikube will require VirtualBox and will need to be installed if you wish to develop on Minikube
Building and developing Agones requires you to use the Windows Subsystem for Linux(WSL), as this makes it easy to create a (relatively) cross platform development and build system.
- Install WSL
- Preferred release is Ubuntu 16.04 or greater.
- Install Docker for Windows
- Within WSL, Install Docker for Ubuntu
- Follow this guide
from "Configure WSL to Connect to Docker for Windows" forward
for integrating the Docker on WSL with the Windows Docker installation
- Note the binding of
/cto/mnt/c(or drive of your choice) - this is very important!
- Note the binding of
- Agones will need to be cloned somewhere on your
/c(or drive of your choice) path, as that is what Docker will support mounts from - All interaction with Agones must be on the
/c(or drive of your choice) path, otherwise Docker mounts will not work - Now the
makecommands can all be run from within your WSL shell - (optional) Minikube is supported via the HyperV driver - the same virtualisation platform as the Docker installation.
- Note: If you want to dev and test with Minikube, you must run WSL as Administrator, otherwise Minikube can't control HyperV.
- Install Make,
brew install make, if it's not installed already - Install Docker for Mac
- (optional) Minikube will require VirtualBox and will need to be installed if you wish to develop on Minikube
This project should be cloned to the directory $GOPATH/src/agones.dev/agones
for when you are developing locally, and require package resolution in your IDE.
If you have a working Go environment, you can also do this through:
go get -d agones.dev/agones
cd $GOPATH/src/agones.dev/agonesThis is not required if you are simply building using the make targets, and do not plan to edit the code
in an IDE.
If you are not familiar with GOPATHs, you can read How to Write Go Code.
Make sure you are in the build directory to start.
First, let's test all the code. To do this, run make test, which will execute all the unit tests for the codebase.
If you haven't run any of the build make targets before then this will also create the Docker based build image,
and then run the tests.
Building the build image may take a few minutes to download all the dependencies, so feel free to make cup of tea or coffee at this point. ☕️
The build image is only created the first time one of the make targets is executed, and will only rebuild if the build Dockerfile has changed.
Assuming that the tests all pass, let's go ahead an compile the code and build the Docker images that Agones consists of.
Let's compile and build everything, by running make build, this will:
- Compile the Agones Kubernetes integration code
- Create the Docker images that we will later push
- Build the local development tooling for all supported OS's
- Compile and archive the SDKs in various languages
You may note that docker images, and tar archives are tagged with a concatenation of the upcoming release number and short git hash for the current commit. This has also been set in the code itself, so that it can be seen in via log statements.
Congratulations! You have now successfully tested and built Agones!
This will setup a test GKE cluster on Google Cloud, with firewall rules set for each of the nodes for ports 7000-8000 to be open to UDP traffic.
First step is to create a Google Cloud Project at https://console.cloud.google.com or reuse an existing one.
The build tools (by default) maintain configuration for gcloud within the build folder, so as to keep
everything separate (see below for overwriting these config locations). Therefore, once the project has been created,
we will need to authenticate out gcloud tooling against it. To do that run make gcloud-init and fill in the
prompts as directed.
Once authenticated, to create the test cluster, run make gcloud-test-cluster, which will use the deployment template
found in the gke-test-cluster directory.
You can customize GKE cluster via environment variables or by using a local-includes file.
See the table below for available customizations :
| Parameter | Description | Default |
|---|---|---|
GCP_CLUSTER_NAME |
The name of the cluster | test-cluster |
GCP_CLUSTER_ZONE |
The name of the Google Compute Engine zone in which the cluster will resides. | us-west1-c |
GCP_CLUSTER_LEGACYABAC |
Enables or disables the ABAC authorization mechanism on a cluster. | false |
GCP_CLUSTER_NODEPOOL_INITIALNODECOUNT |
The number of nodes to create in this cluster. | 3 |
GCP_CLUSTER_NODEPOOL_MACHINETYPE |
The name of a Google Compute Engine machine type. | n1-standard-4 |
If you would like to change more settings, feel free to edit the cluster.yml.jinja file before running this command.
This will take several minutes to complete, but once done you can go to the Google Cloud Platform console and see that a cluster is up and running!
To grab the kubectl authentication details for this cluster, run make gcloud-auth-cluster, which will generate the
required Kubernetes security credentials for kubectl. This will be stored in ~/.kube by default, but can also be
overwritten by setting the KUBEPATH environment variable before running the command.
Great! Now we are setup, let's try out the development shell, and see if our kubectl is working!
Run make shell to enter the development shell. You should see a bash shell that has you as the root user.
Enter kubectl get pods and press enter. You should see that you have no resources currently, but otherwise see no errors.
Assuming that all works, let's exit the shell by typing exit and hitting enter, and look at building, pushing and
installing Agones next.
To prepare building and pushing images, let's set the REGISTRY environment variable to point to our new project.
You can choose any registry region
but for this example, we'll just use gcr.io.
In your shell, run export REGISTRY=gcr.io/<YOUR-PROJECT-ID> which will overwrite the default registry settings in our
Make targets. Then, to rebuild our images for this registry, we run make build again.
Before we can push the images, there is one more small step! So that we can run regular docker push commands
(rather than gcloud docker -- push), we have to authenticate against the registry, which will give us a short
lived key for our local docker config. To do this, run make gcloud-auth-docker, and now we have the short lived tokens.
To push our images up at this point, is simple make push and that will push up all images you just built to your
project's container registry.
Now that the images are pushed, to install the development version (with all imagePolicies set to always download),
run make install and Agones will install the image that you just built and pushed on the test cluster you
created at the beginning of this section. (if you want to see the resulting installation yaml, you can find it in build/.install.yaml)
Finally to run end-to-end tests against your development version previously installed in your test cluster run make test-e2e, this will validate the whole application flow (from start to finish). If you're curious about how they work head to tests/e2e
This will setup a Minikube cluster, running on an agones profile,
Because Minikube runs on a virtualisation layer on the host, some of the standard build and development Make targets need to be replaced by Minikube specific targets.
We recommend installing version 0.28.0 of minikube, due to issues with other versions
First, install Minikube, which may also require you to install a virtualisation solution, such as VirtualBox as well. Check the Building on Different Platforms above for details on what virtualisation solution to use.
Next we will create the Agones Minikube cluster. Run make minikube-test-cluster to create the agones profile,
and a Kubernetes cluster of the supported version under this profile.
This will also install the kubectl authentication credentials in ~/.kube, and set the
kubectl context
to agones.
Great! Now we are setup, let's try out the development shell, and see if our kubectl is working!
Run make minikube-shell to enter the development shell. You should see a bash shell that has you as the root user.
Enter kubectl get pods and press enter. You should see that you have no resources currently, but otherwise see no errors.
Assuming that all works, let's exit the shell by typing exit and hitting enter, and look at a building, pushing and
installing Agones on Minikube next.
You may remember in the first part of this walkthrough, we ran make build, which created all the images and binaries
we needed to work with Agones locally. We can push these images them straight into Minikube very easily!
Run make minikube-push which will send all of Agones's docker images from your local Docker into the Agones Minikube
instance.
Now that the images are pushed, to install the development version,
run make minikube-install and Agones will install the images that you built and pushed to the Agones Minikube instance
(if you want to see the resulting installation yaml, you can find it in build/.install.yaml).
It's worth noting that Minikube does let you reuse its Docker daemon, and build directly on Minikube, but in this case this approach is far simpler, and makes cross-platform support for the build system much easier.
If you find you also want to push your own images into Minikube,
the convenience make target make minikube-transfer-image can be run with the TAG argument specifying
the tag of the Docker image you wish to transfer into Minikube.
For example:
$ make minikube-transfer-image TAG=myimage:0.1Running end-to-end tests on minikube is done via the make minikube-test-e2e target. This target use the same make test-e2e but also setup some prerequisites for use with a minikube cluster.
Have a look in the examples folder to see examples of running Game Servers on Agones.
The version of this build. Version defaults to the short hash of the latest commit
The registry that is being used to store docker images. Defaults to gcr.io/agones-images - the release + CI registry.
The directory the kubectl configuration files are being stored for shell and kubectl targets. Defaults to ~/.kube (where your Kubernetes configs are likely to already exist)
The (gcloud) test cluster that is being worked against. Defaults to test-cluster
All targets will create the build image if it is not present.
Targets for developing with the build image
Build all the images required for Agones, as well as the SDKs
Build all the images required for Agones
Build all the sdks required for Agones
Build the cpp sdk static and dynamic libraries (linux libraries only)
Run the linter and tests
Pushes all built images up to the $(REGISTRY)
Installs the current development version of Agones into the Kubernetes cluster
Runs end-to-end tests on the previously installed version of Agones. These tests validate Agones flow from start to finish.
It uses the kube config (located by default in ~/.kube) to target a Kubernetes cluster.
See make minikube-test-e2e to run end-to-end tests on minikube.
Run a bash shell with the developer tools (go tooling, kubectl, etc) and source code in it.
Run a container with godoc (search index enabled)
Compile the gameserver controller and then build the docker image
Compile the gameserver sidecar and then build the docker image
Generate the /install/yaml/install.yaml from the Helm template
Generate the Custom Resource Definition client(s)
Generate the SDK gRPC server and client code
Targets for building the build image
Cleans the kubernetes and gcloud configurations
Deletes the local build docker image
Creates the build docker image
A set of utilities for setting up a Kubernetes Engine cluster on Google Cloud Platform, since it's an easy way to get a test cluster working with Kubernetes.
Initialise the gcloud login and project configuration, if you are working with GCP
Creates and authenticates a small, 3 node GKE cluster to work against
Pulls down authentication information for kubectl against a cluster, name can be specified through CLUSTER_NAME (defaults to 'test-cluster')
Creates a short lived access to Google Cloud container repositories, so that you are able to call
docker push directly. Useful when used in combination with make push command.
A set of utilities for setting up and running a Minikube instance, for local development.
Since Minikube runs locally, there are some targets that need to be used instead of the standard ones above.
Switches to an "agones" profile, and starts a kubernetes cluster of the right version.
Use MINIKUBE_DRIVER variable to change the VM driver (defaults virtualbox for Linux and macOS, hyperv for windows) if you so desire.
Push the local Agones Docker images that have already been built
via make build or make build-images into the "agones" minikube instance.
Installs the current development version of Agones into the Kubernetes cluster.
Use this instead of make install, as it disables PullAlways on the install.yaml
Runs end-to-end tests on the previously installed version of Agones. These tests validate Agones flow from start to finish.
Connecting to Minikube requires so enhanced permissions, so use this target
instead of make shell to start an interactive shell for development on Minikube.
Convenience target for transferring images into minikube. Use TAG to specify the image to transfer into minikube
This project uses the dep as a dependency manager. You can see the list of dependencies here.