From c26d5f61a0686b4e1a655fc0420555242cf89757 Mon Sep 17 00:00:00 2001
From: igooch <igooch@google.com>
Date: Tue, 8 Oct 2024 13:26:48 -0700
Subject: [PATCH] Adds instructions for adding and removing field from a CRD
 (#3913)

* Adds instructions for adding and removing field from a CRD

* Adds a link from the contribution ReadMe to the CRD ReadMe

---------
---
 README.md                     |  2 +-
 install/helm/agones/README.md | 66 +++++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 53903251a0..21bd25fb84 100644
--- a/README.md
+++ b/README.md
@@ -51,7 +51,7 @@ the [Project Security Policy](.github/SECURITY.md)
 
 Please read the [contributing](CONTRIBUTING.md) guide for directions on submitting Pull Requests to Agones, and community membership governance.
 
-See the [Developing, Testing and Building Agones](build/README.md) documentation for developing, testing and building Agones from source.
+See the [Developing, Testing and Building Agones](build/README.md) documentation for developing, testing and building Agones from source. For adding a new field to one of the Custom Resource Definitions refer to [Development Work on Agones Custom Resource Definitions (CRDs)](install/helm/agones/README.md).
 
 For Agones client SDK development refer to [Developing, Testing, and Building Agones Client SDKs](sdks/README.md).
 
diff --git a/install/helm/agones/README.md b/install/helm/agones/README.md
index b9ca7ad2ce..ecaa85e312 100644
--- a/install/helm/agones/README.md
+++ b/install/helm/agones/README.md
@@ -3,3 +3,69 @@
 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.
+
+## 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.
+
+### 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.
+>
+> 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
+```
+
+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.
+
+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 {
+...
+	Foo     apis.Foos    `json:"foo"`
+	Bar     *apis.Bars   `json:"bar,omitempty"`
+...
+}
+
+const (
+	// Foo1 enum value for testing CRD defaulting
+	Foo1 Foos = "foo1"
+	// Foo2 enum value for testing CRD defaulting
+	Foo2 Foos = "foo2"
+	// Foo3 enum value for testing CRD defaulting
+	Foo3 Foos = "foo3"
+)
+
+// Foos enum values for testing CRD defaulting
+type Foos string
+
+// Bars tracks the initial player capacity
+type Bars struct {
+	BarCapacity int64 `json:"barCapacity,omitempty"`
+}
+```
+
+### 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).