// Copyright 2020 Google LLC All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto3";
package allocation;
option go_package = "./allocation";
import "google/api/annotations.proto";
import "google/protobuf/wrappers.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
info: {
title: "proto/allocation/allocation.proto";
version: "version not set";
};
schemes: HTTPS;
consumes: "application/json";
produces: "application/json";
};
service AllocationService {
rpc Allocate(AllocationRequest) returns (AllocationResponse) {
option (google.api.http) = {
post: "/gameserverallocation"
body: "*"
};
}
}
message AllocationRequest {
// The k8s namespace that is hosting the targeted fleet of gameservers to be allocated
string namespace = 1;
// If specified, multi-cluster policies are applied. Otherwise, allocation will happen locally.
MultiClusterSetting multiClusterSetting = 2;
// Deprecated: Please use gameServerSelectors instead. This field is ignored if the
// gameServerSelectors field is set
// The required allocation. Defaults to all GameServers.
GameServerSelector requiredGameServerSelector = 3 [deprecated = true];
// Deprecated: Please use gameServerSelectors instead. This field is ignored if the
// gameServerSelectors field is set
// The 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.
repeated GameServerSelector preferredGameServerSelectors = 4 [deprecated = true];
// Scheduling strategy. Defaults to "Packed".
SchedulingStrategy scheduling = 5;
enum SchedulingStrategy {
Packed = 0;
Distributed = 1;
}
// Deprecated: Please use metadata instead. This field is ignored if the
// metadata field is set
MetaPatch metaPatch = 6;
// Metadata is optional custom metadata that is added to the game server at
// allocation. You can use this to tell the server necessary session data
MetaPatch metadata = 7;
// Ordered list of GameServer label selectors.
// 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.
// Note: This field can only be set if neither Required or Preferred is set.
repeated GameServerSelector gameServerSelectors = 8;
// [Stage: Beta]
// [FeatureFlag:CountsAndLists]
// `Priorities` configuration alters the order in which `GameServers` are searched for matches to the configured `selectors`.
//
// Priority of sorting is in descending importance. I.e. The position 0 `priority` entry is checked first.
//
// For `Packed` strategy sorting, this priority list will be the tie-breaker within the least utilised infrastructure, to ensure optimal
// infrastructure usage while also allowing some custom prioritisation of `GameServers`.
//
// For `Distributed` strategy sorting, the entire selection of `GameServers` will be sorted by this priority list to provide the
// order that `GameServers` will be allocated by.
repeated Priority priorities = 9;
// [Stage: Beta]
// [FeatureFlag:CountsAndLists]
// Counters and Lists provide a set of actions to perform
// on Counters and Lists during allocation.
map<string, CounterAction> counters = 10;
map<string, ListAction> lists = 11;
}
message AllocationResponse {
string gameServerName = 2;
repeated GameServerStatusPort ports = 3;
// Primary address at which game server can be reached
string address = 4;
// All addresses at which game server can be reached; copy of Node.Status.addresses
repeated GameServerStatusAddress addresses = 8;
string nodeName = 5;
string source = 6;
optional GameServerMetadata metadata = 7;
// (Beta, CountsAndLists feature flag) Status of Counters and Lists on allocation.
map<string, CounterStatus> counters = 9;
map<string, ListStatus> lists = 10;
// The gameserver port info that is allocated.
message GameServerStatusPort {
string name = 1;
int32 port = 2;
}
// A single address; identical to corev1.NodeAddress
message GameServerStatusAddress {
string type = 1;
string address = 2;
}
message GameServerMetadata {
map<string, string> labels = 1;
map<string, string> annotations = 2;
}
message CounterStatus {
google.protobuf.Int64Value count = 1;
google.protobuf.Int64Value capacity = 2;
}
message ListStatus {
repeated string values = 1;
google.protobuf.Int64Value capacity = 2;
}
}
// Specifies settings for multi-cluster allocation.
message MultiClusterSetting {
// If set to true, multi-cluster allocation is enabled.
bool enabled = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {format: "boolean"}];
// Selects multi-cluster allocation policies to apply. If not specified, all multi-cluster allocation policies are to be applied.
LabelSelector policySelector = 2;
}
// MetaPatch is the metadata used to patch the GameServer metadata on allocation
message MetaPatch {
map<string, string> labels = 1;
map<string, string> annotations = 2;
}
// LabelSelector used for finding a GameServer with matching labels.
message LabelSelector {
// Labels to match.
map<string, string> matchLabels = 1;
}
// GameServerSelector used for finding a GameServer with matching filters.
message GameServerSelector {
// Labels to match.
map<string, string> matchLabels = 1;
enum GameServerState {
READY = 0;
ALLOCATED = 1;
};
GameServerState gameServerState = 2;
PlayerSelector players = 3;
map<string, CounterSelector> counters = 4;
map<string, ListSelector> lists = 5;
}
// PlayerSelector is filter for player capacity values.
// minAvailable should always be less or equal to maxAvailable.
message PlayerSelector {
uint64 minAvailable = 1;
uint64 maxAvailable = 2;
}
// CounterSelector is the filter options for a GameServer based on the count and/or available capacity.
// 0 for MaxCount or MaxAvailable means unlimited maximum. Default for all fields: 0
message CounterSelector {
int64 minCount = 1;
int64 maxCount = 2;
int64 minAvailable = 3;
int64 maxAvailable = 4;
}
// ListSelector is the filter options for a GameServer based on List available capacity and/or the
// existence of a value in a List.
// 0 for MaxAvailable means unlimited maximum. Default for integer fields: 0
// "" for ContainsValue means ignore field. Default for string field: ""
message ListSelector {
string containsValue = 1;
int64 minAvailable = 2;
int64 maxAvailable = 3;
}
// Priority is a sorting option for GameServers with Counters or Lists based on the Capacity.
// Type: Sort by a "Counter" or a "List".
// Key: The name of the Counter or List. If not found on the GameServer, has no impact.
// Order: Sort by "Ascending" or "Descending". "Descending" a bigger Capacity is preferred.
// "Ascending" would be smaller Capacity is preferred.
message Priority {
enum Type {
Counter = 0;
List = 1;
}
Type type = 1;
string key = 2;
enum Order {
Ascending = 0;
Descending = 1;
}
Order order = 3;
}
// CounterAction is an optional action that can be performed on a Counter at allocation.
// Action: "Increment" or "Decrement" the Counter's Count (optional). Must also define the Amount.
// Amount: The amount to increment or decrement the Count (optional). Must be a positive integer.
// Capacity: Update the maximum capacity of the Counter to this number (optional). Min 0, Max int64.
message CounterAction {
google.protobuf.StringValue action = 1;
google.protobuf.Int64Value amount = 2;
google.protobuf.Int64Value capacity = 3;
}
// ListAction is an optional action that can be performed on a List at allocation.
// AddValues: Append values to a List's Values array (optional). Any duplicate values will be ignored.
// Capacity: Update the maximum capacity of the Counter to this number (optional). Min 0, Max 1000.
// DeleteValues: Remove values from a List's Values array (optional). Any nonexistant values will be ignored.
message ListAction {
repeated string addValues = 1;
google.protobuf.Int64Value capacity = 2;
repeated string deleteValues = 3;
}