Octops Discover Overview

What is Octops Discover?

Octops Discover is a single entrypoint that delivers a unified view of your game server infrastructure running on Kubernetes and Agones.

Designed to be infrastructure agnostic, the Octops Discover natively supports game servers running on single or multi-cluster, multi-cloud, bare metal or any other hybrid environment. Even distributions like K3S, Minikube and Docker-Desktop are supported.

Major Features

  • Single source of truth about your game server fleet infrastructure.
  • Game server information collected and published in nearly real time.
  • Plug & Play, deploy the Octops Agent and query game servers immediately.
  • Kubernetes cluster can be added or removed seamlessly without the overhead of updating K8S API endpoints or dealing with credentials.
  • Game Servers are tracked throughout their entire lifecycle. From creation to shutdown.
  • Authentication and access control is simplified and TOKEN based. There is no need to share K8S credentials or worrying about exposing the K8S API.
  • Language Agnostic, clients can consume data from the HTTP API.
  • Supports single or multi cloud/clusters.
  • Supports servers hosted on bare metal
  • Works on any cloud provider

How does it work?

Octops Discover has 2 fundamental components:

  • Octops Agent
  • Octops Discover API

Octops Agent

Octops Agent is the only component that runs within the customer infrastructure. It is responsible for watching Agones GameServers resources and publishing the entire game server state to the Octops Cloud whenever a change happens.

The agent was designed to be fail safe and network efficient for our customers. The information about the entire Fleet is collected and pushed in nearly realtime.

Game servers that did not have either a state change or a keep alive in the last minute will not be included in the response payload returned by the Discover API

Game server state change events are broadcast once Agones creates, deletes or update a game server as well as when changes are triggered by the game server itself via the Agones SDK functions. Some examples are:

  • Player capacity
  • Player count
  • Player ids
  • Labels
  • State

Events triggered by the Agones Allocator Service are also collected. That means when a game server transitions from a Ready to Allocated state.

The agent does not collect game server spec details as environment variables, secrets, image or any other game server sensitive data

Game owners can decide what kind of info they want to make part of the data published by setting custom labels. This is a powerful mechanism implemented by Kubernetes and it is supported by the Agones SDK function SetLabel.

Example of game server payload published by the agent:

  "name": "fleet-alpha-release-vlqs6-d28t7",
  "namespace": "default",
  "labels": {
    "agones.dev/fleet": "fleet-alpha-release",
    "agones.dev/gameserverset": "fleet-alpha-release-vlqs6",
    "cluster": "gke-us-west-2-prod",
    "k8s_version": "eks-1.24",
    "region": "us-west-2",
    "version": "v0.0.1",
    "game.io/map": "Desert",
    "game.io/match_type": "Death Match",
    "game.io/ranking_type": "Balanced"
  "address": "",
  "players_capacity": 100,
  "players_count": 4,
  "players_ids": ["35667621", "8763098872", "99873242", "12098334"],
  "gameserver_state": "Allocated"

Octops Discover API

The Octops Discover API is the service hosted in the cloud and maintained by the Octops team. Its receiver and query endpoints are the available channels for customers to publish and query information about their games fleets.


The receiver service handles events published by the Octops Agent. The event is then processed and stored by other internal components part of the Octops Discover infrastructure.

Query API

The query service allows clients to query game servers details using a powerful filtering mechanism. This is a language agnostic HTTP based endpoint that can be consumed by any type of HTTP client application. The simplest example is using tool like curl.

$ curl 'https://api.beta.octops.dev/api/v1/gameservers?labels=agones.dev/fleet=fleet-alpha-release,version=v0.0.1&state=Ready&limit=10000' \
--header 'Authorization: Bearer ${OCTOPS_API_TOKEN}'

Check the Examples section for a complete list of possible ways to query data using different types of filters.

What is next?