Agones
The Agones SDK represents the technical interface through which this server can communicate its current state to Agones. This SDK cannot be used to request new resources in Agones. Instead, its methods are used to manipulate and query the state of the GameServer resource associated with this instance. The SDK focuses solely on the individual instance and ignores the rest of the cluster. For requests to Agones or the cluster, the Kubernetes API should be used instead. A single instance of the SDK should be reused across all requests.
Agones divides its interfaces into three different channels to signal their usage and maturity. This also allows for active changes or complete removal of those interfaces in the case of issues, or if they discover that a solution does not really fit into the Agones system. The available channels are:
Stable: The endpoints were tested extensively and are explicitly recommended or necessary for the general use of the SDK. It is guaranteed that those endpoints will be available in their current form for many versions to come. They can be accessed directly through this interface and are not specially isolated or encapsulated.
Beta: The endpoints were already tested to some extent or are expected to have very few bugs, and the general use is not discouraged. They are enabled by default, and it is guaranteed that there will be no major changes to those features anymore. The endpoints can be accessed through the Beta-Channel in an encapsulated interface.
Alpha: The endpoints have been tested only superficially or rarely, and production use is not recommended. They are disabled by default, and there may be major changes, or the endpoints may be removed completely at any time. The endpoints can be accessed through the Alpha-Channel in an encapsulated interface.
The interfaces that modify the state do not guarantee that the resource in Kubernetes will actually transition immediately to the desired state. For example, if the instance is transitioned to the Shutdown state by another component, the state changes will be silently discarded.
All interfaces are executed asynchronously (through coroutines) and return their results after the response from the SDK has been recorded. Interfaces that work with streams of data are also executed asynchronously and are wrapped into flows to be compatible with the coroutines. Errors will always be returned immediately if they are discovered and the operation will only be automatically retried if the returned condition can be recovered from.
The endpoint signatures of the SDK were slightly adjusted to unify their naming scheme and to better fit into the Kotlin/Java ecosystem. Generally speaking, no hidden logic is embedded into the calls and the value is therefore relayed to the SDK without further changes. The SDK is always kept compatible with the official recommendations and should be used directly whenever possible, as the individual steps are atomic.
See also
Samples
fun main() {
//sampleStart
// host and port are supplied by the default environment variables
val sdk = GrpcAgonesSdk()
// any request can be performed on the sdk while it is open
sdk.ready()
//sampleEnd
}Inheritors
Types
The Alpha-Channel provides the interfaces of the Agones SDK that have not yet been extensively tested and have been deactivated by default. The provided endpoints can change drastically from one version to the next, and they may be removed at any time. But the provided endpoints can be used without any restrictions, but there may be some bugs, as the feature has not been used broadly. As soon as the features have been tested more and have proven to be useful to the Agones system, they will be promoted to the Beta-Channel. The Alpha-Channel can be retrieved through alpha from an instance of the Agones SDK.
The Beta-Channel provides the interfaces of the Agones SDK that may have already been extensively tested and have been activated by default, but they haven't been used broadly enough to promote them to the Stable-Channel yet. But the provided endpoints can be used without any restrictions or preparations and only very few bugs are expected. As soon as the features have been tested enough and have proven to be useful to the Agones system, they will be promoted to the Stable-Channel. The Beta-Channel can be retrieved through beta from an instance of the Agones SDK.
Functions
Notifies Agones that this instance has been allocated/claimed and is currently not available for any other GameServerAllocations. It is preferred, that instances are assigned through GameServerAllocations. However, in cases where this is not possible (e.g., when working with external systems), this interface can be used to manually assign the instance.
Returns the encapsulated Alpha-Channel of the Agones SDK. This sub channel allows the use of the less tested and isolated interfaces within the Agones SDK. The retrieval of the channel does not trigger any communication with the SDK. The interfaces of the Alpha-Channel were not yet extensively tested and are deactivated by default. The endpoints can be freely used, but some bugs are to be expected.
Adds a new annotation with a specific key and value to the GameServer resource of this instance. The key always gets a prefix assigned automatically to ensure better isolation and security. Therefore, the keys cannot collide with normal Kubernetes annotations. This allows further metadata to be published about this instance, which can be read elsewhere, and it is possible to filter the GameServer instances more precisely using the key-value pair.
Returns the encapsulated Beta-Channel of the Agones SDK. This sub channel allows the use of the less tested and isolated interfaces within the Agones SDK. The retrieval of the channel does not trigger any communication with the SDK. The interfaces of the Beta-Channel were already extensively tested and are activated by default. The endpoints can be freely used and only very few bugs are expected.
Closes all open resources that are associated with the Agones SDK. After this operation, this instance of the Agones SDK may no longer be used, as all connections are no longer usable. This method can be called any number of times without changing its behavior. It is guaranteed that after this call, all open connections and allocated resources will be closed or released. Although not all implementations have such resources, the method should still always be called (for example, within a Try-With_Resources block or a use method) to cleanly terminate resource usage.
Gets a new, immutable Snapshot of the GameServer resource of this instance. The data includes, among meta information, the current state, the allocation/assignment and the configuration as present in the Kubernetes resource. This snapshot cannot be changed, and modifications to the state have to happen through the other interfaces of the Agones SDK. The returned value is guaranteed to match the value set within the SDK, even if the value was not yet synchronized with the Kubernetes resource.
Notifies Agones that this instance is still running and healthy. This notification must be sent periodically, otherwise this instance will be marked as Unhealthy and eventually removed. The interval is configured in the Agones GameServer resource and tolerates short delays. These health checks are independent of the normal application lifecycle and should be sent from the beginning. They can be sent at an arbitrary interval.
Adds a new label with a specific key and value to the GameServer resource of this instance. The key always gets a prefix assigned automatically to ensure better isolation and security. Therefore, the keys cannot collide with normal Kubernetes labels. This allows further metadata to be published about this instance, which can be read elsewhere, and it is possible to filter the GameServer instances more precisely using the key-value pair.
Notifies Agones that this instance is now ready to accept player connections. Once this state is set, the associated GameServer resource will be set to Ready, and the address and ports for accessing this instance will be populated and published. Before calling this method, the initialization of this instance must be fully completed.
Notifies Agones to set this instance to Reserved state for a specific duration. This prevents the instance from being deleted during that time period and does not trigger any scaling within the fleet. After the duration passed, the instance will be set back to the Ready state. While the instance is in the Reserved state, it cannot be deleted by fleet updates or scaling, and it cannot be assigned with a GameServerAllocation. Invoking any state changing methods like allocate, ready or shutdown deactivates the scheduled reset to Ready after the duration expires.
Notified Agones to shut down this instance and release any allocations for it in the process. The state will immediately be set to Shutdown and the pod of this instance will be stopped and deleted. The actual instance shutdown is triggered only through this method call, and the instance will be shut down by the pod triggering a SIGTERM signal during termination.
Subscribes to changes of the GameServer resource of this instance. The Flow receives a new item, whenever a change is made to the resource. For changes triggered by this SDK as well as for external changes applied directly to the GameServer resource within Kubernetes. The items always contain all properties of the updated GameServer resource and not just the updated fields.