A full GameServer specification is available below and in the example folder for reference :
apiVersion: "agones.dev/v1" kind: GameServer # GameServer Metadata # https://v1-25.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#objectmeta-v1-meta metadata: # generateName: "gds-example" # generate a unique name, with the given prefix name: "gds-example" # set a fixed name spec: # if there is more than one container, specify which one is the game server container: example-server # Array of ports that can be exposed as direct connections to the game server container ports: # name is a descriptive name for the port - name: default # portPolicy has three options: # - "Dynamic" (default) the system allocates a free hostPort for the gameserver, for game clients to connect to # - "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 # - "Passthrough" dynamically sets the `containerPort` to the same value as the dynamically selected hostPort. # This will mean that users will need to lookup what port has been opened through the server side SDK. portPolicy: Static # The name of the container to open the port on. Defaults to the game server container if omitted or empty. container: simple-game-server # the port that is being opened on the game server process containerPort: 7654 # the port exposed on the host, only required when `portPolicy` is "Static". Overwritten when portPolicy is "Dynamic". hostPort: 7777 # protocol being used. Defaults to UDP. TCP and TCPUDP are other options # - "UDP" (default) use the UDP protocol # - "TCP", use the TCP protocol # - "TCPUDP", uses both TCP and UDP, and exposes the same hostPort for both protocols. # This will mean that it adds an extra port, and the first port is set to TCP, and second port set to UDP protocol: UDP # Health checking for the running game server health: # Disable health checking. defaults to false, but can be set to true disabled: false # Number of seconds after the container has started before health check is initiated. Defaults to 5 seconds initialDelaySeconds: 5 # If the `Health()` function doesn't get called at least once every period (seconds), then # the game server is not healthy. Defaults to 5 periodSeconds: 5 # Minimum consecutive failures for the health probe to be considered failed after having succeeded. # Defaults to 3. Minimum value is 1 failureThreshold: 3 # Parameters for game server sidecar sdkServer: # sdkServer log level parameter has three options: # - "Info" (default) The SDK server will output all messages except for debug messages # - "Debug" The SDK server will output all messages including debug messages # - "Error" The SDK server will only output error messages logLevel: Info # grpcPort and httpPort control what ports the sdkserver listens on. # Starting with Agones 1.2 the default grpcPort is 9357 and the default # httpPort is 9358. In earlier releases, the defaults were 59357 and 59358 # respectively but as these were in the ephemeral port range they could # conflict with other TCP connections. grpcPort: 9357 httpPort: 9358 # [Stage:Alpha] # [FeatureFlag:PlayerTracking] # Players provides the configuration for player tracking features. # Commented out since Alpha, and disabled by default # players: # # set this GameServer's initial player capacity # initialCapacity: 10 # Pod template configuration # https://v1-25.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#podtemplate-v1-core template: # pod metadata. Name & Namespace is overwritten metadata: labels: myspeciallabel: myspecialvalue # Pod Specification spec: containers: - name: simple-game-server image: us-docker.pkg.dev/agones-images/examples/simple-game-server:0.16 imagePullPolicy: Always # nodeSelector is a label that can be used to tell Kubernetes which host # OS to use. For Windows game servers uncomment the nodeSelector # definition below. # Details: https://kubernetes.io/docs/setup/production-environment/windows/user-guide-windows-containers/#ensuring-os-specific-workloads-land-on-the-appropriate-container-host # nodeSelector: # kubernetes.io/os: windows
Since Agones defines a new Custom Resources Definition (CRD) we can define a new resource using the kind
GameServer with the custom group
agones.dev and API version
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.
spec field is the actual GameServer specification and it is composed as follow:
containeris 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.
portsare an array of ports that can be exposed as direct connections to the game server container
nameis an optional descriptive name for a port
portPolicyhas three options: -
Dynamic(default) the system allocates a random free hostPort for the gameserver, for game clients to connect to. -
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,
hostPortis required to be populated. -
Passthroughdynamically sets the
containerPortto the same value as the dynamically selected hostPort. This will mean that users will need to lookup what port to open through the server side SDK before starting communications.
container(Alpha) the name of the container to open the port on. Defaults to the game server container if omitted or empty.
containerPortthe port that is being opened on the game server process, this is a required field for
Staticport policies, and should not be included in
protocolthe protocol being used. Defaults to UDP. TCP and TCPUDP are other options.
healthto track the overall healthy state of the GameServer, more information available in the health check documentation.
sdkServerdefines parameters for the game server sidecar
loggingfield defines log level for SDK server. Defaults to “Info”. It has three options:
- “Info” (default) The SDK server will output all messages except for debug messages
- “Debug” The SDK server will output all messages including debug messages
- “Error” The SDK server will only output error messages
grpcPortthe port that the SDK Server binds to for gRPC connections
httpPortthe port that the SDK Server binds to for HTTP gRPC gateway connections
players(Alpha, behind “PlayerTracking” feature gate), sets this GameServer’s initial player capacity
templatethe pod spec template to run your GameServer containers, see for more information.
NoteThe GameServer resource does not support updates. If you need to make regular updates to the GameServer spec, consider using a Fleet.
Stable Network ID
The Stable Network ID feature is currently Beta, and while it is enabled by default it may change in the future.
Use the Feature Gate
PodHostname to disable this feature.
See the Feature Gate documentation for details on how to disable features.
If you want to connect to a
GameServer from within your Kubernetes cluster via a convention based
DNS entry, each Pod attached to a
GameServer automatically derives its hostname from the name of the
To create internal DNS entries within the cluster, a group of
Pods attached to
GameServers can use a
Headless Service to control
the domain of the Pods, along with providing
subdomain value to the
to provide all the required details such that Kubernetes will create a DNS record for each Pod behind the Service.
You are also responsible for setting the labels on the
GameServer.Spec.Template.Metadata to set the labels on the
created Pods and creating the Headless Service responsible for the network identity of the pods, Agones will not do
this for you, as a stable DNS record is not required for all use cases.
To ensure that the
hostName value matches
RFC 1123, any
GameServer name are replaced by
- when setting the underlying
GameServer State Diagram
The following diagram shows the lifecycle of a
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
Allocatedto handle a game session
- SDK, which manages health checking and shutdown of a game server session
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 June 1, 2023: Remove Rolling Update on Ready warning in docs (#3192) (f2d6fdf)