diff --git a/build/Makefile b/build/Makefile index 4888dacc14..5da4e6a17c 100644 --- a/build/Makefile +++ b/build/Makefile @@ -298,7 +298,7 @@ push-release-chart: $(ensure-build-image) CHART_DIR=install/.helm-$(RELEASE_VERSION)/agones $(MAKE) push-chart # Run all tests -test: $(ensure-build-image) test-go test-sdks test-install-yaml site-test +test: $(ensure-build-image) test-go test-sdks test-install-yaml site-test helm-lint # Run go tests test-go: $(ensure-build-image) @@ -875,3 +875,6 @@ install-release: $(ensure-build-image) $(DOCKER_RUN_ARGS) \ $(build_tag) /go/src/agones.dev/agones/build/install-release.sh +# Validates the Helm values.yaml file against the values.schema.json file. +helm-lint: + $(DOCKER_RUN) bash -c 'cd $(mount_path)/install/helm/agones && helm lint .' diff --git a/install/helm/agones/README.md b/install/helm/agones/README.md index ecaa85e312..c86b5720c2 100644 --- a/install/helm/agones/README.md +++ b/install/helm/agones/README.md @@ -1,44 +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. +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 { @@ -60,7 +77,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"` } @@ -68,4 +85,52 @@ 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 + +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..9cdd2df713 100644 --- a/site/content/en/docs/Installation/Install Agones/helm.md +++ b/site/content/en/docs/Installation/Install Agones/helm.md @@ -24,13 +24,25 @@ helm install my-release --namespace agones-system --create-namespace agones/agon ``` _We recommend installing Agones in its own namespaces, such as `agones-system` as shown above. - If you want to use a different namespace, you can use the helm `--namespace` parameter to specify._ - -When running in production, Agones should be scheduled on a dedicated pool of nodes, distinct from where Game Servers are scheduled for better isolation and resiliency. By default Agones prefers to be scheduled on nodes labeled with `agones.dev/agones-system=true` and tolerates node taint `agones.dev/agones-system=true:NoExecute`. If no dedicated nodes are available, Agones will -run on regular nodes, but that's not recommended for production use. For instructions on setting up a dedicated node -pool for Agones, see the [Agones installation instructions]({{< relref "../_index.md" >}}) for your preferred environment. - -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. +If you want to use a different namespace, you can use the helm `--namespace` parameter to specify._ + +When running in production, Agones should be scheduled on a dedicated pool of nodes, distinct from +where Game Servers are scheduled for better isolation and resiliency. By default Agones prefers to +be scheduled on nodes labeled with `agones.dev/agones-system=true` and tolerates node taint +`agones.dev/agones-system=true:NoExecute`. If no dedicated nodes are available, Agones will +run on regular nodes, but that's not recommended for production use. For instructions on setting up +a dedicated node pool for Agones, see the [Agones installation instructions]({{< relref "../_index.md" >}}) +for your preferred environment. + +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` @@ -38,7 +50,8 @@ List all releases using `helm list --all-namespaces` ### Namespaces -By default Agones is configured to work with game servers deployed in the `default` namespace. If you are planning to use another namespace you can configure Agones via the parameter `gameservers.namespaces`. +By default Agones is configured to work with game servers deployed in the `default` namespace. If +you are planning to use another namespace you can configure Agones via the parameter `gameservers.namespaces`. For example to use `default` **and** `xbox` namespaces: @@ -68,7 +81,8 @@ helm uninstall my-release --namespace=agones-system ## RBAC -By default, `agones.rbacEnabled` is set to true. This enables RBAC support in Agones and must be true if RBAC is enabled in your cluster. +By default, `agones.rbacEnabled` is set to true. This enables RBAC support in Agones and must be true +if RBAC is enabled in your cluster. The chart will take care of creating the required service accounts and roles for Agones. @@ -80,197 +94,192 @@ The following tables lists the configurable parameters of the Agones chart and t ### General - - -| Parameter | Description | Default | -|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------| -| `agones.featureGates` | A URL query encoded string of Flags to enable/disable e.g. `Example=true&OtherThing=false`. Any value accepted by [strconv.ParseBool(string)](https://golang.org/pkg/strconv/#ParseBool) can be used as a boolean value | \`\` | -| `agones.rbacEnabled` | Creates RBAC resources. Must be set for any cluster configured with RBAC | `true` | -| `agones.registerWebhooks` | Registers the webhooks used for the admission controller | `true` | -| `agones.registerApiService` | Registers the apiservice(s) used for the Kubernetes API extension | `true` | -| `agones.registerServiceAccounts` | Attempts to create service accounts for the controllers | `true` | -| `agones.createPriorityClass` | Attempts to create priority classes for the controllers | `true` | -| `agones.priorityClassName` | Name of the priority classes to create | `agones-system` | -| `agones.requireDedicatedNodes` | Forces Agones system components to be scheduled on dedicated nodes, only applies to the GKE Standard without node auto-provisioning | `false` | - +| Parameter | Description | Default | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | +| `agones.featureGates` | A URL query encoded string of Flags to enable/disable e.g. `Example=true&OtherThing=false`. Any value accepted by [strconv.ParseBool(string)](https://golang.org/pkg/strconv/#ParseBool) can be used as a boolean value | \`\` | +| `agones.rbacEnabled` | Creates RBAC resources. Must be set for any cluster configured with RBAC | `true` | +| `agones.registerWebhooks` | Registers the webhooks used for the admission controller | `true` | +| `agones.registerApiService` | Registers the apiservice(s) used for the Kubernetes API extension | `true` | +| `agones.registerServiceAccounts` | Attempts to create service accounts for the controllers | `true` | +| `agones.createPriorityClass` | Attempts to create priority classes for the controllers | `true` | +| `agones.priorityClassName` | Name of the priority classes to create | `agones-system` | +| `agones.requireDedicatedNodes` | Forces Agones system components to be scheduled on dedicated nodes, only applies to the GKE Standard without node auto-provisioning | `false` | ### Custom Resource Definitions - -| Parameter | Description | Default | -|----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| -| `agones.crds.install` | Install the CRDs with this chart. Useful to disable if you want to subchart (since crd-install hook is broken), so you can copy the CRDs into your own chart. | `true` | -| `agones.crds.cleanupOnDelete` | Run the pre-delete hook to delete all GameServers and their backing Pods when deleting the helm chart, so that all CRDs can be removed on chart deletion | `true` | -| `agones.crds.cleanupJobTTL` | The number of seconds for Kubernetes to delete the associated Job and Pods of the pre-delete hook after it completes, regardless if the Job is successful or not. Set to `0` to disable cleaning up the Job or the associated Pods. | `60` | +| Parameter | Description | Default | +| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `agones.crds.install` | Install the CRDs with this chart. Useful to disable if you want to subchart (since crd-install hook is broken), so you can copy the CRDs into your own chart. | `true` | +| `agones.crds.cleanupOnDelete` | Run the pre-delete hook to delete all GameServers and their backing Pods when deleting the helm chart, so that all CRDs can be removed on chart deletion | `true` | +| `agones.crds.cleanupJobTTL` | The number of seconds for Kubernetes to delete the associated Job and Pods of the pre-delete hook after it completes, regardless if the Job is successful or not. Set to `0` to disable cleaning up the Job or the associated Pods. | `60` | ### Metrics -| Parameter | Description | Default | -|----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| -| `agones.metrics.prometheusServiceDiscovery` | Adds annotations for Prometheus ServiceDiscovery (and also Strackdriver) | `true` | -| `agones.metrics.prometheusEnabled` | Enables controller metrics on port `8080` and path `/metrics` | `true` | -| `agones.metrics.stackdriverEnabled` | Enables Stackdriver exporter of controller metrics | `false` | -| `agones.metrics.stackdriverProjectID` | This overrides the default gcp project id for use with stackdriver | \`\` | -| `agones.metrics.stackdriverLabels` | A set of default labels to add to all stackdriver metrics generated in form of key value pair (`key=value,key2=value2`). By default metadata are automatically added using Kubernetes API and GCP metadata enpoint. | \`\` | -| `agones.metrics.serviceMonitor.interval` | Default scraping interval for ServiceMonitor | `30s` | +| Parameter | Description | Default | +| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `agones.metrics.prometheusServiceDiscovery` | Adds annotations for Prometheus ServiceDiscovery (and also Strackdriver) | `true` | +| `agones.metrics.prometheusEnabled` | Enables controller metrics on port `8080` and path `/metrics` | `true` | +| `agones.metrics.stackdriverEnabled` | Enables Stackdriver exporter of controller metrics | `false` | +| `agones.metrics.stackdriverProjectID` | This overrides the default gcp project id for use with stackdriver | \`\` | +| `agones.metrics.stackdriverLabels` | A set of default labels to add to all stackdriver metrics generated in form of key value pair (`key=value,key2=value2`). By default metadata are automatically added using Kubernetes API and GCP metadata enpoint. | \`\` | +| `agones.metrics.serviceMonitor.interval` | Default scraping interval for ServiceMonitor | `30s` | ### Service Accounts -| Parameter | Description | Default | -|----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| -| `agones.serviceaccount.controller.name` | Service account name for the controller | `agones-controller` | -| `agones.serviceaccount.controller.annotations` | [Annotations][annotations] added to the Agones controller service account | `{}` | -| `agones.serviceaccount.sdk.name` | Service account name for the sdk | `agones-sdk` | -| `agones.serviceaccount.sdk.annotations` | A map of namespaces to maps of [Annotations][annotations] added to the Agones SDK service account for the specified namespaces | `{}` | -| `agones.serviceaccount.allocator.name` | Service account name for the allocator | `agones-allocator` | -| `agones.serviceaccount.allocator.annotations` | [Annotations][annotations] added to the Agones allocator service account | `{}` | +| Parameter | Description | Default | +| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------- | +| `agones.serviceaccount.controller.name` | Service account name for the controller | `agones-controller` | +| `agones.serviceaccount.controller.annotations` | [Annotations][annotations] added to the Agones controller service account | `{}` | +| `agones.serviceaccount.sdk.name` | Service account name for the sdk | `agones-sdk` | +| `agones.serviceaccount.sdk.annotations` | A map of namespaces to maps of [Annotations][annotations] added to the Agones SDK service account for the specified namespaces | `{}` | +| `agones.serviceaccount.allocator.name` | Service account name for the allocator | `agones-allocator` | +| `agones.serviceaccount.allocator.annotations` | [Annotations][annotations] added to the Agones allocator service account | `{}` | ### Container Images -| Parameter | Description | Default | -|----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| -| `agones.image.registry` | Global image registry for all the Agones system images | `us-docker.pkg.dev/agones-images/release` | -| `agones.image.tag` | Global image tag for all images | `{{< release-version >}}` | -| `agones.image.controller.name` | Image name for the controller | `agones-controller` | -| `agones.image.controller.pullPolicy` | Image pull policy for the controller | `IfNotPresent` | -| `agones.image.controller.pullSecret` | Image pull secret for the controller, allocator, sdk and ping image. Should be created both in `agones-system` and `default` namespaces | \`\` | -| `agones.image.sdk.name` | Image name for the sdk | `agones-sdk` | -| `agones.image.sdk.tag` | Image tag for the sdk | value of `agones.image.tag` | -| `agones.image.sdk.cpuRequest` | The [cpu request][cpu-constraints] for sdk server container | `30m` | -| `agones.image.sdk.cpuLimit` | The [cpu limit][cpu-constraints] for the sdk server container | `0` (none) | -| `agones.image.sdk.memoryRequest` | The [memory request][memory-constraints] for sdk server container | `0` (none) | -| `agones.image.sdk.memoryLimit` | The [memory limit][memory-constraints] for the sdk server container | `0` (none) | -| `agones.image.sdk.alwaysPull` | Tells if the sdk image should always be pulled | `false` | -| `agones.image.ping.name` | Image name for the ping service | `agones-ping` | -| `agones.image.ping.tag` | Image tag for the ping service | value of `agones.image.tag` | -| `agones.image.ping.pullPolicy` | Image pull policy for the ping service | `IfNotPresent` | -| `agones.image.extensions.name` | Image name for extensions | `agones-extensions` | -| `agones.image.extensions.pullPolicy` | Image pull policy for extensions | `IfNotPresent` | - +| Parameter | Description | Default | +| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | +| `agones.image.registry` | Global image registry for all the Agones system images | `us-docker.pkg.dev/agones-images/release` | +| `agones.image.tag` | Global image tag for all images | `{{< release-version >}}` | +| `agones.image.controller.name` | Image name for the controller | `agones-controller` | +| `agones.image.controller.pullPolicy` | Image pull policy for the controller | `IfNotPresent` | +| `agones.image.controller.pullSecret` | Image pull secret for the controller, allocator, sdk and ping image. Should be created both in `agones-system` and `default` namespaces | \`\` | +| `agones.image.sdk.name` | Image name for the sdk | `agones-sdk` | +| `agones.image.sdk.tag` | Image tag for the sdk | value of `agones.image.tag` | +| `agones.image.sdk.cpuRequest` | The [cpu request][cpu-constraints] for sdk server container | `30m` | +| `agones.image.sdk.cpuLimit` | The [cpu limit][cpu-constraints] for the sdk server container | `0` (none) | +| `agones.image.sdk.memoryRequest` | The [memory request][memory-constraints] for sdk server container | `0` (none) | +| `agones.image.sdk.memoryLimit` | The [memory limit][memory-constraints] for the sdk server container | `0` (none) | +| `agones.image.sdk.alwaysPull` | Tells if the sdk image should always be pulled | `false` | +| `agones.image.ping.name` | Image name for the ping service | `agones-ping` | +| `agones.image.ping.tag` | Image tag for the ping service | value of `agones.image.tag` | +| `agones.image.ping.pullPolicy` | Image pull policy for the ping service | `IfNotPresent` | +| `agones.image.extensions.name` | Image name for extensions | `agones-extensions` | +| `agones.image.extensions.pullPolicy` | Image pull policy for extensions | `IfNotPresent` | ### Agones Controller -| Parameter | Description | Default | -|----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| -| `agones.controller.replicas` | The number of replicas to run in the `agones-controller` deployment. | `2` | -| `agones.controller.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.controller.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.controller.http.port` | Port to use for liveness probe service and metrics | `8080` | -| `agones.controller.healthCheck.initialDelaySeconds` | Initial delay before performing the first probe (in seconds) | `3` | -| `agones.controller.healthCheck.periodSeconds` | Seconds between every liveness probe (in seconds) | `3` | -| `agones.controller.healthCheck.failureThreshold` | Number of times before giving up (in seconds) | `3` | -| `agones.controller.healthCheck.timeoutSeconds` | Number of seconds after which the probe times out (in seconds) | `1` | -| `agones.controller.resources` | Controller [resource requests/limit][resources] | `{}` | -| `agones.controller.generateTLS` | Set to true to generate TLS certificates or false to provide your own certificates | `true` | -| `agones.controller.tlsCert` | Custom TLS certificate provided as a string | \`\` | -| `agones.controller.tlsKey` | Custom TLS private key provided as a string | \`\` | -| `agones.controller.nodeSelector` | Controller [node labels][nodeSelector] for pod assignment | `{}` | -| `agones.controller.tolerations` | Controller [toleration][toleration] labels for pod assignment | `[]` | -| `agones.controller.affinity` | Controller [affinity][affinity] settings for pod assignment | `{}` | -| `agones.controller.labels` | [Labels][labels] added to the Agones controller pods | `{}` | -| `agones.controller.annotations` | [Annotations][annotations] added to the Agones controller pods | `{}` | -| `agones.controller.numWorkers` | Number of workers to spin per resource type | `100` | -| `agones.controller.apiServerQPS` | Maximum sustained queries per second that controller should be making against API Server | `400` | -| `agones.controller.apiServerQPSBurst` | Maximum burst queries per second that controller should be making against API Server | `500` | -| `agones.controller.logLevel` | Agones Controller Log level. Log only entries with that severity and above | `info` | -| `agones.controller.persistentLogs` | Store Agones controller logs in a temporary volume attached to a container for debugging | `true` | -| `agones.controller.persistentLogsSizeLimitMB` | Maximum total size of all Agones container logs in MB | `10000` | -| `agones.controller.disableSecret` | **Deprecated**. Use `agones.extensions.disableSecret` instead. Disables the creation of any allocator secrets. If true, you MUST provide the `{agones.releaseName}-cert` secrets before installation. | `false` | -| `agones.controller.customCertSecretPath` | Remap cert-manager path to server.crt and server.key | `{}` | -| `agones.controller.allocationApiService.annotations` | **Deprecated**. Use `agones.extensions.allocationApiService.annotations` instead. [Annotations][annotations] added to the Agones apiregistration | `{}` | -| `agones.controller.allocationApiService.disableCaBundle` | **Deprecated**. Use `agones.extensions.allocationApiService.disableCaBundle` instead. Disable ca-bundle so it can be injected by cert-manager. | `false` | -| `agones.controller.validatingWebhook.annotations` | **Deprecated**. Use `agones.extensions.validatingWebhook.annotations` instead. [Annotations][annotations] added to the Agones validating webhook | `{}` | -| `agones.controller.validatingWebhook.disableCaBundle` | **Deprecated**. Use `agones.extensions.validatingWebhook.disableCaBundle` instead. Disable ca-bundle so it can be injected by cert-manager | `false` | -| `agones.controller.mutatingWebhook.annotations` | **Deprecated**. Use `agones.extensions.mutatingWebhook.annotations` instead. [Annotations][annotations] added to the Agones mutating webhook | `{}` | -| `agones.controller.mutatingWebhook.disableCaBundle` | **Deprecated**. Use `agones.extensions.mutatingWebhook.disableCaBundle` instead. Disable ca-bundle so it can be injected by cert-manager | `false` | -| `agones.controller.allocationBatchWaitTime` | Wait time between each allocation batch when performing allocations in controller mode | `500ms` | -| `agones.controller.topologySpreadConstraints` | Ensures better resource utilization and high availability by evenly distributing Pods in the agones-system namespace | `{}` | -| `agones.controller.maxCreationParallelism` | Maximum number of parallelizing creation calls in GSS controller | `16` | -| `agones.controller.maxGameServerCreationsPerBatch` | Maximum number of GameServer creation calls per batch | `64` | -| `agones.controller.maxDeletionParallelism` | Maximum number of parallelizing deletion calls in GSS | `64` | -| `agones.controller.maxGameServerDeletionsPerBatch` | Maximum number of GameServer deletion calls per batch | `64` | -| `agones.controller.maxPodPendingCount` | Maximum number of pending pods per game server set | `5000` | +| Parameter | Description | Default | +| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `agones.controller.replicas` | The number of replicas to run in the `agones-controller` deployment. | `2` | +| `agones.controller.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.controller.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.controller.http.port` | Port to use for liveness probe service and metrics | `8080` | +| `agones.controller.healthCheck.initialDelaySeconds` | Initial delay before performing the first probe (in seconds) | `3` | +| `agones.controller.healthCheck.periodSeconds` | Seconds between every liveness probe (in seconds) | `3` | +| `agones.controller.healthCheck.failureThreshold` | Number of times before giving up (in seconds) | `3` | +| `agones.controller.healthCheck.timeoutSeconds` | Number of seconds after which the probe times out (in seconds) | `1` | +| `agones.controller.resources` | Controller [resource requests/limit][resources] | `{}` | +| `agones.controller.generateTLS` | Set to true to generate TLS certificates or false to provide your own certificates | `true` | +| `agones.controller.tlsCert` | Custom TLS certificate provided as a string | \`\` | +| `agones.controller.tlsKey` | Custom TLS private key provided as a string | \`\` | +| `agones.controller.nodeSelector` | Controller [node labels][nodeSelector] for pod assignment | `{}` | +| `agones.controller.tolerations` | Controller [toleration][toleration] labels for pod assignment | `[]` | +| `agones.controller.affinity` | Controller [affinity][affinity] settings for pod assignment | `{}` | +| `agones.controller.labels` | [Labels][labels] added to the Agones controller pods | `{}` | +| `agones.controller.annotations` | [Annotations][annotations] added to the Agones controller pods | `{}` | +| `agones.controller.numWorkers` | Number of workers to spin per resource type | `100` | +| `agones.controller.apiServerQPS` | Maximum sustained queries per second that controller should be making against API Server | `400` | +| `agones.controller.apiServerQPSBurst` | Maximum burst queries per second that controller should be making against API Server | `500` | +| `agones.controller.logLevel` | Agones Controller Log level. Log only entries with that severity and above | `info` | +| `agones.controller.persistentLogs` | Store Agones controller logs in a temporary volume attached to a container for debugging | `true` | +| `agones.controller.persistentLogsSizeLimitMB` | Maximum total size of all Agones container logs in MB | `10000` | +| `agones.controller.disableSecret` | **Deprecated**. Use `agones.extensions.disableSecret` instead. Disables the creation of any allocator secrets. If true, you MUST provide the `{agones.releaseName}-cert` secrets before installation. | `false` | +| `agones.controller.customCertSecretPath` | Remap cert-manager path to server.crt and server.key | `{}` | +| `agones.controller.allocationApiService.annotations` | **Deprecated**. Use `agones.extensions.allocationApiService.annotations` instead. [Annotations][annotations] added to the Agones apiregistration | `{}` | +| `agones.controller.allocationApiService.disableCaBundle` | **Deprecated**. Use `agones.extensions.allocationApiService.disableCaBundle` instead. Disable ca-bundle so it can be injected by cert-manager. | `false` | +| `agones.controller.validatingWebhook.annotations` | **Deprecated**. Use `agones.extensions.validatingWebhook.annotations` instead. [Annotations][annotations] added to the Agones validating webhook | `{}` | +| `agones.controller.validatingWebhook.disableCaBundle` | **Deprecated**. Use `agones.extensions.validatingWebhook.disableCaBundle` instead. Disable ca-bundle so it can be injected by cert-manager | `false` | +| `agones.controller.mutatingWebhook.annotations` | **Deprecated**. Use `agones.extensions.mutatingWebhook.annotations` instead. [Annotations][annotations] added to the Agones mutating webhook | `{}` | +| `agones.controller.mutatingWebhook.disableCaBundle` | **Deprecated**. Use `agones.extensions.mutatingWebhook.disableCaBundle` instead. Disable ca-bundle so it can be injected by cert-manager | `false` | +| `agones.controller.allocationBatchWaitTime` | Wait time between each allocation batch when performing allocations in controller mode | `500ms` | +| `agones.controller.topologySpreadConstraints` | Ensures better resource utilization and high availability by evenly distributing Pods in the agones-system namespace | `{}` | +| `agones.controller.maxCreationParallelism` | Maximum number of parallelizing creation calls in GSS controller | `16` | +| `agones.controller.maxGameServerCreationsPerBatch` | Maximum number of GameServer creation calls per batch | `64` | +| `agones.controller.maxDeletionParallelism` | Maximum number of parallelizing deletion calls in GSS | `64` | +| `agones.controller.maxGameServerDeletionsPerBatch` | Maximum number of GameServer deletion calls per batch | `64` | +| `agones.controller.maxPodPendingCount` | Maximum number of pending pods per game server set | `5000` | ### Ping Service + {{% feature expiryVersion="1.47.0" %}} -| Parameter | Description | Default | +| Parameter | Description | Default | |----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| -| `agones.ping.install` | Whether to install the [ping service][ping] | `true` | -| `agones.ping.replicas` | The number of replicas to run in the deployment | `2` | -| `agones.ping.http.expose` | Expose the http ping service via a Service | `true` | -| `agones.ping.http.response` | The string response returned from the http service | `ok` | -| `agones.ping.http.port` | The port to expose on the service | `80` | -| `agones.ping.http.serviceType` | The [Service Type][service] of the HTTP Service | `LoadBalancer` | -| `agones.ping.http.nodePort` | Static node port to use for HTTP ping service. (Only applies when `agones.ping.http.serviceType` is `NodePort`.) | `0` | -| `agones.ping.http.loadBalancerIP` | The [Load Balancer IP][loadBalancer] of the HTTP Service load balancer. Only works if the Kubernetes provider supports this option. | \`\` | -| `agones.ping.http.loadBalancerSourceRanges` | The [Load Balancer SourceRanges][loadBalancer] of the HTTP Service load balancer. Only works if the Kubernetes provider supports this option. | `[]` | -| `agones.ping.http.annotations` | [Annotations][annotations] added to the Agones ping http service | `{}` | -| `agones.ping.udp.expose` | Expose the udp ping service via a Service | `true` | -| `agones.ping.udp.rateLimit` | Number of UDP packets the ping service handles per instance, per second, per sender | `20` | -| `agones.ping.udp.port` | The port to expose on the service | `80` | -| `agones.ping.udp.serviceType` | The [Service Type][service] of the UDP Service | `LoadBalancer` | -| `agones.ping.udp.nodePort` | Static node port to use for UDP ping service. (Only applies when `agones.ping.udp.serviceType` is `NodePort`.) | `0` | -| `agones.ping.udp.loadBalancerIP` | The [Load Balancer IP][loadBalancer] of the UDP Service load balancer. Only works if the Kubernetes provider supports this option. | \`\` | -| `agones.ping.udp.loadBalancerSourceRanges` | The [Load Balancer SourceRanges][loadBalancer] of the UDP Service load balancer. Only works if the Kubernetes provider supports this option. | `[]` | -| `agones.ping.udp.annotations` | [Annotations][annotations] added to the Agones ping udp service | `{}` | -| `agones.ping.healthCheck.initialDelaySeconds` | Initial delay before performing the first probe (in seconds) | `3` | -| `agones.ping.healthCheck.periodSeconds` | Seconds between every liveness probe (in seconds) | `3` | -| `agones.ping.healthCheck.failureThreshold` | Number of times before giving up (in seconds) | `3` | -| `agones.ping.healthCheck.timeoutSeconds` | Number of seconds after which the probe times out (in seconds) | `1` | -| `agones.ping.resources` | Ping pods [resource requests/limit][resources] | `{}` | -| `agones.ping.nodeSelector` | Ping [node labels][nodeSelector] for pod assignment | `{}` | -| `agones.ping.tolerations` | Ping [toleration][toleration] labels for pod assignment | `[]` | -| `agones.ping.affinity` | Ping [affinity][affinity] settings for pod assignment | `{}` | -| `agones.ping.annotations` | [Annotations][annotations] added to the Agones ping pods | `{}` | -| `agones.ping.updateStrategy` | The [strategy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy) to apply to the allocator deployment | `{}` | -| `agones.ping.pdb.enabled` | Set to `true` to enable the creation of a [PodDisruptionBudget](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) for the ping deployment | `false` | -| `agones.ping.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.ping.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.ping.topologySpreadConstraints` | Ensures better resource utilization and high availability by evenly distributing Pods in the agones-system namespace | `{}` | +| `agones.ping.install` | Whether to install the [ping service][ping] | `true` | +| `agones.ping.replicas` | The number of replicas to run in the deployment | `2` | +| `agones.ping.http.expose` | Expose the http ping service via a Service | `true` | +| `agones.ping.http.response` | The string response returned from the http service | `ok` | +| `agones.ping.http.port` | The port to expose on the service | `80` | +| `agones.ping.http.serviceType` | The [Service Type][service] of the HTTP Service | `LoadBalancer` | +| `agones.ping.http.nodePort` | Static node port to use for HTTP ping service. (Only applies when `agones.ping.http.serviceType` is `NodePort`.) | `0` | +| `agones.ping.http.loadBalancerIP` | The [Load Balancer IP][loadBalancer] of the HTTP Service load balancer. Only works if the Kubernetes provider supports this option. | \`\` | +| `agones.ping.http.loadBalancerSourceRanges` | The [Load Balancer SourceRanges][loadBalancer] of the HTTP Service load balancer. Only works if the Kubernetes provider supports this option. | `[]` | +| `agones.ping.http.annotations` | [Annotations][annotations] added to the Agones ping http service | `{}` | +| `agones.ping.udp.expose` | Expose the udp ping service via a Service | `true` | +| `agones.ping.udp.rateLimit` | Number of UDP packets the ping service handles per instance, per second, per sender | `20` | +| `agones.ping.udp.port` | The port to expose on the service | `80` | +| `agones.ping.udp.serviceType` | The [Service Type][service] of the UDP Service | `LoadBalancer` | +| `agones.ping.udp.nodePort` | Static node port to use for UDP ping service. (Only applies when `agones.ping.udp.serviceType` is `NodePort`.) | `0` | +| `agones.ping.udp.loadBalancerIP` | The [Load Balancer IP][loadBalancer] of the UDP Service load balancer. Only works if the Kubernetes provider supports this option. | \`\` | +| `agones.ping.udp.loadBalancerSourceRanges` | The [Load Balancer SourceRanges][loadBalancer] of the UDP Service load balancer. Only works if the Kubernetes provider supports this option. | `[]` | +| `agones.ping.udp.annotations` | [Annotations][annotations] added to the Agones ping udp service | `{}` | +| `agones.ping.healthCheck.initialDelaySeconds` | Initial delay before performing the first probe (in seconds) | `3` | +| `agones.ping.healthCheck.periodSeconds` | Seconds between every liveness probe (in seconds) | `3` | +| `agones.ping.healthCheck.failureThreshold` | Number of times before giving up (in seconds) | `3` | +| `agones.ping.healthCheck.timeoutSeconds` | Number of seconds after which the probe times out (in seconds) | `1` | +| `agones.ping.resources` | Ping pods [resource requests/limit][resources] | `{}` | +| `agones.ping.nodeSelector` | Ping [node labels][nodeSelector] for pod assignment | `{}` | +| `agones.ping.tolerations` | Ping [toleration][toleration] labels for pod assignment | `[]` | +| `agones.ping.affinity` | Ping [affinity][affinity] settings for pod assignment | `{}` | +| `agones.ping.annotations` | [Annotations][annotations] added to the Agones ping pods | `{}` | +| `agones.ping.updateStrategy` | The [strategy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy) to apply to the allocator deployment | `{}` | +| `agones.ping.pdb.enabled` | Set to `true` to enable the creation of a [PodDisruptionBudget](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) for the ping deployment | `false` | +| `agones.ping.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.ping.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.ping.topologySpreadConstraints` | Ensures better resource utilization and high availability by evenly distributing Pods in the agones-system namespace | `{}` | {{% /feature %}} {{% feature publishVersion="1.47.0" %}} -| Parameter | Description | Default | +| Parameter | Description | Default | |----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| -| `agones.ping.install` | Whether to install the [ping service][ping] | `true` | -| `agones.ping.replicas` | The number of replicas to run in the deployment | `2` | -| `agones.ping.http.expose` | Expose the http ping service via a Service | `true` | -| `agones.ping.http.response` | The string response returned from the http service | `ok` | -| `agones.ping.http.port` | The port to expose on the service | `80` | -| `agones.ping.http.serviceType` | The [Service Type][service] of the HTTP Service | `LoadBalancer` | -| `agones.ping.http.nodePort` | Static node port to use for HTTP ping service. (Only applies when `agones.ping.http.serviceType` is `NodePort`.) | `0` | -| `agones.ping.http.loadBalancerIP` | The [Load Balancer IP][loadBalancer] of the HTTP Service load balancer. Only works if the Kubernetes provider supports this option. | \`\` | -| `agones.ping.http.externalTrafficPolicy` | The `externalTrafficPolicy` for the Agones http ping service | `Cluster` | -| `agones.ping.http.loadBalancerSourceRanges` | The [Load Balancer SourceRanges][loadBalancer] of the HTTP Service load balancer. Only works if the Kubernetes provider supports this option. | `[]` | -| `agones.ping.http.annotations` | [Annotations][annotations] added to the Agones ping http service | `{}` | -| `agones.ping.udp.expose` | Expose the udp ping service via a Service | `true` | -| `agones.ping.udp.rateLimit` | Number of UDP packets the ping service handles per instance, per second, per sender | `20` | -| `agones.ping.udp.port` | The port to expose on the service | `80` | -| `agones.ping.udp.serviceType` | The [Service Type][service] of the UDP Service | `LoadBalancer` | -| `agones.ping.udp.nodePort` | Static node port to use for UDP ping service. (Only applies when `agones.ping.udp.serviceType` is `NodePort`.) | `0` | -| `agones.ping.udp.loadBalancerIP` | The [Load Balancer IP][loadBalancer] of the UDP Service load balancer. Only works if the Kubernetes provider supports this option. | \`\` | -| `agones.ping.udp.externalTrafficPolicy` | The `externalTrafficPolicy` for the Agones udp ping service | `Cluster` | -| `agones.ping.udp.loadBalancerSourceRanges` | The [Load Balancer SourceRanges][loadBalancer] of the UDP Service load balancer. Only works if the Kubernetes provider supports this option. | `[]` | -| `agones.ping.udp.annotations` | [Annotations][annotations] added to the Agones ping udp service | `{}` | -| `agones.ping.healthCheck.initialDelaySeconds` | Initial delay before performing the first probe (in seconds) | `3` | -| `agones.ping.healthCheck.periodSeconds` | Seconds between every liveness probe (in seconds) | `3` | -| `agones.ping.healthCheck.failureThreshold` | Number of times before giving up (in seconds) | `3` | -| `agones.ping.healthCheck.timeoutSeconds` | Number of seconds after which the probe times out (in seconds) | `1` | -| `agones.ping.resources` | Ping pods [resource requests/limit][resources] | `{}` | -| `agones.ping.nodeSelector` | Ping [node labels][nodeSelector] for pod assignment | `{}` | -| `agones.ping.tolerations` | Ping [toleration][toleration] labels for pod assignment | `[]` | -| `agones.ping.affinity` | Ping [affinity][affinity] settings for pod assignment | `{}` | -| `agones.ping.annotations` | [Annotations][annotations] added to the Agones ping pods | `{}` | -| `agones.ping.updateStrategy` | The [strategy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy) to apply to the allocator deployment | `{}` | -| `agones.ping.pdb.enabled` | Set to `true` to enable the creation of a [PodDisruptionBudget](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) for the ping deployment | `false` | -| `agones.ping.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.ping.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.ping.topologySpreadConstraints` | Ensures better resource utilization and high availability by evenly distributing Pods in the agones-system namespace | `{}` | +| `agones.ping.install` | Whether to install the [ping service][ping] | `true` | +| `agones.ping.replicas` | The number of replicas to run in the deployment | `2` | +| `agones.ping.http.expose` | Expose the http ping service via a Service | `true` | +| `agones.ping.http.response` | The string response returned from the http service | `ok` | +| `agones.ping.http.port` | The port to expose on the service | `80` | +| `agones.ping.http.serviceType` | The [Service Type][service] of the HTTP Service | `LoadBalancer` | +| `agones.ping.http.nodePort` | Static node port to use for HTTP ping service. (Only applies when `agones.ping.http.serviceType` is `NodePort`.) | `0` | +| `agones.ping.http.loadBalancerIP` | The [Load Balancer IP][loadBalancer] of the HTTP Service load balancer. Only works if the Kubernetes provider supports this option. | \`\` | +| `agones.ping.http.externalTrafficPolicy` | The `externalTrafficPolicy` for the Agones http ping service | `Cluster` | +| `agones.ping.http.loadBalancerSourceRanges` | The [Load Balancer SourceRanges][loadBalancer] of the HTTP Service load balancer. Only works if the Kubernetes provider supports this option. | `[]` | +| `agones.ping.http.annotations` | [Annotations][annotations] added to the Agones ping http service | `{}` | +| `agones.ping.udp.expose` | Expose the udp ping service via a Service | `true` | +| `agones.ping.udp.rateLimit` | Number of UDP packets the ping service handles per instance, per second, per sender | `20` | +| `agones.ping.udp.port` | The port to expose on the service | `80` | +| `agones.ping.udp.serviceType` | The [Service Type][service] of the UDP Service | `LoadBalancer` | +| `agones.ping.udp.nodePort` | Static node port to use for UDP ping service. (Only applies when `agones.ping.udp.serviceType` is `NodePort`.) | `0` | +| `agones.ping.udp.loadBalancerIP` | The [Load Balancer IP][loadBalancer] of the UDP Service load balancer. Only works if the Kubernetes provider supports this option. | \`\` | +| `agones.ping.udp.externalTrafficPolicy` | The `externalTrafficPolicy` for the Agones udp ping service | `Cluster` | +| `agones.ping.udp.loadBalancerSourceRanges` | The [Load Balancer SourceRanges][loadBalancer] of the UDP Service load balancer. Only works if the Kubernetes provider supports this option. | `[]` | +| `agones.ping.udp.annotations` | [Annotations][annotations] added to the Agones ping udp service | `{}` | +| `agones.ping.healthCheck.initialDelaySeconds` | Initial delay before performing the first probe (in seconds) | `3` | +| `agones.ping.healthCheck.periodSeconds` | Seconds between every liveness probe (in seconds) | `3` | +| `agones.ping.healthCheck.failureThreshold` | Number of times before giving up (in seconds) | `3` | +| `agones.ping.healthCheck.timeoutSeconds` | Number of seconds after which the probe times out (in seconds) | `1` | +| `agones.ping.resources` | Ping pods [resource requests/limit][resources] | `{}` | +| `agones.ping.nodeSelector` | Ping [node labels][nodeSelector] for pod assignment | `{}` | +| `agones.ping.tolerations` | Ping [toleration][toleration] labels for pod assignment | `[]` | +| `agones.ping.affinity` | Ping [affinity][affinity] settings for pod assignment | `{}` | +| `agones.ping.annotations` | [Annotations][annotations] added to the Agones ping pods | `{}` | +| `agones.ping.updateStrategy` | The [strategy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy) to apply to the allocator deployment | `{}` | +| `agones.ping.pdb.enabled` | Set to `true` to enable the creation of a [PodDisruptionBudget](https://kubernetes.io/docs/tasks/run-application/configure-pdb/) for the ping deployment | `false` | +| `agones.ping.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.ping.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.ping.topologySpreadConstraints` | Ensures better resource utilization and high availability by evenly distributing Pods in the agones-system namespace | `{}` | {{% /feature %}} ### Allocator Service - | Parameter | Description | Default | | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | `agones.allocator.apiServerQPS` | Maximum sustained queries per second that an allocator should be making against API Server | `400` | @@ -286,18 +295,19 @@ 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` | | `agones.allocator.service.http.portName` | The name of exposed port | `http` | | `agones.allocator.service.http.targetPort` | The port that is used by the allocator pod to listen for [REST requests][rest-requests]. Note that the allocator server cannot bind to low numbered ports. | `8443` | -| `agones.allocator.service.http.nodePort` | If the ServiceType is set to "NodePort", this is the NodePort that the allocator http service is exposed on. | `30000-32767` | +| `agones.allocator.service.http.nodePort` | If the ServiceType is set to "NodePort", this is the NodePort that the allocator http service is exposed on. | `30000-32767` | | `agones.allocator.service.http.unallocatedStatusCode` | HTTP status code to return when no GameServer is available for allocation. This setting allows for custom responses when a game server allocation fails, offering flexibility in handling these situations. | `429` | | `agones.allocator.service.grpc.enabled` | If true the [allocator service][allocator] will respond to [gRPC requests][grpc-requests] | `true` | | `agones.allocator.service.grpc.port` | The port that is exposed externally by the [allocator service][allocator] for [gRPC requests][grpc-requests] | `443` | | `agones.allocator.service.grpc.portName` | The name of exposed port | `` | | `agones.allocator.service.grpc.appProtocol` | The `appProtocol` to set on the Service for the gRPC allocation port. If left blank, no value is set. | `` | -| `agones.allocator.service.grpc.nodePort` | If the ServiceType is set to "NodePort", this is the NodePort that the allocator gRPC service is exposed on. | `30000-32767` | +| `agones.allocator.service.grpc.nodePort` | If the ServiceType is set to "NodePort", this is the NodePort that the allocator gRPC service is exposed on. | `30000-32767` | | `agones.allocator.service.grpc.targetPort` | The port that is used by the allocator pod to listen for [gRPC requests][grpc-requests]. Note that the allocator server cannot bind to low numbered ports. | `8443` | | `agones.allocator.generateClientTLS` | Set to true to generate client TLS certificates or false to provide certificates in `certs/allocator/allocator-client.default/*` | `true` | | `agones.allocator.generateTLS` | Set to true to generate TLS certificates or false to provide your own certificates | `true` | @@ -326,66 +336,60 @@ 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 -| Parameter | Description | Default | -|----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| -|`agones.extensions.hostNetwork` | Determines if the Agones extensions should operate in hostNetwork mode. If running in hostNetwork mode, you should change `agones.extensions.http.port` and `agones.extensions.webhooks.port` to an available port. | `false` | -| `agones.extensions.http.port` | Port to use for liveness probe service and metrics | `8080` | -|`agones.extensions.webhooks.port` | Port to use for webhook service | `8081` | -| `agones.extensions.healthCheck.initialDelaySeconds` | Initial delay before performing the first probe (in seconds) | `3` | -| `agones.extensions.healthCheck.periodSeconds` | Seconds between every liveness probe (in seconds) | `3` | -| `agones.extensions.healthCheck.failureThreshold` | Number of times before giving up (in seconds) | `3` | -| `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 | `{}` | -| `agones.extensions.labels` | [Labels][labels] added to the Agones extensions pods | `{}` | -| `agones.extensions.annotations` | [Annotations][annotations] added to the Agones extensions pods | `{}` | -| `agones.extensions.numWorkers` | Number of workers to spin per resource type | `100` | -| `agones.extensions.apiServerQPS` | Maximum sustained queries per second that extensions should be making against API Server | `400` | -| `agones.extensions.apiServerQPSBurst` | Maximum burst queries per second that extensions should be making against API Server | `500` | -| `agones.extensions.logLevel` | Agones Extensions Log level. Log only entries with that severity and above | `info` | -| `agones.extensions.persistentLogs` | Store Agones extensions logs in a temporary volume attached to a container for debugging | `true` | -| `agones.extensions.persistentLogsSizeLimitMB` | Maximum total size of all Agones container logs in MB | `10000` | -| `agones.extensions.disableSecret` | Disables the creation of any allocator secrets. You MUST provide the `{agones.releaseName}-cert` secrets before installation if this is set to `true`. | `false` | -| `agones.extensions.customCertSecretPath` | Remap cert-manager path to server.crt and server.key | `{}` | -| `agones.extensions.allocationApiService.annotations` | [Annotations][annotations] added to the Agones API registration. | `{}` | -| `agones.extensions.allocationApiService.disableCaBundle` | Disable ca-bundle so it can be injected by cert-manager. | `false` | -| `agones.extensions.validatingWebhook.annotations` | [Annotations][annotations] added to the Agones validating webhook. | `{}` | -| `agones.extensions.validatingWebhook.disableCaBundle` | Disable ca-bundle so it can be injected by cert-manager. | `false` | -| `agones.extensions.mutatingWebhook.annotations` | [Annotations][annotations] added to the Agones mutating webhook. | `{}` | -| `agones.extensions.mutatingWebhook.disableCaBundle` | Disable ca-bundle so it can be injected by cert-manager. | `false` | -| `agones.extensions.allocationBatchWaitTime` | Wait time between each allocation batch when performing allocations in controller mode | `500ms` | -| `agones.extensions.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.extensions.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.extensions.replicas` | The number of replicas to run in the deployment | `2` | -| `agones.extensions.topologySpreadConstraints` | Ensures better resource utilization and high availability by evenly distributing Pods in the agones-system namespace | `{}` | - - +| Parameter | Description | Default | +| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| `agones.extensions.hostNetwork` | Determines if the Agones extensions should operate in hostNetwork mode. If running in hostNetwork mode, you should change `agones.extensions.http.port` and `agones.extensions.webhooks.port` to an available port. | `false` | +| `agones.extensions.http.port` | Port to use for liveness probe service and metrics | `8080` | +| `agones.extensions.webhooks.port` | Port to use for webhook service | `8081` | +| `agones.extensions.healthCheck.initialDelaySeconds` | Initial delay before performing the first probe (in seconds) | `3` | +| `agones.extensions.healthCheck.periodSeconds` | Seconds between every liveness probe (in seconds) | `3` | +| `agones.extensions.healthCheck.failureThreshold` | Number of times before giving up (in seconds) | `3` | +| `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.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 | `{}` | +| `agones.extensions.labels` | [Labels][labels] added to the Agones extensions pods | `{}` | +| `agones.extensions.annotations` | [Annotations][annotations] added to the Agones extensions pods | `{}` | +| `agones.extensions.numWorkers` | Number of workers to spin per resource type | `100` | +| `agones.extensions.apiServerQPS` | Maximum sustained queries per second that extensions should be making against API Server | `400` | +| `agones.extensions.apiServerQPSBurst` | Maximum burst queries per second that extensions should be making against API Server | `500` | +| `agones.extensions.logLevel` | Agones Extensions Log level. Log only entries with that severity and above | `info` | +| `agones.extensions.persistentLogs` | Store Agones extensions logs in a temporary volume attached to a container for debugging | `true` | +| `agones.extensions.persistentLogsSizeLimitMB` | Maximum total size of all Agones container logs in MB | `10000` | +| `agones.extensions.disableSecret` | Disables the creation of any allocator secrets. You MUST provide the `{agones.releaseName}-cert` secrets before installation if this is set to `true`. | `false` | +| `agones.extensions.customCertSecretPath` | Remap cert-manager path to server.crt and server.key | `{}` | +| `agones.extensions.allocationApiService.annotations` | [Annotations][annotations] added to the Agones API registration. | `{}` | +| `agones.extensions.allocationApiService.disableCaBundle` | Disable ca-bundle so it can be injected by cert-manager. | `false` | +| `agones.extensions.validatingWebhook.annotations` | [Annotations][annotations] added to the Agones validating webhook. | `{}` | +| `agones.extensions.validatingWebhook.disableCaBundle` | Disable ca-bundle so it can be injected by cert-manager. | `false` | +| `agones.extensions.mutatingWebhook.annotations` | [Annotations][annotations] added to the Agones mutating webhook. | `{}` | +| `agones.extensions.mutatingWebhook.disableCaBundle` | Disable ca-bundle so it can be injected by cert-manager. | `false` | +| `agones.extensions.allocationBatchWaitTime` | Wait time between each allocation batch when performing allocations in controller mode | `500ms` | +| `agones.extensions.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.extensions.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.extensions.replicas` | The number of replicas to run in the deployment | `2` | +| `agones.extensions.topologySpreadConstraints` | Ensures better resource utilization and high availability by evenly distributing Pods in the agones-system namespace | `{}` | ### GameServers -| Parameter | Description | Default | -|----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| -| `gameservers.namespaces` | a list of namespaces you are planning to use to deploy game servers | `["default"]` | -| `gameservers.minPort` | Minimum port to use for dynamic port allocation | `7000` | -| `gameservers.maxPort` | Maximum port to use for dynamic port allocation | `8000` | -| `gameservers.additionalPortRanges` | Port ranges from which to do named dynamic port allocation. Example:
additionalPortRanges:
  game: [9000, 10000] | `{}` | -| `gameservers.podPreserveUnknownFields` | Disable [field pruning][pruning] and schema validation on the Pod template for a [GameServer][gameserver] definition | `false` | +| Parameter | Description | Default | +| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| `gameservers.namespaces` | a list of namespaces you are planning to use to deploy game servers | `["default"]` | +| `gameservers.minPort` | Minimum port to use for dynamic port allocation | `7000` | +| `gameservers.maxPort` | Maximum port to use for dynamic port allocation | `8000` | +| `gameservers.additionalPortRanges` | Port ranges from which to do named dynamic port allocation. Example:
