GameServerAllocation Specification
GameServerAllocation
is used to atomically allocate a GameServer out of a set of GameServers. This could be a single Fleet, multiple Fleets, or a self managed group of GameServers.A full GameServerAllocation
specification is available below and in the
example folder
for reference:
apiVersion: "allocation.agones.dev/v1"
kind: GameServerAllocation
spec:
# GameServer selector from which to choose GameServers from.
# Defaults to all GameServers.
# matchLabels, matchExpressions, gameServerState and player filters can be used for filtering.
# See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ for more details on label selectors.
# An ordered list of GameServer label selectors.
# If the first selector is not matched, the selection attempts the second selector, and so on.
# This is useful for things like smoke testing of new game servers.
selectors:
- matchLabels:
agones.dev/fleet: green-fleet
# [Stage:Alpha]
# [FeatureFlag:PlayerAllocationFilter]
players:
minAvailable: 0
maxAvailable: 99
- matchLabels:
agones.dev/fleet: blue-fleet
- matchLabels:
game: my-game
matchExpressions:
- {key: tier, operator: In, values: [cache]}
# Specifies which State is the filter to be used when attempting to retrieve a GameServer
# via Allocation. Defaults to "Ready". The only other option is "Allocated", which can be used in conjunction with
# label/annotation/player selectors to retrieve an already Allocated GameServer.
gameServerState: Ready
# [Stage:Alpha]
# [FeatureFlag:PlayerAllocationFilter]
# Provides a filter on minimum and maximum values for player capacity when retrieving a GameServer
# through Allocation. Defaults to no limits.
players:
minAvailable: 0
maxAvailable: 99
# defines how GameServers are organised across the cluster.
# Options include:
# "Packed" (default) is aimed at dynamic Kubernetes clusters, such as cloud providers, wherein we want to bin pack
# resources
# "Distributed" is aimed at static Kubernetes clusters, wherein we want to distribute resources across the entire
# cluster
scheduling: Packed
# Optional custom metadata that is added to the game server at allocation
# You can use this to tell the server necessary session data
metadata:
labels:
mode: deathmatch
annotations:
map: garden22
apiVersion: "allocation.agones.dev/v1"
kind: GameServerAllocation
spec:
# Deprecated, use field selectors instead.
# GameServer selector from which to choose GameServers from.
# Defaults to all GameServers.
# matchLabels, matchExpressions, gameServerState and player filters can be used for filtering.
# See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ for more details on label selectors.
# Deprecated, use field selectors instead.
required:
matchLabels:
game: my-game
matchExpressions:
- {key: tier, operator: In, values: [cache]}
# Specifies which State is the filter to be used when attempting to retrieve a GameServer
# via Allocation. Defaults to "Ready". The only other option is "Allocated", which can be used in conjunction with
# label/annotation/player selectors to retrieve an already Allocated GameServer.
gameServerState: Ready
# [Stage:Alpha]
# [FeatureFlag:PlayerAllocationFilter]
# Provides a filter on minimum and maximum values for player capacity when retrieving a GameServer
# through Allocation. Defaults to no limits.
players:
minAvailable: 0
maxAvailable: 99
# Deprecated, use field selectors instead.
# An ordered list of preferred GameServer label selectors
# that are optional to be fulfilled, but will be searched before the `required` selector.
# If the first selector is not matched, the selection attempts the second selector, and so on.
# If any of the preferred selectors are matched, the required selector is not considered.
# This is useful for things like smoke testing of new game servers.
# This also support matchExpressions, gameServerState and player filters.
preferred:
- matchLabels:
agones.dev/fleet: green-fleet
# [Stage:Alpha]
# [FeatureFlag:PlayerAllocationFilter]
players:
minAvailable: 0
maxAvailable: 99
- matchLabels:
agones.dev/fleet: blue-fleet
# defines how GameServers are organised across the cluster.
# Options include:
# "Packed" (default) is aimed at dynamic Kubernetes clusters, such as cloud providers, wherein we want to bin pack
# resources
# "Distributed" is aimed at static Kubernetes clusters, wherein we want to distribute resources across the entire
# cluster
scheduling: Packed
# Optional custom metadata that is added to the game server at allocation
# You can use this to tell the server necessary session data
metadata:
labels:
mode: deathmatch
annotations:
map: garden22
The spec
field is the actual GameServerAllocation
specification, and it is composed as follows:
- Deprecated, use
selectors
instead. Ifselectors
is set, this field will be ignored.required
is a GameServerSelector (matchLabels. matchExpressions, gameServerState and player filters) from which to choose GameServers from. - Deprecated, use
selectors
instead. Ifselectors
is set, this field will be ignored.preferred
is an ordered list of preferred GameServerSelector that are optional to be fulfilled, but will be searched before therequired
selector. If the first selector is not matched, the selection attempts the second selector, and so on. If any of thepreferred
selectors are matched, therequired
selector is not considered. This is useful for things like smoke testing of new game servers. selectors
is an ordered list of GameServerSelector. If the first selector is not matched, the selection attempts the second selector, and so on. This is useful for things like smoke testing of new game servers.scheduling
defines how GameServers are organised across the cluster, in this case specifically when allocatingGameServers
for usage. “Packed” (default) is aimed at dynamic Kubernetes clusters, such as cloud providers, wherein we want to bin pack resources. “Distributed” is aimed at static Kubernetes clusters, wherein we want to distribute resources across the entire cluster. See Scheduling and Autoscaling for more details.metadata
is an optional list of custom labels and/or annotations that will be used to patch the game server’s metadata in the moment of allocation. This can be used to tell the server necessary session data
Once created the GameServerAllocation
will have a status
field consisting of the following:
State
is the current state of a GameServerAllocation, e.g.Allocated
, orUnAllocated
GameServerName
is the name of the game server attached to this allocation, once thestate
isAllocated
Ports
is a list of the ports that the game server makes available. See the GameServer Reference for more details.Address
is the primary network address where the game server can be reached.Addresses
is an array of all network addresses where the game server can be reached. It is a copy of theNode.Status.addresses
field for the node theGameServer
is scheduled on.NodeName
is the name of the node that the gameserver is running on.Source
is “local” unless this allocation is from a remote cluster, in which caseSource
is the endpoint of the remote agones-allocator. See Multi-cluster Allocation for more details.Metadata
conststs of:Labels
containing the labels of the game server at allocation time.Annotations
containing the annotations of the underlying game server at allocation time.
Info
For performance reasons, the query cache for a GameServerAllocation
is eventually consistent.
Usually, the cache is populated practically immediately on GameServer
change, but under high load of the Kubernetes
control plane, it may take some time for updates to GameServer
selectable features to be populated into the cache
(although this doesn’t affect the atomicity of the Allocation operation).
While Agones will do a small series of retries when an allocatable GameServer
is not available in its cache,
depending on your game requirements, it may be worth implementing your own more extend retry mechanism for
Allocation requests for high load scenarios.
Each GameServerAllocation
will allocate from a single namespace. The namespace can be specified outside of
the spec, either with the --namespace
flag when using the command line / kubectl
or
in the url
when using an API call. If not specified when using the command line, the namespace will be automatically set to default
.
Next Steps:
- Check out the Allocator Service as a richer alternative to
GameServerAllocation
.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.
Last modified September 14, 2023: Upgrade Hugo (#3369) (c8649e2)