Agones – Agones Documentation

Docs: Feature Stages

Thu, 26 Sep 2019 01:20:41 +0000

Supported Versions

Agones versions are expressed as x.y.z, where x is the major version, y is the minor version, and z is the patch version , following Semantic Versioning terminology.

Agones Features

A feature within Agones can be in Alpha, Beta or Stable stage.

Feature Gates

Alpha and Beta features can be enabled or disabled through the agones.featureGates configuration option that can be found in the Helm configuration documentation.

The current set of alpha and beta feature gates are:

Feature Name	Gate	Default	Stage	Since
Multicluster Allocation^*	N/A	Enabled	`Beta`	1.6.0
Example Gate (not in use)	`Example`	Disabled	None	0.13.0
Port Allocations to Multiple Containers	`ContainerPortAllocation`	Enabled	`Beta`	1.7.0
Player Tracking	`PlayerTracking`	Disabled	`Alpha`	1.6.0

^*Multicluster Allocation was started before this process was in place, and therefore does not have a feature gate and cannot be disabled.

Description of Stages

Alpha

An Alpha feature means:

Disabled by default.
Might be buggy. Enabling the feature may expose bugs.
Support for this feature may be dropped at any time without notice.
The API may change in incompatible ways in a later software release without notice.
Recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support.

Note

Please do try Alpha features and give feedback on them. This is important to ensure less breaking changes through the Beta period.

Beta

A Beta feature means:

Enabled by default, but able to be disabled through a feature gate.
The feature is well tested. Enabling the feature is considered safe.
Support for the overall feature will not be dropped, though details may change.
The schema and/or semantics of objects may change in incompatible ways in a subsequent beta or stable releases. When this happens, we will provide instructions for migrating to the next version. This may require deleting, editing, and re-creating API objects. The editing process may require some thought. This may require downtime for applications that rely on the feature.
Recommended for only non-business-critical uses because of potential for incompatible changes in subsequent releases. If you have multiple clusters that can be upgraded independently, you may be able to relax this restriction.

Note

Note: Please do try Beta features and give feedback on them! After they exit beta, it may not be practical for us to make more changes.

Stable

A Stable feature means:

The feature is enabled and the corresponding feature gate no longer exists.
Stable versions of features will appear in released software for many subsequent versions.

Feature Stage Indicators

There are a variety of features with Agones, how can we determine what stage each feature is in?

Below are indicators for each type of functionality that can be used to determine the feature stage for a given aspect of Agones.

Custom Resource Definitions (CRDs)

This refers to Kubernetes resource for Agones, such as GameServer, Fleet and GameServerAllocation.

New CRDs

For new resources, the stage of the resource will be indicated by the apiVersion of the resource.

For example: apiVersion: "agones.dev/v1" is a stable resource, apiVersion: "agones.dev/v1beta1" is a beta stage resource, and apiVersion: "agones.dev/v1alpha1" is an alpha stage resource.

New CRD attributes

When alpha and beta attributes are added to an existing stable Agones CRD, we will follow the Kubernetes Adding Unstable Features to Stable Versions Guide to optimise on the least amount of breaking changes for users as attributes progress through feature stages.

alpha and beta attributes will be added to the existing CRD as optional and documented with their feature stage. Attempting to populate these alpha and beta attributes on an Agones CRD will return a validation error if their accompanying Feature Flag is not enabled.

alpha and beta attributes can be subject to change of name and structure, and will result in breaking changes before moving to a stable stage. These changes will be outlined in release notes and feature documentation.

Agones Game Server SDK

Any alpha or beta Game Server SDK functionality will be a subpackage of the sdk package. For example , functionality found in a sdk.alphav1 package should be considered at the alpha feature stage.

Only experimental functionality will be found in any alpha and beta SDK packages, and as such may change as development occurs.

As SDK features move to through feature stages towards stable, the previous version of the SDK API will remain for at least one release to enable easy migration to the more stable feature stage (i.e. from alpha -> beta, beta -> stable)

Any other SDK functionality not marked as alpha or beta is assumed to be stable.

REST & gRPC APIs

REST and gRPC API will have versioned paths where appropriate to indicate their feature stage.

For example, a REST API with a prefix of v1alpha1 is an alpha stage feature: http://api.example.com/v1alpha1/exampleaction.

Similar to the SDK, any alpha or beta gRPC functionality will be a subpackage of the main API package. For example, functionality found in a api.alphav1 package should be considered at the alpha feature stage.

Docs: Unreal Engine Game Server Client Plugin

Thu, 13 Jun 2019 10:17:50 +0000

Note

The Unreal SDK is functional, but not yet feature complete. Pull requests to finish the functionality are appreciated.

Check the Client SDK Documentation for more details on each of the SDK functions and how to run the SDK locally.

Download

Download the source from the Releases Page or directly from GitHub .

Usage

The Unreal Engine plugin is specifically designed to be as simple as possible. No programming should be required to use the plugin within your Unreal Engine project.

From source

At this moment we do not provide binaries for the plugin. This requires you to compile the plugin yourself. In order to do this you need to have a C++ Unreal Engine project.

Create a Plugins directory in your Unreal Engine project root directory.
Copy the Agones plugin directory into the Plugins directory.
Build the project.

Agones Hook

To manually call the Agones SDK methods add the plugin as a dependency inside the <project>.Build.cs file:

PublicDependencyModuleNames.AddRange(
    new string[]
    {
        ...
        "Agones"
    });

Then use FAgonesModule::GetHook() to get a reference to the Agones hook and call the SDK methods using the hook:

#include "Agones.h"

...

// Get a reference to the Agones hook.
FAgonesHook& Hook = FAgonesModule::GetHook();

Hook.Ready();
Hook.SetLabel(TEXT("key"), TEXT("value"));

// GetGameServerDelegate here is a class member of type FGameServerRequestCompleteDelegate.
Hook.GetGameServer(GetGameServerDelegate);
GetGameServerDelegate.BindLambda([](TSharedPtr<FGameServer> GameServer, bool bSuccess)
{
    // ...
});

Settings

The settings for the Agones Plugin can be found in the Unreal Engine editor Edit > Project Settings > Plugins > Agones

Available settings:

Health Ping Enabled. Whether the server sends a health ping to the Agones sidecar. (default: true)
Health Ping Seconds. Interval of the server sending a health ping to the Agones sidecar. (default: 5)
Request Retry Limit. Maximum number of times a failed request to the Agones sidecar is retried. Health requests are not retried. (default: 30)
Send Ready at Startup. Automatically send a Ready request when the server starts. Disable this to manually control when the game server should be marked as ready. (default: true)

Docs: Third Party Videos and Presentations

Thu, 03 Jan 2019 08:37:35 +0000

Presentations

Large-Scale Multiplayer Gaming on Kubernetes (Cloud Next ‘19)

Agones: Scaling Multiplayer Game Servers with Open Source (GDC 2019)

Intro to Agones: Scaling Multiplayer Game Servers with Kubernetes (Kubecon, 2018)

Google Cloud Next ‘18 London: Carl Dionne, Development Director at Ubisoft Montreal

Agones: Scaling Multiplayer Dedicated Game Servers with Kubernetes (Cloud Next ‘18)

Screencasts

Agones: How Do I Docker and Kubernetes? (Part 1 & Part 2)

Docs: Scheduling and Autoscaling

Thu, 03 Jan 2019 05:45:05 +0000

Cluster Autoscaler

Kubernetes has a cluster node autoscaler that works with a wide variety of cloud providers.

The default scheduling strategy (Packed) is designed to work with the Kubernetes autoscaler out of the box.

The autoscaler will automatically add Nodes to the cluster when GameServers don’t have room to be scheduled on the clusters, and then scale down when there are empty Nodes with no GameServers running on them.

This means that scaling Fleets up and down can be used to control the size of the cluster, as the cluster autoscaler will adjust the size of the cluster to match the resource needs of one or more Fleets running on it.

To enable and configure autoscaling on your cloud provider, check their connector implementation, or their cloud specific documentation.

Google Kubernetes Engine

Azure Kubernetes Service

Cluster Autoscaler on Azure Kubernetes Service (AKS) - Preview

Fleet Autoscaling

Fleet autoscaling is the only type of autoscaling that exists in Agones. It is currently available as a buffer autoscaling strategy or as a webhook driven strategy, such that you can provide your own autoscaling logic.

Have a look at the Create a Fleet Autoscaler quickstart, the Create a Webhook Fleet Autoscaler quickstart, and the Fleet Autoscaler Specification for details.

Autoscaling Concepts

To facilitate autoscaling, we need to combine several concepts and functionality, as described below.

Allocation Scheduling

Allocation scheduling refers to the order in which GameServers, and specifically their backing Pods are chosen from across the Kubernetes cluster within a given Fleet when allocation occurs.

Pod Scheduling

Each GameServer is backed by a Kubernetes Pod. Pod scheduling refers to the strategy that is in place that determines which node in the Kubernetes cluster the Pod is assigned to, when it is created.

Fleet Scale Down Strategy

Fleet Scale Down strategy refers to the order in which the GameServers that belong to a Fleet are deleted, when Fleets are shrunk in size.

Fleet Scheduling

There are two scheduling strategies for Fleets - each designed for different types of Kubernetes Environments.

Packed

apiVersion: "agones.dev/v1"
kind: Fleet
metadata:
  name: simple-udp
spec:
  replicas: 100
  scheduling: Packed
  template:
    spec:
      ports:
      - containerPort: 7654
      template:
        spec:
          containers:
          - name: simple-udp
            image: gcr.io/agones-images/udp-server:0.21

This is the default Fleet scheduling strategy. It is designed for dynamic Kubernetes environments, wherein you wish to scale up and down as load increases or decreases, such as in a Cloud environment where you are paying for the infrastructure you use.

It attempts to pack as much as possible into the smallest set of nodes, to make scaling infrastructure down as easy as possible.

This affects the Cluster autoscaler, Allocation Scheduling, Pod Scheduling and Fleet Scale Down Scheduling.

Cluster Autoscaler

To ensure that the Cluster Autoscaler doesn’t attempt to evict and move GameServer Pods onto new Nodes during gameplay, Agones adds the annotation "cluster-autoscaler.kubernetes.io/safe-to-evict": "false" to the backing Pod.

Allocation Scheduling Strategy

Under the “Packed” strategy, allocation will prioritise allocating GameServers to nodes that are running on Nodes that already have allocated GameServers running on them.

Pod Scheduling Strategy

Under the “Packed” strategy, Pods will be scheduled using the PodAffinity with a preferredDuringSchedulingIgnoredDuringExecution affinity with hostname topology. This attempts to group together GameServer Pods within as few nodes in the cluster as it can.

Note

The default Kubernetes scheduler doesn’t do a perfect job of packing, but it’s a good enough job for what we need - at least at this stage.

Fleet Scale Down Strategy

With the “Packed” strategy, Fleets will remove Ready GameServers from Nodes with the least number of Ready and Allocated GameServers on them. Attempting to empty Nodes so that they can be safely removed.

Distributed

apiVersion: "agones.dev/v1"
kind: Fleet
metadata:
  name: simple-udp
spec:
  replicas: 100
  scheduling: Distributed
  template:
    spec:
      ports:
      - containerPort: 7654
      template:
        spec:
          containers:
          - name: simple-udp
            image: gcr.io/agones-images/udp-server:0.21

This Fleet scheduling strategy is designed for static Kubernetes environments, such as when you are running Kubernetes on bare metal, and the cluster size rarely changes, if at all.

This attempts to distribute the load across the entire cluster as much as possible, to take advantage of the static size of the cluster.

This affects Allocation Scheduling, Pod Scheduling and Fleet Scale Down Scheduling.

Cluster Autoscaler

Since this strategy is not aimed at clusters that autoscale, this strategy does nothing for the cluster autoscaler.

Allocation Scheduling Strategy

Under the “Distributed” strategy, allocation will prioritise allocating GameServers to nodes that have the least number of allocated GameServers on them.

Pod Scheduling Strategy

Under the “Distributed” strategy, Pod scheduling is provided by the default Kubernetes scheduler, which will attempt to distribute the GameServer Pods across as many nodes as possible.

Fleet Scale Down Strategy

With the “Distributed” strategy, Fleets will remove Ready GameServers from Nodes with at random, to ensure a distributed load is maintained.

Docs: GameServer Specification

Thu, 03 Jan 2019 03:58:48 +0000

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

apiVersion: "agones.dev/v1"
kind: GameServer
# GameServer Metadata
# https://v1-15.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.15/#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
    # [Stage:Beta]
    # [FeatureFlag:ContainerPortAllocation]
    # The name of the container to open the port on. Defaults to the game server container if omitted or empty.
    container: simple-udp
    # 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 is the only other option
    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-15.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.15/#podtemplate-v1-core
  template:
    # pod metadata. Name & Namespace is overwritten
    metadata:
      labels:
        myspeciallabel: myspecialvalue
    # Pod Specification
    spec:
      containers:
      - name: simple-udp
        image:  gcr.io/agones-images/udp-server:0.21
        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 agones.dev and API version v1.

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 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, 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 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.
- containerPort the port that is being opened on the game server process, this is a required field for Dynamic and Static port policies, and should not be included in Passthrough configuration.
- 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. -sdkServer defines parameters for the game server sidecar
- logging field 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
- grpcPort the port that the SDK Server binds to for gRPC connections
- httpPort the 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
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

Docs: Quickstart: Create a Game Server

Wed, 02 Jan 2019 06:35:31 +0000

Objectives

Create a GameServer in Kubernetes using Agones custom resource.
Get information about the GameServer such as IP address, port and state.
Connect to the GameServer.

Prerequisites

The following prerequisites are required to create a GameServer :

A Kubernetes cluster with the UDP port range 7000-8000 open on each node.
Agones controller installed in the targeted cluster
kubectl properly configured
Netcat which is already installed on most Linux/macOS distributions, for windows you can use WSL.

If you don’t have a Kubernetes cluster you can follow these instructions to create a cluster on Google Kubernetes Engine (GKE), Minikube or Azure Kubernetes Service (AKS), and install Agones.

For the purpose of this guide we’re going to use the simple-udp example as the GameServer container. This example is a very simple UDP server written in Go. Don’t hesitate to look at the code of this example for more information.

1. Create a GameServer

Let’s create a GameServer using the following command :

kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/simple-udp/gameserver.yaml

You should see a successful output similar to this :

gameserver "simple-udp" created

This has created a GameServer record inside Kubernetes, which has also created a backing Pod to run our simple udp game server code in. If you want to see all your running GameServers you can run:

kubectl get gameservers

It should look something like this:

NAME               STATE     ADDRESS       PORT   NODE     AGE
simple-udp-7pjrq   Ready   35.233.183.43   7190   agones   3m

You can also see the Pod that got created by running kubectl get pods, the Pod will be prefixed by simple-udp.

NAME                READY     STATUS    RESTARTS   AGE
simple-udp-7pjrq    2/2       Running   0          5m

As you can see above it says READY: 2/2 this means there are two containers running in this Pod, this is because Agones injected the SDK sidecar for readiness and health checking of your Game Server.

For the full details of the YAML file head to the GameServer Specification Guide

2. Fetch the GameServer Status

Let’s wait for the GameServer state to become Ready:

watch kubectl describe gameserver

Name:         simple-udp-7pjrq
Namespace:    default
Labels:       <none>
Annotations:  agones.dev/sdk-version: 0.9.0-764fa53
API Version:  agones.dev/v1
Kind:         GameServer
Metadata:
  Creation Timestamp:  2019-02-27T15:06:20Z
  Finalizers:
    agones.dev
  Generate Name:     simple-udp-
  Generation:        1
  Resource Version:  30377
  Self Link:         /apis/agones.dev/v1/namespaces/default/gameservers/simple-udp-7pjrq
  UID:               3d7ac3e1-3aa1-11e9-a4f5-42010a8a0019
Spec:
  Container:  simple-udp
  Health:
    Failure Threshold:      3
    Initial Delay Seconds:  5
    Period Seconds:         5
  Ports:
    Container Port:  7654
    Host Port:       7190
    Name:            default
    Port Policy:     Dynamic
    Protocol:        UDP
  Scheduling:        Packed
  Template:
    Metadata:
      Creation Timestamp:  <nil>
    Spec:
      Containers:
        Image:  gcr.io/agones-images/udp-server:0.21
        Name:   simple-udp
        Resources:
          Limits:
            Cpu:     20m
            Memory:  32Mi
          Requests:
            Cpu:     20m
            Memory:  32Mi
Status:
  Address:    35.233.183.43
  Node Name:  agones
  Ports:
    Name:  default
    Port:  7190
  State:   Ready
Events:
  Type    Reason          Age   From                   Message
  ----    ------          ----  ----                   -------
  Normal  PortAllocation  34s   gameserver-controller  Port allocated
  Normal  Creating        34s   gameserver-controller  Pod simple-udp-7pjrq created
  Normal  Scheduled       34s   gameserver-controller  Address and port populated
  Normal  Ready           27s   gameserver-controller  SDK.Ready() executed

If you look towards the bottom, you can see there is a Status > State value. We are waiting for it to move to Ready, which means that the game server is ready to accept connections.

You might also be interested to see the Events section, which outlines when various lifecycle events of the GameServer occur. We can also see when the GameServer is ready on the event stream as well - at which time the Status > Address and Status > Ports > Port have also been populated, letting us know what IP and port our client can now connect to!

Let’s retrieve the IP address and the allocated port of your Game Server :

kubectl get gs

This should output your Game Server IP address and ports, eg:

NAME               STATE   ADDRESS         PORT   NODE     AGE
simple-udp-7pjrq   Ready   35.233.183.43   7190   agones   4m

Note

If you have Agones installed on minikube the address printed will not be reachable from the host machine. Instead, use the output of minikube ip for the following section.

3. Connect to the GameServer

Note

If you have Agones installed on Google Kubernetes Engine, and are using Cloud Shell for your terminal, UDP is blocked. For this step, we recommend SSH’ing into a running VM in your project, such as a Kubernetes node. You can click the ‘SSH’ button on the Google Compute Engine Instances page to do this. Run toolbox on GKE Node to run docker container with tools and then nc command would be available.

You can now communicate with the Game Server :

Note

If you do not have netcat installed (i.e. you get a response of nc: command not found), you can install netcat by running sudo apt install netcat.

nc -u {IP} {PORT}
Hello World !
ACK: Hello World !
EXIT

You can finally type EXIT which tells the SDK to run the Shutdown command, and therefore shuts down the GameServer.

If you run kubectl describe gameserver again - either the GameServer will be gone completely, or it will be in Shutdown state, on the way to being deleted.

Next Step

If you want to use your own GameServer container make sure you have properly integrated the Agones SDK.

Docs: Google Kubernetes Engine

Mon, 01 Jan 0001 00:00:00 +0000

Before you begin

Take the following steps to enable the Kubernetes Engine API:

Visit the Kubernetes Engine page in the Google Cloud Platform Console.
Create or select a project.
Wait for the API and related services to be enabled. This can take several minutes.
Enable billing for your project.
- If you are not an existing GCP user, you may be able to enroll for a $300 US Free Trial credit.

Choosing a shell

To complete this quickstart, we can use either Google Cloud Shell or a local shell.

Google Cloud Shell is a shell environment for managing resources hosted on Google Cloud Platform (GCP). Cloud Shell comes preinstalled with the gcloud and kubectl command-line tools. gcloud provides the primary command-line interface for GCP, and kubectl provides the command-line interface for running commands against Kubernetes clusters.

If you prefer using your local shell, you must install the gcloud and kubectl command-line tools in your environment.

Cloud shell

To launch Cloud Shell, perform the following steps:

Go to Google Cloud Platform Console
From the top-right corner of the console, click the Activate Google Cloud Shell button:
A Cloud Shell session opens inside a frame at the bottom of the console. Use this shell to run gcloud and kubectl commands.
Set a compute zone in your geographical region with the following command. The compute zone will be something like us-west1-a. A full list can be found here.
```
gcloud config set compute/zone [COMPUTE_ZONE]
```

Local shell

To install gcloud and kubectl, perform the following steps:

Install the Google Cloud SDK, which includes the gcloud command-line tool.
Initialize some default configuration by running the following command.
- When asked Do you want to configure a default Compute Region and Zone? (Y/n)?, enter Y and choose a zone in your geographical region of choice.
```
gcloud init
```
Install the kubectl command-line tool by running the following command:
```
gcloud components install kubectl
```

Creating the cluster

A cluster consists of at least one cluster master machine and multiple worker machines called nodes: Compute Engine virtual machine instances that run the Kubernetes processes necessary to make them part of the cluster.

gcloud container clusters create [CLUSTER_NAME] --cluster-version=1.15 \
  --tags=game-server \
  --scopes=gke-default \
  --num-nodes=4 \
  --no-enable-autoupgrade \
  --machine-type=n1-standard-4

Flag explanations:

cluster-version: Agones requires Kubernetes version 1.15.
tags: Defines the tags that will be attached to new nodes in the cluster. This is to grant access through ports via the firewall created in the next step.
scopes: Defines the Oauth scopes required by the nodes.
num-nodes: The number of nodes to be created in each of the cluster’s zones. Default: 4. Depending on the needs of your game, this parameter should be adjusted.
no-enable-autoupgrade: Disable automatic upgrades for nodes to reduce the likelihood of in-use games being disrupted.
machine-type: The type of machine to use for nodes. Default: n1-standard-4. Depending on the needs of your game, you may wish to have smaller or larger machines.

Optional: Create a dedicated node pool for the Agones controllers. If you choose to skip this step, the Agones controllers will share the default node pool with your game servers which is fine for kicking the tires but is not recommended for a production deployment.

gcloud container node-pools create agones-system \
  --cluster=[CLUSTER_NAME] \
  --no-enable-autoupgrade \
  --node-taints agones.dev/agones-system=true:NoExecute \
  --node-labels agones.dev/agones-system=true \
  --num-nodes=1

Optional: Create a node pool for Metrics if you want to monitor the Agones system using Prometheus with Grafana or Stackdriver.

gcloud container node-pools create agones-metrics \
  --cluster=[CLUSTER_NAME] \
  --no-enable-autoupgrade \
  --node-taints agones.dev/agones-metrics=true:NoExecute \
  --node-labels agones.dev/agones-metrics=true \
  --num-nodes=1

Flag explanations:

cluster: The name of the cluster in which the node pool is created.
no-enable-autoupgrade: Disable automatic upgrades for nodes to reduce the likelihood of in-use games being disrupted.
node-taints: The Kubernetes taints to automatically apply to nodes in this node pool.
node-labels: The Kubernetes labels to automatically apply to nodes in this node pool.
num-nodes: The Agones system controllers only require a single node of capacity to run. For faster recovery time in the event of a node failure, you can increase the size to 2.

Finally, let’s tell gcloud that we are speaking with this cluster, and get auth credentials for kubectl to use.

gcloud config set container/cluster [CLUSTER_NAME]
gcloud container clusters get-credentials [CLUSTER_NAME]

Creating the firewall

We need a firewall to allow UDP traffic to nodes tagged as game-server via ports 7000-8000.

gcloud compute firewall-rules create game-server-firewall \
  --allow udp:7000-8000 \
  --target-tags game-server \
  --description "Firewall to allow game server udp traffic"

Next Steps

Continue to Install Agones.

Docs: Installing Agones on Google Kubernetes Engine using Terraform

Mon, 01 Jan 0001 00:00:00 +0000

Before you begin

Take the following steps to enable the Kubernetes Engine API:

Visit the Kubernetes Engine page in the Google Cloud Platform Console.
Create or select a project.
Wait for the API and related services to be enabled. This can take several minutes.
Enable billing for your project.
- If you are not an existing GCP user, you may be able to enroll for a $300 US Free Trial credit.

Choosing a shell

To complete this quickstart, we can use either Google Cloud Shell or a local shell.

If you prefer using your local shell, you must install the gcloud and kubectl command-line tools in your environment.

Cloud shell

To launch Cloud Shell, perform the following steps:

Go to Google Cloud Platform Console
From the top-right corner of the console, click the Activate Google Cloud Shell button:
A Cloud Shell session opens inside a frame at the bottom of the console. Use this shell to run gcloud and kubectl commands.
Set a compute zone in your geographical region with the following command. The compute zone will be something like us-west1-a. A full list can be found here.
```
gcloud config set compute/zone [COMPUTE_ZONE]
```

Local shell

To install gcloud and kubectl, perform the following steps:

Install the Google Cloud SDK, which includes the gcloud command-line tool.
Initialize some default configuration by running the following command.
- When asked Do you want to configure a default Compute Region and Zone? (Y/n)?, enter Y and choose a zone in your geographical region of choice.
```
gcloud init
```
Install the kubectl command-line tool by running the following command:
```
gcloud components install kubectl
```

Installation

An example configuration can be found here: Terraform configuration with Agones submodule .

Copy this file into a local directory where you will execute the terraform commands.

The GKE cluster created from the example configuration will contain 3 Node Pools:

"default" node pool with "game-server" tag, containing 4 nodes.
"agones-system" node pool for Agones Controller.
"agones-metrics" for monitoring and metrics collecting purpose.

Additionally, a "tiller" service account will be created with ClusterRole.

Configurable parameters:

project - your Google Cloud Project ID (required)
name - the name of the GKE cluster (default is “agones-terraform-example”)
agones_version - the version of agones to install (an empty string, which is the default, is the latest version from the Helm repository)
machine_type - machine type for hosting game servers (default is “n1-standard-4”)
node_count - count of game server nodes for the default node pool (default is “4”)
zone - the name of the zone you want your cluster to be created in (default is “us-west1-c”)
network - the name of the VPC network you want your cluster and firewall rules to be connected to (default is “default”)
log_level - possible values: Fatal, Error, Warn, Info, Debug (default is “info”)
feature_gates - a list of alpha and beta version features to enable. For example, “PlayerTracking=true&ContainerPortAllocation=true”

Warning

On the lines that read source = "git::https://github.com/googleforgames/agones.git//install/terraform/modules/gke/?ref=master" make sure to change ?ref=master to match your targeted Agones release, as Terraform modules can change between releases.

For example, if you are targeting release master, then you will want to have source = "git::https://github.com/googleforgames/agones.git//install/terraform/modules/gke/?ref=release-master" as your source.

Creating the cluster

In the directory where you created module.tf, run:

terraform init

This will cause terraform to clone the Agones repository and use the ./install/terraform folder as a starting point of Agones submodule, which contains all necessary Terraform configuration files.

Next, make sure that you can authenticate using gcloud:

gcloud auth application-default login

Now you can create your GKE cluster (optionally specifying the version of Agones you want to use):