additionalPortRanges:
  game: [9000, 10000] | `{}` | +| `gameservers.podPreserveUnknownFields` | Disable [field pruning][pruning] and schema validation on the Pod template for a [GameServer][gameserver] definition | `false` | ### Helm Installation -| Parameter | Description | Default | -|----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| -| `helm.installTests` | Add an ability to run `helm test agones` to verify the installation | `false` | +| Parameter | Description | Default | +| ------------------- | ------------------------------------------------------------------- | ------- | +| `helm.installTests` | Add an ability to run `helm test agones` to verify the installation | `false` | [toleration]: https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/ [nodeSelector]: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector @@ -414,9 +418,11 @@ helm install my-release --namespace agones-system \ --set gameservers.minPort=1000,gameservers.maxPort=5000 agones ``` -The above command will deploy Agones controllers to `agones-system` namespace. Additionally Agones will use a dynamic GameServers' port allocation range of 1000-5000. +The above command will deploy Agones controllers to `agones-system` namespace. Additionally Agones +will use a dynamic GameServers' port allocation range of 1000-5000. -Alternatively, a YAML file that specifies the values for the parameters can be provided while installing the chart. For example, +Alternatively, a YAML file that specifies the values for the parameters can be provided while +installing the chart. For example, ```bash helm install my-release --namespace agones-system -f values.yaml agones/agones @@ -431,15 +437,18 @@ You can use the default {{< ghlink href="install/helm/agones/values.yaml" >}}val This test would create a `GameServer` resource and delete it afterwards. {{< alert title="Tip" color="info">}} -In order to use `helm test` command described in this section you need to set `helm.installTests` helm parameter to `true`. +In order to use `helm test` command described in this section you need to set `helm.installTests` +helm parameter to `true`. {{< /alert >}} Check the Agones installation by running the following command: + ```bash helm test my-release -n agones-system ``` You should see a successful output similar to this : + ``` NAME: my-release LAST DEPLOYED: Wed Mar 29 06:13:23 2023 @@ -454,26 +463,33 @@ Phase: Succeeded ## Controller TLS Certificates -By default agones chart generates tls certificates used by the admission controller, while this is handy, it requires the agones controller to restart on each `helm upgrade` command. +By default agones chart generates tls certificates used by the admission controller, while this is +handy, it requires the agones controller to restart on each `helm upgrade` command. ### Manual -For most use cases the controller would have required a restart anyway (eg: controller image updated). However if you really need to avoid restarts we suggest that you turn off tls automatic generation (`agones.controller.generateTLS` to `false`) and provide your own certificates (`certs/server.crt`,`certs/server.key`). +For most use cases the controller would have required a restart anyway (eg: controller image updated). +However if you really need to avoid restarts we suggest that you turn off tls automatic generation +(`agones.controller.generateTLS` to `false`) and provide your own certificates (`certs/server.crt`,`certs/server.key`). {{< alert title="Tip" color="info">}} -You can use our script located at {{< ghlink href="install/helm/agones/certs/cert.sh" >}}cert.sh{{< /ghlink >}} to generate them. +You can use our script located at {{< ghlink href="install/helm/agones/certs/cert.sh" >}}cert.sh{{< /ghlink >}} +to generate them. {{< /alert >}} ### Cert-Manager -Another approach is to use [cert-manager.io](https://cert-manager.io/) solution for cluster level certificate management. +Another approach is to use [cert-manager.io](https://cert-manager.io/) solution for cluster level +certificate management. -In order to use the cert-manager solution, first [install cert-manager](https://cert-manager.io/docs/installation/kubernetes/) on the cluster. -Then, [configure](https://cert-manager.io/docs/configuration/) an `Issuer`/`ClusterIssuer` resource and -last [configure](https://cert-manager.io/docs/usage/certificate/) a `Certificate` resource to manage controller `Secret`. -Make sure to configure the `Certificate` based on your system's requirements, including the validity `duration`. +In order to use the cert-manager solution, first [install cert-manager](https://cert-manager.io/docs/installation/kubernetes/) +on the cluster. Then, [configure](https://cert-manager.io/docs/configuration/) an `Issuer`/`ClusterIssuer` +resource and last [configure](https://cert-manager.io/docs/usage/certificate/) a `Certificate` +resource to manage controller `Secret`. Make sure to configure the `Certificate` based on your +system's requirements, including the validity `duration`. -Here is an example of using a self-signed `ClusterIssuer` for configuring controller `Secret` where secret name is `my-release-cert` or `{{ template "agones.fullname" . }}-cert`: +Here is an example of using a self-signed `ClusterIssuer` for configuring controller `Secret` where +secret name is `my-release-cert` or `{{ template "agones.fullname" . }}-cert`: ```bash #!/bin/bash @@ -504,19 +520,21 @@ spec: EOF ``` -After the certificates are generated, we will want to [inject caBundle](https://cert-manager.io/docs/concepts/ca-injector/) into the controller and extensions webhook and disable the controller and extensions secret creation through the following values.yaml file.: +After the certificates are generated, we will want to [inject caBundle](https://cert-manager.io/docs/concepts/ca-injector/) +into the controller and extensions webhook and disable the controller and extensions secret creation +through the following values.yaml file.: ```yaml agones: controller: disableSecret: true customCertSecretPath: - - key: ca.crt - path: ca.crt - - key: tls.crt - path: server.crt - - key: tls.key - path: server.key + - key: ca.crt + path: ca.crt + - key: tls.crt + path: server.crt + - key: tls.key + path: server.key allocationApiService: annotations: cert-manager.io/inject-ca-from: agones-system/my-release-agones-cert @@ -532,12 +550,12 @@ agones: extensions: disableSecret: true customCertSecretPath: - - key: ca.crt - path: ca.crt - - key: tls.crt - path: server.crt - - key: tls.key - path: server.key + - key: ca.crt + path: ca.crt + - key: tls.crt + path: server.crt + - key: tls.key + path: server.key allocationApiService: annotations: cert-manager.io/inject-ca-from: agones-system/my-release-agones-cert @@ -553,13 +571,17 @@ agones: ``` After copying the above yaml into a `values.yaml` file, use below command to install Agones: + ```bash helm install my-release --namespace agones-system --create-namespace --values values.yaml agones/agones ``` ## Reserved Allocator Load Balancer IP -In order to reuse the existing load balancer IP on upgrade or install the `agones-allocator` service as a `LoadBalancer` using a reserved static IP, a user can specify the load balancer's IP with the `agones.allocator.http.loadBalancerIP` helm configuration parameter value. By setting the `loadBalancerIP` value: +In order to reuse the existing load balancer IP on upgrade or install the `agones-allocator` service +as a `LoadBalancer` using a reserved static IP, a user can specify the load balancer's IP with the +`agones.allocator.http.loadBalancerIP` helm configuration parameter value. By setting the +`loadBalancerIP` value: 1. The `LoadBalancer` is created with the specified IP, if supported by the cloud provider. 2. A self-signed server TLS certificate is generated for the IP, used by the `agones-allocator` service. diff --git a/site/content/en/docs/Installation/upgrading.md b/site/content/en/docs/Installation/upgrading.md index f2bd031999..1d2d5b233e 100644 --- a/site/content/en/docs/Installation/upgrading.md +++ b/site/content/en/docs/Installation/upgrading.md @@ -53,11 +53,21 @@ for the period of your upgrade, as there will be a short period in which Agones #### In-Place Agones Upgrades +publish='{{% feature expiryVersion="1.47.0" %}}' {{< alert color="warning" title="Warning" >}} Work is ongoing for [In-Place Agones Upgrades](https://github.com/googleforgames/agones/issues/3766), and the feature is currently in `Alpha`. Please continue to use the multi-cluster strategy for production critical upgrades. Feedback on this `Alpha` feature is welcome and appreciated. {{< /alert >}} +{{% /feature %}} + +publish='{{% feature publishVersion="1.47.0" %}}' +{{< alert color="warning" title="Warning" >}} +Work is ongoing for [In-Place Agones Upgrades](https://github.com/googleforgames/agones/issues/3766), +and the feature is currently in `Beta`. Please continue to use the multi-cluster strategy for +production critical upgrades. Feedback on this `Beta` feature is welcome and appreciated. +{{< /alert >}} +{{% /feature %}} For In-Place Agones Upgrades we highly recommend installing using Helm. Helm has a significant advantage over `install.yaml` in that Helm automatically rolls back the upgrade if the agones-system @@ -77,44 +87,51 @@ are not part of the Game Server spec template that are instead passed to the Gam 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. + 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 + 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. - 1. Make any change to the Fleet Spec Template in your fleet.yaml and reapply with - `kubectl apply -f fleet.yaml`. We recommend you also add or update a label on the fleet as in - the next step. - 2. If you have no changes to make to the existing `spec.template` in the fleet.yaml, then either - add a label or annotation to the `spec.template.metadata`. Reapply with `kubectl apply -f fleet.yaml`. - ```yaml - apiVersion: agones.dev/v1 - kind: Fleet - metadata: - name: example-fleet - spec: - replicas: 2 - template: - metadata: - # Adding a label will start a Fleet rollout with the most up to date Agones config. The label can be any `key: value` pair. - labels: - release: 1.42.0 - ``` - 3. Ready Game Servers will shut down (RollingUpdate or Recreate based on the Fleet replacement - strategy type) and be recreated on the new configuraiton. Allocated Game Servers will use the - existing configuration, and once they are set back to Ready, these Game Servers will shut down - and be replaced by Ready Game Servers at the new configuration. - 4. Wait until all the previous Ready GameServers have been replaced by the new configuration. - - 2. *Option 2 -- Not Recommended* Continue using Fleet at its existing configuration without kicking - off a Fleet upgrade. - 1. Ready Game Servers and Allocated Game servers that return to the Ready state retain the old - configuration. - 2. Any newly created Game Servers will be at the new configuration. - 3. This make it difficult to track when the entire fleet is at a new configuration, and - increases the likelihood of having multiple Game Server configurations on the same Fleet. + + 1. _Option 1 -- Recommended_ Kick off rolling update of the existing Fleet. + + 1. Make any change to the Fleet Spec Template in your fleet.yaml and reapply with + `kubectl apply -f fleet.yaml`. We recommend you also add or update a label on the fleet as in + the next step. + 2. If you have no changes to make to the existing `spec.template` in the fleet.yaml, then either + add a label or annotation to the `spec.template.metadata`. Reapply with `kubectl apply -f fleet.yaml`. + + ```yaml + apiVersion: agones.dev/v1 + kind: Fleet + metadata: + name: example-fleet + spec: + replicas: 2 + template: + metadata: + # Adding a label will start a Fleet rollout with the most up to date Agones config. The label can be any `key: value` pair. + labels: + release: 1.42.0 + ``` + + 3. Ready Game Servers will shut down (RollingUpdate or Recreate based on the Fleet replacement + strategy type) and be recreated on the new configuraiton. Allocated Game Servers will use the + existing configuration, and once they are set back to Ready, these Game Servers will shut down + and be replaced by Ready Game Servers at the new configuration. + 4. Wait until all the previous Ready GameServers have been replaced by the new configuration. + + 2. _Option 2 -- Not Recommended_ Continue using Fleet at its existing configuration without kicking + off a Fleet upgrade. + 1. Ready Game Servers and Allocated Game servers that return to the Ready state retain the old + configuration. + 2. Any newly created Game Servers will be at the new configuration. + 3. This make it difficult to track when the entire fleet is at a new configuration, and + increases the likelihood of having multiple Game Server configurations on the same Fleet. + 4. Run any other tests to ensure the Agones installation is working as expected. 5. Congratulations - you have now upgraded to a new version of Agones! 👍 @@ -132,7 +149,7 @@ the new version. 1. Deploy the same set of Fleets, GameServers and FleetAutoscalers back into the cluster. 1. Run any other tests to ensure the Agones installation is working as expected. 1. Close your maintenance window. -7. Congratulations - you have now upgraded to a new version of Agones! 👍 +1. Congratulations - you have now upgraded to a new version of Agones! 👍 #### Installation with Helm @@ -150,16 +167,19 @@ Given the above, the steps for upgrade are simpler: 6. Close your maintenance window. 7. Congratulations - you have now upgraded to a new version of Agones! 👍 - ## Upgrading Kubernetes -The following are strategies for safely upgrading the underlying Kubernetes cluster from one version to another. -They may require adjustment to your particular game architecture but should provide a solid foundation for updating your cluster safely. +The following are strategies for safely upgrading the underlying Kubernetes cluster from one version +to another. They may require adjustment to your particular game architecture but should provide a +solid foundation for updating your cluster safely. -The recommended approach is to use [multiple clusters](#multiple-clusters), such that the upgrade can be tested -gradually with production load and easily rolled back if the need arises. +The recommended approach is to use [multiple clusters](#multiple-clusters), such that the upgrade +can be tested gradually with production load and easily rolled back if the need arises. -Agones has [multiple supported Kubernetes versions]({{< relref "_index.md#agones-and-kubernetes-supported-versions" >}}) for each version. You can stick with a minor Kubernetes version until it is not supported by Agones, but it is recommended to do supported minor (e.g. 1.12.1 ➡ 1.13.2) Kubernetes version upgrades at the same time as a matching Agones upgrades. +Agones has [multiple supported Kubernetes versions]({{< relref "_index.md#agones-and-kubernetes-supported-versions" >}}) +for each version. You can stick with a minor Kubernetes version until it is not supported by Agones, +but it is recommended to do supported minor (e.g. 1.12.1 ➡ 1.13.2) Kubernetes version upgrades at +the same time as a matching Agones upgrades. Patch upgrades (e.g. 1.12.1 ➡ 1.12.3) within the same minor version of Kubernetes can be done at any time. @@ -167,12 +187,12 @@ Patch upgrades (e.g. 1.12.1 ➡ 1.12.3) within the same minor version of Kuberne This process is very similar to the [Upgrading Agones: Multiple Clusters](#upgrading-agones-multiple-clusters) approach above. -We essentially want to transition our GameServer allocations from a cluster with the old version of Kubernetes, -to a cluster with the upgraded version of Kubernetes while ensuring nothing surprising +We essentially want to transition our GameServer allocations from a cluster with the old version of +Kubernetes, to a cluster with the upgraded version of Kubernetes while ensuring nothing surprising happens during this process. -This also allows easy rollback to the previous infrastructure that we already know to be working in production, with -minimal interruptions to player experience. +This also allows easy rollback to the previous infrastructure that we already know to be working in +production, with minimal interruptions to player experience. The following are steps to implement this: @@ -191,14 +211,15 @@ for the period of your upgrade, as there will be a short period in which Agones upgrades. 1. Start your maintenance window. -1. Scale your Fleets down to 0 and/or delete your GameServers. This is a good safety measure so there aren't race conditions - between the Agones controller being recreated and GameServers being deleted doesn't occur, and GameServers can end up stuck in erroneous states. -1. Start and complete your control plane upgrade(s). -1. Start and complete your node upgrades. -1. Scale your Fleets back up and/or recreate your GameServers. -1. Run any other tests to ensure the Agones installation is still working as expected. -1. Close your maintenance window. -7. Congratulations - you have now upgraded to a new version of Kubernetes! 👍 +2. Scale your Fleets down to 0 and/or delete your GameServers. This is a good safety measure so + there aren't race conditions between the Agones controller being recreated and GameServers being + deleted doesn't occur, and GameServers can end up stuck in erroneous states. +3. Start and complete your control plane upgrade(s). +4. Start and complete your node upgrades. +5. Scale your Fleets back up and/or recreate your GameServers. +6. Run any other tests to ensure the Agones installation is still working as expected. +7. Close your maintenance window. +8. Congratulations - you have now upgraded to a new version of Kubernetes! 👍 ## SDK Compatibility Guarantees @@ -211,23 +232,24 @@ information. **Our SDK Server compatibility contract as of Agones v1.41.0**: A game server binary using Beta and Stable SDKs will remain compatible with a _newer_ Agones Release, within possible deprecation windows: + - If your game server uses a non-deprecated Stable API, your binary will be compatible for 10 -releases (~1y) or more starting from the SDK version packaged. + releases (~1y) or more starting from the SDK version packaged. - For example, if the game server uses non-deprecated stable APIs in the 1.40 SDK, it will be - compatible through the 1.50 SDK. + compatible through the 1.50 SDK. - Stable APIs will almost certainly be compatible beyond 10 releases, as deprecation of stable - APIs is rare, but 10 releases is guaranteed. + APIs is rare, but 10 releases is guaranteed. - If your game server uses a non-deprecated Beta API, your binary will be guaranteed compatible for 5 releases (~6mo), but may be compatible past that point. - Alpha SDK APIs are subject to change between releases. - A game server binary using Alpha SDKs may not be compatible with a newer Agones release if - breaking changes have been made between releases. + breaking changes have been made between releases. - When we make incompatible Alpha changes, we will document the APIs involved. ## SDK Deprecation Policies as of Agones 1.41 - Client SDK updates are not mandatory for game server binaries except for SDK when the underlying -proto format has deprecations or breaking Alpha API changes. + proto format has deprecations or breaking Alpha API changes. - Breaking changes will be called out in upgrade documentation to allow admins to plan their upgrades. @@ -239,11 +261,11 @@ A Stable API may be marked as deprecated in release X and removed from Stable in ### Beta Deprecation Policies -When a SDK API feature graduates from Beta to Stable at release X, the API will be present in both Beta and -Stable surfaces from release X to release X+5. The Beta API is marked as deprecated in release X and -removed from Beta in release X+5. -A Beta API may be marked as deprecated in release X and removed from Beta in release X+5 without the -API graduating to Stable if it's determined that changes need to be made to the Beta API. +When a SDK API feature graduates from Beta to Stable at release X, the API will be present in both +Beta and Stable surfaces from release X to release X+5. The Beta API is marked as deprecated in +release X and removed from Beta in release X+5. A Beta API may be marked as deprecated in release X +and removed from Beta in release X+5 without the API graduating to Stable if it's determined that +changes need to be made to the Beta API. ### Alpha Deprecation Policies @@ -258,28 +280,27 @@ SDK compatibility with release 1.41.0. \ The Actions may differ from the [Client SDK]({{< relref "Client SDKs">}}) depending on how each Client SDK is implemented. -| Area | Action | Stable | Beta | Alpha | -|---------------------|-----------------------|--------|------|--------| -| Lifecycle | Ready | Legacy | | | -| Lifecycle | Health | Legacy | | | -| Lifecycle | Reserve | Legacy | | | -| Lifecycle | Allocate | Legacy | | | -| Lifecycle | Shutdown | Legacy | | | -| Configuration | GetGameServer | Legacy | | | -| Configuration | WatchGameServer | Legacy | | | -| Metadata | SetAnnotation | Legacy | | | -| Metadata | SetLabel | Legacy | | | -| Counters | GetCounter | | | 1.37.0 | -| Counters | UpdateCounter | | | 1.37.0 | -| Lists | GetList | | | 1.37.0 | -| Lists | UpdateList | | | 1.37.0 | -| Lists | AddListValue | | | 1.37.0 | -| Lists | RemoveListValue | | | 1.37.0 | -| Player Tracking | GetPlayerCapacity | | | Legacy | -| Player Tracking | SetPlayerCapacity | | | Legacy | -| Player Tracking | PlayerConnect | | | Legacy | -| Player Tracking | GetConnectedPlayers | | | Legacy | -| Player Tracking | IsPlayerConnected | | | Legacy | -| Player Tracking | GetPlayerCount | | | Legacy | -| Player Tracking | PlayerDisconnect | | | Legacy | - +| Area | Action | Stable | Beta | Alpha | +| --------------- | ------------------- | ------ | ------ | ------ | +| Lifecycle | Ready | Legacy | | | +| Lifecycle | Health | Legacy | | | +| Lifecycle | Reserve | Legacy | | | +| Lifecycle | Allocate | Legacy | | | +| Lifecycle | Shutdown | Legacy | | | +| Configuration | GetGameServer | Legacy | | | +| Configuration | WatchGameServer | Legacy | | | +| Metadata | SetAnnotation | Legacy | | | +| Metadata | SetLabel | Legacy | | | +| Counters | GetCounter | | 1.41.0 | 1.37.0 | +| Counters | UpdateCounter | | 1.41.0 | 1.37.0 | +| Lists | GetList | | 1.41.0 | 1.37.0 | +| Lists | UpdateList | | 1.41.0 | 1.37.0 | +| Lists | AddListValue | | 1.41.0 | 1.37.0 | +| Lists | RemoveListValue | | 1.41.0 | 1.37.0 | +| Player Tracking | GetPlayerCapacity | | | Legacy | +| Player Tracking | SetPlayerCapacity | | | Legacy | +| Player Tracking | PlayerConnect | | | Legacy | +| Player Tracking | GetConnectedPlayers | | | Legacy | +| Player Tracking | IsPlayerConnected | | | Legacy | +| Player Tracking | GetPlayerCount | | | Legacy | +| Player Tracking | PlayerDisconnect | | | Legacy |