Skip to content

Commit

Permalink
User and developer documentation for Helm json schema validation
Browse files Browse the repository at this point in the history
  • Loading branch information
@igooch
igooch committed Feb 4, 2025
1 parent 04eaa69 commit 7e1a43d
Show file tree
Hide file tree
Showing 3 changed files with 59 additions and 8 deletions.
52 changes: 50 additions & 2 deletions install/helm/agones/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand All @@ -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"`
}
Expand All @@ -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"
]
},
// ...
```
8 changes: 5 additions & 3 deletions site/content/en/docs/Installation/Install Agones/helm.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 >}}
Expand Down Expand Up @@ -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` |
Expand Down Expand Up @@ -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
Expand All @@ -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 | `{}` |
Expand Down
7 changes: 4 additions & 3 deletions site/content/en/docs/Installation/upgrading.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit 7e1a43d

Please sign in to comment.