terraform apply -var project="<YOUR_GCP_ProjectID>" [-var agones_version="1.0.0"]

To verify that the cluster was created successfully, set up your kubectl credentials:

gcloud container clusters get-credentials --zone us-west1-c agones-terraform-example

Then check that you have access to the Kubernetes cluster:

kubectl get nodes

You should have 6 nodes in Ready state.

Uninstall the Agones and delete GKE cluster

To delete all resources provisioned by Terraform:

terraform destroy -var project="<YOUR_GCP_ProjectID>"

Next Steps

Confirm Agones is up and running

Docs: Install Agones using YAML

Mon, 01 Jan 0001 00:00:00 +0000

Warning

Installing Agones with the install.yaml will setup the TLS certificates stored in this repository for securing kubernetes webhooks communication.

If you want to generate new certificates or use your own for production workloads, we recommend using the helm installation.

kubectl create namespace agones-system
kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/master/install/yaml/install.yaml

You can also find the install.yaml in the latest agones-install zip from the releases archive.

Next Steps

Confirm Agones is up and running

Docs: Unity Game Server Client SDK

Thu, 13 Jun 2019 10:17:50 +0000

Note

The Unity SDK is not feature complete in 1.2.0, but will be feature complete with the 1.3.0 release.

Check the Client SDK Documentation for more details on each of the SDK functions and how to run the SDK locally.

Download

Download the source directly from GitHub .

Prerequisites

Unity >= 2018.x (.NET 4.x)

Usage

Import this script to your unity project and attach it to GameObject.

To begin working with the SDK, get an instance of it.

var agones = agonesGameObject.GetComponent<Agones.AgonesSdk>();

To connect to the SDK server, either local or when running on Agones, run the async Connect() method. This will wait for up to 30 seconds if the SDK server has not yet started and the connection cannot be made, and will return false if there was an issue connecting.

bool ok = await agones.Connect();

To mark the game server as ready to receive player connections, call the async method Ready().

async void SomeMethod()
{
    bool ok = await agones.Ready();
}

To get the details on the backing GameServer call GameServer().

Will return null if there is an error in retrieving the GameServer record.

var gameserver = await agones.GameServer();

To mark the GameServer as Reserved for a duration call Reserve(TimeSpan duration).

ok = await agones.Reserve(duration);

To mark that the game session is completed and the game server should be shut down call Shutdown().

bool ok = await agones.Shutdown();

Similarly SetAnnotation(string key, string value) and SetLabel(string key, string value) are async methods that perform an action.

And there is no need to call Health(), it is automatically called.

To watch when the backing GameServer configuration changes call WatchGameServer(callback), where the delegate function callback will be executed every time the GameServer configuration changes.

agones.WatchGameServer(gameServer => Debug.Log($"Server - Watch {gameServer}"));

Warning

The following code causes deadlock. Do not use a Wait method with the returned Task.

void Deadlock()
{
    Task<bool> t = agones.Shutdown();
    t.Wait(); // deadlock!!!
}

Settings

The properties for the Unity Agones SDK can be found in the Inspector.

Health Interval Second
- Interval of the server sending a health ping to the Agones sidecar. (default: 5)
Health Enabled
- Whether the server sends a health ping to the Agones sidecar. (default: true)
Log Enabled
- Debug Logging Enabled. Debug logging for development of this Plugin. (default: false)

Docs: GameServer Creation, Allocation and Shutdown Lifecycle

Fri, 01 Feb 2019 02:15:18 +0000

Matchmaker requests a GameServer from a Fleet

This is the preferred workflow for a GameServer, in which an external matchmaker requests an allocation from one or more Fleets using a GameServerAllocation:

Matchmaker requires game server process registration

Scenarios in which a Matchmaker requires a game server process to register themselves with the matchmaker, and the matchmaker decides which GameServer players are sent to, this flow is common:

Warning

This does relinquish control over how GameServers are packed across the cluster to the external matchmaker. It is likely it will not do as good a job at packing and scaling as Agones.

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.

Docs: Installing Agones on AWS Elastic Kubernetes Service using Terraform

Tue, 21 Jan 2020 00:00:00 +0000

Installation

You can use Terraform to provision your Amazon EKS (Elastic Kubernetes Service) cluster and install Agones on it using the Helm Terraform provider.

An example of the EKS submodule config file can be found here: Terraform configuration with Agones submodule

Copy this file into a separate folder.

Configure your AWS CLI tool CLI configure:

aws configure

Initialise your terraform:

terraform init

Creating Cluster

By editing modules.tf you can change the parameters that you need to. For instance, the - machine_type variable.

Configurable parameters:

cluster_name - the name of the EKS cluster (default is “agones-terraform-example”)
agones_version - the version of agones to install (an empty string, which is the default, is the latest version from the Helm repository)
machine_type - EC2 instance type for hosting game servers (default is “t2.large”)
region - the location of the cluster (default is “us-west2”)
node_count - count of game server nodes for the default node pool (default is “4”)
log_level - possible values: Fatal, Error, Warn, Info, Debug (default is “info”)
feature_gates - a list of alpha and beta version features to enable. For example, “PlayerTracking=true&ContainerPortAllocation=true”

Now you can create an EKS cluster and deploy Agones on EKS:

terraform apply [-var agones_version="1.7.0"]

After deploying the cluster with Agones, you can get or update your kubeconfig by using:

aws eks --region us-west-2 update-kubeconfig --name agones-cluster

With the following output:

Added new context arn:aws:eks:us-west-2:601646756426:cluster/agones-cluster to /Users/user/.kube/config

Switch kubectl context to the recently created one:

kubectl config use-context arn:aws:eks:us-west-2:601646756426:cluster/agones-cluster

Check that you are authenticated against the recently created Kubernetes cluster:

kubectl get nodes

Uninstall the Agones and delete EKS cluster

Run the following commands to delete all Terraform provisioned resources:

terraform destroy -target module.helm_agones.helm_release.agones -auto-approve && sleep 60
terraform destroy

Note

There is an issue with the AWS Terraform provider: https://github.com/terraform-providers/terraform-provider-aws/issues/9101 Due to this issue you should remove helm release first (as stated above), otherwise terraform destroy will timeout and never succeed. Remove all created resources manually in that case, namely: 3 Auto Scaling groups, EKS cluster, and a VPC with all dependent resources.

Docs: Third Party Podcasts

Wed, 15 Jan 2020 00:00:00 +0000

2019

Nov 6 - Google Cloud Platform Podcast: Supersolid with Kami May

2018

Docs: Fleet Updates

Tue, 27 Aug 2019 03:58:19 +0000

Rolling Update Strategy

When Fleets are edited and updated, the default strategy of Agones is to roll the new version of the GameServer out to the entire Fleet, in a step by step increment and decrement by adding a chunk of the new version and removing a chunk of the current set of GameServers.

This is done while ensuring that Allocated GameServers are not deleted until they are specifically shutdown through the game servers SDK, as they are expected to have players on them.

You can see this in the Fleet.Spec.Strategy reference, with controls for how much of the Fleet is incremented and decremented at one time:

  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%

So when a Fleet is edited (any field other than replicas, see note below), either through kubectl edit/apply or via the Kubernetes API, this performs the following operations:

Adds the maxSurge number of GameServers to the Fleet.
Shutdown the maxUnavailable number of GameServers in the Fleet, skipping Allocated GameServers.
Repeat above steps until all the previous GameServer configurations have been Shutdown and deleted.

Note

When Fleet update contains only changes to the replicas parameter, then new GameServers will be created/deleted straight away, which means in that case maxSurge and maxUnavailable parameters for a RollingUpdate will not be used. The RollingUpdate strategy takes place when you update spec parameters other than replicas.

If you are using a Fleet which is scaled by a FleetAutoscaler, read the Fleetautoscaler guide for more details on how RollingUpdates with FleetAutoscalers need to be implemented.

You could also check the behaviour of the Fleet with a RollingUpdate strategy on a test Fleet to preview your upcoming updates. Use kubectl describe fleet to track scaling events in a Fleet.

Recreate Strategy

This is an optimal Fleet update strategy if you want to replace all GameServers that are not Allocated with a new version as quickly as possible.

You can see this in the Fleet.Spec.Strategy reference:

  strategy:
    type: Recreate

So when a Fleet is edited, either through kubectl edit/apply or via the Kubernetes API, this performs the following operations:

Shutdown all GameServers in the Fleet that are not currently Allocated.
Create the same number of the new version of the GameServers that were previously deleted.
Repeat above steps until all the previous GameServer configurations have been Shutdown and deleted.

Two (or more) Fleets Strategy

If you want very fine-grained control over the rate that new versions of a GameServer configuration is rolled out, or if you want to do some version of A/B testing or smoke test between different versions, running two (or more) Fleets at the same time is a good solution for this.

To do this, create a second Fleet inside your cluster, starting with zero replicas. From there you can scale this newer Fleet up and the older Fleet down as required by your specific rollout strategy.

This also allows you to rollback if issues arise with the newer version, as you can delete the newer Fleet and scale up the old Fleet to its previous levels, resulting in minimal impact to the players.

Note

For GameServerAllocation, you will need to have at least a single shared label between the GameServers in each Fleet.

GameServerAllocation Across Fleets

Since GameServerAllocation is powered by label selectors, it is possible to allocate across multiple fleets, and/or give preference to particular sets of GameServers over others. You can see details of this in the GameServerAllocation reference.

In a scenario where a new v2 version of a Fleet is being slowly scaled up in a separate Fleet from the previous v1 Fleet, we can specify that we prefer allocation to occur from the v2 Fleet, and if none are available, fallback to the v1 Fleet, like so:

apiVersion: "allocation.agones.dev/v1"
kind: GameServerAllocation
spec:
  required:
    matchLabels:
      game: my-awesome-game
  preferred:
    - matchLabels:
        agones.dev/fleet: v2

In this example, all GameServers have the label game: my-awesome-game, so the Allocation will search across both Fleets through that mechanism. The preferred label matching selector tells the allocation system to first search all GameServers with the v2 Fleet label, and if not found, search through the rest of the set.

The above GameServerAllocation can then be used while you scale up the v2 Fleet and scale down the original Fleet at the rate that you deem fit for your specific rollout.

Docs: Fleet Specification

Thu, 03 Jan 2019 03:58:52 +0000

To allocate a GameServer from a Fleet, use a GameServerAllocation.

Like any other Kubernetes resource you describe a Fleet’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 Fleet specification is available below and in the example folder for reference :

apiVersion: "agones.dev/v1"
kind: Fleet
# Fleet Metadata
# https://v1-15.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.15/#objectmeta-v1-meta
metadata:
  name: fleet-example
spec:
  # the number of GameServers to keep Ready or Allocated in this Fleet
  replicas: 2
  # 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
  # a GameServer template - see:
  # https://agones.dev/site/docs/reference/gameserver/ for all the options
  strategy:
    # The replacement strategy for when the GameServer template is changed. Default option is "RollingUpdate",
    # "RollingUpdate" will increment by maxSurge value on each iteration, while decrementing by maxUnavailable on each
    # iteration, until all GameServers have been switched from one version to another.
    # "Recreate" terminates all non-allocated GameServers, and starts up a new set with the new details to replace them.
    type: RollingUpdate
    # Only relevant when `type: RollingUpdate`
    rollingUpdate:
      # the amount to increment the new GameServers by. Defaults to 25%
      maxSurge: 25%
      # the amount to decrements GameServers by. Defaults to 25%
      maxUnavailable: 25%
  template:
    # GameServer metadata
    metadata:
      labels:
        foo: bar
    # GameServer specification
    spec:
      ports:
      - name: default
        portPolicy: Dynamic
        containerPort: 26000
      health:
        initialDelaySeconds: 30
        periodSeconds: 60
      # Parameters for game server sidecar
      sdkServer:
        logLevel: Info
        grpcPort: 9357
        httpPort: 9358
      # The GameServer's Pod template
      template:
        spec:
          containers:
          - name: simple-udp
            image: gcr.io/agones-images/udp-server:0.21

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

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 fleet should be at most 63 characters.

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

replicas is the number of GameServers to keep Ready or Allocated in this Fleet
scheduling defines how GameServers are organised across the cluster. Affects backing Pod scheduling, as well as scale down mechanics. “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.
strategy is the GameServer replacement strategy for when the GameServer template is edited.
- type is replacement strategy for when the GameServer template is changed. Default option is “RollingUpdate”, but “Recreate” is also available.
- RollingUpdate will increment by maxSurge value on each iteration, while decrementing by maxUnavailable on each iteration, until all GameServers have been switched from one version to another.
- Recreate terminates all non-allocated GameServers, and starts up a new set with the new GameServer configuration to replace them.
- rollingUpdate is only relevant when type: RollingUpdate
- maxSurge is the amount to increment the new GameServers by. Defaults to 25%
- maxUnavailable is the amount to decrements GameServers by. Defaults to 25%
template a full GameServer configuration template. See the GameServer reference for all available fields.

Fleet Scale Subresource Specification

Scale subresource is defined for a Fleet. Please refer to Kubernetes docs.

You can use the following command to scale the fleet with name simple-udp:

$ kubectl scale fleet simple-udp --replicas=10
fleet.agones.dev/simple-udp scaled

You can also use Kubernetes API to get or update the Replicas count:

