agones.dev/agones@v1.53.0/install/helm/agones/README.md (about)

     1  # Install Agones using Helm
     2  
     3  This chart installs the Agones application and defines deployment on a [Kubernetes](http://kubernetes.io)
     4  cluster using the [Helm](https://helm.sh) package manager.
     5  
     6  See [Install Agones using Helm](https://agones.dev/site/docs/installation/install-agones/helm/) for
     7  installation and configuration instructions.
     8  
     9  ## Development Work on Agones Custom Resource Definitions (CRDs)
    10  
    11  Agones [extends the Kubernetes API with CustomResourceDefinitions](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)
    12  for the kinds `Fleet`, `GameServerSet`, `GameServer`, `FleetAutoscaler`.
    13  (`GameServerAllocation` does not a have CRD.) Regardless of installation method, the definitions for
    14  the Agones Custom Resources are in the [agones/install/helm/agones/templates/crds](./templates/crds/)
    15  directory. The double braces `{{ }}` in the CRDs and elsewhere are
    16  [Helm chart template](https://helm.sh/docs/chart_template_guide/getting_started/) features.
    17  
    18  ### Adding a New Field to a CRD
    19  
    20  > [!IMPORTANT]
    21  >
    22  > Any new _required_ field in a CRD must be non-nullable **and** have a default. We define a field
    23  > as required if the controller throws a panic or error when it encounters a `nil` value for that
    24  > field. Most new fields should be `nullable: true`, and the controller should be able to handle a
    25  > `nil` value without a panic or error.
    26  >
    27  > This ensures that after an Agones upgrade to a version that introduces a new field, the upgraded
    28  > controller does not panic or error when encountering an older custom resource that was created
    29  > before the Agones upgrade.
    30  
    31  ```yaml
    32  foo:
    33    title: Example required CRD field. Non-nullable with default.
    34    type: string
    35    enum:
    36      - foo1
    37      - foo2
    38      - foo3
    39    default: foo3
    40  bar:
    41    title: Example non-required CRD field. Nullable with optional default.
    42    type: object
    43    nullable: true
    44    properties:
    45      barCapacity:
    46        type: integer
    47        minimum: 0
    48        default: 99 # Default for a nullable field is optional
    49  ```
    50  
    51  Once you have added a new field to a CRD, generate the values for the `install.yaml` file by running
    52  `~/agones/build$ make gen-install`. This ensure that the `yaml` installation methods has the same
    53  values as the preferred Helm installation method. Note that changes to a CRD may also need changes
    54  to the [Helm schema validation file](#updating-the-helm-validation-schema).
    55  
    56  If the above example fields were added, for example, to the
    57  [\_gameserverspecschema.yaml](./templates/crds/_gameserverspecschema.yaml), then the fields should
    58  also be added to the `GameServerSpec` struct in [gameserver.go](../../../pkg/apis/agones/v1/gameserver.go).
    59  
    60  ```go
    61  type GameServerSpec struct {
    62  ...
    63  	Foo     apis.Foos    `json:"foo"`
    64  	Bar     *apis.Bars   `json:"bar,omitempty"`
    65  ...
    66  }
    67  
    68  const (
    69  	// Foo1 enum value for testing CRD defaulting
    70  	Foo1 Foos = "foo1"
    71  	// Foo2 enum value for testing CRD defaulting
    72  	Foo2 Foos = "foo2"
    73  	// Foo3 enum value for testing CRD defaulting
    74  	Foo3 Foos = "foo3"
    75  )
    76  
    77  // Foos enum values for testing CRD defaulting
    78  type Foos string
    79  
    80  // Bars tracks the initial bar capacity
    81  type Bars struct {
    82  	BarCapacity int64 `json:"barCapacity,omitempty"`
    83  }
    84  ```
    85  
    86  ### Removing an Existing Field From a CRD
    87  
    88  Keep in mind that there can only be one definition of a `kind` in the `apiVersion: agones.dev/v1`
    89  in a Kubernetes cluster. This means that change to a CRD during an upgrade, downgrade, or Feature
    90  Gate change of Agones is immediately applied to custom resources in the cluster. Breaking changes to
    91  fields may be covered under our [SDK deprecation policy](../../../site/content/en/docs/Installation/upgrading.md).
    92  
    93  ### Updating the Helm Validation Schema
    94  
    95  Any changes to the [Helm template](https://helm.sh/docs/topics/charts/#template-files) values which
    96  are denoted as `{{ .Values... }}` should also have a corresponding update the
    97  [values.schema.json](values.schema.json) file. The `values.schema.json` validates value field type,
    98  and whether or not the value or its subvalues are required. More information on how the schema
    99  validation works in Helm is in the
   100  [Helm chart](https://helm.sh/docs/topics/charts/#schema-files) documentation.
   101  
   102  For example, adding the [sample values](#adding-a-new-field-to-a-crd) `foo` and `bar` to a template
   103  such that the template uses the value from the [values.yaml](values.yaml) file like
   104  `foo: {{ .Values.gameservers.foo }}` the additions to the json schema would look like:
   105  
   106  ```json
   107      // ...
   108      "gameservers": {
   109        "type": "object",
   110        "properties": {
   111          // ...
   112          "foo": {
   113            "type": "string",
   114            "enum": [
   115              "foo1",
   116              "foo2",
   117              "foo3"
   118            ]
   119          },
   120          "bar": {
   121            "type": "object",
   122            "properties": {
   123              "barCapacity": {
   124                "type": "integer",
   125                "minimum": 0,
   126                "maximum": 99
   127              },
   128          }
   129        },
   130        "required": [
   131          // ...
   132          "foo"
   133        ]
   134      },
   135      // ...
   136  ```