GameServer Specification

Like any other Kubernetes resource you describe a GameServer’s desired state via a specification written in YAML or JSON to the Kubernetes API. The Agones controller will then change the actual state to the desired state.

A full GameServer specification is available below and in the example folder for reference :

apiVersion: "stable.agones.dev/v1alpha1"
kind: GameServer
metadata:
  name: "gds-example"
spec:
  ports:
  - name: default
    portPolicy: Static
    containerPort: 7654
    hostPort: 7777
    protocol: UDP
  health:
    disabled: false
    initialDelaySeconds: 5
    periodSeconds: 5
    failureThreshold: 3
  template:
    metadata:
      labels:
        myspeciallabel: myspecialvalue
    spec:
      containers:
      - name: example-server
        image: gcr.io/agones/test-server:0.1
        imagePullPolicy: Always

Since Agones defines a new Custom Resources Definition (CRD) we can define a new resource using the kind GameServer with the custom group stable.agones.dev and API version v1alpha1.

You can use the metadata field to target a specific namespaces but also attach specific annotations and labels to your resource. This is a very common pattern in the Kubernetes ecosystem.

The length of the name field of the Gameserver should not exceed 63 characters.

The spec field is the actual GameServer specification and it is composed as follow:

  • container is the name of container running the GameServer in case you have more than one container defined in the pod. If you do, this is a mandatory field. For instance this is useful if you want to run a sidecar to ship logs.
  • ports are an array of ports that can be exposed as direct connections to the game server container
    • name is an optional descriptive name for a port
    • portPolicy has two options Dynamic (default) the system allocates a free hostPort for the gameserver, for game clients to connect to. And Static, user defines the hostPort that the game client will connect to. Then onus is on the user to ensure that the port is available. When static is the policy specified, hostPort is required to be populated.
    • containerPort the port that is being opened on the game server process, this is a required field.
    • protocol the protocol being used. Defaults to UDP. TCP is the only other option.
  • health to track the overall healthy state of the GameServer, more information available in the health check documentation.
  • template the pod spec template to run your GameServer containers, see for more information.

GameServer State Diagram

The following diagram shows the lifecycle of a GameServer.

Game Servers are created through Kubernetes API (either directly or through a Fleet) and their state transitions are orchestrated by:

  • GameServer controller, which allocates ports, launches Pods backing game servers and manages their lifetime
  • Allocation controller, which marks game servers as Allocated to handle a game session
  • SDK, which manages health checking and shutdown of a game server session

GameServer State Diagram