curl http://localhost:8001/apis/agones.dev/v1/namespaces/default/fleets/simple-udp/scale
...
{
  "kind": "Scale",
  "apiVersion": "autoscaling/v1",
  "metadata": {
    "name": "simple-udp",
    "namespace": "default",
    "selfLink": "/apis/agones.dev/v1/namespaces/default/fleets/simple-udp/scale",
    "uid": "4dfaa310-2566-11e9-afd1-42010a8a0058",
    "resourceVersion": "292652",
    "creationTimestamp": "2019-01-31T14:41:33Z"
  },
  "spec": {
    "replicas": 10
  },
  "status": {
    "replicas": 10
  }

Also exposing a Scale subresource would allow you to configure HorizontalPodAutoscaler and PodDisruptionBudget for a fleet in the future. However these features have not been tested, and are not currently supported - but if you are looking for these features, please be sure to let us know in the ticket.

Docs: GameServer Health Checking

Thu, 03 Jan 2019 01:20:19 +0000

Disabling Health Checking

By default, health checking is enabled, but it can be turned off by setting the spec.health.disabled property to true.

SDK API

The Health() function on the SDK object needs to be called at an interval less than the spec.health.periodSeconds threshold time to be considered before it will be considered a failure.

The health check will also need to have not been called a consecutive number of times (spec.health.failureTheshold), giving it a chance to heal if it there is an issue.

Health Failure Strategy

The following is the process for what happens to a GameServer when it is unhealthy.

If the GameServer container exits with an error before the GameServer moves to Ready then, it is restarted as per the restartPolicy (which defaults to “Always”).
If the GameServer fails health checking at any point, then it doesn’t restart, but moves to an Unhealthy state.
If the GameServer container exits while in Ready, Allocated or Reserved state, it will be restarted as per the restartPolicy (which defaults to “Always”, since RestartPolicy is a Pod wide setting), but will immediately move to an Unhealthy state.
If the SDK sidecar fails, then it will be restarted, assuming the RestartPolicy is Always/OnFailure.

Fleet Management of Unhealthy GameServers

If a GameServer moves into an Unhealthy state when it is not part of a Fleet, the GameServer will remain in the Unhealthy state until explicitly deleted. This is useful for debugging Unhealthy GameServers, or if you are creating your own GameServer management layer, you can explicitly choose what to do if a GameServer becomes Unhealthy.

If a GameServer is part of a Fleet, the Fleet management system will delete any Unhealthy GameServers and immediately replace them with a brand new GameServer to ensure it has the configured number of Replicas.

Configuration Reference

  # 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

See the full GameServer example for more details

Example

C++

For a configuration that requires a health ping every 5 seconds, the example below sends a request every 2 seconds to be sure that the GameServer is under the threshold.

void doHealth(agones::SDK *sdk) {
    while (true) {
        if (!sdk->Health()) {
            std::cout << "Health ping failed" << std::endl;
        } else {
            std::cout << "Health ping sent" << std::endl;
        }
        std::this_thread::sleep_for(std::chrono::seconds(2));
    }
}

int main() {
    agones::SDK *sdk = new agones::SDK();
    bool connected = sdk->Connect();
    if (!connected) {
        return -1;
    }
    std::thread health (doHealth, sdk);

    // ...  run the game server code

}

Full Game Server

Also look in the examples directory.

Docs: C++ Game Server Client SDK

Wed, 02 Jan 2019 10:17:50 +0000

Check the Client SDK Documentation for more details on each of the SDK functions and how to run the SDK locally.

Download

Download the source from the Releases Page or directly from GitHub .

Usage

The C++ SDK is specifically designed to be as simple as possible, and deliberately doesn’t include any kind of singleton management, or threading/asynchronous processing to allow developers to manage these aspects as they deem appropriate for their system.

We may consider these types of features in the future, depending on demand.

To begin working with the SDK, create an instance of it:

agones::SDK *sdk = new agones::SDK();

To connect to the SDK server, either local or when running on Agones, run the sdk->Connect() method. This will block for up to 30 seconds if the SDK server has not yet started and the connection cannot be made, and will return false if there was an issue connecting.

bool ok = sdk->Connect();

To send a health check call sdk->Health(). This is a synchronous request that will return false if it has failed in any way. Read GameServer Health Checking for more details on the game server health checking strategy.

bool ok = sdk->Health();

To mark the game server as ready to receive player connections, call sdk->Ready(). This will return a grpc::Status object, from which we can call status.ok() to determine if the function completed successfully.

For more information you can also look at the gRPC Status reference.

grpc::Status status = sdk->Ready();
if (!status.ok()) { ... }

To mark the game server as allocated, call sdk->Allocate(). This will return a grpc::Status object, from which we can call status.ok() to determine if the function completed successfully.

For more information you can also look at the gRPC Status reference.

grpc::Status status = sdk->Allocate();
if (!status.ok()) { ... }

To mark the game server as reserved, call sdk->Reserve(seconds). This will return a grpc::Status object, from which we can call status.ok() to determine if the function completed successfully.

For more information you can also look at the gRPC Status reference.

grpc::Status status = sdk->Reserve(std::chrono::seconds(N));
if (!status.ok()) { ... }

To mark that the game session is completed and the game server should be shut down call sdk->Shutdown(). This will return a grpc::Status object, from which we can call status.ok() to determine if the function completed successfully.

For more information you can also look at the gRPC Status reference.

grpc::Status status = sdk->Shutdown();
if (!status.ok()) { ... }

To set a Label on the backing GameServer call sdk->SetLabel(key, value). This will return a grpc::Status object, from which we can call status.ok() to determine if the function completed successfully.

For more information you can also look at the gRPC Status reference.

grpc::Status status = sdk->SetLabel("test-label", "test-value");
if (!status.ok()) { ... }

To set an Annotation on the backing GameServer call sdk->SetAnnotation(key, value). This will return a grpc::Status object, from which we can call status.ok() to determine if the function completed successfully.

For more information you can also look at the gRPC Status reference.

status = sdk->SetAnnotation("test-annotation", "test value");
if (!status.ok()) { ... }

To get the details on the backing GameServer call sdk->GameServer(&gameserver), passing in a agones::dev::sdk::GameServer* to push the results of the GameServer configuration into.

This function will return a grpc::Status object, from which we can call status.ok() to determine if the function completed successfully.

agones::dev::sdk::GameServer gameserver;
grpc::Status status = sdk->GameServer(&gameserver);
if (!status.ok()) {...}

To get updates on the backing GameServer as they happen, call sdk->WatchGameServer([](const agones::dev::sdk::GameServer& gameserver){...}).

This will call the passed in std::function synchronously (this is a blocking function, so you may want to run it in its own thread) whenever the backing GameServer is updated.

sdk->WatchGameServer([](const agones::dev::sdk::GameServer& gameserver){
  std::cout << "GameServer Update:\n"                                 //
            << "\tname: " << gameserver.object_meta().name() << "\n"  //
            << "\tstate: " << gameserver.status().state() << "\n"
            << std::flush;
});

For more information, you can also read the SDK Overview, check out sdk.h and also look at the C++ example .

Failure

When running on Agones, the above functions should only fail under exceptional circumstances, so please file a bug if it occurs.

Building the Libraries from source

CMake is used to build SDK for all supported platforms (Linux/Window/MacOS).

Prerequisites

CMake >= 3.13.0
Git
C++14 compiler

Agones SDK depends on gRPC. If CMake cannot find gRPC with find_package(), it downloads and builds gRPC. There are some extra prerequisites for OpenSSL on Windows, see documentation:

Perl
NASM

Note that OpenSSL is not used in Agones SDK, but it is required to have full successfull build of gRPC.

Options

Following options are available:

AGONES_THIRDPARTY_INSTALL_PATH (default is CMAKE_INSTALL_PREFIX) - installation path for Agones prerequisites (used only if gRPC and Protobuf are not found by find_package)
AGONES_ZLIB_STATIC (default is ON) - use static version of zlib for gRPC

(Windows only):

AGONES_BUILD_THIRDPARTY_DEBUG (default is OFF) - build both debug and release versions of SDK’s prerequisites. Option is not used if you already have built gRPC.
AGONES_OPENSSL_CONFIG_STRING (default is VC-WIN64A) - arguments to configure OpenSSL build (documentation). Used only if OpenSSL and gRPC is built by Agones.

Linux / MacOS

mkdir -p .build
cd .build
cmake .. -DCMAKE_BUILD_TYPE=Release -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=./install
cmake --build . --target install

Windows

Building with Visual Studio:

md .build
cd .build
cmake .. -G "Visual Studio 15 2017 Win64" -DCMAKE_INSTALL_PREFIX=./install
cmake --build . --config Release --target install

Building with NMake

md .build
cd .build
cmake .. -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=./install
cmake --build . --target install

Remarks

CMAKE_INSTALL_PREFIX may be skipped if it is OK to install Agones SDK to a default location (usually /usr/local or c:/Program Files/Agones).

CMake option -Wno-dev is specified to suppress CMP0048 deprecation warning for gRPC build.

If AGONES_ZLIB_STATIC is set to OFF, ensure that you have installed zlib. For Windows it’s enough to copy zlib.dll near to gameserver executable. For Linux/Mac usually no actions are needed.

Using SDK

In CMake-based projects it’s enough to specify a folder where SDK is installed with CMAKE_PREFIX_PATH and use find_package(agones CONFIG REQUIRED) command. For example: cpp-simple . It may be useful to disable some protobuf warnings in your project.

Docs: Quickstart: Create a Game Server Fleet

Wed, 02 Jan 2019 06:42:20 +0000

Prerequisites

The following prerequisites are required to create a GameServer:

A Kubernetes cluster with the UDP port range 7000-8000 open on each node.
Agones controller installed in the targeted cluster
kubectl properly configured
Netcat which is already installed on most Linux/macOS distributions, for windows you can use WSL.

If you don’t have a Kubernetes cluster you can follow these instructions to create a cluster on Google Kubernetes Engine (GKE), Minikube or Azure Kubernetes Service (AKS), and install Agones.

While not required, you may wish to go through the Create a Game Server quickstart before this one.

Objectives

Create a Fleet in Kubernetes using Agones custom resource.
Scale the Fleet up from its initial configuration.
Request a GameServer allocation from the Fleet to play on.
Connect to the allocated GameServer.
Deploy a new GameServer configuration to the Fleet

1. Create a Fleet

Let’s create a Fleet using the following command :

kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/simple-udp/fleet.yaml

You should see a successful output similar to this :

fleet "simple-udp" created

This has created a Fleet record inside Kubernetes, which in turn creates two warm GameServers that are available to be allocated for a game session.

kubectl get fleet

It should look something like this:

NAME         SCHEDULING   DESIRED   CURRENT   ALLOCATED   READY     AGE
simple-udp   Packed       2         3         0           2         9m

You can also see the GameServers that have been created by the Fleet by running kubectl get gameservers, the GameServer will be prefixed by simple-udp.

NAME                     STATE     ADDRESS            PORT   NODE      AGE
simple-udp-llg4x-rx6rc   Ready     192.168.122.205    7752   minikube   9m
simple-udp-llg4x-v6g2r   Ready     192.168.122.205    7623   minikube   9m

For the full details of the YAML file head to the Fleet Specification Guide

2. Fetch the Fleet status

Let’s wait for the two GameServers to become ready.

watch kubectl describe fleet simple-udp

Name:         simple-udp
Namespace:    default
Labels:       <none>
Annotations:  kubectl.kubernetes.io/last-applied-configuration={"apiVersion":"agones.dev/v1","kind":"Fleet","metadata":{"annotations":{},"name":"simple-udp","namespace":"default"},"spec":{"replicas":2,...
API Version:  agones.dev/v1
Kind:         Fleet
Metadata:
  Cluster Name:
  Creation Timestamp:  2018-07-01T18:55:35Z
  Generation:          1
  Resource Version:    24685
  Self Link:           /apis/agones.dev/v1/namespaces/default/fleets/simple-udp
  UID:                 56710a91-7d60-11e8-b2dd-08002703ef08
Spec:
  Replicas:  2
  Strategy:
    Rolling Update:
      Max Surge:        25%
      Max Unavailable:  25%
    Type:               RollingUpdate
  Template:
    Metadata:
      Creation Timestamp:  <nil>
    Spec:
      Health:
      Ports:
        Container Port:  7654
        Name:            default
        Port Policy:     Dynamic
      Template:
        Metadata:
          Creation Timestamp:  <nil>
        Spec:
          Containers:
            Image:  gcr.io/agones-images/udp-server:0.21
            Name:   simple-udp
            Resources:
Status:
  Allocated Replicas:  0
  Ready Replicas:      2
  Replicas:            2
Events:
  Type    Reason                 Age   From              Message
  ----    ------                 ----  ----              -------
  Normal  CreatingGameServerSet  13s   fleet-controller  Created GameServerSet simple-udp-wlqnd

If you look towards the bottom, you can see there is a section of Status > Ready Replicas which will tell you how many GameServers are currently in a Ready state. After a short period, there should be 2 Ready Replicas.

3. Scale up the Fleet

Let’s scale up the Fleet from 2 replicates to 5.

Run kubectl scale fleet simple-udp --replicas=5 to change Replicas count from 2 to 5.

If we now run kubectl get gameservers we should see 5 GameServers prefixed by simple-udp.

NAME                     STATE    ADDRESS           PORT    NODE       AGE
simple-udp-sdhzn-kcmh6   Ready    192.168.122.205   7191    minikube   52m
simple-udp-sdhzn-pdpk5   Ready    192.168.122.205   7752    minikube   53m
simple-udp-sdhzn-r4d6x   Ready    192.168.122.205   7623    minikube   52m
simple-udp-sdhzn-wng5k   Ready    192.168.122.205   7709    minikube   53m
simple-udp-sdhzn-wnhsw   Ready    192.168.122.205   7478    minikube   52m

4. Allocate a Game Server from the Fleet

Since we have a fleet of warm gameservers, we need a way to request one of them for usage, and mark that it has players access it (and therefore, it should not be deleted until they are finished with it).

Note

In production, you would likely do the following through a Kubernetes API call, but we can also do this through kubectl as well, and ask it to return the response in yaml so that we can see what has happened.

We can do the allocation of a GameServer for usage through a GameServerAllocation, which will both return to us the details of a GameServer (assuming one is available), and also move it to the Allocated state, which demarcates that it has players on it, and should not be removed until SDK.Shutdown() is called, or it is manually deleted.

It is worth noting that there is nothing specific that ties a GameServerAllocation to a fleet. A GameServerAllocation uses a label selector to determine what group of GameServers it will attempt to allocate out of. That being said, a Fleet and GameServerAllocation are often used in conjunction.

This example uses the label selector to specifically target the simple-udp fleet that we just created.

kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/simple-udp/gameserverallocation.yaml -o yaml

For the full details of the YAML file head to the GameServerAllocation Specification Guide

You should get back a response that looks like the following:

apiVersion: allocation.agones.dev/v1
kind: GameServerAllocation
metadata:
  creationTimestamp: 2019-02-19T02:13:12Z
  name: simple-udp-dph9b-hfk24
  namespace: default
spec:
  metadata: {}
  required:
    matchLabels:
      agones.dev/fleet: simple-udp
  scheduling: Packed
status:
  address: 192.168.122.152
  gameServerName: simple-udp-dph9b-hfk24
  nodeName: minikube
  ports:
  - name: default
    port: 7714
  state: Allocated

If you look at the status section, there are several things to take note of. The state value will tell if a GameServer was allocated or not. If a GameServer could not be found, this will be set to UnAllocated. If there are too many concurrent requests overwhelmed the system, state will be set to Contention even though there are available GameServers.

However, we see that the status.state value was set to Allocated. This means you have been successfully allocated a GameServer out of the fleet, and you can now connect your players to it!

You can see various immutable details of the GameServer in the status - the address, ports and the name of the GameServer, in case you want to use it to retrieve more details.

We can also check to see how many GameServers you have Allocated vs Ready with the following command (“gs” is shorthand for “gameserver”).

kubectl get gs

This will get you a list of all the current GameServers and their Status.State.

NAME                     STATE       ADDRESS           PORT   NODE      AGE
simple-udp-sdhzn-kcmh6   Ready       192.168.122.205   7191   minikube  52m
simple-udp-sdhzn-pdpk5   Ready       192.168.122.205   7752   minikube  53m
simple-udp-sdhzn-r4d6x   Allocated   192.168.122.205   7623   minikube  52m
simple-udp-sdhzn-wng5k   Ready       192.168.122.205   7709   minikube  53m
simple-udp-sdhzn-wnhsw   Ready       192.168.122.205   7478   minikube  52m

Note

GameServerAllocations are create only and not stored for performance reasons, so you won’t be able to list them after they have been created - but you can see their effects on GameServers

A handy trick for checking to see how many GameServers you have Allocated vs Ready, run the following:

kubectl get gs

This will get you a list of all the current GameServers and their Status > State.

NAME                     STATE       ADDRESS          PORT   NODE        AGE
simple-udp-tfqn7-c9tqz   Ready       192.168.39.150   7136   minikube    52m
simple-udp-tfqn7-g8fhq   Allocated   192.168.39.150   7148   minikube    53m
simple-udp-tfqn7-p8wnl   Ready       192.168.39.150   7453   minikube    52m
simple-udp-tfqn7-t6bwp   Ready       192.168.39.150   7228   minikube    53m
simple-udp-tfqn7-wkb7b   Ready       192.168.39.150   7226   minikube    52m

5. Scale down the Fleet

Not only can we scale our fleet up, but we can scale it down as well.

The nice thing about Agones is that it is smart enough to know when GameServers have been moved to Allocated and will automatically leave them running on scale down – as we assume that players are playing on this game server, and we shouldn’t disconnect them!

Let’s scale down our Fleet to 0 (yep! you can do that!), and watch what happens.

Run kubectl scale fleet simple-udp --replicas=0 to change Replicas count from 5 to 0.

It may take a moment for all the GameServers to shut down, so let’s watch them all and see what happens:

watch kubectl get gs

Eventually, one by one they will be removed from the list, and you should simply see:

NAME                     STATUS      ADDRESS          PORT    NODE       AGE
simple-udp-tfqn7-g8fhq   Allocated   192.168.39.150   7148    minikube   55m

That lone Allocated GameServer is left all alone, but still running!

If you would like, try editing the Fleet configuration replicas field and watch the list of GameServers grow and shrink.

6. Connect to the GameServer

Since we’ve only got one allocation, we’ll just grab the details of the IP and port of the only allocated GameServer:

kubectl get gameservers | grep Allocated | awk '{print $3":"$4 }'

This should output your Game Server IP address and port. (eg 10.130.65.208:7936)

You can now communicate with the GameServer:

nc -u {IP} {PORT}
Hello World !
ACK: Hello World !
EXIT

You can finally type EXIT which tells the SDK to run the Shutdown command, and therefore shuts down the GameServer.

If you run kubectl describe gs | grep State again - either the GameServer will be replaced with a new, Ready GameServer , or it will be in Shutdown state, on the way to being deleted.

Since we are running a Fleet, Agones will always do it’s best to ensure there are always the configured number of GameServers in the pool in either a Ready or Allocated state.

7. Deploy a new version of the GameServer on the Fleet

We can also change the configuration of the GameServer of the running Fleet, and have the changes roll out, without interrupting the currently Allocated GameServers.

Let’s take this for a spin! Run kubectl scale fleet simple-udp --replicas=5 to return Replicas count back to 5.

Let’s also allocate ourselves a GameServer

kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/simple-udp/gameserverallocation.yaml -o yaml

We should now have four Ready GameServers and one Allocated.

We can check this by running kubectl get gs.

NAME                     STATE       ADDRESS          PORT   NODE       AGE 
simple-udp-tfqn7-c9tz7   Ready       192.168.39.150   7136   minikube   5m       
simple-udp-tfqn7-g8fhq   Allocated   192.168.39.150   7148   minikube   5m   
simple-udp-tfqn7-n0wnl   Ready       192.168.39.150   7453   minikube   5m   
simple-udp-tfqn7-hiiwp   Ready       192.168.39.150   7228   minikube   5m   
simple-udp-tfqn7-w8z7b   Ready       192.168.39.150   7226   minikube   5m

In production, we’d likely be changing a containers > image configuration to update our Fleet to run a new game server process, but to make this example simple, change containerPort from 7654 to 6000.

Run kubectl edit fleet simple-udp, and make the necessary changes, and then save and exit your editor.

This will start the deployment of a new set of GameServers running with a Container Port of 6000.

Warning

This will make it such that you can no longer connect to the simple-udp game server.

Run watch kubectl get gs until you can see that there is one with a containerPort of 7654, which is the Allocated GameServer, and four instances with a containerPort of 6000 which is the new configuration.

You have now deployed a new version of your game!

Next Steps

Have a look at the GameServerAllocation specification, and see how the extra functionality can enable smoke testing, server information communication, and more.
You can now create a fleet autoscaler to automatically resize your fleet based on the actual usage. See Create a Fleet Autoscaler.
Have a look at the GameServer Creation, Allocation and Shutdown Lifecycle diagram, to give you a good overview of how all the pieces fit together - from creating to integrating with a matchmaker.
Or if you want to try to use your own GameServer container make sure you have properly integrated the Agones SDK.
If you would like to learn how to programmatically allocate a Game Server from the fleet, see how to Access Agones via the Kubernetes API or alternatively use the Allocator Service, depending on your needs.

Docs: Amazon Elastic Kubernetes Service

Mon, 01 Jan 0001 00:00:00 +0000

Create your EKS Cluster using the Getting Started Guide.

Possible steps are the following:

Create new IAM role for cluster management.
Run aws configure to authorize your awscli with proper AWS Access Key ID and AWS Secret Access Key.

Create an example cluster:

eksctl create cluster \
--name prod \
--version 1.15 \
--nodegroup-name standard-workers \
--node-type t3.medium \
--nodes 3 \
--nodes-min 3 \
--nodes-max 4 \
--node-ami auto

Note

EKS does not use the normal Kubernetes networking since it is incompatible with Amazon VPC networking.

Allowing UDP Traffic

For Agones to work correctly, we need to allow UDP traffic to pass through to our EKS cluster worker nodes. To achieve this, we must update the workers’ nodepool SG (Security Group) with the proper rule. A simple way to do that is:

Log in to the AWS Management Console
Go to the VPC Dashboard and select Security Groups
Find the Security Group for the workers nodepool, which will be named something like eksctl-[cluster-name]-nodegroup-[cluster-name]-workers/SG
Select Inbound Rules
Edit Rules to add a new Custom UDP Rule with a 7000-8000 port range and an appropriate Source CIDR range (0.0.0.0/0 allows all traffic)

Next Steps

Continue to Install Agones.

Docs: Installing Agones on Azure Kubernetes Service using Terraform

Mon, 01 Jan 0001 00:00:00 +0000

Installation

Install az utility by following these instructions.

The example of AKS submodule configuration could be found here: Terraform configuration with Agones submodule

Copy module.tf file into a separate folder.

az login

Configure your terraform:

terraform init

Now you can deploy your cluster (use variables from the above az ad sp create-for-rbac command output):

terraform apply -var client_id="<appId>" -var client_secret="<password>"

Once you created all resources on AKS you can get the credentials so that you can use kubectl to configure your cluster:

az aks get-credentials --resource-group agonesRG --name test-cluster

Check that you have access to the Kubernetes cluster:

kubectl get nodes

Configurable parameters:

log_level - possible values: Fatal, Error, Warn, Info, Debug (default is “info”)
cluster_name - the name of the AKS cluster (default is “agones-terraform-example”)
agones_version - the version of agones to install (an empty string, which is the default, is the latest version from the Helm repository)
machine_type - node machine type for hosting game servers (default is “Standard_D2_v2”)
disk_size - disk size of the node
region - the location of the cluster
node_count - count of game server nodes for the default node pool (default is “4”)
feature_gates - a list of alpha and beta version features to enable. For example, “PlayerTracking=true&ContainerPortAllocation=true”

Uninstall the Agones and delete AKS cluster

Run next command to delete all Terraform provisioned resources:

terraform destroy

Reference

Details on how you can authenticate your AKS terraform provider using official instructions

Next Steps

Confirm Agones is up and running

Docs: Install Agones using Helm

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Helm package manager 2.10.0+
Supported Kubernetes Cluster

Installing the Chart

Note

If you don’t have Helm installed locally, or Tiller installed in your Kubernetes cluster, read the Using Helm documentation to get started.

To install the chart with the release name my-release using our stable helm repository:

$ helm repo add agones https://agones.dev/chart/stable
$ helm install --name my-release --namespace agones-system agones/agones

We recommend to install Agones in its own namespaces (like agones-system as shown above) you can use the helm --namespace parameter to specify a different namespace.

When running in production, Agones should be scheduled on a dedicated pool of nodes, distinct from where Game Servers are scheduled for better isolation and resiliency. By default Agones prefers to be scheduled on nodes labeled with agones.dev/agones-system=true and tolerates node taint agones.dev/agones-system=true:NoExecute. If no dedicated nodes are available, Agones will run on regular nodes, but that’s not recommended for production use. For instructions on setting up a dedicated node pool for Agones, see the Agones installation instructions for your preferred environment.

The command deploys Agones on the Kubernetes cluster with the default configuration. The configuration section lists the parameters that can be configured during installation.

Tip

List all releases using helm list

Note

If you are installing a development build of Agones (i.e. not the 1.7.0 release), you will need to install Agones the following way:

$ cd install/helm/
$ helm install --name my-release --namespace agones-system agones --set agones.image.tag=1.7.0-481970d

where 481970d - is a short hash of the latest commit.

The full list of available tags is here

Namespaces

By default Agones is configured to work with game servers deployed in the default namespace. If you are planning to use another namespace you can configure Agones via the parameter gameservers.namespaces.

For example to use default and xbox namespaces:

$ kubectl create namespace xbox
$ helm install --set "gameservers.namespaces={default,xbox}" --namespace agones-system --name my-release agones/agones

Note

You need to create your namespaces before installing Agones.

If you want to add a new namespace afterward simply upgrade your release:

$ kubectl create namespace ps4
$ helm upgrade --set "gameservers.namespaces={default,xbox,ps4}" my-release agones/agones

RBAC

By default, agones.rbacEnabled is set to true. This enables RBAC support in Agones and must be true if RBAC is enabled in your cluster.

The chart will take care of creating the required service accounts and roles for Agones.

If you have RBAC disabled, or to put it another way, ABAC enabled, you should set this value to false.

Uninstalling the Chart

To uninstall/delete the my-release deployment:

$ helm delete my-release

The command removes all the Kubernetes components associated with the chart and deletes the release.

Configuration

The following tables lists the configurable parameters of the Agones chart and their default values.

Parameter	Description	Default
`agones.rbacEnabled`	Creates RBAC resources. Must be set for any cluster configured with RBAC	`true`
`agones.registerWebhooks`	Registers the webhooks used for the admission controller	`true`
`agones.registerApiService`	Registers the apiservice(s) used for the Kubernetes API extension	`true`
`agones.registerServiceAccounts`	Attempts to create service accounts for the controllers	`true`
`agones.createPriorityClass`	Attempts to create priority classes for the controllers	`true`
`agones.priorityClassName`	Name of the priority classes to create	`agones-system`
`agones.featureGates`	A URL query encoded string of Flags to enable/disable e.g. `Example=true&OtherThing=false`. Any value accepted by strconv.ParseBool(string) can be used as a boolean value	``
`agones.crds.install`	Install the CRDs with this chart. Useful to disable if you want to subchart (since crd-install hook is broken), so you can copy the CRDs into your own chart.	`true`
`agones.crds.cleanupOnDelete`	Run the pre-delete hook to delete all GameServers and their backing Pods when deleting the helm chart, so that all CRDs can be removed on chart deletion	`true`
`agones.metrics.prometheusServiceDiscovery`	Adds annotations for Prometheus ServiceDiscovery (and also Strackdriver)	`true`
`agones.metrics.prometheusEnabled`	Enables controller metrics on port `8080` and path `/metrics`	`true`
`agones.metrics.stackdriverEnabled`	Enables Stackdriver exporter of controller metrics	`false`
`agones.metrics.stackdriverProjectID`	This overrides the default gcp project id for use with stackdriver	``
`agones.metrics.stackdriverLabels`	A set of default labels to add to all stackdriver metrics generated in form of key value pair (`key=value,key2=value2`). By default metadata are automatically added using Kubernetes API and GCP metadata enpoint.	``
`agones.serviceaccount.controller`	Service account name for the controller	`agones-controller`
`agones.serviceaccount.sdk`	Service account name for the sdk	`agones-sdk`
`agones.image.registry`	Global image registry for all images	`gcr.io/agones-images`
`agones.image.tag`	Global image tag for all images	`1.7.0`
`agones.image.controller.name`	Image name for the controller	`agones-controller`
`agones.image.controller.pullPolicy`	Image pull policy for the controller	`IfNotPresent`
`agones.image.controller.pullSecret`	Image pull secret for the controller, allocator, sdk and ping image. Should be created both in `agones-system` and `default` namespaces	``
`agones.image.sdk.name`	Image name for the sdk	`agones-sdk`
`agones.image.sdk.tag`	Image tag for the sdk	value of `agones.image.tag`
`agones.image.sdk.cpuRequest`	The cpu request for sdk server container	`30m`
`agones.image.sdk.cpuLimit`	The cpu limit for the sdk server container	`0` (none)
`agones.image.sdk.memoryRequest`	The memory request for sdk server container	`0` (none)
`agones.image.sdk.memoryLimit`	The memory limit for the sdk server container	`0` (none)
`agones.image.sdk.alwaysPull`	Tells if the sdk image should always be pulled	`false`
`agones.image.ping.name`	Image name for the ping service	`agones-ping`
`agones.image.ping.tag`	Image tag for the ping service	value of `agones.image.tag`
`agones.image.ping.pullPolicy`	Image pull policy for the ping service	`IfNotPresent`
`agones.controller.http.port`	Port to use for liveness probe service and metrics	`8080`
`agones.controller.healthCheck.initialDelaySeconds`	Initial delay before performing the first probe (in seconds)	`3`
`agones.controller.healthCheck.periodSeconds`	Seconds between every liveness probe (in seconds)	`3`
`agones.controller.healthCheck.failureThreshold`	Number of times before giving up (in seconds)	`3`
`agones.controller.healthCheck.timeoutSeconds`	Number of seconds after which the probe times out (in seconds)	`1`
`agones.controller.resources`	Controller resource requests/limit	`{}`
`agones.controller.generateTLS`	Set to true to generate TLS certificates or false to provide your own certificates in `certs/*`	`true`
`agones.controller.nodeSelector`	Controller node labels for pod assignment	`{}`
`agones.controller.tolerations`	Controller toleration labels for pod assignment	`[]`
`agones.controller.affinity`	Controller affinity settings for pod assignment	`{}`
`agones.controller.numWorkers`	Number of workers to spin per resource type	`64`
`agones.controller.apiServerQPS`	Maximum sustained queries per second that controller should be making against API Server	`100`
`agones.controller.apiServerQPSBurst`	Maximum burst queries per second that controller should be making against API Server	`200`
`agones.controller.logLevel`	Agones Controller Log level. Log only entries with that severity and above	`info`
`agones.controller.persistentLogs`	Store Agones controller logs in a temporary volume attached to a container for debugging	`true`
`agones.controller.persistentLogsSizeLimitMB`	Maximum total size of all Agones container logs in MB	`10000`
`agones.ping.install`	Whether to install the ping service	`true`
`agones.ping.replicas`	The number of replicas to run in the deployment	`2`
`agones.ping.http.expose`	Expose the http ping service via a Service	`true`
`agones.ping.http.response`	The string response returned from the http service	`ok`
`agones.ping.http.port`	The port to expose on the service	`80`
`agones.ping.http.serviceType`	The Service Type of the HTTP Service	`LoadBalancer`
`agones.ping.udp.expose`	Expose the udp ping service via a Service	`true`
`agones.ping.udp.rateLimit`	Number of UDP packets the ping service handles per instance, per second, per sender	`20`
`agones.ping.udp.port`	The port to expose on the service	`80`
`agones.ping.udp.serviceType`	The Service Type of the UDP Service	`LoadBalancer`
`agones.ping.healthCheck.initialDelaySeconds`	Initial delay before performing the first probe (in seconds)	`3`
`agones.ping.healthCheck.periodSeconds`	Seconds between every liveness probe (in seconds)	`3`
`agones.ping.healthCheck.failureThreshold`	Number of times before giving up (in seconds)	`3`
`agones.ping.healthCheck.timeoutSeconds`	Number of seconds after which the probe times out (in seconds)	`1`
`agones.ping.resources`	Ping pods resource requests/limit	`{}`
`agones.ping.nodeSelector`	Ping node labels for pod assignment	`{}`
`agones.ping.tolerations`	Ping toleration labels for pod assignment	`[]`
`agones.ping.affinity`	Ping affinity settings for pod assignment	`{}`
`agones.allocator.install`	Whether to install the allocator service	`true`
`agones.allocator.replicas`	The number of replicas to run in the deployment	`3`
`agones.allocator.http.port`	The port to expose on the service	`443`
`agones.allocator.http.serviceType`	The Service Type of the HTTP Service	`LoadBalancer`
`agones.allocator.generateTLS`	Set to true to generate TLS certificates or false to provide certificates in `certs/allocator/*`	`true`
`agones.allocator.tolerations`	Allocator toleration labels for pod assignment	`[]`
`agones.allocator.affinity`	Allocator affinity settings for pod assignment	`{}`
`gameservers.namespaces`	a list of namespaces you are planning to use to deploy game servers	`["default"]`
`gameservers.minPort`	Minimum port to use for dynamic port allocation	`7000`
`gameservers.maxPort`	Maximum port to use for dynamic port allocation	`8000`

New Configuration Features:

Parameter	Description	Default
`helm.installTests`	Add an ability to run `helm test agones` to verify the installation	`8000`

Specify each parameter using the --set key=value[,key=value] argument to helm install. For example,

$ helm install --name my-release --namespace agones-system \
  --set gameservers.minPort=1000,gameservers.maxPort=5000 agones

The above command will deploy Agones controllers to agones-system namespace. Additionally Agones will use a dynamic GameServers’ port allocation range of 1000-5000.

Alternatively, a YAML file that specifies the values for the parameters can be provided while installing the chart. For example,

$ helm install --name my-release --namespace agones-system -f values.yaml agones/agones

Tip

You can use the default values.yaml

Helm test

Tip

In order to use helm test command described in this section you need to set helm.installTests helm parameter to true.

Check the Agones installation by running the following command:

$ helm test my-release --cleanup                     
RUNNING: agones-test
PASSED: agones-test

This test would create a GameServer resource and delete it afterwards.

Tip

If you receive the following error:

RUNNING: agones-test
ERROR: pods "agones-test" already exists
Error: 1 test(s) failed

That mean that you skiped --cleanup flag and you should either delete agones-test pod manually or run with the same test helm test my-release --cleanup two more times.

TLS Certificates

By default agones chart generates tls certificates used by the admission controller, while this is handy, it requires the agones controller to restart on each helm upgrade command. For most use cases the controller would have required a restart anyway (eg: controller image updated). However if you really need to avoid restarts we suggest that you turn off tls automatic generation (agones.controller.generateTLS to false) and provide your own certificates (certs/server.crt,certs/server.key).

Tip

You can use our script located at cert.sh to generate them.

Next Steps

Confirm Agones is up and running

Docs: Player Tracking

Tue, 19 May 2020 00:00:00 +0000

Warning

The Player Tracking feature is currently Alpha, not enabled by default, and may change in the future.

Use the Feature Gate PlayerTracking to enable and test this feature.

See the Feature Gate documentation for details on how to enable features.

Managing GameServer Capacities

To track your GameServer current player capacity, Agones gives you the ability to both set an initial capacity at GameServer creation, as well be able to change it during the lifecycle of the GameServer through the Agones SDK.

To set the initial capacity, you can do so via GameServer.Spec.Players.InitialCapacity like so:

apiVersion: "agones.dev/v1"
kind: GameServer
metadata:
  name: "gs-example"
spec:
  # ...
  players:
    # set this GameServer's initial player capacity to 10
    initialCapacity: 10

From there, if you need to change the capacity of the GameSever as gameplay is in progress, you can also do so via SDK.Alpha().SetPlayerCapacity(count)

The current player capacity is represented in GameServer.Status.Players.Capacity resource value.

We can see this in action, when we look at the Status section of a GameServer resource , wherein the capacity has been set to 20:

...
Status:
  Address:    14.81.195.72
  Node Name:  gke-test-cluster-default-6cd0ba67-1mps
  Players:
    Capacity:  20
    Count:     0
    Ids:       <nil>
  Ports:
    Name:          gameport
    Port:          7983
  Reserved Until:  <nil>
  State:           Ready

From the SDK, the game server binary can also retrieve the current player capacity via SDK.Alpha().GetPlayerCapacity().

Note

Changing the capacity value here has no impact on players actually connected to or trying to connect to your server, as that is not a responsibility of Agones.

This functionality is for tracking purposes only.

Connecting and Disconnecting Players

As players connect and disconnect from your game, the Player Tracking functions enable you to track which players are currently connected.

It assumed that each player that connects has a unique token that identifies them as a player.

When a player connects to the game server binary, calling SDK.Alpha().PlayerConnect(playerID) with the unique player token will register them as connected, and store their player id.

At disconnection time, call SDK.Alpha().PlayerDisconnect(playerID) , which will deregister them and remove their player id from the list.

Each of these playerIDs is stored on GameServer.Status.Players.IDs, and the current count of connected players can be seen in GameServer.Status.Players.Count.

You can see this in action below in the GameServer Status section, where there are 4 players connected:

...
Status:
  Address:    39.82.196.74
  Node Name:  gke-test-cluster-default-6cd0ba77-1mps
  Players:
    Capacity:  10
    Count:     4
    Ids:
      xy8a
      m0ux
      71nj
      lpq5
  Ports:
    Name:          gameport
    Port:          7166
  Reserved Until:  <nil>
  State:           Ready

Note

Calling PlayerConnect or PlayerDisconnect functions will not connect or disconnect players, as that is not under the control of Agones.

This functionality is for tracking purposes only.

Checking Player Data

Not only is the connected player data stored on the GameServer resource, it is also stored in memory within the SDK, so that it can be used from within the game server binary as a realtime, thread safe, registry of connected players.

Therefore, if you want to:

Get the current player count, call SDK.Alpha().GetPlayerCount()
Check if a specific player is connected, call SDK.Alpha().IsPlayerConnected(playerID)
Retrieve the full list of connected players, call SDK.Alpha().GetConnectedPlayers()

Next Steps

Review the Player Tracking SDK Reference

Docs: Third Party Libraries and Tools

Fri, 15 May 2020 00:00:00 +0000

Messaging

Libraries or applications that implement messaging systems.

Agones Event Broadcaster - Broadcast Agones events to the external world.

Docs: GameServerAllocation Specification

Sun, 07 Jul 2019 03:58:52 +0000

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.
  # GameServers still have the hard requirement to be `Ready` to be allocated from
  # however we can also make available `matchExpressions` for even greater
  # flexibility.
  # Below is an example of a GameServer allocated against a given fleet.
  # See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ for more details
  required:
    matchLabels:
      game: my-game
    matchExpressions:
      - {key: tier, operator: In, values: [cache]}
  # ordered list of preferred allocations out of the `required` set.
  # 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.
  # This also support `matchExpressions`
  preferred:
    - matchLabels:
        agones.dev/fleet: green-fleet
    - 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

We recommend using metadata > generateName, to declare to Kubernetes that a unique name for the GameServerAllocation is generated when the GameServerAllocation is created.

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

required is a label selector (matchLabels and/or matchExpressions) from which to choose GameServers from. GameServers still have the hard requirement to be Ready to be allocated from
preferred is an order list of label selectors out of the required set. 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 allocating GameServers 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

Docs: Go Game Server Client SDK

Fri, 17 May 2019 10:17:50 +0000

Check the Client SDK Documentation for more details on each of the SDK functions and how to run the SDK locally.

Installation

go get the source, directly from GitHub

Usage

Review the GoDoc for usage instructions

Docs: Limiting CPU & Memory

Thu, 03 Jan 2019 05:45:15 +0000

As a short description:

CPU Requests are limits that are applied when there is CPU congestion, and as such can burst above their set limits.
CPU Limits are hard limits on how much CPU time the particular container gets access to.

This is useful for game servers, not just as a mechanism to distribute compute resources evenly, but also as a way to advice the Kubernetes scheduler how many game server processes it is able to fit into a given node in the cluster.

It’s worth reading the Managing Compute Resources for Containers Kubernetes documentation for more details on “requests” and “limits” to both CPU and Memory, and how to configure them.

GameServers

Since the GameServer specification provides a full PodSpecTemplate, we can take advantage of both resource limits and requests in our GameServer configurations.

For example, to set a CPU limit on our GameServer configuration of 250m/0.25 of a CPU, we could do so as followed:

apiVersion: "agones.dev/v1"
kind: GameServer
metadata:
  name: "simple-udp"
spec:
  ports:
  - name: default
    containerPort: 7654
  template:
    spec:
      containers:
      - name: simple-udp
        image: gcr.io/agones-images/udp-server:0.21
        resources:
          limit:
            cpu: "250m" #this is our limit here

If you do not set a limit or request, the default is set by Kubernetes at a 100m CPU request.

SDK GameServer sidecar

You may also want to tweak the CPU request or limits on the SDK GameServer sidecar process that spins up alongside each game server container.

You can do this through the Helm configuration when installing Agones.

By default, this is set to having a CPU request value of 30m, with no hard CPU limit. This ensures that the sidecar always has enough CPU to function, but it is configurable in case a lower, or higher value is required on your clusters, or if you desire hard limit.

Docs: Fleet Autoscaler Specification

Thu, 03 Jan 2019 03:58:55 +0000

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

apiVersion: "autoscaling.agones.dev/v1"
kind: FleetAutoscaler
# FleetAutoscaler Metadata
# https://v1-15.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.15/#objectmeta-v1-meta
metadata:
  name: fleet-autoscaler-example
spec:
  # The name of the fleet to attach to and control. Must be an existing Fleet in the same namespace
  # as this FleetAutoscaler
  fleetName: fleet-example
  # The autoscaling policy
  policy:
    # type of the policy. for now, only Buffer is available
    type: Buffer
    # parameters of the buffer policy
    buffer:
      # Size of a buffer of "ready" game server instances
      # The FleetAutoscaler will scale the fleet up and down trying to maintain this buffer, 
      # as instances are being allocated or terminated
      # it can be specified either in absolute (i.e. 5) or percentage format (i.e. 5%)
      bufferSize: 5
      # minimum fleet size to be set by this FleetAutoscaler. 
      # if not specified, the actual minimum fleet size will be bufferSize
      minReplicas: 10
      # maximum fleet size that can be set by this FleetAutoscaler
      # required
      maxReplicas: 20

Or for Webhook FleetAutoscaler below and in example folder :

apiVersion: "autoscaling.agones.dev/v1"
kind: FleetAutoscaler
metadata:
  name: webhook-fleet-autoscaler
spec:
  fleetName: simple-udp
  policy:
    # type of the policy - this example is Webhook
    type: Webhook
    # parameters for the webhook policy - this is a WebhookClientConfig, as per other K8s webhooks
    webhook:
      # use a service, or URL
      service:
        name: autoscaler-webhook-service
        namespace: default
        path: scale
      # optional for URL defined webhooks
      # url: ""
      # caBundle:  optional, used for HTTPS webhook type

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

The spec field is the actual FleetAutoscaler specification and it is composed as follows:

fleetName is name of the fleet to attach to and control. Must be an existing Fleet in the same namespace as this FleetAutoscaler.
policy is the autoscaling policy
- type is type of the policy. “Buffer” and “Webhook” are available
- buffer parameters of the buffer policy type
- bufferSize is the size of a buffer of “ready” and “reserved” game server instances. The FleetAutoscaler will scale the fleet up and down trying to maintain this buffer, as instances are being allocated or terminated. Note that “reserved” game servers could not be scaled down. It can be specified either in absolute (i.e. 5) or percentage format (i.e. 5%)
- minReplicas is the minimum fleet size to be set by this FleetAutoscaler. if not specified, the minimum fleet size will be bufferSize if absolute value is used. When bufferSize in percentage format is used, minReplicas should be more than 0.
- maxReplicas is the maximum fleet size that can be set by this FleetAutoscaler. Required.
- webhook parameters of the webhook policy type
- service is a reference to the service for this webhook. Either service or url must be specified. If the webhook is running within the cluster, then you should use service. Port 8000 will be used if it is open, otherwise it is an error.
  - name is the service name bound to Deployment of autoscaler webhook. Required (see example) The FleetAutoscaler will scale the fleet up and down based on the response from this webhook server
  - namespace is the kubernetes namespace where webhook is deployed. Optional If not specified, the “default” would be used
  - path is an optional URL path which will be sent in any request to this service. (i. e. /scale)
- url gives the location of the webhook, in standard URL form ([scheme://]host:port/path). Exactly one of url or service must be specified. The host should not refer to a service running in the cluster; use the service field instead. (optional, instead of service)
- caBundle is a PEM encoded certificate authority bundle which is used to issue and then validate the webhook’s server certificate. Base64 encoded PEM string. Required only for HTTPS. If not present HTTP client would be used.

Note: only one buffer or webhook could be defined for FleetAutoscaler which is based on the type field.

Webhook Endpoint Specification

Webhook endpoint is used to delegate the scaling logic to a separate pod or server.

FleetAutoscaler would send a request to the webhook endpoint every sync period (which is currently 30s) with a JSON body, and scale the target fleet based on the data that is returned. JSON payload with a FleetAutoscaleReview data structure would be sent to webhook endpoint and received from it with FleetAutoscaleResponse field populated. FleetAutoscaleResponse contains target Replica count which would trigger scaling of the fleet according to it.

In order to define the path to your Webhook you can use either URL or service. Note that caBundle parameter is required if you use HTTPS for webhook fleetautoscaler, caBundle should be omitted if you want to use HTTP webhook server.

The connection to this webhook endpoint should be defined in FleetAutoscaler using Webhook policy type.

// FleetAutoscaleReview is passed to the webhook with a populated Request value,
// and then returned with a populated Response.
type FleetAutoscaleReview struct {
	Request  *FleetAutoscaleRequest  `json:"request"`
	Response *FleetAutoscaleResponse `json:"response"`
}

type FleetAutoscaleRequest struct {
	// UID is an identifier for the individual request/response. It allows us to distinguish instances of requests which are
	// otherwise identical (parallel requests, requests when earlier requests did not modify etc)
	// The UID is meant to track the round trip (request/response) between the Autoscaler and the WebHook, not the user request.
	// It is suitable for correlating log entries between the webhook and apiserver, for either auditing or debugging.
	UID types.UID `json:"uid""`
	// Name is the name of the Fleet being scaled
	Name string `json:"name"`
	// Namespace is the namespace associated with the request (if any).
	Namespace string `json:"namespace"`
	// The Fleet's status values
	Status v1.FleetStatus `json:"status"`
}

type FleetAutoscaleResponse struct {
	// UID is an identifier for the individual request/response.
	// This should be copied over from the corresponding FleetAutoscaleRequest.
	UID types.UID `json:"uid"`
	// Set to false if no scaling should occur to the Fleet
	Scale bool `json:"scale"`
	// The targeted replica count
	Replicas int32 `json:"replicas"`
}

// FleetStatus is the status of a Fleet
type FleetStatus struct {
	// Replicas the total number of current GameServer replicas
	Replicas int32 `json:"replicas"`
	// ReadyReplicas are the number of Ready GameServer replicas
	ReadyReplicas int32 `json:"readyReplicas"`
	// ReservedReplicas are the total number of Reserved GameServer replicas in this fleet.
	// Reserved instances won't be deleted on scale down, but won't cause an autoscaler to scale up.
	ReservedReplicas int32 `json:"reservedReplicas"`
	// AllocatedReplicas are the number of Allocated GameServer replicas
	AllocatedReplicas int32 `json:"allocatedReplicas"`
}

For Webhook Fleetautoscaler Policy either HTTP or HTTPS could be used. Switching between them occurs depending on https presence in URL or by the presence of caBundle. The example of the webhook written in Go could be found here .

It implements the scaling logic based on the percentage of allocated gameservers in a fleet.

Docs: Quickstart: Create a Fleet Autoscaler

Wed, 02 Jan 2019 06:42:33 +0000

Prerequisites

It is assumed that you have followed the instructions to Create a Game Server Fleet and you have a running fleet of game servers.

Objectives

Create a Fleet Autoscaler in Kubernetes using Agones custom resource.
Watch the Fleet scale up when allocating GameServers
Watch the Fleet scale down when shutting down allocated GameServers
Edit the autoscaler specification to apply live changes

1. Create a Fleet Autoscaler

Let’s create a Fleet Autoscaler using the following command :

kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/simple-udp/fleetautoscaler.yaml

You should see a successful output similar to this :

fleetautoscaler.autoscaling.agones.dev "simple-udp-autoscaler" created

This has created a FleetAutoscaler record inside Kubernetes.

2. See the autoscaler status.

kubectl describe fleetautoscaler simple-udp-autoscaler

It should look something like this:

Name:         simple-udp-autoscaler
Namespace:    default
Labels:       <none>
Annotations:  kubectl.kubernetes.io/last-applied-configuration={"apiVersion":"au
toscaling.agones.dev/v1","kind":"FleetAutoscaler","metadata":{"annotations":{},
"name":"simple-udp-autoscaler","namespace":"default"},...
API Version:  autoscaling.agones.dev/v1
Kind:         FleetAutoscaler
Metadata:
  Cluster Name:
  Creation Timestamp:  2018-10-02T15:19:58Z
  Generation:          1
  Owner References:
    API Version:           autoscaling.agones.dev/v1
    Block Owner Deletion:  true
    Controller:            true
    Kind:                  Fleet
    Name:                  simple-udp
    UID:                   9960762e-c656-11e8-933e-fa163e07a1d4
  Resource Version:        6123197
  Self Link:               /apis/autoscaling.agones.dev/v1/namespaces/default/f
leetautoscalers/simple-udp-autoscaler
  UID:                     9fd0efa1-c656-11e8-933e-fa163e07a1d4
Spec:
  Fleet Name:  simple-udp
  Policy:
    Buffer:
      Buffer Size:   2
      Max Replicas:  10
      Min Replicas:  2
    Type:            Buffer
Status:
  Able To Scale:     true
  Current Replicas:  2
  Desired Replicas:  2
  Last Scale Time:   <nil>
  Scaling Limited:   false
Events:              <none>

You can see the status (able to scale, not limited), the last time the fleet was scaled (nil for never) and the current and desired fleet size.

The autoscaler works by changing the desired size, and the fleet creates/deletes game server instances to achieve that number. The convergence is achieved in time, which is usually measured in seconds.

3. Allocate a Game Server from the Fleet

If you’re interested in more details for game server allocation, you should consult the Create a Game Server Fleet page. In here we are only interested in triggering allocations to see the autoscaler in action.

kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/simple-udp/gameserverallocation.yaml -o yaml

You should get in return the allocated game server details, which should end with something like:

status:
  address: 34.94.118.237
  gameServerName: simple-udp-v6jwb-6bzkz
  nodeName: gke-test-cluster-default-f11755a7-5km3
  ports:
  - name: default
    port: 7832
  state: Allocated

Note the address and port, you might need them later to connect to the server.

4. See the autoscaler in action

Now let’s wait a few seconds to allow the autoscaler to detect the change in the fleet and check again its status

kubectl describe fleetautoscaler simple-udp-autoscaler

The last part should look something like this:

Spec:
  Fleet Name:  simple-udp
  Policy:
    Buffer:
      Buffer Size:   2
      Max Replicas:  10
      Min Replicas:  2
    Type:            Buffer
Status:
  Able To Scale:     true
  Current Replicas:  3
  Desired Replicas:  3
  Last Scale Time:   2018-10-02T16:00:02Z
  Scaling Limited:   false
Events:
  Type    Reason            Age   From                        Message
  ----    ------            ----  ----                        -------
  Normal  AutoScalingFleet  2m    fleetautoscaler-controller  Scaling fleet simple-udp from 2 to 3

You can see that the fleet size has increased, the autoscaler having compensated for the allocated instance. Last Scale Time has been updated, and a scaling event has been logged.

Double-check the actual number of game server instances and status by running

kubectl get gs

This will get you a list of all the current GameServers and their Status > State.

NAME                     STATE       ADDRESS        PORT     NODE        AGE
simple-udp-mzhrl-hz8wk   Allocated   10.30.64.99    7131     minikube    5m
simple-udp-mzhrl-k6jg5   Ready       10.30.64.100   7243     minikube    5m  
simple-udp-mzhrl-n2sk2   Ready       10.30.64.168   7658     minikube    5m

5. Shut the allocated instance down

Since we’ve only got one allocation, we’ll just grab the details of the IP and port of the only allocated GameServer:

kubectl get gameservers | grep Allocated | awk '{print $3":"$4 }'

This should output your Game Server IP address and port. (eg 10.130.65.208:7936)

You can now communicate with the GameServer:

nc -u {IP} {PORT}
Hello World !
ACK: Hello World !
EXIT

You can finally type EXIT which tells the SDK to run the Shutdown command, and therefore shuts down the GameServer.

6. See the fleet scaling down

Now let’s wait a few seconds to allow the autoscaler to detect the change in the fleet and check again its status

kubectl describe fleetautoscaler simple-udp-autoscaler

It should look something like this:

Spec:
  Fleet Name:  simple-udp
  Policy:
    Buffer:
      Buffer Size:   2
      Max Replicas:  10
      Min Replicas:  2
    Type:            Buffer
Status:
  Able To Scale:     true
  Current Replicas:  3
  Desired Replicas:  2
  Last Scale Time:   2018-10-02T16:09:02Z
  Scaling Limited:   false
Events:
  Type    Reason            Age   From                        Message
  ----    ------            ----  ----                        -------
  Normal  AutoScalingFleet  9m    fleetautoscaler-controller  Scaling fleet simple-udp from 2 to 3
  Normal  AutoScalingFleet  45s   fleetautoscaler-controller  Scaling fleet simple-udp from 3 to 2

You can see that the fleet size has decreased, the autoscaler adjusting to game server instance being de-allocated, the Last Scale Time and the events have been updated. Note that simple-udp game server instance you just closed earlier might stay a bit in ‘Unhealthy’ state (and its pod in ‘Terminating’ until it gets removed.

Double-check the actual number of game server instances and status by running

kubectl get gs

This will get you a list of all the current GameServers and their Status > State.

NAME                     STATE     ADDRESS        PORT    NODE       AGE
simple-udp-mzhrl-k6jg5   Ready     10.30.64.100   7243    minikube   5m
simple-udp-mzhrl-t7944   Ready     10.30.64.168   7561    minikube   5m

7. Change autoscaling parameters

We can also change the configuration of the FleetAutoscaler of the running Fleet, and have the changes applied live, without interruptions of service.

Run kubectl edit fleetautoscaler simple-udp-autoscaler and set the bufferSize field to 5. ] Let’s look at the list of game servers again. Run watch kubectl get gs until you can see that are 5 ready server instances:

NAME                     STATE     ADDRESS        PORT    NODE         AGE
simple-udp-mzhrl-7jpkp   Ready     10.30.64.100   7019    minikube     5m
simple-udp-mzhrl-czt8v   Ready     10.30.64.168   7556    minikube     5m
simple-udp-mzhrl-k6jg5   Ready     10.30.64.100   7243    minikube     5m
simple-udp-mzhrl-nb8h2   Ready     10.30.64.168   7357    minikube     5m
simple-udp-mzhrl-qspb6   Ready     10.30.64.99    7859    minikube     5m
simple-udp-mzhrl-zg9rq   Ready     10.30.64.99    7745    minikube     5m

Note

If you want to update a Fleet which has RollingUpdate replacement strategy and is controlled by a FleetAutoscaler: 1. With kubectl apply: you should omit replicas parameter in a Fleet Spec before re-applying the Fleet configuration. 1. With kubectl edit: you should not change the replicas parameter in the Fleet Spec when updating other field parameters.

If you follow the rules above, then the maxSurge and maxUnavailable parameters will be used as the RollingUpdate strategy updates your Fleet. Otherwise the Fleet would be scaled according to Fleet replicas parameter first and only after a certain amount of time it would be rescaled to fit FleetAutoscaler BufferSize parameter.

You could also check the behaviour of the Fleet with Fleetautoscaler on a test Fleet to preview what would occur in your production environment.

Next Steps

Read the advanced Scheduling and Autoscaling guide, for more details on autoscaling.

If you want to use your own GameServer container make sure you have properly integrated the Agones SDK.

Docs: Azure Kubernetes Service

Mon, 01 Jan 0001 00:00:00 +0000

Choosing your shell

You can use either Azure Cloud Shell or install the Azure CLI on your local shell in order to install AKS in your own Azure subscription. Cloud Shell comes preinstalled with az and kubectl utilities whereas you need to install them locally if you want to use your local shell. If you use Windows 10, you can use the WIndows Subsystem for Windows as well.

Creating the AKS cluster

If you are using Azure CLI from your local shell, you need to log in to your Azure account by executing the az login command and following the login procedure.

Here are the steps you need to follow to create a new AKS cluster (additional instructions and clarifications are listed here):

# Declare necessary variables, modify them according to your needs
AKS_RESOURCE_GROUP=akstestrg     # Name of the resource group your AKS cluster will be created in
AKS_NAME=akstest                 # Name of your AKS cluster
AKS_LOCATION=westeurope          # Azure region in which you'll deploy your AKS cluster

# Create the Resource Group where your AKS resource will be installed
az group create --name $AKS_RESOURCE_GROUP --location $AKS_LOCATION

# Create the AKS cluster - this might take some time. Type 'az aks create -h' to see all available options
# The following command will create a four Node AKS cluster. Node size is Standard A1 v1 and Kubernetes version is 1.15.10. Plus, SSH keys will be generated for you, use --ssh-key-value to provide your values
az aks create --resource-group $AKS_RESOURCE_GROUP --name $AKS_NAME --node-count 4 --generate-ssh-keys --node-vm-size Standard_A4_v2 --kubernetes-version 1.15.10

# Install kubectl
sudo az aks install-cli

# Get credentials for your new AKS cluster
az aks get-credentials --resource-group $AKS_RESOURCE_GROUP --name $AKS_NAME

Alternatively, you can use the Azure Portal to create a new AKS cluster (instructions).

Allowing UDP traffic

For Agones to work correctly, we need to allow UDP traffic to pass through to our AKS cluster. To achieve this, we must update the NSG (Network Security Group) with the proper rule. A simple way to do that is:

Log in to the Azure Portal
Find the resource group where the AKS resources are kept, which should have a name like MC_resourceGroupName_AKSName_westeurope. Alternative, you can type az resource show --namespace Microsoft.ContainerService --resource-type managedClusters -g $AKS_RESOURCE_GROUP -n $AKS_NAME -o json | jq .properties.nodeResourceGroup
Find the Network Security Group object, which should have a name like aks-agentpool-********-nsg
Select Inbound Security Rules
Select Add to create a new Rule with UDP as the protocol and 7000-8000 as the Destination Port Ranges. Pick a proper name and leave everything else at their default values

Alternatively, you can use the following command, after modifying the RESOURCE_GROUP_WITH_AKS_RESOURCES and NSG_NAME values:

az network nsg rule create \
  --resource-group RESOURCE_GROUP_WITH_AKS_RESOURCES \
  --nsg-name NSG_NAME \
  --name AgonesUDP \
  --access Allow \
  --protocol Udp \
  --direction Inbound \
  --priority 520 \
  --source-port-range "*" \
  --destination-port-range 7000-8000

Creating and assigning Public IPs to Nodes

Nodes in AKS don’t get a Public IP by default. To assign a Public IP to a Node, find the Resource Group where the AKS resources are installed on the portal (it should have a name like MC_resourceGroupName_AKSName_westeurope). Then, you can follow the instructions here to create a new Public IP and assign it to the Node/VM. For more information on Public IPs for VM NICs, see this document. If you are looking for an automated way to create and assign Public IPs for your AKS Nodes, check this project.

Next Steps

Continue to Install Agones.

Docs: Local Game Server

Tue, 19 Feb 2019 08:00:00 +0000

You can register a local game server with Agones. This means you can run an experimental build of your game server in the Agones environment without the need of packaging and deploying it to a fleet. This allows you to quickly iterate on your game server code while still being able to plugin to your Agones environment.

Register your server with Agones

To register your local game server you’ll need to know the IP address of the machine running it and the port. With that you’ll create a game server config like the one below.

apiVersion: "agones.dev/v1"
kind: GameServer
metadata:
  name: my-local-server
  annotations:
    # Causes Agones to register your local game server at 192.1.1.2, replace with your server's IP address.
    agones.dev/dev-address: "192.1.1.2"
spec:
  ports:
  - name: default
    portPolicy: Static
    hostPort: 17654
    containerPort: 17654
  # The following is ignored but required due to validation.
  template:
    spec:
      containers:
      - name: simple-udp
        image: gcr.io/agones-images/udp-server:0.21

Once you save this to a file make sure you have kubectl configured to point to your Agones cluster and then run kubectl apply -f dev-gameserver.yaml. This will register your server with Agones.

Local Game Servers has a few limitations:

PortPolicy must be Static.
The game server is not managed by Agones. Features like autoscaling, replication, etc are not available.

When you are finished working with your server, you can remove the registration with kubectl delete -f dev-gameserver.yaml

Docs: Latency Testing with Multiple Clusters

Thu, 03 Jan 2019 01:20:30 +0000

To make latency testing easier, Agones installs with a simple ping service with both HTTP and UDP services that can be called for the purpose of timing how long the roundtrip takes for information to be returned from either of these services.

Installing

By default, Agones installs Kubernetes Services for both HTTP and the UDP ping endpoints. These can be disabled entirely, or disabled individually. See the Helm install guide for the parameters to pass through, as well as configuration options.

The ping services as all installed under the agones-system namespace.

HTTP Service

This exposes an endpoint that returns a simple text HTTP response on request to the root “/” path. By default this is ok, but it can be configured via the agones.ping.http.response parameter.

This could be useful for providing clusters with unique lookup names, such that clients are able to identify clusters from their responses.

To lookup the details of this service, run kubectl describe service agones-ping-http-service --namespace=agones-system

UDP Service

The UDP ping service is a rate limited UDP echo service that returns the udp packet that it receives to its designated sender.

Since UDP sender details can be spoofed, this service is rate limited to 20 requests per second, per sender address, per running instance (default is 2).

This rate limit can be raised or lowered via the Helm install parameter agones.ping.udp.rateLimit.

UDP packets are also limited to 1024 bytes in size.

To lookup the details of this service, run kubectl describe service agones-ping-udp-service --namespace=agones-system

Client side tooling

We deliberately didn’t provide any game client libraries, as all major languages and engines have capabilities to send HTTP requests as well as UDP packets.

Docs: Quickstart: Create a Fleet Autoscaler with Webhook Policy

Wed, 02 Jan 2019 06:42:44 +0000

In some cases, your game servers may need to use custom logic for scaling your fleet that is more complex than what can be expressed using the Buffer policy in the fleetautoscaler. This guide shows how you can extend Agones with an autoscaler webhook to implement a custom autoscaling policy.

When you use an autoscaler webhook the logic computing the number of target replicas is delegated to an external HTTP/S endpoint, such as one provided by a Kubernetes deployment and service in the same cluster (as shown in the examples below). The fleetautoscaler will send a request to the webhook autoscaler’s /scale endpoint every sync period (currently 30s) with a JSON body, and scale the target fleet based on the data that is returned.

Chapter 1 Configuring HTTP fleetautoscaler webhook

Prerequisites

It is assumed that you have completed the instructions to Create a Game Server Fleet and have a running fleet of game servers.

Objectives

Run a fleet
Deploy the Webhook Pod and service for autoscaling
Create a Fleet Autoscaler with Webhook policy type in Kubernetes using Agones custom resource
Watch the Fleet scales up when allocating GameServers
Watch the Fleet scales down after GameServer shutdown

1. Deploy the fleet

Run a fleet in a cluster:

kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/simple-udp/fleet.yaml

2. Deploy a Webhook service for autoscaling

In this step we would deploy an example webhook that will control the size of the fleet based on allocated gameservers portion in a fleet. You can see the source code for this example webhook server here . The fleetautoscaler would trigger this endpoint every 30 seconds. More details could be found also here . We need to create a pod which will handle HTTP requests with json payload FleetAutoscaleReview and return back it with FleetAutoscaleResponse populated.

The Scale flag and Replicas values returned in the FleetAutoscaleResponse tells the FleetAutoscaler what target size the backing Fleet should be scaled up or down to. If Scale is false - no scaling occurs.

Run next command to create a service and a Webhook pod in a cluster:

kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/autoscaler-webhook/autoscaler-service.yaml

To check that it is running and liveness probe is fine:

kubectl describe pod autoscaler-webhook

Name:           autoscaler-webhook-86944884c4-sdtqh
Namespace:      default
Node:           gke-test-cluster-default-1c5dec79-h0tq/10.138.0.2
...
Status:         Running

3. Create a Fleet Autoscaler

Let’s create a Fleet Autoscaler using the following command:

kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/webhookfleetautoscaler.yaml

You should see a successful output similar to this:

fleetautoscaler.autoscaling.agones.dev "webhook-fleet-autoscaler" created

This has created a FleetAutoscaler record inside Kubernetes. It has the link to Webhook service we deployed above.

4. See the fleet and autoscaler status.

In order to track the list of gameservers which run in your fleet you can run this command in a separate terminal tab:

 watch "kubectl get gs -n default"

In order to get autoscaler status use the following command:

kubectl describe fleetautoscaler webhook-fleet-autoscaler

It should look something like this:

Name:         webhook-fleet-autoscaler
Namespace:    default
Labels:       <none>
Annotations:  kubectl.kubernetes.io/last-applied-configuration={"apiVersion":
"autoscaling.agones.dev/v1","kind":"FleetAutoscaler","metadata":{"annotations"
:{},"name":"webhook-fleet-autoscaler","namespace":"default...
API Version:  autoscaling.agones.dev/v1
Kind:         FleetAutoscaler
etadata:
  Cluster Name:
  Creation Timestamp:  2018-12-22T12:52:23Z
  Generation:          1
  Resource Version:    2274579
  Self Link:           /apis/autoscaling.agones.dev/v1/namespaces/default/fleet
autoscalers/webhook-fleet-autoscaler
  UID:                 6d03eae4-05e8-11e9-84c2-42010a8a01c9
Spec:
  Fleet Name:  simple-udp
  Policy:
    Type:  Webhook
    Webhook:
      Service:
        Name:       autoscaler-webhook-service
        Namespace:  default
        Path:       scale
      URL:
Status:
  Able To Scale:     true
  Current Replicas:  2
  Desired Replicas:  2
  Last Scale Time:   <nil>
  Scaling Limited:   false
Events:              <none>

You can see the status (able to scale, not limited), the last time the fleet was scaled (nil for never), current and desired fleet size.

The autoscaler makes a query to a webhoook service deployed on step 1 and on response changing the target Replica size, and the fleet creates/deletes game server instances to achieve that number. The convergence is achieved in time, which is usually measured in seconds.

5. Allocate Game Servers from the Fleet to trigger scale up

If you’re interested in more details for game server allocation, you should consult the Create a Game Server Fleet page. Here we only interested in triggering allocations to see the autoscaler in action.

kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/simple-udp/gameserverallocation.yaml -o yaml

You should get in return the allocated game server details, which should end with something like:

status:
  address: 34.94.118.237
  gameServerName: simple-udp-v6jwb-6bzkz
  nodeName: gke-test-cluster-default-f11755a7-5km3
  ports:
  - name: default
    port: 7832
  state: Allocated

Note the address and port, you might need them later to connect to the server.

Run the kubectl command one more time so that we have both servers allocated:

kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/simple-udp/gameserverallocation.yaml -o yaml

6. Check new Autoscaler and Fleet status

Now let’s wait a few seconds to allow the autoscaler to detect the change in the fleet and check again its status

kubectl describe fleetautoscaler webhook-fleet-autoscaler

The last part should look similar to this:

Spec:
  Fleet Name:  simple-udp
  Policy:
    Type:  Webhook
    Webhook:
      Service:
        Name:       autoscaler-webhook-service
        Namespace:  default
        Path:       scale
      URL:
Status:
  Able To Scale:     true
  Current Replicas:  4
  Desired Replicas:  4
  Last Scale Time:   2018-12-22T12:53:47Z
  Scaling Limited:   false
Events:
  Type    Reason            Age   From                        Message
  ----    ------            ----  ----                        -------
  Normal  AutoScalingFleet  35s   fleetautoscaler-controller  Scaling fleet simple-udp from 2 to 4

You can see that the fleet size has increased in particular case doubled to 4 gameservers (based on our custom logic in our webhook), the autoscaler having compensated for the two allocated instances. Last Scale Time has been updated and a scaling event has been logged.

Double-check the actual number of game server instances and status by running:

 kubectl get gs -n default

This will get you a list of all the current GameServers and their Status > State.

NAME                     STATE       ADDRESS         PORT     NODE        AGE
simple-udp-dmkp4-8pkk2   Ready       35.247.13.175   7386     minikube     5m
simple-udp-dmkp4-b7x87   Allocated   35.247.13.175   7219     minikube     5m
simple-udp-dmkp4-r4qtt   Allocated   35.247.13.175   7220     minikube     5m
simple-udp-dmkp4-rsr6n   Ready       35.247.13.175   7297     minikube     5m

7. Check downscaling using Webhook Autoscaler policy

Based on our custom webhook deployed earlier, if the fraction of allocated replicas in whole Replicas count would be less than threshold (0.3) then the fleet would scale down by scaleFactor, in our example by 2.

Note that the example webhook server has a limitation that it would not decrease fleet replica count under minReplicasCount, which is equal to 2.

We need to run EXIT command on one gameserver (Use IP address and port of the allocated gameserver from the previous step) in order to decrease the number of allocated gameservers in a fleet (<0.3).

nc -u 35.247.13.175 7220
EXIT

Server would be in shutdown state. Wait about 30 seconds. Then you should see scaling down event in the output of next command:

kubectl describe fleetautoscaler webhook-fleet-autoscaler

You should see these lines in events:

  Normal   AutoScalingFleet  11m                fleetautoscaler-controller  Scaling fleet simple-udp from 2 to 4
  Normal   AutoScalingFleet  1m                 fleetautoscaler-controller  Scaling fleet simple-udp from 4 to 2

And get gameservers command output:

kubectl get gs -n default

NAME                     STATUS      ADDRESS          PORT     NODE       AGE
simple-udp-884fg-6q5sk   Ready       35.247.117.202   7373     minikube   5m
simple-udp-884fg-b7l58   Allocated   35.247.117.202   7766     minikube   5m

8. Cleanup

You can delete the autoscaler service and associated resources with the following commands.

kubectl delete -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/autoscaler-webhook/autoscaler-service.yaml

Removing the fleet:

kubectl delete -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/simple-udp/fleet.yaml

Chapter 2 Configuring HTTPS fleetautoscaler webhook with CA Bundle

Objectives

Using TLS and a certificate authority (CA) bundle we can establish trusted communication between Fleetautoscaler and an HTTPS server running the autoscaling webhook that controls the size of the fleet (Replicas count). The certificate of the autoscaling webhook must be signed by the CA provided in fleetautoscaler yaml configuration file. Using TLS eliminates the possibility of a man-in-the-middle attack between the fleetautoscaler and the autoscaling webhook.

1. Deploy the fleet

Run a fleet in a cluster:

kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/simple-udp/fleet.yaml

2. Create X509 Root and Webhook certificates

The procedure of generating a Self-signed CA certificate taken from here

The first step is to create the private root key:

openssl genrsa -out rootCA.key 2048

The next step is to self-sign this certificate:

openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.pem

This will start an interactive script that will ask you for various bits of information. Fill it out as you see fit.

Every webhook that you wish to install a trusted certificate will need to go through this process. First, just like with the root CA step, you’ll need to create a private key (different from the root CA):

openssl genrsa -out webhook.key 2048

Once the key is created, you’ll generate the certificate signing request, use valid hostname which is autoscaler-tls-service.default.svc as Common Name (eg, fully qualified host name) when prompted:

openssl req -new -key webhook.key -out webhook.csr

Once that’s done, you’ll sign the CSR, which requires the CA root key:

openssl x509 -req -in webhook.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out webhook.crt -days 500 -sha256

This would generate webhook.crt certificate

Add secret which later would be mounted to autoscaler-webhook-tls pod.

kubectl create secret tls autoscalersecret --cert=webhook.crt --key=webhook.key

You need to put Base64-encoded string into caBundle field in your fleetautoscaler yaml configuration:

base64 -i ./rootCA.pem

Copy the output of the command above and replace the caBundle field in your text editor (say vim) with the new value:

wget https://raw.githubusercontent.com/googleforgames/agones/master/examples/webhookfleetautoscalertls.yaml
vim ./webhookfleetautoscalertls.yaml

3. Deploy a Webhook service for autoscaling

Run next command to create a service and a Webhook pod in a cluster:

kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/autoscaler-webhook/autoscaler-service-tls.yaml

To check that it is running and liveness probe is fine:

kubectl describe pod autoscaler-webhook-tls

Wait for the Running status results:

Name:               autoscaler-webhook-tls-f74c9bff7-ssrsc
Namespace:          default
...
Status:         Running

4. Create a Fleet Autoscaler

Let’s create a Fleet Autoscaler using the following command (caBundle should be set properly on Step 2):

kubectl apply -f ./webhookfleetautoscalertls.yaml

5. See the fleet and autoscaler status.

In order to track the list of gameservers which run in your fleet you can run this command in a separate terminal tab:

 watch "kubectl get gs -n default"

6. Allocate two Game Servers from the Fleet to trigger scale up

for i in {0..1} ; do kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/simple-udp/gameserverallocation.yaml -o yaml ; done

7. Check new Autoscaler and Fleet status

Now let’s wait a few seconds to allow the autoscaler to detect the change in the fleet and check again its status

kubectl describe fleetautoscaler  webhook-fleetautoscaler-tls

The last part should look similar to this:

  Fleet Name:  simple-udp
  Policy:
    Type:  Webhook
    Webhook:
      Ca Bundle:  LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUN1RENDQWFBQ0NRQ29kcEFNbTlTd0pqQU5CZ2txaGtpRzl3MEJBUXNGQURBZU1Rc3dDUVlEVlFRR0V3SlYKVXpFUE1BMEdBMVVFQ3d3R1FXZHZibVZ6TUI0WERURTVNREV3TkRFeE5URTBORm9YRFRJeE1UQXlOREV4TlRFMApORm93SGpFTE1Ba0dBMVVFQmhNQ1ZWTXhEekFOQmdOVkJBc01Ca0ZuYjI1bGN6Q0NBU0l3RFFZSktvWklodmNOCkFRRUJCUUFEZ2dFUEFEQ0NBUW9DZ2dFQkFOQ0h5dndDOTZwZDlTdkFhMUIvRWg2ekcxeDBLS1dPaVhtNzhJcngKKzZ5WHd5YVpsMVo1cVExbUZoOThMSGVZUmQwWVgzRTJnelZ5bFpvUlUra1ZESzRUc0VzV0tNUFVpdVo0MUVrdApwbythbEN6alAyaXZzRGZaOGEvdnByL3dZZ2FrWGtWalBUaGpKUk9xTnFIdWROMjZVcUFJYnNOTVpoUkxkOVFFCnFLSjRPNmFHNVMxTVNqZFRGVHFlbHJiZitDcXNKaHltZEIzZmxGRUVvdXExSmoxS0RoQjRXWlNTbS9VSnpCNkcKNHUzY3BlQm1jTFVRR202ZlFHb2JFQSt5SlpMaEVXcXBrd3ZVZ2dCNmRzWE8xZFNIZXhhZmlDOUVUWGxVdFRhZwo1U2JOeTVoYWRWUVV3Z253U0J2djR2R0t1UUxXcWdXc0JyazB5Wll4Sk5Bb0V5RUNBd0VBQVRBTkJna3Foa2lHCjl3MEJBUXNGQUFPQ0FRRUFRMkgzaWJRcWYzQTNES2l1eGJISURkbll6TlZ2Z0dhRFpwaVZyM25ocm55dmxlNVgKR09hRm0rMjdRRjRWV29FMzZDTGhYZHpEWlM4bEpIY09YUW5KOU83Y2pPYzkxVmh1S2NmSHgwS09hU1oweVNrVAp2bEtXazlBNFdoNGE0QXFZSlc3Z3BUVHR1UFpydnc4VGsvbjFaWEZOYVdBeDd5RU5OdVdiODhoNGRBRDVaTzRzCkc5SHJIdlpuTTNXQzFBUXA0Q3laRjVyQ1I2dkVFOWRkUmlKb3IzM3pLZTRoRkJvN0JFTklZZXNzZVlxRStkcDMKK0g4TW5LODRXeDFUZ1N5Vkp5OHlMbXFpdTJ1aThjaDFIZnh0OFpjcHg3dXA2SEZLRlRsTjlBeXZUaXYxYTBYLwpEVTk1eTEwdi9oTlc0WHpuMDJHNGhrcjhzaUduSEcrUEprT3hBdz09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
      Service:    <nil>
      URL:        https://autoscaler-tls-service.default.svc:8000/scale
Events:
  Type    Reason            Age   From                        Message
  ----    ------            ----  ----                        -------
  Normal  AutoScalingFleet  5s   fleetautoscaler-controller  Scaling fleet simple-udp from 2 to 4

Double-check the actual number of game server instances and status by running:

 kubectl get gs -n default

This will get you a list of all the current GameServers and their Status > State.

NAME                     STATE       ADDRESS         PORT      NODE      AGE
simple-udp-njmr7-2t4nx   Ready       35.203.159.68   7330      minikube   1m
simple-udp-njmr7-65rp6   Allocated   35.203.159.68   7294      minikube   4m

8. Cleanup

You can delete the autoscaler service and associated resources with the following commands.

kubectl delete -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/autoscaler-webhook/autoscaler-service-tls.yaml

Removing x509 key secret:

kubectl delete secret autoscalersecret

Removing the fleet:

kubectl delete -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/simple-udp/fleet.yaml

Comments

Note that secure communication has been established and we can trust that communication between the fleetautoscaler and the autoscaling webhook. If you need to run the autoscaling webhook outside of the Kubernetes cluster, you can use another root certificate authority as long as you put it into the caBundle parameter in fleetautoscaler configuration (in pem format, base64-encoded).

Troubleshooting Guide

If you run into problems with the configuration of your fleetautoscaler and webhook service the easiest way to debug them is to run:

kubectl describe fleetautoscaler <FleetAutoScalerName>

and inspect the events at the bottom of the output.

Common error messages.

If you have configured the wrong service Path for the FleetAutoscaler you will see a message like

Error calculating desired fleet size on FleetAutoscaler simple-fleet-r7fdv-autoscaler. Error: bad status code 404 from the server: https://autoscaler-tls-service.default.svc:8000/scale

If you are using a hostname other than autoscaler-tls-service.default.svc as the Common Name (eg, fully qualified host name) when creating a certificate using openssl tool you will see a message like

Post https://autoscaler-tls-service.default.svc:8000/scale: x509: certificate is not valid for any names, but wanted to match autoscaler-tls-service.default.svc

If you see errors like the following in autoscaler-webhook-tls pod logs:

http: TLS handshake error from 10.48.3.125:33374: remote error: tls: bad certificate

Then there could be an issue with your ./rootCA.pem.

You can repeat the process from step 2, in order to fix your certificates setup.

Next Steps

Read the advanced Scheduling and Autoscaling guide, for more details on autoscaling.

If you want to use your own GameServer container make sure you have properly integrated the Agones SDK.

Docs: C# Game Server Client SDK

Thu, 28 May 2020 00:00:00 +0000

Note

The C# SDK will also be available as a NuGet package in a future release.

Check the Client SDK Documentation for more details on each of the SDK functions and how to run the SDK locally.

Download

Download the source directly from GitHub .

Prerequisites

.Net Standard 2.0 compliant framework.

Usage

Reference the SDK in your project & create a new instance of the SDK wrapper:

var agones = new AgonesSDK();

To connect to the SDK server, either locally or when running on Agones, run the ConnectAsync() method. This will wait for up to 30 seconds if the SDK server has not yet started and the connection cannot be made, and will return false if there was an issue connecting.

bool ok = await agones.ConnectAsync();

To mark the game server as ready to receive player connections, call the async method ReadyAsync().

async void SomeMethod()
{
    var status = await agones.ReadyAsync();
}

To send Health pings, call the async method HealthAsync()

await agones.HealthAsync();

To get the details on the backing GameServer call GetGameServerAsync().

Will return null if there is an error in retrieving the GameServer record.

var gameserver = await agones.GetGameServerAsync();

To mark the GameServer as Reserved for a duration call ReserveAsync(long duration).

long duration = 30;
var status = await agones.ReserveAsync(duration);

To mark that the game session is completed and the game server should be shut down call ShutdownAsync().

var status = await agones.ShutdownAsync();

Similarly SetAnnotation(string key, string value) and SetLabel(string key, string value) are async methods that perform an action & return a Status object.

To watch when the backing GameServer configuration changes call WatchGameServer(callback), where the delegate function callback of type Action<GameServer> will be executed every time the GameServer configuration changes. This process is non-blocking internally.

agonesSDK.WatchGameServer((gameServer) => { Console.WriteLine($"Server - Watch {gameServer}");});

Remarks

All requests other than ConnectAsync will wait for up to 15 seconds before giving up, can also be set in the constructor.
Default host & port are localhost:9357
Methods that do not return a data object such as GameServer will return a gRPC Status object. To check the state of the request, check Status.StatusCode & Status.Detail. Ex:
```
if(status.StatusCode == StatusCode.OK)
//do stuff
```

Docs: Node.js Game Server Client SDK

Sun, 24 Feb 2019 15:56:57 +0000

Check the Client SDK Documentation for more details on each of the SDK functions and how to run the SDK locally.

Prerequisites

Node.js >= 10.13.0

Usage

Add the agones dependency to your project:

$ npm install @google-cloud/agones-sdk

If you need to download the source, rather than install from NPM, you can find it on GitHub .

To begin working with the SDK, create an instance of it.

const AgonesSDK = require('@google-cloud/agones-sdk');

let agonesSDK = new AgonesSDK();

To connect to the SDK server, either local or when running on Agones, run the async method sdk.connect(), which will resolve once connected or reject on error or if no connection can be made after 30 seconds.

await agonesSDK.connect();

To send a health check ping call health().

agonesSDK.health();

To mark the game server as ready to receive player connections, call the async method ready(). The result will be an empty object in this case.

let result = await agonesSDK.ready();

Similarly shutdown(), allocate(), setAnnotation(key, value) and setLabel(key, value) are async methods that perform an action and return an empty result.

To get details of the backing GameServer call the async method getGameServer(). The result will be an object representing GameServer defined in `sdk.proto` .

let result = await agonesSDK.getGameServer();

To get updates on the backing GameServer as they happen, call watchGameServer(callback). The callback will be called with a parameter matching the result of getGameServer().

agonesSDK.watchGameServer((result) => {
	console.log('watch', result);
});

To mark the game server as reserved for a period of time, call the async method reserve(seconds). The result will be an empty object.

For more information, please read the SDK Overview, check out agonesSDK.js and also look at the Node.js example .

Docs: Metrics

Thu, 03 Jan 2019 03:58:19 +0000

Agones controller exposes metrics via OpenCensus. OpenCensus is a single distribution of libraries that collect metrics and distributed traces from your services, we only use it for metrics but it will allow us to support multiple exporters in the future.

We choose to start with Prometheus as this is the most popular with Kubernetes but it is also compatible with Stackdriver. If you need another exporter, check the list of supported exporters. It should be pretty straightforward to register a new one. (GitHub PRs are more than welcome.)

We plan to support multiple exporters in the future via environment variables and helm flags.

Backend integrations

Prometheus

If you are running a Prometheus instance you just need to ensure that metrics and kubernetes service discovery are enabled. (helm chart values agones.metrics.prometheusEnabled and agones.metrics.prometheusServiceDiscovery). This will automatically add annotations required by Prometheus to discover Agones metrics and start collecting them. (see example)

Prometheus Operator

If you have Prometheus operator installed in your cluster, make sure to add a ServiceMonitor to discover Agones metrics as shown below:

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: agones
  labels:
    app: agones
spec:
  selector:
    matchLabels:
        agones.dev/role: controller
  endpoints:
  - port: web

Finally include that ServiceMonitor in your Prometheus instance CRD, this is usually done by adding a label to the ServiceMonitor above that is matched by the prometheus instance of your choice.

Stackdriver

We support the OpenCensus Stackdriver exporter. In order to use it you should enable Stackdriver Monitoring API in Google Cloud Console. Follow the Stackdriver Installation steps to see your metrics on Stackdriver Monitoring website.

Metrics available

Name	Description	Type
agones_gameservers_count	The number of gameservers per fleet and status	gauge
agones_gameserver_allocations_duration_seconds	The distribution of gameserver allocation requests latencies	histogram
agones_gameservers_total	The total of gameservers per fleet and status	counter
agones_fleets_replicas_count	The number of replicas per fleet (total, desired, ready, allocated)	gauge
agones_fleet_autoscalers_able_to_scale	The fleet autoscaler can access the fleet to scale	gauge
agones_fleet_autoscalers_buffer_limits	The limits of buffer based fleet autoscalers (min, max)	gauge
agones_fleet_autoscalers_buffer_size	The buffer size of fleet autoscalers (count or percentage)	gauge
agones_fleet_autoscalers_current_replicas_count	The current replicas count as seen by autoscalers	gauge
agones_fleet_autoscalers_desired_replicas_count	The desired replicas count as seen by autoscalers	gauge
agones_fleet_autoscalers_limited	The fleet autoscaler is capped (1)	gauge
agones_gameservers_node_count	The distribution of gameservers per node	histogram
agones_nodes_count	The count of nodes empty and with gameservers	gauge
agones_k8s_client_http_request_total	The total of HTTP requests to the Kubernetes API by status code	counter
agones_k8s_client_http_request_duration_seconds	The distribution of HTTP requests latencies to the Kubernetes API by status code	histogram
agones_k8s_client_cache_list_total	The total number of list operations for client-go caches	counter
agones_k8s_client_cache_list_duration_seconds	Duration of a Kubernetes list API call in seconds	histogram
agones_k8s_client_cache_list_items	Count of items in a list from the Kubernetes API	histogram
agones_k8s_client_cache_watches_total	The total number of watch operations for client-go caches	counter
agones_k8s_client_cache_last_resource_version	Last resource version from the Kubernetes API	gauge
agones_k8s_client_workqueue_depth	Current depth of the work queue	gauge
agones_k8s_client_workqueue_latency_seconds	How long an item stays in the work queue	histogram
agones_k8s_client_workqueue_items_total	Total number of items added to the work queue	counter
agones_k8s_client_workqueue_work_duration_seconds	How long processing an item from the work queue takes	histogram
agones_k8s_client_workqueue_retries_total	Total number of items retried to the work queue	counter
agones_k8s_client_workqueue_longest_running_processor	How long the longest running workqueue processor has been running in microseconds	gauge
agones_k8s_client_workqueue_unfinished_work_seconds	How long unfinished work has been sitting in the workqueue in seconds	gauge

Dashboard

Grafana Dashboards

We provide a set of useful Grafana dashboards to monitor Agones workload, they are located under the grafana folder :

Agones Autoscalers allows you to monitor your current autoscalers replicas request as well as fleet replicas allocation and readyness statuses. You can only select one autoscaler at the time using the provided dropdown.
Agones GameServers displays your current game servers workload status (allocations, game servers statuses, fleets replicas) with optional fleet name filtering.
Agones GameServer Allocations displays Agones gameservers allocations rates and counts per fleet.
Agones Allocator Resource displays Agones Allocators CPU, memory usage and also some useful Golang runtime metrics.
Agones Status displays Agones controller health status.
Agones Controller Resource Usage displays Agones Controller CPU and memory usage and also some Golang runtime metrics.
Agones Controller go-client requests displays Agones Controller Kubernetes API consumption.
Agones Controller go-client caches displays Agones Controller Kubernetes Watches/Lists operations used.
Agones Controller go-client workqueues displays Agones Controller workqueue processing time and rates.
Agones Controller API Server requests displays your current API server request rate, errors rate and request latencies with optional CustomResourceDefinition filtering by Types: fleets, gameserversets, gameservers, gameserverallocations.

Dashboard screenshots :

Note

You can import our dashboards by copying the json content from each config map into your own instance of Grafana (+ > Create > Import > Or paste json) or follow the installation guide.

Installation

When operating a live multiplayer game you will need to observe performances, resource usage and availability to learn more about your system. This guide will explain how you can setup Prometheus and Grafana into your own Kubernetes cluster to monitor your Agones workload.

Before attemping this guide you should make sure you have kubectl and helm installed and configured to reach your kubernetes cluster.

Prometheus installation

Prometheus is an open source monitoring solution, we will use it to store Agones controller metrics and query back the data.

Let’s install Prometheus using the helm stable repository.

helm upgrade --install --wait prom stable/prometheus --namespace metrics \
    --set server.global.scrape_interval=30s \
    --set server.persistentVolume.enabled=true \
    --set server.persistentVolume.size=64Gi \
    -f ./build/prometheus.yaml

Note

You can also run our Makefile target make setup-prometheus or make kind-setup-prometheus and make minikube-setup-prometheus for Kind and Minikube .

For resiliency it is recommended to run Prometheus on a dedicated node which is separate from nodes where Game Servers are scheduled. If you use the above command, with our prometheus.yaml to set up Prometheus, it will schedule Prometheus pods on nodes tainted with agones.dev/agones-metrics=true:NoExecute and labeled with agones.dev/agones-metrics=true if available.

As an example, to set up a dedicated node pool for Prometheus on GKE, run the following command before installing Prometheus. Alternatively you can taint and label nodes manually.

gcloud container node-pools create agones-metrics --cluster=... --zone=... \
  --node-taints agones.dev/agones-metrics=true:NoExecute \
  --node-labels agones.dev/agones-metrics=true \
  --num-nodes=1

By default we will disable the push gateway (we don’t need it for Agones) and other exporters.

The helm chart support nodeSelector, affinity and toleration, you can use them to schedule prometheus deployments on an isolated node(s) to have an homogeneous game servers workload.

This will install a Prometheus Server in your current cluster with Persistent Volume Claim (Deactivated for Minikube and Kind) for storing and querying time series, it will automatically start collecting metrics from Agones Controller.

Finally to access Prometheus metrics, rules and alerts explorer use

kubectl port-forward deployments/prom-prometheus-server 9090 -n metrics

Note

Again you can use our Makefile make prometheus-portforward . (For Kind and Minikube use their specific targets make kind-prometheus-portforward and make minikube-prometheus-portforward)

Now you can access the prometheus dashboard http://localhost:9090.

On the landing page you can start exploring metrics by creating queries. You can also verify what targets Prometheus currently monitors (Header Status > Targets), you should see Agones controller pod in the kubernetes-pods section.

Note

Metrics will be first registered when you will start using Agones.

Now let’s install some Grafana dashboards.

Grafana installation

Grafana is a open source time series analytics platform which supports Prometheus data source. We can also easily import pre-built dashboards.

First we will install Agones dashboard as config maps in our cluster.

kubectl apply -f ./build/grafana/

Now we can install grafana chart from stable repository. (Replace <your-admin-password> with the admin password of your choice)

helm install --wait --name grafana stable/grafana --version=5.0.13 --namespace metrics \
  --set adminPassword=<your-admin-password> -f ./build/grafana.yaml

This will install Grafana with our prepopulated dashboards and prometheus datasource previously installed

Note

You can also use our Makefile targets (setup-grafana, minikube-setup-grafana and kind-setup-grafana).

Finally to access dashboards run

kubectl port-forward deployments/grafana 3000 -n metrics

Open a web browser to http://localhost:3000, you should see Agones dashboards after login as admin.

Note

You can also use our Makefile targets make grafana-portforward, make kind-grafana-portforward and make minikube-grafana-portforward.

Stackdriver installation

In order to use Stackdriver monitoring you should enable Stackdriver Monitoring API on Google Cloud Console. You need to grant all the necessary permissions to the users (see Access Control Guide). Stackdriver exporter uses a strategy called Application Default Credentials (ADC) to find your application’s credentials. Details could be found here Setting Up Authentication for Server to Server Production Applications.

Note that Stackdriver monitoring is enabled by default on GKE clusters, however you can follow this guide if it was disabled on your GKE cluster.

Default metrics exporter is Prometheus. If you are using the Helm installation, you can install or upgrade Agones to use Stackdriver, using the following chart parameters:

helm upgrade --install --wait --set agones.metrics.stackdriverEnabled=true --set agones.metrics.prometheusEnabled=false --set agones.metrics.prometheusServiceDiscovery=false my-release-name agones/agones --namespace=agones-system

With this configuration only Stackdriver exporter would be used instead of Prometheus exporter.

Create a Fleet or a Gameserver in order to check that connection with stackdriver API is configured properly and so that you will be able to see the metrics data.

Visit Stackdriver monitoring website, select your project, or choose Create a new Workspace and select GCP project where your cluster resides. In Stackdriver metrics explorer you should be able to find new metrics with prefix agones/ after a couple of minutes. Choose the metrics you are interested in and add to a single or separate graphs. Select Kubernetes Container resource type for each of them. You can create multiple graphs, save them into your dashboard and use various aggregation parameters and reducers for each graph.

Example of the dashboard appearance is provided below:

Currently there exists only manual way of configuring Stackdriver Dashboard. So it is up to you to set an Alignment Period (minimal is 1 minute), GroupBy, Filter parameters and other graph settings.

Troubleshooting

If you can’t see Agones metrics you should have a look at the controller logs for connection errors. Also ensure that your cluster has the necessary credentials to interact with Stackdriver Monitoring. You can configure stackdriverProjectID manually, if the automatic discovery is not working.

Permissions problem example from controller logs:

Failed to export to Stackdriver: rpc error: code = PermissionDenied desc = Permission monitoring.metricDescriptors.create denied (or the resource may not exist).

Docs: Access Agones via the Kubernetes API

Thu, 03 Jan 2019 01:20:41 +0000

Installing Agones creates several Custom Resource Definitions (CRD), which can be accessed and manipulated through the Kubernetes API.

The detailed list of Agones CRDs with their parameters could be found here - Agones CRD API Reference.

Kubernetes has multiple client libraries, however, at time of writing, only the Go and Python clients are documented to support accessing CRDs.

This can be found in the Accessing a custom resource section of the Kubernetes documentation.

At this time, we recommend interacting with Agones through the Go client that has been generated in this repository, but other methods may also work as well.

Go Client

Kubernetes Go Client tooling generates a Client for Agones that we can use to interact with the Agones installation on our Kubernetes cluster.

Authentication

This client uses the same authentication mechanisms as the Kubernetes API.

If you plan to run your code in the same cluster as the Agones install, have a look at the in cluster configuration example from the Kubernetes Client.

If you plan to run your code outside the Kubernetes cluster as your Agones install, look at the out of cluster configuration example from the Kubernetes client.

Example

The following is an example of a in-cluster configuration, that creates a Clientset for Agones and then creates a GameServer.

A full example code is available in the example folder .

package main

import (
	"fmt"

	agonesv1 "agones.dev/agones/pkg/apis/agones/v1"
	"agones.dev/agones/pkg/client/clientset/versioned"
	"agones.dev/agones/pkg/util/runtime"
	corev1 "k8s.io/api/core/v1"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/client-go/kubernetes"
	"k8s.io/client-go/rest"
)

func main() {
	config, err := rest.InClusterConfig()
	logger := runtime.NewLoggerWithSource("main")
	if err != nil {
		logger.WithError(err).Fatal("Could not create in cluster config")
	}

	// Access to standard Kubernetes resources through the Kubernetes Clientset
	// We don't actually need this for this example, but it's just here for
	// illustrative purposes
	kubeClient, err := kubernetes.NewForConfig(config)
	if err != nil {
		logger.WithError(err).Fatal("Could not create the kubernetes clientset")
	}

	// Access to the Agones resources through the Agones Clientset
	// Note that we reuse the same config as we used for the Kubernetes Clientset
	agonesClient, err := versioned.NewForConfig(config)
	if err != nil {
		logger.WithError(err).Fatal("Could not create the agones api clientset")
	}

	// Create a GameServer
	gs := &agonesv1.GameServer{ObjectMeta: metav1.ObjectMeta{GenerateName: "udp-server", Namespace: "default"},
		Spec: agonesv1.GameServerSpec{
			Container: "udp-server",
			Ports: []agonesv1.GameServerPort{{
				ContainerPort: 7654,
				HostPort:      7654,
				Name:          "gameport",
				PortPolicy:    agonesv1.Static,
				Protocol:      corev1.ProtocolUDP,
			}},
			Template: corev1.PodTemplateSpec{
				Spec: corev1.PodSpec{
					Containers: []corev1.Container{{Name: "udp-server", Image: "gcr.io/agones-images/udp-server:0.21"}},
				},
			},
		},
	}
	newGS, err := agonesClient.AgonesV1().GameServers("default").Create(gs)
	if err != nil {
		panic(err)
	}

	fmt.Printf("New game servers' name is: %s", newGS.ObjectMeta.Name)
}

In order to create GS using provided example, you can run it as a Kubernetes Job:

$ kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/crd-client/create-gs.yaml --namespace agones-system
$ kubectl get pods --namespace agones-system
NAME                                 READY   STATUS      RESTARTS   AGE
create-gs-6wz86-7qsm5                0/1     Completed   0          6s
$ kubectl logs create-gs-6wz86-7qsm5  --namespace agones-system
{"message":"\u0026{0xc0001dde00 default}","severity":"info","source":"main","time":"2020-04-21T11:14:00.477576428Z"}
{"message":"New GameServer name is: helm-test-server-fxfgg","severity":"info","time":"2020-04-21T11:14:00.516024697Z"}

You have just created a GameServer using Kubernetes Go Client.

Direct Access to the REST API via Kubectl

If there isn’t a client written in your preferred language, it is always possible to communicate directly with Kubernetes API to interact with Agones.

The Kubernetes API can be authenticated and exposed locally through the kubectl proxy

For example:

$ kubectl proxy &
Starting to serve on 127.0.0.1:8001

# list all Agones endpoints
$ curl http://localhost:8001/apis | grep agones -A 5 -B 5
...
    {
      "name": "agones.dev",
      "versions": [
        {
          "groupVersion": "agones.dev/v1",
          "version": "v1"
        }
      ],
      "preferredVersion": {
        "groupVersion": "agones.dev/v1",
        "version": "v1"
      },
      "serverAddressByClientCIDRs": null
    }
...

# List Agones resources
$ curl http://localhost:8001/apis/agones.dev/v1
{
  "kind": "APIResourceList",
  "apiVersion": "v1",
  "groupVersion": "agones.dev/v1",
  "resources": [
    {
      "name": "gameservers",
      "singularName": "gameserver",
      "namespaced": true,
      "kind": "GameServer",
      "verbs": [
        "delete",
        "deletecollection",
        "get",
        "list",
        "patch",
        "create",
        "update",
        "watch"
      ],
      "shortNames": [
        "gs"
      ]
    }
  ]
}

# list all gameservers in the default namespace
$ curl http://localhost:8001/apis/agones.dev/v1/namespaces/default/gameservers
{
    "apiVersion": "agones.dev/v1",
    "items": [
        {
            "apiVersion": "agones.dev/v1",
            "kind": "GameServer",
            "metadata": {
                "annotations": {
                    "kubectl.kubernetes.io/last-applied-configuration": "{\"apiVersion\":\"agones.dev/v1\",\"kind\":\"GameServer\",\"metadata\":{\"annotations\":{},\"name\":\"simple-udp\",\"namespace\":\"default\"},\"spec\":{\"containerPort\":7654,\"hostPort\":7777,\"portPolicy\":\"static\",\"template\":{\"spec\":{\"containers\":[{\"image\":\"gcr.io/agones-images/udp-server:0.21\",\"name\":\"simple-udp\"}]}}}}\n"
                },
                "clusterName": "",
                "creationTimestamp": "2018-03-02T21:41:05Z",
                "finalizers": [
                    "agones.dev"
                ],
                "generation": 0,
                "name": "simple-udp",
                "namespace": "default",
                "resourceVersion": "760",
                "selfLink": "/apis/agones.dev/v1/namespaces/default/gameservers/simple-udp",
                "uid": "692beea6-1e62-11e8-beb2-080027637781"
            },
            "spec": {
                "PortPolicy": "Static",
                "container": "simple-udp",
                "containerPort": 7654,
                "health": {
                    "failureThreshold": 3,
                    "initialDelaySeconds": 5,
                    "periodSeconds": 5
                },
                "hostPort": 7777,
                "protocol": "UDP",
                "template": {
                    "metadata": {
                        "creationTimestamp": null
                    },
                    "spec": {
                        "containers": [
                            {
                                "image": "gcr.io/agones-images/udp-server:0.21",
                                "name": "simple-udp",
                                "resources": {}
                            }
                        ]
                    }
                }
            },
            "status": {
                "address": "192.168.99.100",
                "nodeName": "agones",
                "port": 7777,
                "state": "Ready"
            }
        }
    ],
    "kind": "GameServerList",
    "metadata": {
        "continue": "",
        "resourceVersion": "1062",
        "selfLink": "/apis/agones.dev/v1/namespaces/default/gameservers"
    }
}

# allocate a gameserver from a fleet named 'simple-udp', with GameServerAllocation

$ curl -d '{"apiVersion":"allocation.agones.dev/v1","kind":"GameServerAllocation","spec":{"required":{"matchLabels":{"agones.dev/fleet":"simple-udp"}}}}' -H "Content-Type: application/json" -X POST http://localhost:8001/apis/allocation.agones.dev/v1/namespaces/default/gameserverallocations

{
    "kind": "GameServerAllocation",
    "apiVersion": "allocation.agones.dev/v1",
    "metadata": {
        "name": "simple-udp-v6jwb-cmdcv",
        "namespace": "default",
        "creationTimestamp": "2019-07-03T17:19:47Z"
    },
    "spec": {
        "multiClusterSetting": {
            "policySelector": {}
        },
        "required": {
            "matchLabels": {
                "agones.dev/fleet": "simple-udp"
            }
        },
        "scheduling": "Packed",
        "metadata": {}
    },
    "status": {
        "state": "Allocated",
        "gameServerName": "simple-udp-v6jwb-cmdcv",
        "ports": [
            {
                "name": "default",
                "port": 7445
            }
        ],
        "address": "34.94.118.237",
        "nodeName": "gke-test-cluster-default-f11755a7-5km3"
    }
}

You may wish to review the Agones Kubernetes API for the full data structure reference.

The Kubernetes API Concepts section may also provide the more details on the API conventions that are used in the Kubernetes API.

Next Steps

Learn how to use Allocator Service for single and multi-cluster Allocation.

Docs: Rust Game Server Client SDK

Wed, 02 Jan 2019 10:17:57 +0000

Check the Client SDK Documentation for more details on each of the SDK functions and how to run the SDK locally.

Download

Download the source directly from GitHub .

Prerequisites

CMake >= 3.8.0
Rust >= 1.19.0
Go (>=1.7)

The SDK needs the above for building to gRPC-rs.

Usage

Add this crate to dependencies section in your Cargo.toml. Specify a directory where this README.md is located to the path.

[dependencies]
agones = { path = "../agones/sdks/rust" }

Add extern crate agones to your crate root.

To begin working with the SDK, create an instance of it. This function blocks until connection and handshake are made.

let sdk = agones::Sdk::new()?;

To send a health check ping call sdk.health().

if sdk.health().is_ok() {
    println!("Health ping sent");
}

To mark the game session as ready call sdk.ready().

sdk.ready()?;

To mark the game server as reserved for a period of time, call sdk.reserve(duration).

sdk.reserve(Duration::new(5, 0))?;

To mark that the game session is completed and the game server should be shut down call sdk.shutdown().

if sdk.shutdown().is_err() {
    println!("Could not run Shutdown");
}

To set a Label on the backing GameServer call sdk.set_label(key, value).

sdk.set_label("test-label", "test-value")?;

To set an Annotation on the backing GameServer call sdk.set_annotation(key, value).

sdk.set_annotation("test-annotation", "test value")?;

To get details of the backing GameServer call sdk.get_gameserver().

The function will return an instance of agones::types::GameServer including GameServer configuration info.

let gameserver = sdk.get_gameserver()?;

To get updates on the backing GameServer as they happen, call sdk.watch_gameserver(|gameserver| {...}).

This will call the passed closure synchronously (this is a blocking function, so you may want to run it in its own thread) whenever the backing GameServer is updated.

sdk.watch_gameserver(|gameserver| {
    println!("GameServer Update, name: {}", gameserver.object_meta.unwrap().name);
    println!("GameServer Update, state: {}", gameserver.status.unwrap().state);
})?;

For more information, please read the SDK Overview, check out agones sdk implementation and also look at the Rust example .

Docs: Confirming Agones Installation

Mon, 01 Jan 0001 00:00:00 +0000

To confirm Agones is up and running, run the following command:

kubectl describe --namespace agones-system pods

It should describe six pods created in the agones-system namespace, with no error messages or status. All Conditions sections should look like this:

Conditions:
  Type              Status
  Initialized       True
  Ready             True
  ContainersReady   True
  PodScheduled      True

All this pods should be in a RUNNING state:

kubectl get pods --namespace agones-system

NAME                                 READY   STATUS    RESTARTS   AGE
agones-allocator-5c988b7b8d-cgtbs    1/1     Running   0          8m47s
agones-allocator-5c988b7b8d-hhhr5    1/1     Running   0          8m47s
agones-allocator-5c988b7b8d-pv577    1/1     Running   0          8m47s
agones-controller-7db45966db-56l66   1/1     Running   0          8m44s
agones-ping-84c64f6c9d-bdlzh         1/1     Running   0          8m37s
agones-ping-84c64f6c9d-sjgzz         1/1     Running   0          8m47s

That’s it!

Now with Agones installed, you can utilise its Custom Resource Definitions to create resources of type GameServer, Fleet and more!

What’s next

Go through the Create a Game Server Quickstart

Docs: Upgrading Agones and Kubernetes

Fri, 16 Aug 2019 00:19:19 +0000

Note

Whichever approach you take to upgrading Agones, make sure to test it in your development environment before applying it to production.

Upgrading Agones

The following are strategies for safely upgrading Agones from one version to another. They may require adjustment to your particular game architecture but should provide a solid foundation for updating Agones safely.

The recommended approach is to use multiple clusters, such that the upgrade can be tested gradually with production load and easily rolled back if the need arises.

Upgrading Agones: Multiple Clusters

We essentially want to transition our GameServer allocations from a cluster with the old version of Agones, to a cluster with the upgraded version of Agones while ensuring nothing surprising happens during this process.

This also allows easy rollback to the previous infrastructure that we already know to be working in production, with minimal interruptions to player experience.

The following are steps to implement this:

Create a new cluster of the same size or smaller as the current cluster.
Install the new version of Agones on the new cluster.
Deploy the same set of Fleets and/or GameServers from the old cluster into the new cluster.
With your matchmaker, start sending a small percentage of your matched players’ game sessions to the new cluster.
Assuming everything is working successfully on the new cluster, slowly increase the percentage of matched sessions to the new cluster, until you reach 100%.
Once you are comfortable with the stability of the new cluster with the new Agones version, shut down the old cluster.
Congratulations - you have now upgraded to a new version of Agones! 👍

Upgrading Agones: Single Cluster

If you are upgrading a single cluster, we recommend creating a maintenance window, in which your game goes offline for the period of your upgrade, as there will be a short period in which Agones will be non-responsive during the upgrade.

Installation with install.yaml

If you installed Agones with install.yaml, then you will need to delete the previous installation of Agones before upgrading to the new version, as we need to remove all of Agones before installing the new version.

Start your maintenance window.
Delete the current set of Fleets and/or GameServers in your cluster.
Make sure to delete the same version of Agones that was previously installed, for example: kubectl delete -f https://raw.githubusercontent.com/googleforgames/agones/<old-release-version>/install/yaml/install.yaml
Install Agones with install.yaml.
Deploy the same set of Fleets and/or GameServers back into the cluster.
Run any other tests to ensure the Agones installation is working as expected.
Close your maintenance window.
Congratulations - you have now upgraded to a new version of Agones! 👍

Installation with Helm

Helm features capabilities for upgrading to newer versions of Agones without having to delete the older version or your existing Fleets.

For details on how to use Helm for upgrades, see the helm upgrade documentation.

Given the above, the steps for upgrade are simpler:

Start your maintenance window.
Run helm upgrade with the appropriate arguments, such a --version, for your specific upgrade
Run any other tests to ensure the Agones installation is working as expected.
Close your maintenance window.
Congratulations - you have now upgraded to a new version of Agones! 👍

Upgrading Kubernetes

The following are strategies for safely upgrading the underlying Kubernetes cluster from one version to another. They may require adjustment to your particular game architecture but should provide a solid foundation for updating your cluster safely.

The recommended approach is to use multiple clusters, such that the upgrade can be tested gradually with production load and easily rolled back if the need arises.

Agones currently has only a single supported Kubernetes version for each version, so it is recommended to do supported minor (e.g. 1.12.1 ➡ 1.13.2) Kubernetes version upgrades at the same time as a matching Agones upgrades.

Patch upgrades (e.g. 1.12.1 ➡ 1.12.3) within the same minor version of Kubernetes can be done at any time.

Multiple Clusters

This process is very similar to the Upgrading Agones: Multiple Clusters approach above.

We essentially want to transition our GameServer allocations from a cluster with the old version of Kubernetes, to a cluster with the upgraded version of Kubernetes while ensuring nothing surprising happens during this process.

This also allows easy rollback to the previous infrastructure that we already know to be working in production, with minimal interruptions to player experience.

The following are steps to implement this:

Create a new cluster of the same size or smaller as the current cluster, with the new version of Kubernetes
Install the same version of Agones on the new cluster, as you have on the previous cluster.
Deploy the same set of Fleets and/or GameServers from the old cluster into the new cluster.
With your matchmaker, start sending a small percentage of your matched players’ game sessions to the new cluster.
Assuming everything is working successfully on the new cluster, slowly increase the percentage of matched sessions to the new cluster, until you reach 100%.
Once you are comfortable with the stability of the new cluster with the new Kubernetes version, shut down the old cluster.
Congratulations - you have now upgraded to a new version of Kubernetes! 👍

Single Cluster

Start your maintenance window.
Scale your Fleets down to 0 and/or delete your GameServers. This is a good safety measure so there aren’t race conditions between the Agones controller being recreated and GameServers being deleted doesn’t occur, and GameServers can end up stuck in erroneous states.
Start and complete you master upgrade(s).
Start and complete your node upgrades.
Scale your Fleets back up and/or recreate your GameServers.
Run any other tests to ensure the Agones installation is still working as expected.
Close your maintenance window.
Congratulations - you have now upgraded to a new version of Kubernetes! 👍

Docs: REST Game Server Client API

Wed, 02 Jan 2019 10:18:08 +0000

Check the Client SDK Documentation for more details on each of the SDK functions and how to run the SDK locally.

The REST API can be accessed from http://localhost:${AGONES_SDK_HTTP_PORT}/ from the game server process. AGONES_SDK_HTTP_PORT is an environment variable automatically set for the game server process by Agones to support binding the REST API to a dynamic port. It is advised to use the environment variable rather than a hard coded port; otherwise your game server will not be able to contact the SDK server if it is configured to use a non-default port.

Generally the REST interface gets used if gRPC isn’t well supported for a given language or platform.

Warning

The SDK Server sidecar process may startup after your game server binary. So your REST SDK API calls should contain some retry logic to take this into account.

Generating clients

While you can hand write REST integrations, we also have a set of generated OpenAPI/Swagger definitions available. This means you can use OpenAPI/Swagger tooling to generate clients as well, if you need them.

For example, to create a cpp client for the stable sdk endpoints (to be run in the agones home directory):

docker run --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate -i /local/sdks/swagger/sdk.swagger.json  -l cpprest -o /local/out/cpp

The same could be run for alpha.swagger.json and beta.swagger.json as required.

You can read more about OpenAPI/Swagger code generation in their Command Line Tool Documentation

Reference

Lifecycle Management

Ready

Call when the GameServer is ready to accept connections

Path: /ready
Method: POST
Body: {}

Example

$ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/ready

Health

Send a Empty every d Duration to declare that this GameServer is healthy

Path: /health
Method: POST
Body: {}

Example

$ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/health

Reserve

Move Gameserver into a Reserved state for a certain amount of seconds for the future allocation.

Path: /reserve
Method: POST
Body: {"seconds": "5"}

Example

$ curl -d '{"seconds": "5"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/reserve

Allocate

With some matchmakers and game matching strategies, it can be important for game servers to mark themselves as Allocated. For those scenarios, this SDK functionality exists.

Note

Using a GameServerAllocation is preferred in all other scenarios, as it gives Agones control over how packed GameServers are scheduled within a cluster, whereas with Allocate() you relinquish control to an external service which likely doesn’t have as much information as Agones.

Example

$ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/allocate

Shutdown

Call when the GameServer session is over and it’s time to shut down

Path: /shutdown
Method: POST
Body: {}

Example

$ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/shutdown

Configuration Retrieval

GameServer

Call when you want to retrieve the backing GameServer configuration details

Path: /gameserver

Method: GET

$ curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/gameserver

Response:

{
    "object_meta": {
        "name": "local",
        "namespace": "default",
        "uid": "1234",
        "resource_version": "v1",
        "generation": "1",
        "creation_timestamp": "1531795395",
        "annotations": {
            "annotation": "true"
        },
        "labels": {
            "islocal": "true"
        }
    },
    "status": {
        "state": "Ready",
        "address": "127.0.0.1",
        "ports": [
            {
                "name": "default",
                "port": 7777
            }
        ]
    }
}

Watch GameServer

Call this when you want to get updates of when the backing GameServer configuration is updated.

These updates will come as newline delimited JSON, send on each update. To that end, you will want to keep the http connection open, and read lines from the result stream and and process as they come in.

$ curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/watch/gameserver

Response:

{"result":{"object_meta":{"name":"local","namespace":"default","uid":"1234","resource_version":"v1","generation":"1","creation_timestamp":"1533766607","annotations":{"annotation":"true"},"labels":{"islocal":"true"}},"status":{"state":"Ready","address":"127.0.0.1","ports":[{"name":"default","port":7777}]}}}
{"result":{"object_meta":{"name":"local","namespace":"default","uid":"1234","resource_version":"v1","generation":"1","creation_timestamp":"1533766607","annotations":{"annotation":"true"},"labels":{"islocal":"true"}},"status":{"state":"Ready","address":"127.0.0.1","ports":[{"name":"default","port":7777}]}}}
{"result":{"object_meta":{"name":"local","namespace":"default","uid":"1234","resource_version":"v1","generation":"1","creation_timestamp":"1533766607","annotations":{"annotation":"true"},"labels":{"islocal":"true"}},"status":{"state":"Ready","address":"127.0.0.1","ports":[{"name":"default","port":7777}]}}}

Metadata Management

Set Label

Apply a Label with the prefix “agones.dev/sdk-” to the backing GameServer metadata.

See the SDK SetLabel documentation for restrictions.

Example

$ curl -d '{"key": "foo", "value": "bar"}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/metadata/label

Set Annotation

Apply an Annotation with the prefix “agones.dev/sdk-” to the backing GameServer metadata

Example

$ curl -d '{"key": "foo", "value": "bar"}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/metadata/annotation

Player Tracking

Warning

The Player Tracking feature is currently Alpha, not enabled by default, and may change in the future.

Use the Feature Gate PlayerTracking to enable and test this feature.

See the Feature Gate documentation for details on how to enable features.

Alpha: PlayerConnect

This function increases the SDK’s stored player count by one, and appends this playerID to GameServer.Status.Players.IDs.

Example

$ curl -d '{"playerID": "uzh7i"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/connect

Response:

{"bool":true}

Alpha: PlayerDisconnect

This function decreases the SDK’s stored player count by one, and removes the playerID from GameServer.Status.Players.IDs.

Example

$ curl -d '{"playerID": "uzh7i"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/disconnect

Response:

{"bool":true}

Alpha: SetPlayerCapacity

Update the GameServer.Status.Players.Capacity value with a new capacity.

Example

$ curl -d '{"count": 5}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/capacity

Alpha: GetPlayerCapacity

This function retrieves the current player capacity. This is always accurate from what has been set through this SDK, even if the value has yet to be updated on the GameServer status resource.

Example

$ curl -d '{}' -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/capacity

Response:

{"count":"5"}

Alpha: GetPlayerCount

This function returns if the playerID is currently connected to the GameServer. This is always accurate from what has been set through this SDK, even if the value has yet to be updated on the GameServer status resource.

$ curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/count

Response:

{"count":"2"}

Example

Alpha: IsPlayerConnected

Example

$ curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/connected/uzh7i

Response:

{"bool":true}

Alpha: GetConnectedPlayers

This function returns the list of the currently connected player ids. This is always accurate from what has been set through this SDK, even if the value has yet to be updated on the GameServer status resource.

Example

$ curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/connected

Response:

{"list":["uzh7i","3zh7i"]}

Docs: Minikube

Mon, 01 Jan 0001 00:00:00 +0000

Installing Minikube

First, install Minikube, which may also require you to install a virtualisation solution, such as VirtualBox as well.

Creating an `agones` profile

Let’s use a minikube profile for agones, to make sure we don’t overlap any existing Minikube clusters you may be running.

minikube profile agones

Starting Minikube

The following command starts a local minikube cluster via virtualbox - but this can be replaced by a vm-driver of your choice.

minikube start --kubernetes-version v1.15.10 --vm-driver virtualbox

Next Steps

Continue to Install Agones.

Docs: Troubleshooting

Thu, 03 Jan 2019 01:20:49 +0000

Something went wrong with my GameServer

If there is something going wrong with your GameServer, there are a few approaches to determining the cause:

Depending on what is happening, you may want to run kubectl describe <gameserver name> to view the events that are associated with that particular GameServer resource. This can give you insight into the lifecycle of the GameServer and if anything has gone wrong.

For example, here we can see where the simple-udp example has been moved to the Unhealthy state due to a crash in the backing GameServer Pod container’s binary.

root@6a71afd42291:/go/src/agones.dev/agones# kubectl describe gs simple-udp-zqppv
Name:         simple-udp-zqppv
Namespace:    default
Labels:       <none>
Annotations:  agones.dev/sdk-version: 1.0.0-dce1546
API Version:  agones.dev/v1
Kind:         GameServer
Metadata:
  Creation Timestamp:  2019-08-16T21:25:44Z
  Finalizers:
    agones.dev
  Generate Name:     simple-udp-
  Generation:        1
  Resource Version:  1378575
  Self Link:         /apis/agones.dev/v1/namespaces/default/gameservers/simple-udp-zqppv
  UID:               6818adc7-c06c-11e9-8dbd-42010a8a0109
Spec:
  Container:  simple-udp
  Health:
    Failure Threshold:      3
    Initial Delay Seconds:  5
    Period Seconds:         5
  Ports:
    Container Port:  7654
    Host Port:       7058
    Name:            default
    Port Policy:     Dynamic
    Protocol:        UDP
  Scheduling:        Packed
  Template:
    Metadata:
      Creation Timestamp:  <nil>
    Spec:
      Containers:
        Image:  gcr.io/agones-images/udp-server:0.21
        Name:   simple-udp
        Resources:
          Limits:
            Cpu:     20m
            Memory:  32Mi
          Requests:
            Cpu:     20m
            Memory:  32Mi
Status:
  Address:    35.230.59.117
  Node Name:  gke-test-cluster-default-590db5e4-4s6r
  Ports:
    Name:          default
    Port:          7058
  Reserved Until:  <nil>
  State:           Unhealthy
Events:
  Type     Reason          Age   From                   Message
  ----     ------          ----  ----                   -------
  Normal   PortAllocation  72s   gameserver-controller  Port allocated
  Normal   Creating        72s   gameserver-controller  Pod simple-udp-zqppv created
  Normal   Scheduled       72s   gameserver-controller  Address and port populated
  Normal   RequestReady    67s   gameserver-sidecar     SDK state change
  Normal   Ready           66s   gameserver-controller  SDK.Ready() complete
  Warning  Unhealthy       34s   health-controller      Issue with Gameserver pod

The backing Pod has the same name as the GameServer - so it’s also worth looking at the details and events for the Pod to see if there are any issues there, such as restarts due to binary crashes etc.

For example, you can see the restart count on the gcr.io/agones-images/udp-server:0.21 container is set to 1, due to the game server binary crash

root@6a71afd42291:/go/src/agones.dev/agones# kubectl describe pod simple-udp-zqppv
Name:               simple-udp-zqppv
Namespace:          default
Priority:           0
PriorityClassName:  <none>
Node:               gke-test-cluster-default-590db5e4-4s6r/10.138.0.23
Start Time:         Fri, 16 Aug 2019 21:25:44 +0000
Labels:             agones.dev/gameserver=simple-udp-zqppv
                    agones.dev/role=gameserver
Annotations:        agones.dev/container: simple-udp
                    agones.dev/sdk-version: 1.0.0-dce1546
                    cluster-autoscaler.kubernetes.io/safe-to-evict: false
Status:             Running
IP:                 10.48.1.80
Controlled By:      GameServer/simple-udp-zqppv
Containers:
  simple-udp:
    Container ID:   docker://69eacd03cc89b0636b78abe47926b02183ba84d18fa20649ca443f5232511661
    Image:          gcr.io/agones-images/udp-server:0.21
    Image ID:       docker-pullable://gcr.io/agones-images/udp-server@sha256:6a60eff5e68b88b5ce75ae98082d79cff36cda411a090f3495760e5c3b6c3575
    Port:           7654/UDP
    Host Port:      7058/UDP
    State:          Running
      Started:      Fri, 16 Aug 2019 21:26:22 +0000
    Last State:     Terminated
      Reason:       Completed
      Exit Code:    0
      Started:      Fri, 16 Aug 2019 21:25:45 +0000
      Finished:     Fri, 16 Aug 2019 21:26:22 +0000
    Ready:          True
    Restart Count:  1
    Limits:
      cpu:     20m
      memory:  32Mi
    Requests:
      cpu:        20m
      memory:     32Mi
    Liveness:     http-get http://:8080/gshealthz delay=5s timeout=1s period=5s #success=1 #failure=3
    Environment:  <none>
    Mounts:
      /var/run/secrets/kubernetes.io/serviceaccount from empty (ro)
  agones-gameserver-sidecar:
    Container ID:   docker://f3c475c34d26232e19b60be65b03bc6ce41931f4c37e00770d3ab4a36281d31c
    Image:          gcr.io/agones-mark/agones-sdk:1.0.0-dce1546
    Image ID:       docker-pullable://gcr.io/agones-mark/agones-sdk@sha256:4b5693e95ee3023a2b2e2099d102bb6bac58d4ce0ac472e58a09cee6d160cd19
    Port:           <none>
    Host Port:      <none>
    State:          Running
      Started:      Fri, 16 Aug 2019 21:25:48 +0000
    Ready:          True
    Restart Count:  0
    Requests:
      cpu:     30m
    Liveness:  http-get http://:8080/healthz delay=3s timeout=1s period=3s #success=1 #failure=3
    Environment:
      GAMESERVER_NAME:  simple-udp-zqppv
      POD_NAMESPACE:    default (v1:metadata.namespace)
    Mounts:
      /var/run/secrets/kubernetes.io/serviceaccount from agones-sdk-token-vr6qq (ro)
Conditions:
  Type              Status
  Initialized       True
  Ready             True
  ContainersReady   True
  PodScheduled      True
Volumes:
  empty:
    Type:    EmptyDir (a temporary directory that shares a pod's lifetime)
    Medium:
  agones-sdk-token-vr6qq:
    Type:        Secret (a volume populated by a Secret)
    SecretName:  agones-sdk-token-vr6qq
    Optional:    false
QoS Class:       Burstable
Node-Selectors:  <none>
Tolerations:     node.kubernetes.io/not-ready:NoExecute for 300s
                 node.kubernetes.io/unreachable:NoExecute for 300s
Events:
  Type    Reason     Age                   From                                             Message
  ----    ------     ----                  ----                                             -------
  Normal  Scheduled  2m32s                 default-scheduler                                Successfully assigned default/simple-udp-zqppv to gke-test-cluster-default-590db5e4-4s6r
  Normal  Pulling    2m31s                 kubelet, gke-test-cluster-default-590db5e4-4s6r  pulling image "gcr.io/agones-mark/agones-sdk:1.0.0-dce1546"
  Normal  Started    2m28s                 kubelet, gke-test-cluster-default-590db5e4-4s6r  Started container
  Normal  Pulled     2m28s                 kubelet, gke-test-cluster-default-590db5e4-4s6r  Successfully pulled image "gcr.io/agones-mark/agones-sdk:1.0.0-dce1546"
  Normal  Created    2m28s                 kubelet, gke-test-cluster-default-590db5e4-4s6r  Created container
  Normal  Created    114s (x2 over 2m31s)  kubelet, gke-test-cluster-default-590db5e4-4s6r  Created container
  Normal  Started    114s (x2 over 2m31s)  kubelet, gke-test-cluster-default-590db5e4-4s6r  Started container
  Normal  Pulled     114s (x2 over 2m31s)  kubelet, gke-test-cluster-default-590db5e4-4s6r  Container image "gcr.io/agones-images/udp-server:0.21" already present on machine

Finally, you can also get the logs of your GameServer Pod as well via kubectl logs <pod name> -c <game server container name>, for example:

root@6a71afd42291:/go/src/agones.dev/agones# kubectl logs simple-udp-zqppv -c simple-udp
2019/08/16 21:26:23 Creating SDK instance
2019/08/16 21:26:24 Starting Health Ping
2019/08/16 21:26:24 Starting UDP server, listening on port 7654
2019/08/16 21:26:24 Marking this server as ready

The above commands will only give the most recent container’s logs (so we won’t get the previous crash), but you can use kubectl logs --previous=true simple-udp-zqppv -c simple-udp to get the previous instance of the containers logs, or use your Kubernetes platform of choice’s logging aggregation tools to view the crash details.

For more tips and tricks, the Kubernetes Cheatsheet: Interactive with Pods also provides more troubleshooting techniques.

How do I see the logs for Agones?

If something is going wrong, and you want to see the logs for Agones, there are potentially two places you will want to check:

The controller: assuming you installed Agones in the agones-system namespace, you will find that there is a single pod called agones-controller-<hash> (where hash is the unique code that Kubernetes generates) that exists there, that you can get the logs from. This is the main controller for Agones, and should be the first place to check when things go wrong.
1. To get the logs from this controller run:
  kubectl logs --namespace=agones-system agones-controller-<hash>
The SDK server sidecar: Agones runs a small gRPC + http server for the SDK in a container in the same network namespace as the game server container to connect to via the SDK.
The logs from this SDK server are also useful for tracking down issues, especially if you are having trouble with a particular GameServer.
1. To find the Pod for the GameServer look for the pod with a name that is prefixed with the name of the owning GameServer. For example if you have a GameServer named simple-udp, it’s pod could potentially be named simple-udp-dnbwj.
2. To get the logs from that Pod, we need to specify that we want the logs from the agones-gameserver-sidecar container. To do that, run the following:
  kubectl logs simple-udp-dnbwj -c agones-gameserver-sidecar

Agones uses JSON structured logging, therefore errors will be visible through the "severity":"info" key and value.

I uninstalled Agones before deleted all my `GameServers` and now they won’t delete

Agones GameServers use Finalizers to manage garbage collection of the GameServers. This means that if the Agones controller doesn’t remove the finalizer for you (i.e. if it has been uninstalled), it can be tricky to remove them all.

Thankfully, if we create a patch to remove the finalizers from all GameServers, we can delete them with impunity.

A quick one liner to do this:

kubectl get gameserver -o name | xargs -n1 -P1 -I{} kubectl patch {} --type=merge -p '{"metadata": {"finalizers": []}}'

Once this is done, you can kubectl delete gs --all and clean everything up (if it’s not gone already).

I’m getting Forbidden errors when trying to install Agones

Ensure that you are running Kubernetes 1.12 or later, which does not require any special clusterrolebindings to install Agones.

If you want to install Agones on an older version of Kubernetes, you need to create a clusterrolebinding to add your identity as a cluster admin, e.g.

# Kubernetes Engine
kubectl create clusterrolebinding cluster-admin-binding \
  --clusterrole cluster-admin --user `gcloud config get-value account`
# Minikube
kubectl create clusterrolebinding cluster-admin-binding \
  --clusterrole=cluster-admin --serviceaccount=kube-system:default

On GKE, gcloud config get-value accounts will return a lowercase email address, so if you are using a CamelCase email, you may need to type it in manually.

Docs: Local Development

Tue, 29 Jan 2019 10:18:08 +0000

Local Development

When the game server is running on Agones, the SDK communicates over TCP to a small gRPC server that Agones coordinated to run in a container in the same network namespace as it - usually referred to in Kubernetes terms as a “sidecar”.

Therefore, when developing locally, we also need a process for the SDK to connect to!

To do this, we can run the same binary that runs inside Agones, but pass in a flag to run it in “local mode”. Local mode means that the sidecar binary will not try to connect to anything, and will just send log messages to stdout and persist local state in memory so that you can see exactly what the SDK in your game server is doing, and can confirm everything works.

To do this you will need to download agonessdk-server-1.7.0.zip , and unzip it. You will find the executables for the SDK server, one for each type of operating system.

sdk-server.windows.amd64.exe - Windows
sdk-server.darwin.amd64 - macOS
sdk-server.linux.amd64 - Linux

To run in local mode, pass the flag --local to the executable.

For example:

$ ./sdk-server.linux.amd64 --local
{"ctlConf":{"Address":"localhost","IsLocal":true,"LocalFile":"","Delay":0,"Timeout":0,"Test":"","GRPCPort":9357,"HTTPPort":9358},"message":"Starting sdk sidecar","severity":"info","source":"main","time":"2019-10-30T21:44:37.973139+03:00","version":"1.1.0"}
{"grpcEndpoint":"localhost:9357","message":"Starting SDKServer grpc service...","severity":"info","source":"main","time":"2019-10-30T21:44:37.974585+03:00"}
{"httpEndpoint":"localhost:9358","message":"Starting SDKServer grpc-gateway...","severity":"info","source":"main","time":"2019-10-30T21:44:37.975086+03:00"}
{"message":"Ready request has been received!","severity":"info","time":"2019-10-30T21:45:47.031989+03:00"}
{"message":"gameserver update received","severity":"info","time":"2019-10-30T21:45:47.03225+03:00"}
{"message":"Shutdown request has been received!","severity":"info","time":"2019-10-30T21:46:18.179341+03:00"}
{"message":"gameserver update received","severity":"info","time":"2019-10-30T21:46:18.179459+03:00"}

Providing your own `GameServer` configuration for local development

By default, the local sdk-server will create a dummy GameServer configuration that is used for GameServer() and WatchGameServer() SDK calls. If you wish to provide your own configuration, as either yaml or json, this can be passed through as either --file or -f along with the --local flag.

If the GamerServer configuration file is changed while the local server is running, this will be picked up by the local server, and will change the current active configuration, as well as sending out events for WatchGameServer(). This is a useful way of testing functionality, such as changes of state from Ready to Allocated in your game server code.

Note

File modification events can fire more than one for each save (for a variety of reasons), but it’s best practice to ensure handlers that implement WatchGameServer() be idempotent regardless, as repeats can happen when live as well.

For example:

$ wget https://raw.githubusercontent.com/googleforgames/agones/master/examples/simple-udp/gameserver.yaml
$ ./sdk-server.linux.amd64 --local -f ./gameserver.yaml
{"ctlConf":{"Address":"localhost","IsLocal":true,"LocalFile":"./gameserver.yaml","Delay":0,"Timeout":0,"Test":"","GRPCPort":9357,"HTTPPort":9358},"message":"Starting sdk sidecar","severity":"info","source":"main","time":"2019-10-30T21:47:45.742776+03:00","version":"1.1.0"}
{"filePath":"/Users/alexander.apalikov/Downloads/agonessdk-server-1.1.0/gameserver.yaml","message":"Reading GameServer configuration","severity":"info","time":"2019-10-30T21:47:45.743369+03:00"}
{"grpcEndpoint":"localhost:9357","message":"Starting SDKServer grpc service...","severity":"info","source":"main","time":"2019-10-30T21:47:45.759692+03:00"}
{"httpEndpoint":"localhost:9358","message":"Starting SDKServer grpc-gateway...","severity":"info","source":"main","time":"2019-10-30T21:47:45.760312+03:00"}

Changing State of a Local GameServer

Some SDK calls would change the GameServer state according to GameServer State Diagram. Also local SDK server would persist labels and annotations updates.

Here is a complete list of these commands: ready, allocate, setlabel, setannotation, shutdown, reserve.

For example call to Reserve() for 30 seconds would change the GameServer state to Reserve and if no call to Allocate() occurs it would return back to Ready state after this period.

Note

All state transitions are supported for local SDK server, however not all of them are valid in the real scenario. For instance, you cannot make a transition of a GameServer from Shutdown to a Ready state, but can do using local SDK server.

All changes to the GameServer state could be observed and retrieved using Watch() or GameServer() methods using GameServer SDK.

Example of using HTTP gateway locally:

$ curl -X POST "http://localhost:9358/ready" -H "accept: application/json" -H "Content-Type: application/json" -d "{}"
{}
$ curl -GET "http://localhost:9358/gameserver" -H "accept: application/json"
{"object_meta":{"creation_timestamp":"-62135596800"},"spec":{"health":{}},"status":{"state":"Ready"}}
$ curl -X PUT "http://localhost:9358/metadata/label" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"key\": \"foo\", \"value\": \"bar\"}"
$ curl -GET "http://localhost:9358/gameserver" -H "accept: application/json"
{"object_meta":{"creation_timestamp":"-62135596800","labels":{"agones.dev/sdk-foo":"bar"}},"spec":{"health":{}},"status":{"state":"Ready"}}

Docs: Allocator Service

Tue, 19 May 2020 05:45:05 +0000

To allocate a game server, Agones in addition to GameServerAllocations , provides a gRPC service with mTLS authentication, called agones-allocator, which is on stable version , starting on agones v1.6.

The gRPC service is accessible through a Kubernetes service that is externalized using a load balancer. For the gRPC request to succeed, a client certificate must be provided that is in the authorization list of the allocator service.

The remainder of this article describes how to manually make a successful allocation request using the gRPC API.

Find the external IP

The service is hosted under the same namespace as the Agones controller. To find the external IP of your allocator service, replace agones-system namespace with the namespace to which Agones is deployed and execute the following command:

kubectl get service agones-allocator -n agones-system

The output of the command should look like:

NAME                        TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)            AGE
agones-allocator            LoadBalancer   10.55.251.73    34.82.195.204   443:30250/TCP      7d22h

Server TLS certificate

Replace the default server TLS certificate with a certificate with CN and subjectAltName. There are multiple approaches to generate a certificate. Agones recommends using cert-manager.io solution for cluster level certificate management.

In order to use cert-manager solution, first, install cert-manager on the cluster. Then, configure an Issuer/ClusterIssuer resource and last configure a Certificate resource to manage allocator-tls Secret.

Here is an example of using a self-signed ClusterIssuer for configuring allocator-tls Secret:

#!/bin/bash
# Create a self-signed ClusterIssuer
cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
  name: selfsigned
spec:
  selfSigned: {}
EOF

EXTERNAL_IP=`kubectl get services agones-allocator -n agones-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}'`

# Create a Certificate with IP for the allocator-tls secret
cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1alpha2
kind: Certificate
metadata:
  name: allocator-selfsigned-cert
  namespace: agones-system
spec:
  commonName: ${EXTERNAL_IP}
  ipAddresses:
    - ${EXTERNAL_IP}
  secretName: allocator-tls
  issuerRef:
    name: selfsigned
    kind: ClusterIssuer
EOF

# Optional: Store the secret ca.crt in a file to be used by the client for the server authentication
TLS_CA_FILE=ca.crt
TLS_CA_VALUE=`kubectl get secret allocator-tls -n agones-system -ojsonpath='{.data.ca\.crt}'`
echo ${TLS_CA_VALUE} | base64 -d > ${TLS_CA_FILE}

# In case of MacOS
# echo ${TLS_CA_VALUE} | base64 -D > ${TLS_CA_FILE}

# Add ca.crt to the allocator-tls-ca Secret
kubectl get secret allocator-tls-ca -o json -n agones-system | jq '.data["tls-ca.crt"]="'${TLS_CA_VALUE}'"' | kubectl apply -f -

Client Certificate

Because agones-allocator uses an mTLS authentication mechanism, client must provide a certificate that is accepted by the server. Here is an example of generating a client certificate. For the agones-allocator service to accept the newly generate client certificate, the generated client certificate CA or public portion of the certificate must be added to a kubernetes secret called allocator-client-ca.

#!/bin/bash

KEY_FILE=client.key
CERT_FILE=client.crt

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ${KEY_FILE} -out ${CERT_FILE}

CERT_FILE_VALUE=`cat ${CERT_FILE} | base64 -w 0`

# In case of MacOS
# CERT_FILE_VALUE=`cat ${CERT_FILE} | base64`

# white-list client certificate
kubectl get secret allocator-client-ca -o json -n agones-system | jq '.data["client_trial.crt"]="'${CERT_FILE_VALUE}'"' | kubectl apply -f -

The last command creates a new entry in the secret data map called client_trial.crt for allocator-client-ca and stores it. You can also achieve this by kubectl edit secret allocator-client-ca -n agones-system, and then add the entry.

Restart pods

Restart pods to get the new TLS certificate loaded to the agones-allocator service.

kubectl get pods -n agones-system -o=name | grep agones-allocator | xargs kubectl delete -n agones-system

Send allocation request

Now the service is ready to accept requests from the client with the generated certificates. Create a fleet and send a gRPC request to agones-allocator. To start, take a look at the allocation gRPC client examples in golang and C# languages. In the following, the golang gRPC client example is used to allocate a Game Server in the default namespace.

#!/bin/bash

NAMESPACE=default # replace with any namespace
EXTERNAL_IP=`kubectl get services agones-allocator -n agones-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}'`
KEY_FILE=client.key
CERT_FILE=client.crt
TLS_CA_FILE=ca.crt

go run examples/allocator-client/main.go --ip ${EXTERNAL_IP} \
    --port 443 \
    --namespace ${NAMESPACE} \
    --key ${KEY_FILE} \
    --cert ${CERT_FILE} \
    --cacert ${TLS_CA_FILE}

If your matchmaker is external to the cluster on which your game servers are hosted, the agones-allocator provides the gRPC API to allocate game services using mTLS authentication, which can scale independently to the Agones controller.

Docs: Multi-cluster Allocation

Fri, 25 Oct 2019 05:45:05 +0000

Beta

This feature is in a pre-release state and might change.

There may be different types of clusters, such as on-premise, and Google Kubernetes Engine (GKE), used by a game to help with the cost-saving and availability. For this purpose, Agones provides a mechanism to define priorities on the clusters. Priorities are defined on GameServerAllocationPolicy agones CRD. A matchmaker can enable the multi-cluster rules on a request and target agones-allocator endpoint in any of the clusters and get resources allocated on the cluster with the highest priority. If the cluster with the highest priority is overloaded, the allocation request is redirected to the cluster with the next highest priority.

The remainder of this article describes how to enable multi-cluster allocation.

Define Cluster Priority

GameServerAllocationPolicy is the CRD defined by Agones for setting multi-cluster allocation rules. In addition to cluster priority, it describes the connection information for the target cluster, including the game server namespace, agones-allocator endpoint and client K8s secrets name for redirecting the allocation request. Here is an example of setting the priority for a cluster and it’s connection rules. One such resource should be defined per cluster. For clusters with the same priority, the cluster is chosen with a probability relative to its weight.

In the following example the policy is defined for cluster B in cluster A.

cat <<EOF | kubectl apply -f -
apiVersion: multicluster.agones.dev/v1
kind: GameServerAllocationPolicy
metadata:
  name: allocator-cluster-B
  namespace: cluster-A-ns
spec:
  connectionInfo:
    allocationEndpoints:
    - 34.82.195.204
    clusterName: "clusterB"
    namespace: cluster-B-ns
    secretName: allocator-client-to-cluster-B
    serverCa: c2VydmVyQ0E=
  priority: 1
  weight: 100
EOF

To define the local cluster priority, similarly, an allocation rule should be defined, while leaving allocationEndpoints unset. If the local cluster priority is not defined, the allocation from the local cluster happens only if allocation from other clusters with the existing allocation rules is unsuccessful.

serverCa is the server TLS CA public certificate, set only if the remote server certificate is not signed by a public CA (e.g. self-signed). If this field is not specified, the certificate can also be specified in the ca.crt field of the client secret (i.e. the secret referred to in the secretName field).

Establish trust

To accept allocation requests from other clusters, agones-allocator for cluster B should be configured to accept the client’s certificate from cluster A and the cluster A’s client should be configured to accept the server TLS certificate, if it is not signed by a public Certificate Authority (CA).

Follow the steps to configure the agones allocator gRPC service. The client certificate pair in the mentioned document is stored as a K8s secret. Here are the secrets to set:

1.Client certificate to talk to other clusters:

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: allocator-client-to-cluster-B
  namespace: cluster-A-ns
type: Opaque
data:
  tls.crt: <REDACTED>
  tls.key: <REDACTED>
  ca.crt: <REDACTED>
EOF

The certificates are base 64 string of the certificate file e.g. cat ${CERT_FILE} | base64 -w 0

Agones recommends using cert-manager.io solution for generating client certificates.

2.Add client CA to the list of authorized client certificates by agones-allocator in the targeted cluster.

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: allocator-client-ca
  namespace: agones-system
type: Opaque
data:
  client1.crt: <REDACTED>
  client2.crt: <REDACTED>
  …
  clientN.crt: <REDACTED>
EOF

Allocate multi-cluster

To enable multi-cluster allocation, set multiClusterSetting.enabled to true in allocation.proto and send allocation requests. For more information visit agones-allocator. In the following, using allocator-client sample , a multi-cluster allocation request is sent to the agones-allocator service.

#!/bin/bash
EXTERNAL_IP=`kubectl get services agones-allocator -n agones-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}'`

NAMESPACE=default # replace with any namespace

go run examples/allocator-client/main.go --ip ${EXTERNAL_IP} \
    --namespace ${NAMESPACE} \
    --key ${KEY_FILE} \
    --cert ${CERT_FILE} \
    --cacert ${TLS_CA_FILE} \
    --multicluster true

Docs: Tutorial Build and Run a Simple Gameserver (Rust)

Tue, 30 Jul 2019 07:47:45 +0000

Objectives

Run a simple gameserver
Understand how the simple gameserver uses the Agones Rust SDK
Build a customized version of the simple gameserver
Run your customized simple gameserver

Prerequisites

Docker
Agones installed on GKE
kubectl properly configured
A local copy of the Agones repository
A repository for Docker images, such as Docker Hub or GC Container Registry

To install on GKE, follow the install instructions (if you haven’t already) at Setting up a Google Kubernetes Engine (GKE) cluster. Also complete the “Installing Agones” instructions on the same page.

While not required, you may wish to review the Create a Game Server, Create a Game Server Fleet, and/or Edit a Game Server quickstarts.

1. Run the simple gameserver

First, run the pre-built version of the simple gameserver and take note of the name that was created:

$ kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/rust-simple/gameserver.yaml
$ GAMESERVER_NAME=$(kubectl get gs -o go-template --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}')

The game server sets up the Agones SDK, calls sdk.ready() to inform Agones that it is ready to serve traffic, prints a message every 10 seconds, and then calls sdk.shutdown() after a minute to indicate that the gameserver is going to exit.

You can follow along with the lifecycle of the gameserver by running

$ kubectl logs ${GAMESERVER_NAME} rust-simple -f

which should produce output similar to

Rust Game Server has started!
Creating SDK instance
Setting a label
Starting to watch GameServer updates...
Health ping sent
Setting an annotation
Marking server as ready...
...marked Ready
Getting GameServer details...
GameServer name: rust-simple-txsc6
Running for 0 seconds
GameServer Update, name: rust-simple-txsc6
GameServer Update, state: Scheduled
GameServer Update, name: rust-simple-txsc6
GameServer Update, state: Scheduled
GameServer Update, name: rust-simple-txsc6
GameServer Update, state: RequestReady
GameServer Update, name: rust-simple-txsc6
GameServer Update, state: Ready
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Running for 10 seconds
GameServer Update, name: rust-simple-txsc6
GameServer Update, state: Ready
...
Shutting down after 60 seconds...
...marked for Shutdown
Running for 60 seconds
Health ping sent
GameServer Update, name: rust-simple-txsc6
GameServer Update, state: Shutdown
GameServer Update, name: rust-simple-txsc6
GameServer Update, state: Shutdown
...

If everything goes as expected, the gameserver will exit automatically after about a minute.

In some cases, the gameserver goes into an unhealthy state, in which case it will be restarted indefinitely. If this happens, you can manually remove it by running

$ kubectl delete gs ${GAMESERVER_NAME}

2. Build a simple gameserver

Change directories to your local agones/examples/rust-simple directory. To experiment with the SDK, open up main.rs in your favorite editor and change the interval at which the gameserver calls sdk.health() from 2 seconds to 20 seconds by modifying the line in the thread assigned to let _health to be

thread::sleep(Duration::from_secs(20));

Next build a new docker image by running

$ cd examples/rust-simple
$ REPOSITORY=<your-repository> # e.g. gcr.io/agones-images
$ make build-image REPOSITORY=${REPOSITORY}

The multi-stage Dockerfile will pull down all of the dependencies needed to build the image. Note that it is normal for this to take several minutes to complete.

Once the container has been built, push it to your repository

$ docker push ${REPOSITORY}/rust-simple-server:0.4

3. Run the customized gameserver

Now it is time to deploy your newly created gameserver container into your Agones cluster.

First, you need to edit examples/rust-simple/gameserver.yaml to point to your new image:

containers:
- name: rust-simple
  image: $(REPOSITORY)/rust-simple-server:0.4
  imagePullPolicy: Always

Then, deploy your gameserver

$ kubectl create -f gameserver.yaml
$ GAMESERVER_NAME=$(kubectl get gs -o go-template --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}')

Again, follow along with the lifecycle of the gameserver by running

$ kubectl logs ${GAMESERVER_NAME} rust-simple -f

which should produce output similar to

Rust Game Server has started!
Creating SDK instance
Setting a label
Starting to watch GameServer updates...
Health ping sent
Setting an annotation
Marking server as ready...
...marked Ready
Getting GameServer details...
GameServer name: rust-simple-z6lz8
Running for 0 seconds
GameServer Update, name: rust-simple-z6lz8
GameServer Update, state: Scheduled
GameServer Update, name: rust-simple-z6lz8
GameServer Update, state: RequestReady
GameServer Update, name: rust-simple-z6lz8
GameServer Update, state: RequestReady
GameServer Update, name: rust-simple-z6lz8
GameServer Update, state: Ready
Running for 10 seconds
GameServer Update, name: rust-simple-z6lz8
GameServer Update, state: Ready
GameServer Update, name: rust-simple-z6lz8
GameServer Update, state: Unhealthy
Health ping sent
Running for 20 seconds
Running for 30 seconds
Health ping sent
Running for 40 seconds
GameServer Update, name: rust-simple-z6lz8
GameServer Update, state: Unhealthy
Running for 50 seconds
Health ping sent
Shutting down after 60 seconds...
...marked for Shutdown
Running for 60 seconds
Running for 70 seconds
GameServer Update, name: rust-simple-z6lz8
GameServer Update, state: Unhealthy
Health ping sent
Running for 80 seconds
Running for 90 seconds
Health ping sent
Rust Game Server finished.

with the slower healthcheck interval, the gameserver gets automatically marked an Unhealthy by Agones.

To finish, clean up the gameserver by manually removing it

$ kubectl delete gs ${GAMESERVER_NAME}

Docs: Tutorial Build and Run a Simple Gameserver (node.js)

Thu, 25 Jul 2019 17:34:37 +0000

Objectives

Run a simple gameserver
Understand how the simple gameserver uses the Agones node.js SDK
Build a customized version of the simple gameserver
Run your customized simple gameserver

Prerequisites

Docker
Agones installed on GKE
kubectl properly configured
A local copy of the Agones repository
A repository for Docker images, such as Docker Hub or GC Container Registry

While not required, you may wish to review the Create a Game Server, Create a Game Server Fleet, and/or Edit a Game Server quickstarts.

1. Run the simple gameserver

First, run the pre-built version of the simple gameserver and take note of the name that was created:

$ kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/nodejs-simple/gameserver.yaml
$ GAMESERVER_NAME=$(kubectl get gs -o go-template --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}')

You can follow along with the lifecycle of the gameserver by running

$ kubectl logs ${GAMESERVER_NAME} nodejs-simple -f

which should produce output similar to

> @ start /home/server/examples/nodejs-simple
> node src/index.js

node.js Game Server has started!
Setting a label
(node:20) [DEP0005] DeprecationWarning: Buffer() is deprecated due to security and usability issues. Please use the Buffer.alloc(), Buffer.allocUnsafe(), or Buffer.from() methods instead.
Setting an annotation
Marking server as ready...
...marked Ready
GameServer Update:
	name: nodejs-simple-9bw4g 
	state: Scheduled
GameServer Update:
	name: nodejs-simple-9bw4g 
	state: RequestReady
GameServer Update:
	name: nodejs-simple-9bw4g 
	state: RequestReady
GameServer Update:
	name: nodejs-simple-9bw4g 
	state: Ready
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Running for 10 seconds!
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Running for 20 seconds!
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Health ping sent
GameServer Update:
	name: nodejs-simple-9bw4g 
	state: Ready
Running for 30 seconds!
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Running for 40 seconds!
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Running for 50 seconds!
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Health ping sent
GameServer Update:
	name: nodejs-simple-9bw4g 
	state: Ready
Running for 60 seconds!
Shutting down after 60 seconds...
...marked for Shutdown
GameServer Update:
	name: nodejs-simple-9bw4g 
	state: Shutdown
Health ping sent
GameServer Update:
	name: nodejs-simple-9bw4g 
	state: Shutdown
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Running for 70 seconds!
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Running for 80 seconds!
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Running for 90 seconds!

If everything goes as expected, the gameserver will exit automatically after about a minute.

In some cases, the gameserver goes into an unhealthy state, in which case it will be restarted indefinitely. If this happens, you can manually remove it by running

$ kubectl delete gs ${GAMESERVER_NAME}

2. Build a simple gameserver

Change directories to your local agones/examples/nodejs-simple directory. To experiment with the SDK, open up src/index.js in your favorite editor and change the interval at which the gameserver calls sdk.health() from 2 seconds to 20 seconds by modifying the lines in the health ping handler to be

setInterval(() => {
	agonesSDK.health();
	console.log('Health ping sent');
}, 20000);

Next build a new docker image by running

$ cd examples/nodejs-simple
$ REPOSITORY=<your-repository> # e.g. gcr.io/agones-images
$ make build REPOSITORY=${REPOSITORY}

Once the container has been built, push it to your repository

$ docker push ${REPOSITORY}/nodejs-simple-server:0.1

3. Run the customized gameserver

Now it is time to deploy your newly created gameserver container into your Agones cluster.

First, you need to edit examples/nodejs-simple/gameserver.yaml to point to your new image:

containers:
- name: nodejs-simple
  image: $(REPOSITORY)/nodejs-simple-server:0.1
  imagePullPolicy: Always

Then, deploy your gameserver

$ kubectl create -f gameserver.yaml
$ GAMESERVER_NAME=$(kubectl get gs -o go-template --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}')

Again, follow along with the lifecycle of the gameserver by running

$ kubectl logs ${GAMESERVER_NAME} nodejs-simple -f

which should produce output similar to

> @ start /home/server/examples/nodejs-simple
> node src/index.js

node.js Game Server has started!
Setting a label
(node:20) [DEP0005] DeprecationWarning: Buffer() is deprecated due to security and usability issues. Please use the Buffer.alloc(), Buffer.allocUnsafe(), or Buffer.from() methods instead.
Setting an annotation
Marking server as ready...
...marked Ready
GameServer Update:
	name: nodejs-simple-qkpqn 
	state: Scheduled
GameServer Update:
	name: nodejs-simple-qkpqn 
	state: Scheduled
GameServer Update:
	name: nodejs-simple-qkpqn 
	state: RequestReady
GameServer Update:
	name: nodejs-simple-qkpqn 
	state: Ready
Running for 10 seconds!
GameServer Update:
	name: nodejs-simple-qkpqn 
	state: Unhealthy
Health ping sent
Running for 20 seconds!
GameServer Update:
	name: nodejs-simple-qkpqn 
	state: Unhealthy
Running for 30 seconds!
Health ping sent
Running for 40 seconds!
Running for 50 seconds!
GameServer Update:
	name: nodejs-simple-qkpqn 
	state: Unhealthy
Health ping sent
Shutting down after 60 seconds...
...marked for Shutdown
Running for 60 seconds!
Running for 70 seconds!
Health ping sent
Running for 80 seconds!
GameServer Update:
	name: nodejs-simple-qkpqn 
	state: Unhealthy
Running for 90 seconds!

with the slower healthcheck interval, the gameserver gets automatically marked an Unhealthy by Agones.

To finish, clean up the gameserver by manually removing it

$ kubectl delete gs ${GAMESERVER_NAME}

Docs: Tutorial Build and Run a Simple Gameserver (C++)

Wed, 24 Jul 2019 05:52:12 +0000

Objectives

Run a simple gameserver
Understand how the simple gameserver uses the Agones C++ SDK
Build a customized version of the simple gameserver
Run your customized simple gameserver

Prerequisites

Docker
Agones installed on GKE
kubectl properly configured
A local copy of the Agones repository
A repository for Docker images, such as Docker Hub or GC Container Registry

While not required, you may wish to review the Create a Game Server, Create a Game Server Fleet, and/or Edit a Game Server quickstarts.

1. Run the simple gameserver

First, run the pre-built version of the simple gameserver and take note of the name that was created:

$ kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/cpp-simple/gameserver.yaml
$ GAMESERVER_NAME=$(kubectl get gs -o go-template --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}')

The game server sets up the Agones SDK, calls SDK::Ready() to inform Agones that it is ready to serve traffic, prints a message every 10 seconds, and then calls SDK::Shutdown() after a minute to indicate that the gameserver is going to exit.

You can follow along with the lifecycle of the gameserver by running

$ kubectl logs ${GAMESERVER_NAME} cpp-simple -f

which should produce output similar to

C++ Game Server has started!
Getting the instance of the SDK!
Attempting to connect...
...handshake complete.
Setting a label
Starting to watch GameServer updates...
Health ping sent
Setting an annotation
Marking server as ready...
...marked Ready
Getting GameServer details...
GameServer name: cpp-simple-tlgzp
Running for 0 seconds !
GameServer Update:
	name: cpp-simple-tlgzp
	state: Scheduled
GameServer Update:
	name: cpp-simple-tlgzp
	state: RequestReady
GameServer Update:
	name: cpp-simple-tlgzp
	state: RequestReady
GameServer Update:
	name: cpp-simple-tlgzp
	state: Ready
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Health ping sent
Running for 10 seconds !
Health ping sent
...
GameServer Update:
	name: cpp-simple-2mtdc
	state: Ready
Shutting down after 60 seconds...
...marked for Shutdown
Running for 60 seconds !
Health ping sent
GameServer Update:
	name: cpp-simple-2mtdc
	state: Shutdown
GameServer Update:
	name: cpp-simple-2mtdc
	state: Shutdown
Health ping failed
Health ping failed
Health ping failed
Health ping failed
Running for 70 seconds !
Health ping failed
Health ping failed
Health ping failed
Health ping failed
Health ping failed
Running for 80 seconds !
Health ping failed
Health ping failed
Health ping failed
Health ping failed
Health ping failed

If everything goes as expected, the gameserver will exit automatically after about a minute.

In some cases, the gameserver goes into an unhealthy state, in which case it will be restarted indefinitely. If this happens, you can manually remove it by running

$ kubectl delete gs ${GAMESERVER_NAME}

2. Run a fleet of simple gameservers

Next, run a fleet of gameservers

$ kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/master/examples/cpp-simple/fleet.yaml
$ FLEET_NAME=$(kubectl get fleets -o go-template --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}')

You can again inspect the output of an individual gameserver (which will look the same as above), but what is more interesting is to watch the set of all gameservers over time. Each gameserver exits after about a minute, but a fleet is responsible for keeping a sufficient number of gameservers in the Ready state. So as each gameserver exits, it is replaced by a new one. You can see this in action by running

$ watch "kubectl get gameservers"

which should show how gameservers are constantly transitioning from Scheduled to Ready to Shutdown before disappearing.

When you are finished watching the fleet produce new gameservers you should remove the fleet by running

$ kubectl delete fleet ${FLEET_NAME}

3. Build a simple gameserver

Change directories to your local agones/examples/cpp-simple directory. To experiment with the SDK, open up server.cc in your favorite editor and change the interval at which the gameserver calls SDK::Health from 2 seconds to 20 seconds by modifying the line in DoHealth to be

std::this_thread::sleep_for(std::chrono::seconds(20));

Next build a new docker image by running

$ cd examples/cpp-simple
$ REPOSITORY=<your-repository> # e.g. gcr.io/agones-images
$ make build REPOSITORY=${REPOSITORY}

The multi-stage Dockerfile will pull down all of the dependencies needed to build the image. Note that it is normal for this to take several minutes to complete.

Once the container has been built, push it to your repository

$ docker push ${REPOSITORY}/cpp-simple-server:0.6

4. Run the customized gameserver

Now it is time to deploy your newly created gameserver container into your Agones cluster.

First, you need to edit examples/cpp-simple/gameserver.yaml to point to your new image:

containers:
- name: cpp-simple
  image: $(REPOSITORY)/cpp-simple-server:0.6
  imagePullPolicy: Always # add for development

Then, deploy your gameserver

$ kubectl create -f gameserver.yaml
$ GAMESERVER_NAME=$(kubectl get gs -o go-template --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}')

Again, follow along with the lifecycle of the gameserver by running

$ kubectl logs ${GAMESERVER_NAME} cpp-simple -f

which should produce output similar to

C++ Game Server has started!
Getting the instance of the SDK!
Attempting to connect...
...handshake complete.
Setting a label
Health ping sent
Starting to watch GameServer updates...
Setting an annotation
Marking server as ready...
...marked Ready
Getting GameServer details...
GameServer name: cpp-simple-f255n
Running for 0 seconds !
GameServer Update:
	name: cpp-simple-f255n
	state: Scheduled
GameServer Update:
	name: cpp-simple-f255n
	state: Scheduled
GameServer Update:
	name: cpp-simple-f255n
	state: RequestReady
GameServer Update:
	name: cpp-simple-f255n
	state: Ready
Running for 10 seconds !
GameServer Update:
	name: cpp-simple-f255n
	state: Unhealthy
Health ping sent
Running for 20 seconds !
GameServer Update:
	name: cpp-simple-f255n
	state: Unhealthy
Running for 30 seconds !
Health ping sent
Running for 40 seconds !
Running for 50 seconds !
GameServer Update:
	name: cpp-simple-f255n
	state: Unhealthy
Health ping sent
Shutting down after 60 seconds...
...marked for Shutdown
Running for 60 seconds !
Running for 70 seconds !
Health ping sent
Running for 80 seconds !
GameServer Update:
	name: cpp-simple-f255n
	state: Unhealthy
Running for 90 seconds !
Health ping sent

with the slower healthcheck interval, the gameserver gets automatically marked an Unhealthy by Agones.

To finish, clean up the gameserver by manually removing it

$ kubectl delete gs ${GAMESERVER_NAME}

Docs: GameServer Pod Service Accounts

Thu, 14 Mar 2019 04:30:37 +0000

Default Settings

By default, Agones sets up service accounts and sets them appropriately for the Pods that are created for GameServers.

Since Agones provides GameServer Pods with a sidecar container that needs access to Agones Custom Resource Definitions, Pods are configured with a service account with extra RBAC permissions to ensure that it can read and modify the resources it needs.

Since service accounts apply to all containers in a Pod, Agones will automatically overwrite the mounted key for the service account in the container that is running the dedicated game server in the backing Pod. This is done since game server containers are exposed publicly, and generally don’t require the extra permissions to access aspects of the Kubernetes API.

Bringing your own Service Account

If needed, you can provide your own service account on the Pod specification in the GameServer configuration.

For example:

apiVersion: "agones.dev/v1"
kind: GameServer
metadata:
  generateName: "simple-udp-"
spec:
  ports:
  - name: default
    containerPort: 7654
  template:
    spec:
      serviceAccountName: my-special-service-account # a custom service account
      containers:
      - name: simple-udp
        image: gcr.io/agones-images/udp-server:0.21

If a service account is configured, the mounted key is not overwritten, as it assumed that you want to have full control of the service account and underlying RBAC permissions.

Docs: Tutorial Create an Allocator Service

Thu, 03 Jan 2019 03:15:34 +0000

To do this, we will implement a Service which allocates a Game Server on demand by calling the Create() method of the GameServerAllocationInterface. After creating the fleet allocation, we will return the JSON encoded GameServerStatus of the allocated GameServer.

The type of service we will be learning about could be used by a game client to connect directly to a dedicated Game Server, as part of a larger system, such as a matchmaker service, or in conjunction with a database of level transition data. We will be using the service as a vehicle with which to execute the API calls found in our main.go file.

Objectives

Create a secure allocator service
Deploy the service to GKE
Allocate a Game Server from a Fleet using the Agones API

Prerequisites

Docker
Agones installed on GKE, running a simple-udp fleet
kubectl properly configured
A local copy of the allocator service
A repository for Docker images, such as Docker Hub or GC Container Registry

While not required, you may wish to review the Create a Game Server, Create a Game Server Fleet, and/or Edit a Game Server quickstarts.

1. Build and Push the Service

Change directories to your local agones/examples/allocator-service directory and build a new docker image. The multi-stage Dockerfile will pull down all the dependencies for you and build the executable. For example, where USER is your username, REPO is your repository, and TAG is your tag:

docker build -t [USER]/allocator-service:[TAG] .

Push it to your repository:

docker push [USER]/allocator-service:[TAG]

Edit allocator-service.yaml to point to your new image:

containers:
- name: fleet-allocator
  image: [REPO]/[USER]/allocator-service:[TAG]
  imagePullPolicy: Always

2. Create Firewall Rules

Let’s making some firewall rules that will be used by kubernetes health checks and the ingress which we will create shortly.

First, we will make one for the HTTPS health checks that will be sent to our service by running:

gcloud compute firewall-rules create fleet-allocator-healthcheck \
  --allow tcp \
  --source-ranges 130.211.0.0/22,35.191.0.0/16 \
  --target-tags fleet-allocator \
  --description "Firewall to allow health check of fleet allocator service"

The output should be something like:

Creating firewall...done.                                            
NAME                         NETWORK  DIRECTION  PRIORITY  ALLOW  DENY  DISABLED
fleet-allocator-healthcheck  default  INGRESS    1000      tcp          False

Create a firewall rule for nodePort traffic on the range of ports used by Ingress services of type nodePort. We are using nodePort because it supports TLS.

gcloud compute firewall-rules create nodeport-rule \
  --allow=tcp:30000-32767 \
  --target-tags fleet-allocator \
  --description "Firewall to allow nodePort traffic of fleet allocator service"

The output should be something like:

Creating firewall...done.                                            
NAME           NETWORK  DIRECTION  PRIORITY  ALLOW            DENY  DISABLED
nodeport-rule  default  INGRESS    1000      tcp:30000-32767        False

3. Make It Secure

Let’s keep security in mind from the beginning by creating a certificate, key and secret for the allocator service, and another set for the web server.

Pick a more permanent location for the files if you like - /tmp may be purged depending on your operating system.

Create a public private key pair for the allocator service:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /tmp/allocsvc.key -out  /tmp/allocsvc.crt -subj "/CN=my-allocator/O=my-allocator"

The output should be something like:

Generating a 2048 bit RSA private key
....................................................+++
......................+++
writing new private key to '/tmp/allocsvc.key'
-----

Create a public private key pair that will be bound to the pod and used by the web server :

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /tmp/tls.key -out  /tmp/tls.crt -subj "/CN=my-allocator-w3/O=my-allocator-w3"

The output should be something like:

Generating a 2048 bit RSA private key
....................................................+++
......................+++
writing new private key to '/tmp/tls.key'
-----

4. Create Kubernetes Secrets

The allocatorsecret will allow the service to use TLS for connections with workers.

Create the secret by running this command:

kubectl create secret tls allocatorsecret --cert=/tmp/allocsvc.crt --key=/tmp/allocsvc.key

secret/allocatorsecret created

The allocatorw3secret will let data be served by the webserver over https.

Create the secret by running this command:

kubectl create secret tls allocatorw3secret --cert=/tmp/tls.crt --key=/tmp/tls.key

The output should be something like:

secret/allocatorw3secret created

See that the secrets exist by running:

kubectl get secrets

The output should contain the secrets:

NAME                     TYPE                                  DATA      AGE
...
allocatorsecret          kubernetes.io/tls                     2         29s
allocatorw3secret        kubernetes.io/tls                     2         15s
...

5. Create the Service Account

This service will interact with Agones via the Agones API by using a service account named fleet-allocator. Specifically, the fleet-allocator service account is granted permissions to perform create operations against GameServerAllocation objects, and get operations against Fleet objects.

Create the service account by changing directories to your local agones/examples/allocator-service directory and running this command:

kubectl create -f service-account.yaml

The output should look like this:

role.rbac.authorization.k8s.io/fleet-allocator created
serviceaccount/fleet-allocator created
rolebinding.rbac.authorization.k8s.io/fleet-allocator created

6. Define and Deploy the Service

The service definition defines a nodePort service which uses https, and sets up ports and names. The deployment describes the number of replicas we would like, which account to use, which image to use, and defines a health check.

Define and Deploy the service by running this command:

kubectl create -f allocator-service.yaml

The output should look like this:

service/fleet-allocator-backend created
deployment.apps/fleet-allocator created

7. Deploy the Ingress Resource

This Ingress directs traffic to the allocator service using an ephemeral IP address. The allocator service pod needs to exist and the readiness probe should be passing health checks before the ingress is created.

Deploy the Ingress with this command:

kubectl apply -f allocator-ingress.yaml

The output should look like this:

ingress.extensions/fleet-allocator-ingress created

8. Retrieve the Ephemeral Public IP Address

After deployment, it will take about a minute for the IP address to be present, and up to 10 minutes before it can start returning data.

Run this command to get the IP address:

kubectl get ingress fleet-allocator-ingress

The output should look something like this:

NAME                      HOSTS     ADDRESS          PORTS     AGE
fleet-allocator-ingress   *         35.186.225.103   80, 443   1m

To learn more about the status of the ingress, run:

kubectl get ingress fleet-allocator-ingress -o yaml

When the output shows the ingress.kubernetes.io/backends as ‘HEALTHY’ rather than ‘UNHEALTHY’ or ‘UNKOWN’ it is probably ready.

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  annotations:
    ingress.kubernetes.io/backends: '{"k8s-be-30021--7e98a70481f48a13":"HEALTHY"}'
    ingress.kubernetes.io/https-forwarding-rule: k8s-fws-default-fleet-allocator-ingress--7e98a70481f48a13
    ingress.kubernetes.io/https-target-proxy: k8s-tps-default-fleet-allocator-ingress--7e98a70481f48a13
    ingress.kubernetes.io/ssl-cert: k8s-ssl-1ab99915a1f6b5f1-b2a9924cee73d20a--7e98a70481f48a13
    ingress.kubernetes.io/url-map: k8s-um-default-fleet-allocator-ingress--7e98a70481f48a13
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"extensions/v1beta1","kind":"Ingress","metadata":{"annotations":{"kubernetes.io/ingress.allow-http":"false","kubernetes.io/ingress.class":"gce"},"labels":{"app":"fleet-allocator"},"name":"fleet-allocator-ingress","namespace":"default"},"spec":{"backend":{"serviceName":"fleet-allocator-backend","servicePort":8000},"tls":[{"secretName":"allocatorsecret"}]}}
    kubernetes.io/ingress.allow-http: "false"
    kubernetes.io/ingress.class: gce
  creationTimestamp: 2018-09-23T19:13:36Z
  generation: 1
  labels:
    app: fleet-allocator
  name: fleet-allocator-ingress
  namespace: default
  resourceVersion: "4086"
  selfLink: /apis/extensions/v1beta1/namespaces/default/ingresses/fleet-allocator-ingress
  uid: c5a149b3-bf64-11e8-8a6e-42010a8e013f
spec:
  backend:
    serviceName: fleet-allocator-backend
    servicePort: 8000
  tls:
  - secretName: allocatorsecret
status:
  loadBalancer:
    ingress:
    - ip: 35.186.225.103

9. Check Game Servers

Let’s make sure that we have one or more Game Servers in a ready state by running this command:

kubectl get gs

For a fleet of 2 replicas, you should see 2 Game Servers with a Status of Ready:

NAME                     STATE     ADDRESS           PORT    NODE       AGE                                
simple-udp-s2snf-765bc   Ready     35.231.204.26     7260    minikube   5m
simple-udp-s2snf-vf6l8   Ready     35.196.162.169    7591    minikube   5m

If there is no fleet, please review Create a Game Server Fleet.

10. Allocate a Game Server

Now that the ingress has been created, let’s allocate a Game Server by passing in our user and key to the /address endpoint. This will call the allocate() function in main.go, which will return a JSON string of the GameServerStatus of an allocated GameServer, or an error. The service uses Basic Auth to provide some security as to who can allocate GameServer resources, and the generated key is in main.go, in the function basicAuth(). Read the comments and code in main.go for a more detailed explanation of each function and method.

Allocate a Game Server by running this command:

curl -k -u v1GameClientKey:EAEC945C371B2EC361DE399C2F11E https://[the.ip.address]/address

The output should show the JSON of the GameServerStatus, similar to this:

{"status":"Allocated"}

You may need to wait a few moments longer if the output has ssl errors like this:

curl: (35) error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure

Check the Game Servers again, and notice the Allocated Status. You should see something like this:

NAME                     STATUS      ADDRESS          PORT    NODE      AGE
simple-udp-s2snf-765bc   Allocated   35.231.204.26    7260    minikube   5m
simple-udp-s2snf-vf6l8   Ready       35.196.162.169   7591    minikube   5m

Congratulations, your call to the API has allocated a Game Server from your simple-udp Fleet!

11. Cleanup

You can delete the allocator service and associated resources with the following commands.

Delete the Ingress

kubectl delete ingress fleet-allocator-ingress

Delete the Service

kubectl delete -f allocator-service.yaml

Delete the Service Account

kubectl delete -f service-account.yaml

Delete the health check and firewall rules

gcloud compute health-checks delete fleet-allocator-healthcheck
gcloud compute firewall-rules delete fleet-allocator-healthcheck
gcloud compute health-checks delete nodeport-rule
gcloud compute firewall-rules delete nodeport-rule

Next Steps

Customize the service by changing the constants and service key in main.go
Make the IP Address Permanent
Create an A record that points to your permanent IP address
Create a Fleet Autoscaler