Platform
Fleets: groups, servers and deploys
A group is a named fleet of servers running one game on your hosts. You deploy, start, stop, restart and scale a group as a unit, and still reach every server in it individually.
Groups
A group ties together one game, the hosts it may use, a placement strategy and a naming pattern. Every server the group deploys is named from the pattern.
- The default pattern is
{group}-###. - A pattern may use the tokens
{group},{region}and{env}, and must contain exactly one sequence of#characters, between 2 and 6 long. - Names are lower-case letters, digits and dashes, so they are safe in file paths and log names.
A group shows one overall state, worked out from its servers: unknown, deploying, degraded, running, stopped and partial. When a host cannot be reached, the group shows unknown, never failed: the platform does not guess.
Deploying
A deploy of up to 100 servers is one job. The platform places every server before it starts any of them, so a request that does not fit changes nothing. When the job finishes, each server has its own outcome, and a running job can be cancelled.
Each request can carry an Idempotency-Key, so a retried request never deploys twice. See Studio API and API keys.
Deploy failures
A server that fails to deploy carries one of these codes:
| Code | What it means |
|---|---|
CAPACITY_EXHAUSTED | Should not occur post-planning; a race did |
HOST_UNREACHABLE | The agent stopped answering mid-item |
BUILD_MISSING | The game files are not on the host |
BUILD_CORRUPT | Checksum mismatch on the host's copy |
EXECUTABLE_NOT_FOUND | The definition's executable is not in the build |
PORT_BIND_FAILED | The process would not bind an allocated port |
HEALTH_TIMEOUT | Did not become healthy inside startupGraceSeconds |
RESOURCE_CAP_UNAVAILABLE | Job objects / cgroups could not be applied |
SERVICE_ACCOUNT_FAILED | The per-org account could not be created |
CONFIG_RENDER_FAILED | A config template referenced a missing variable |
DISK_FULL | The host filled during the item |
CANCELLED | The job was cancelled before this item ran |
AGENT_VERSION_TOO_OLD | The agent cannot read this schemaVersion |
Server states
Every server is in one of these states: creating, stopped, starting, running, stopping, failed, deleting and deleted. What you ask for is recorded separately, as one of running, stopped and deleted.
The state you see follows what the host reports. Starting or stopping a server does not mark it running or stopped until the host confirms it, and a server whose host cannot be reached keeps its last known state instead of being marked failed.
Start, stop and restart
- One server or the whole group. Start, stop and restart work on a single server or on every server in a group. The group-wide actions ask you to type a confirmation.
- Graceful by default. When players are online and the game's console can broadcast, a stop or restart first warns players in game with a countdown (300 seconds by default).
- Rolling restart. Restarts the group one server at a time and stops at the first server that fails, so a bad change never takes the whole fleet down.
- Delete. Deleting a server stops it, removes its files from the host and releases its ports. The record is kept, marked deleted.
Scaling
Scaling a group up or down produces a plan first. You review exactly which servers will be added or removed, and the plan is valid for 10 minutes. When scaling down, stopped servers go first, then empty ones, then those with the fewest players.
A group can also carry an autoscaling policy that keeps a buffer of ready servers between a minimum and a maximum. Through the API, your matchmaker can take a ready, running server from the group and hand it back when the match ends.
Console
Each server has a console showing its recent output, refreshed every 3 seconds. It is not a live stream.
Commands are sent one at a time over the channel your game definition declares: rcon, telnet, stdin and none. A game that declares none has a read-only console.
- A command is a single line of at most 2048 characters.
- Each server accepts up to 10 commands a minute from each person or key.
- Every command is written to your audit log with its full text.
Scheduled restarts
A group can restart on a schedule. Schedules use standard 5-field cron expressions in UTC, may not run more often than every 5 minutes, and show the next 3 run times before you save them.
Scheduled restarts warn players in game the same way a manual graceful restart does, and a schedule can be run now, cancelled or ended early.