-
Notifications
You must be signed in to change notification settings - Fork 826
/
Copy pathfleet.md
160 lines (144 loc) · 7.59 KB
/
fleet.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
---
title: "Fleet Specification"
linkTitle: "Fleet"
date: 2019-01-03T03:58:52Z
description: "A `Fleet` is a set of warm GameServers that are available to be allocated from."
weight: 20
---
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 {{< ghlink href="examples/fleet.yaml" >}}example folder{{< /ghlink >}} for reference :
```yaml
apiVersion: "agones.dev/v1"
kind: Fleet
# Fleet Metadata
# {{< k8s-api-version href="#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%
# [Stage:Alpha]
# [FeatureFlag:FleetAllocationOverflow]
# Labels and/or Annotations to apply to overflowing GameServers when the number of Allocated GameServers is more
# than the desired replicas on the underlying `GameServerSet`
allocationOverflow:
labels:
mykey: myvalue
version: "" # empty an existing label value
annotations:
otherkey: setthisvalue
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-game-server
image: {{< example-image >}}
```
Since Agones defines a new
[Custom Resources Definition (CRD)](https://kubernetes.io/docs/concepts/api-extension/custom-resources/)
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](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) but also
attach specific [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/)
and [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/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]({{< relref "../Advanced/scheduling-and-autoscaling.md" >}}) 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%
- `allocationOverflow` (Alpha, requires `FleetAllocationOverflow` flag) The labels and/or Annotations to apply to
GameServers when the number of Allocated GameServers exceeds the desired replicas in the underlying
`GameServerSet`.
- `labels` the map of labels to be applied
- `annotations` the map of annotations to be applied
- `Fleet's Scheduling Strategy`: The GameServers associated with the GameServerSet are sorted based on either `Packed` or `Distributed` strategy.
- `Packed`: Agones maximizes resource utilization by trying to populate nodes that are already in use before allocating GameServers to other nodes.
- `Distributed`: Agones employs this strategy to spread out GameServer allocations, ensuring an even distribution of GameServers across the available nodes.
- `template` a full `GameServer` configuration template.
See the [GameServer]({{< relref "gameserver.md" >}}) reference for all available fields.
## Fleet Scale Subresource Specification
Scale subresource is defined for a Fleet. Please refer to [Kubernetes docs](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#subresources).
You can use the following command to scale the fleet with name simple-game-server:
```bash
kubectl scale fleet simple-game-server --replicas=10
```
```
fleet.agones.dev/simple-game-server scaled
```
You can also use [Kubernetes API]({{< ref "/docs/Guides/access-api.md" >}}) to get or update the Replicas count:
```bash
curl http://localhost:8001/apis/agones.dev/v1/namespaces/default/fleets/simple-game-server/scale
```
```
{
"kind": "Scale",
"apiVersion": "autoscaling/v1",
"metadata": {
"name": "simple-game-server",
"namespace": "default",
"selfLink": "/apis/agones.dev/v1/namespaces/default/fleets/simple-game-server/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](https://github.com/googleforgames/agones/issues/553).