Skip to content

Commit

Permalink
Markdown formatting changes only
Browse files Browse the repository at this point in the history
  • Loading branch information
igooch committed Feb 4, 2025
1 parent 2e184e3 commit 3f220a2
Show file tree
Hide file tree
Showing 3 changed files with 410 additions and 364 deletions.
65 changes: 41 additions & 24 deletions install/helm/agones/README.md
Original file line number Diff line number Diff line change
@@ -1,47 +1,61 @@
# Install Agones using Helm

This chart installs the Agones application and defines deployment on a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager.
This chart installs the Agones application and defines deployment on a [Kubernetes](http://kubernetes.io)
cluster using the [Helm](https://helm.sh) package manager.

See [Install Agones using Helm](https://agones.dev/site/docs/installation/install-agones/helm/) for installation and configuration instructions.
See [Install Agones using Helm](https://agones.dev/site/docs/installation/install-agones/helm/) for
installation and configuration instructions.

## Development Work on Agones Custom Resource Definitions (CRDs)

Agones [extends the Kubernetes API with CustomResourceDefinitions](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/) for the kinds `Fleet`, `GameServerSet`, `GameServer`, `FleetAutoscaler`. (`GameServerAllocation` does not a have CRD.) Regardless of installation method, the definitions for the Agones Custom Resources are in the [agones/install/helm/agones/templates/crds](./templates/crds/) directory. The double braces `{{ }}` in the CRDs and elsewhere are [Helm chart template](https://helm.sh/docs/chart_template_guide/getting_started/) features.
Agones [extends the Kubernetes API with CustomResourceDefinitions](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)
for the kinds `Fleet`, `GameServerSet`, `GameServer`, `FleetAutoscaler`.
(`GameServerAllocation` does not a have CRD.) Regardless of installation method, the definitions for
the Agones Custom Resources are in the [agones/install/helm/agones/templates/crds](./templates/crds/)
directory. The double braces `{{ }}` in the CRDs and elsewhere are
[Helm chart template](https://helm.sh/docs/chart_template_guide/getting_started/) features.

### Adding a New Field to a CRD

> [!IMPORTANT]
>
> Any new *required* field in a CRD must be non-nullable **and** have a default. We define a field as required if the controller throws a panic or error when it encounters a `nil` value for that field. Most new fields should be `nullable: true`, and the controller should be able to handle a `nil` value without a panic or error.
> Any new _required_ field in a CRD must be non-nullable **and** have a default. We define a field
> as required if the controller throws a panic or error when it encounters a `nil` value for that
> field. Most new fields should be `nullable: true`, and the controller should be able to handle a
> `nil` value without a panic or error.
>
> This ensures that after an Agones upgrade to a version that introduces a new field, the upgraded controller does not panic or error when encountering an older custom resource that was created before the Agones upgrade.
> This ensures that after an Agones upgrade to a version that introduces a new field, the upgraded
> controller does not panic or error when encountering an older custom resource that was created
> before the Agones upgrade.
```yaml
foo:
title: Example required CRD field. Non-nullable with default.
type: string
enum:
- foo1
- foo2
- foo3
default: foo3
bar:
title: Example non-required CRD field. Nullable with optional default.
type: object
nullable: true
properties:
barCapacity:
type: integer
minimum: 0
default: 99 # Default for a nullable field is optional
foo:
title: Example required CRD field. Non-nullable with default.
type: string
enum:
- foo1
- foo2
- foo3
default: foo3
bar:
title: Example non-required CRD field. Nullable with optional default.
type: object
nullable: true
properties:
barCapacity:
type: integer
minimum: 0
default: 99 # Default for a nullable field is optional
```
Once you have added a new field to a CRD, generate the values for the `install.yaml` file by running
`~/agones/build$ make gen-install`. This ensure that the `yaml` installation methods has the same
values as the preferred Helm installation method. Note that changes to a CRD may also need changes
to the [Helm schema validation file](#updating-the-helm-validation-schema).

If the above example fields were added, for example, to the [_gameserverspecschema.yaml](./templates/crds/_gameserverspecschema.yaml), then the fields should also be added to the `GameServerSpec` struct in [gameserver.go](../../../pkg/apis/agones/v1/gameserver.go).
If the above example fields were added, for example, to the
[\_gameserverspecschema.yaml](./templates/crds/_gameserverspecschema.yaml), then the fields should
also be added to the `GameServerSpec` struct in [gameserver.go](../../../pkg/apis/agones/v1/gameserver.go).

```go
type GameServerSpec struct {
Expand Down Expand Up @@ -71,7 +85,10 @@ type Bars struct {

### Removing an Existing Field From a CRD

Keep in mind that there can only be one definition of a `kind` in the `apiVersion: agones.dev/v1` in a Kubernetes cluster. This means that change to a CRD during an upgrade, downgrade, or Feature Gate change of Agones is immediately applied to custom resources in the cluster. Breaking changes to fields may be covered under our [SDK deprecation policy](../../../site/content/en/docs/Installation/upgrading.md).
Keep in mind that there can only be one definition of a `kind` in the `apiVersion: agones.dev/v1`
in a Kubernetes cluster. This means that change to a CRD during an upgrade, downgrade, or Feature
Gate change of Agones is immediately applied to custom resources in the cluster. Breaking changes to
fields may be covered under our [SDK deprecation policy](../../../site/content/en/docs/Installation/upgrading.md).

### Updating the Helm Validation Schema

Expand Down
Loading

0 comments on commit 3f220a2

Please sign in to comment.