From 7e1a43d1660213bf75a18b1288baddea5d776a47 Mon Sep 17 00:00:00 2001 From: Ivy Gooch Date: Mon, 3 Feb 2025 18:00:01 -0800 Subject: [PATCH] User and developer documentation for Helm json schema validation --- install/helm/agones/README.md | 52 ++++++++++++++++++- .../docs/Installation/Install Agones/helm.md | 8 +-- .../content/en/docs/Installation/upgrading.md | 7 +-- 3 files changed, 59 insertions(+), 8 deletions(-) diff --git a/install/helm/agones/README.md b/install/helm/agones/README.md index ecaa85e312..502494c985 100644 --- a/install/helm/agones/README.md +++ b/install/helm/agones/README.md @@ -36,7 +36,10 @@ Agones [extends the Kubernetes API with CustomResourceDefinitions](https://kuber 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. +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). @@ -60,7 +63,7 @@ const ( // Foos enum values for testing CRD defaulting type Foos string -// Bars tracks the initial player capacity +// Bars tracks the initial bar capacity type Bars struct { BarCapacity int64 `json:"barCapacity,omitempty"` } @@ -69,3 +72,48 @@ 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). + +### Updating the Helm Validation Schema + +Any changes to the [Helm template](https://helm.sh/docs/topics/charts/#template-files) values which +are denoted as `{{ .Values... }}` should also have a corresponding update the +[values.schema.json](values.schema.json) file. The `values.schema.json` validates value field type, +and whether or not the value or its subvalues are required. More information on how the schema +validation works in Helm is in the +[Helm chart](https://helm.sh/docs/topics/charts/#schema-files) documentation. + +For example, adding the [sample values](#adding-a-new-field-to-a-crd) `foo` and `bar` to a template +such that the template uses the value from the [values.yaml](values.yaml) file like +`foo: {{ .Values.gameservers.foo }}` the additions to the json schema would look like: + +```json + // ... + "gameservers": { + "type": "object", + "properties": { + // ... + "foo": { + "type": "string", + "enum": [ + "foo1", + "foo2", + "foo3" + ] + }, + "bar": { + "type": "object", + "properties": { + "barCapacity": { + "type": "integer", + "minimum": 0, + "maximum": 99 + }, + } + }, + "required": [ + // ... + "foo" + ] + }, + // ... +``` diff --git a/site/content/en/docs/Installation/Install Agones/helm.md b/site/content/en/docs/Installation/Install Agones/helm.md index 016a245ba5..fc5ac60afe 100644 --- a/site/content/en/docs/Installation/Install Agones/helm.md +++ b/site/content/en/docs/Installation/Install Agones/helm.md @@ -32,6 +32,10 @@ pool for Agones, see the [Agones installation instructions]({{< relref "../_inde The command deploys Agones on the Kubernetes cluster with the default configuration. The [configuration](#configuration) section lists the parameters that can be configured during installation. +publish='{{% feature publishVersion="1.47.0" %}}' +The Agones chart uses a [Helm Schema](https://helm.sh/docs/topics/charts/#schema-files) to validate fields set by the user. In the event this validation schema marks a valid edge case as invalid, please [file a bug](https://github.com/googleforgames/agones/issues), and you can still attempt a Helm install or Helm upgrade with the Helm flag `--skip-schema-validation`. +{{% /feature %}} + {{< alert title="Tip" color="info">}} List all releases using `helm list --all-namespaces` {{< /alert >}} @@ -286,6 +290,7 @@ The following tables lists the configurable parameters of the Agones chart and t | `agones.allocator.service.loadBalancerIP` | The [Load Balancer IP][loadBalancer] of the Agones allocator load balancer. Only works if the Kubernetes provider supports this option. | \`\` | | `agones.allocator.service.loadBalancerSourceRanges` | The [Load Balancer SourceRanges][loadBalancer] of the Agones allocator load balancer. Only works if the Kubernetes provider supports this option. | `[]` | | `agones.allocator.service.annotations` | [Annotations][annotations] added to the Agones allocator service | `{}` | +| `agones.allocator.service.externalTrafficPolicy` | The `externalTrafficPolicy` for the Agones allocator service | `Cluster` | | `agones.allocator.service.http.enabled` | If true the [allocator service][allocator] will respond to [REST requests][rest-requests] | `true` | | `agones.allocator.service.http.appProtocol` | The `appProtocol` to set on the Service for the http allocation port. If left blank, no value is set. | `` | | `agones.allocator.service.http.port` | The port that is exposed externally by the [allocator service][allocator] for [REST requests][rest-requests] | `443` | @@ -326,7 +331,6 @@ The following tables lists the configurable parameters of the Agones chart and t | `agones.allocator.pdb.minAvailable` | Description of the number of pods from that set that must still be available after the eviction, even in the absence of the evicted pod. Can be either an absolute number or a percentage. Mutually Exclusive with `maxUnavailable` | `1` | | `agones.allocator.pdb.maxUnavailable` | Description of the number of pods from that set that can be unavailable after the eviction. It can be either an absolute number or a percentage. Mutually Exclusive with `minAvailable` | \`\` | | `agones.allocator.topologySpreadConstraints` | Ensures better resource utilization and high availability by evenly distributing Pods in the agones-system namespace | `{}` | -| `agones.allocator.externalTrafficPolicy` | The `externalTrafficPolicy` for the Agones allocator service | `Cluster` | ### Extensions @@ -342,8 +346,6 @@ The following tables lists the configurable parameters of the Agones chart and t | `agones.extensions.healthCheck.timeoutSeconds` | Number of seconds after which the probe times out (in seconds) | `1` | | `agones.extensions.resources` | Extensions [resource requests/limit][resources] | `{}` | | `agones.extensions.generateTLS` | Set to true to generate TLS certificates or false to provide your own certificates | `true` | -| `agones.extensions.tlsCert` | Custom TLS certificate provided as a string | \`\` | -| `agones.extensions.tlsKey` | Custom TLS private key provided as a string | \`\` | | `agones.extensions.nodeSelector` | Extensions [node labels][nodeSelector] for pod assignment | `{}` | | `agones.extensions.tolerations` | Extensions [toleration][toleration] labels for pod assignment | `[]` | | `agones.extensions.affinity` | Extensions [affinity][affinity] settings for pod assignment | `{}` | diff --git a/site/content/en/docs/Installation/upgrading.md b/site/content/en/docs/Installation/upgrading.md index f2bd031999..45a61c7288 100644 --- a/site/content/en/docs/Installation/upgrading.md +++ b/site/content/en/docs/Installation/upgrading.md @@ -78,9 +78,10 @@ controller, such as the FEATURE_GATES or the Agones SDK Image. 1. Run `helm upgrade my-release agones/agones --install --atomic --wait --timeout 10m --namespace=agones-system` with all the appropriate arguments, such a `--version`, for your specific upgrade. Keep in mind that -`helm upgrade` overwrites all `--set agones.` arguments, so these must be set for each upgrade. See -[Helm Configuration]({{< relref "./Install Agones/helm.md" >}}) for a list of all available -configurable parameters. +`helm upgrade` overwrites all `--set agones.*` arguments, so these must be set for each upgrade. See +the [Helm Upgrade](https://helm.sh/docs/helm/helm_upgrade/) documentaion for information on the Helm +flags `--reset-values` or `--reuse-values`. See also the [Helm Configuration]({{< relref "./Install +Agones/helm.md" >}}) for a list of all available Agones configurable parameters. 2. Wait until the `helm upgrade` is complete. 3. To Upgrade the Fleet, or Not to Upgrade 1. *Option 1 -- Recommended* Kick off rolling update of the existing Fleet.