Common Integration Patterns

• 1: Matchmaker requests a GameServer from a Fleet
• 2: Matchmaker requires game server process registration
• 3: Canary Testing a new Fleet
• 4: Reusing Allocated GameServers for more than one game session
• 5: High Density GameServers
• 6: Allocating based on GameServer Player Capacity

1 - Matchmaker requests a GameServer from a Fleet

Sample GameServerAllocation

Since Code Blind will automatically add the label agones.dev/fleet to a GameServer of a given Fleet, we can use that label selector to target a specific Fleet by name. In this instance, we are targeting the Fleet xonotic.

apiVersion: "allocation.agones.dev/v1"
kind: GameServerAllocation
spec:
  required:
    matchLabels:
      agones.dev/fleet: xonotic

Next Steps:

• Read the various specification references.
  • Review the GameServer spec.
  • Review the Fleet spec.
  • Review the GameServerAllocation spec.
• Review the specifics of Health Checking.
• See all the commands the Client SDK provides - we only show a few here!
• Check out the Allocator Service as a richer alternative to GameServerAllocation.
• If you aren’t familiar with the term Pod, this should provide a reference.

2 - Matchmaker requires game server process registration

In this scenario, the GameServer process will need to self Allocate when informed by the matchmaker that players are being sent to them.

Next Steps:

• Read the various references, including the GameServer and Fleet reference materials.
• Review the specifics of Health Checking.
• See all the commands the Client SDK provides - we only show a few here!
• If you aren’t familiar with the term Pod, this should provide a reference.

3 - Canary Testing a new Fleet

To canary release/test a new Fleet, we can run a small, fixed size Fleet of the new version of our GameServer, while also running the current stable production version.

Allocations can then prefer to come from the canary Fleet, but if all GameServers are already allocated from the canary Fleet, players will be allocated to the current stable Fleets.

Over time, if the monitoring of those playing on the canary Fleet is working as expected, the size of the canary Fleet can be grown until you feel confident in its stability.

Once confidence has been achieved, the configuration for stable Fleet can be updated to match the canary (usually triggering a rolling update). The canary Fleet can then be deleted or updated to a new testing version of the game server process.

Sample GameServerAllocation

To ensure we don’t have to change the Allocation system every time we have a canary Fleet, in this example, we will state that in our system, the label canary: "true" will be added to any canary Fleet in the cluster.

apiVersion: "allocation.agones.dev/v1"
kind: GameServerAllocation
spec:
  preferred:
    - matchLabels:
        canary: "true"
  required:
    matchLabels:
      agones.dev/fleet: stable

The above Allocation will then preferentially choose the Fleet that has GameServers with the label and key value ofcanary:"true", if it exists, and has remaining Ready GameServers, and if not, will apply the Allocation to the Fleet named “stable”.

Next Steps

• Read about different Fleet update options and strategies that are available.
• Have a look at all the options available on a GameServerAllocation.
• Review the Fleet reference.

4 - Reusing Allocated GameServers for more than one game session

Having a GameServer terminate after a single player session is better for packing and optimisation of infrastructure usage, as well as safety to ensure the process returns to an absolute zero state.

However, depending on the GameServer startup time, or other factors there may be reasons you wish to reuse a GameServer for n number of sessions before finally shutting it down.

The “magic trick” to this is knowing that the GameServer process can call SDK.Ready() to return to a Ready state after the GameServer has been allocated.

It is then up to the game developer to ensure that the game server process returns to a zero state once a game session has been completed.

Next Steps

• Have a look at all commands the Client SDK provides.
• If you aren’t familiar with the term Pod, this shouldw provide a reference.

5 - High Density GameServers

Depending on the setup and resource requirements of your game server process, sometimes it can be a more economical use of resources to run multiple concurrent game sessions from within a single GameServer instance.

The tradeoff here is that this requires more management on behalf of the integrated game server process and external systems, since it works around the common Kubernetes and/or Code Blind container lifecycle.

Utilising the new allocation gameServerState filter as well as the existing ability to edit the GameServer labels at both allocation time, and from within the game server process, via the SDK, means Code Blind is able to atomically remove a GameServer from the list of potentially allocatable GameServers at allocation time, and then return it back into the pool of allocatable GameServers if and when the game server process deems that is has room to host another game session.

Example GameServerAllocation

The below Allocation will first attempt to find a GameServer from the Fleet simple-udp that is already Allocated and also has the label agones.dev/sdk-gs-session-ready with the value of true.

The above condition indicates that the matching game server process behind the matched GameServer record is able to accept another game session at this time.

If an Allocated GameServer does not exist with the desired labels, then use the next selector to allocate a Ready GameServer from the simple-udp Fleet.

Whichever condition is met, once allocation is made against a GameServer, its label of agones.dev/sdk-gs-session-ready will be set to the value of false and it will no longer match the first selector, thereby removing it from any future allocations with the below schema.

It will then be up to the game server process to decide on if and when it is appropriate to set the agones.dev/sdk-gs-session-ready value back to true, thereby indicating that it can accept another concurrent gameplay session.

apiVersion: "allocation.agones.dev/v1"
kind: GameServerAllocation
spec:
  selectors:
    - matchLabels:
        agones.dev/fleet: simple-udp
        agones.dev/sdk-gs-session-ready: "true" # this is important
      gameServerState: Allocated # new state filter: allocate from Allocated servers
    - matchLabels:
        agones.dev/fleet: simple-udp
      gameServerState: Ready # Allocate out of the Ready Pool (which would be default, so backward compatible)
  metadata:
    labels:
      agones.dev/sdk-gs-session-ready: "false" # this removes it from the pool

Consistency

Code Blind, and Kubernetes itself are built as eventually consistent, self-healing systems. To that end, it is worth noting that there may be minor delays between each of the operations in the above flow. For example, depending on the cluster load, it may take up to a second for an SDK driven label change on a GameServer record to be visible to the Code Blind allocation system. We recommend building your integrations with Code Blind with this in mind.

Next Steps

• View the details about using the SDK to set labels on the GameServer.
• Check all the options available on GameServerAllocation.

6 - Allocating based on GameServer Player Capacity

Using this approach, we are able to be able to make a request that is akin to: “Find me a GameServer that is already allocated, with room for n number of players, and if one is not available, allocate me a Ready GameServer”.

Common applications of this type of allocation are Lobby servers where players await matchmaking, or a persistent world server where players connect and disconnect from a large map.

Example GameServerAllocation

The below allocation will attempt to find an already Allocated GameServer from the Fleet “lobby” with room for 10 to 15 players, and if it cannot find one, will allocate a Ready one from the same Fleet.

apiVersion: "allocation.agones.dev/v1"
kind: GameServerAllocation
spec:
  selectors:
    - matchLabels:
        agones.dev/fleet: lobby
      gameServerState: Allocated
      players:
        minAvailable: 10
        maxAvailable: 15
    - matchLabels:
        agones.dev/fleet: lobby

Next Steps

• Have a look at all commands the Client SDK provides.
• Check all the options available on GameServerAllocation.
• If you aren’t familiar with the term Pod, this should provide a reference.