Skip to content

Commit

Permalink
Update development guide to current practices (googleforgames#2595)
Browse files Browse the repository at this point in the history 
* Update development guide to current practices

Updated the Agones development guide to include some missing variables,
remove some inaccurate/old documentation and also capture some best
practices and more efficient workflows, such as:

* How to only build images rather than everything
* How to use `local-includes`
* How to run individual e2e tests
* Adding extra make targets to the documentation.
  • Loading branch information
@markmandel
markmandel authored May 26, 2022
1 parent c9774d5 commit aebe6fc
Showing 1 changed file with 71 additions and 17 deletions.
88 changes: 71 additions & 17 deletions build/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@ Table of Contents
* [Running a Test Minikube cluster](#running-a-test-minikube-cluster)
* [Running a Test Kind cluster](#running-a-test-kind-cluster)
* [Running a Custom Test Environment](#running-a-custom-test-environment)
* [Next Steps](#next-steps)
* [Set Local Make Targets and Variables with `local-includes`](#set-local-make-targets-and-variables-with-local-includes)
* [Running Individual End-to-End Tests](#running-individual-end-to-end-tests)
* [Make Variable Reference](#make-variable-reference)
* [VERSION](#version)
* [REGISTRY](#registry)
Expand All @@ -29,6 +30,7 @@ Table of Contents
* [IMAGE_PULL_SECRET_FILE](#image_pull_secret_file)
* [WITH_WINDOWS](#with_windows)
* [WINDOWS_VERSIONS](#windows_versions)
* [WITH_ARM64](#with_arm64)
* [Make Target Reference](#make-target-reference)
* [Development Targets](#development-targets)
* [make build](#make-build)
Expand All @@ -38,6 +40,8 @@ Table of Contents
* [make run-sdk-conformance-tests](#make-run-sdk-conformance-tests)
* [make clean-sdk-conformance-tests](#make-clean-sdk-conformance-tests)
* [make test](#make-test)
* [make test-go](#make-test-go)
* [make lint](#make-lint)
* [make push](#make-push)
* [make install](#make-install)
* [make uninstall](#make-uninstall)
Expand Down Expand Up @@ -150,9 +154,12 @@ 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.
Assuming that the tests all pass, let's go ahead and compile the code and build the Docker images that Agones
consists of.

Let's compile and build everything, by running `make build`, this will:
To compile the Agones images, run `make build-images`. This is often all you need for Agones development.

If you want to compile and build everything (this can take a while), run `make build`, this will:

- Compile the Agones Kubernetes integration code
- Create the Docker images that we will later push
Expand All @@ -163,9 +170,6 @@ You may note that docker images, and tar archives are tagged with a concatenatio
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.

If you don't have a long time to wait, you can run `make build-images` to only build the images for running Agones
, which is often all you need for development.

Congratulations! You have now successfully tested and built Agones!

### Running a Test Google Kubernetes Engine Cluster
Expand All @@ -175,15 +179,18 @@ 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
The build tools (by default) maintain configuration for gcloud within the `build` folder, 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
we will need to authenticate our 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 Terraform
configuration found in the `build/terraform/gke` directory.

You can customize GKE cluster via environment variables or by using a [`local-includes`](./local-includes) file.
You can customize the GKE cluster by appending the following parameters to your make target, via environment
variables, or by setting them within your
[`local-includes`](#set-local-make-targets-and-variables-with-local-includes) directory.

See the table below for available customizations :

| Parameter | Description | Default |
Expand All @@ -195,8 +202,6 @@ See the table below for available customizations :
| `GCP_CLUSTER_NODEPOOL_WINDOWSINITIALNODECOUNT` | The number of Windows nodes to create in this cluster. | `0` |
| `GCP_CLUSTER_NODEPOOL_WINDOWSMACHINETYPE` | The name of a Google Compute Engine machine type for Windows nodes. | `e2-standard-4` |

If you would like to change more settings, feel free to edit the [`cluster.yml.jinja`](./gke-test-cluster/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!

Expand Down Expand Up @@ -229,9 +234,12 @@ Now that the images are pushed, to install the development version (with all ima
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](../test/e2e/)
Finally, to run all the end-to-end tests against your development version previously installed in your test cluster run
`make test-e2e` (this can also take a while). This will validate the whole application flow from start to finish. If
you're curious about how they work head to [tests/e2e](../test/e2e/).
Also [see below](#running-individual-end-to-end-tests) for how to run individual end-to-end tests during development.

When your are finished, you can run `make clean-gcloud-test-cluster` to tear down your cluster.
When you are finished, you can run `make clean-gcloud-test-cluster` to tear down your cluster.

### Running a Test Minikube cluster
This will setup a [Minikube](https://github.com/kubernetes/minikube) cluster, running on an `agones` profile,
Expand Down Expand Up @@ -339,11 +347,45 @@ Now you're ready to begin the development/test cycle:

You can combine some of the above steps into a single one, for example `make build push install` or `make build push test-e2e`.

If you need to clean-up your cluster, you can use `make uninstall` to remove Agones and `make clean-custom-test-cluster` to reset helm.
If you need to clean up your cluster, you can use `make uninstall` to remove Agones.

### Set Local Make Targets and Variables with `local-includes`

If you want to permanently set `Makefile` variables or add targets to your local setup, all `local-includes/*.mk`
are included into the main `Makefile`, and also ignored by the git repository.

Therefore, you can add your own `.mk` files in the [`local-includes`](./local-includes) directory without affecting
the shared git repository.

For examaple, if I only worked with Linux images for Agones, I could permanently turn off Windows and Arm64 images,
by writing a `images.mk` within that folder, with the following contents:

```makefile
# Just Linux
WITH_WINDOWS=0
WITH_ARM64=0
```

### Running Individual End-to-End Tests

When you are working on an individual feature of Agones, it doesn't make sense to run the entire end-to-end suite of
tests (and it can take a really long time!).

The end-to-end tests within the [`tests/e2e`](../test/e2e) folder are plain
[Go Tests](https://go.dev/doc/tutorial/add-a-test) that will use your local `~/.kube` configuration to connect and
run against the currently active local cluster.

This means you can run individual e2e tests from within your IDE or as a `go` command.

For example:

### Next Steps
```shell
go test -race -run ^TestCreateConnect$
```

Have a look in the [examples](../examples) folder to see examples of running Game Servers on Agones.
#### Troubleshooting
If you run into cluster connection issues, this can usually be resolved by running any kind of authenticated `kubectl`
command from within `make shell` or locally, to refresh your authentication token.

## Make Variable Reference

Expand Down Expand Up @@ -386,6 +428,12 @@ To disable, use `make WITH_WINDOWS=0 build-images`.
List of Windows Server versions to build for. Defaults to `ltsc2019` for Windows Server 2019.
See https://hub.docker.com/_/microsoft-windows-servercore for all available Windows versions.

### WITH_ARM64
Build ARM64 container images for Agones

This option is enabled by default via implicit `make WITH_ARM64=1 build-images`.
To disable, use `make WITH_ARM64=0 build-images`.

## Make Target Reference

All targets will create the build image if it is not present.
Expand Down Expand Up @@ -425,7 +473,13 @@ Run SDK server (sidecar) in test mode (which would record all GRPC requests) ver
Clean leftover binary and package files after running SDK conformance tests.

#### `make test`
Run the linter and tests
Run the go tests, the sdk tests, the website tests and yaml tests.

#### `make test-go`
Run only the golang tests

#### `make lint`
Lint the Go code

#### `make build-examples`
Run `make build` for all `examples` subdirectories
Expand Down

0 comments on commit aebe6fc

Please sign in to comment.