Port Allocation

// PortPolicy is the port policy for the GameServer
type PortPolicy string

const (
    // Static PortPolicy means that the user defines the hostPort to be used
    // in the configuration.
    Static PortPolicy = "Static"
    // Dynamic PortPolicy means that the system will choose an open
    // port for the GameServer in question
    Dynamic PortPolicy = "Dynamic"
    // Passthrough dynamically sets the `containerPort` to the same value as the dynamically selected hostPort.
    // This will mean that users will need to lookup what port has been opened through the server side SDK.
    Passthrough PortPolicy = "Passthrough"
    // None means the `hostPort` is ignored and if defined, the `containerPort` (optional) is used to set the port on the GameServer instance.
    None PortPolicy = "None"
)

apiVersion: agones.dev/v1
kind: GameServer
metadata:
  name: dynamic-gameserver
spec:
  ports:
  - name: default
    portPolicy: Dynamic  # System allocates hostPort
    containerPort: 7654  # Your game server listens here
    protocol: UDP
  template:
    spec:
      containers:
      - name: game-server
        image: my-game:latest

status:
  ports:
  - name: default
    port: 7234  # Dynamically allocated hostPort
  state: Ready
  address: 203.0.113.42
  nodeName: game-node-1

// Allocate assigns a port to the GameServer and returns it.
func (pa *portRangeAllocator) Allocate(gs *agonesv1.GameServer) *agonesv1.GameServer {
    pa.mutex.Lock()
    defer pa.mutex.Unlock()

    findOpenPorts := func(amount int) []pn {
        var ports []pn
        if amount <= 0 {
            return ports
        }
        for _, n := range pa.portAllocations {
            for p, taken := range n {
                if !taken {
                    ports = append(ports, pn{pa: n, port: p})
                    if len(ports) == amount {
                        return ports
                    }
                }
            }
        }
        return ports
    }
    // ... allocates and marks ports as taken
}

apiVersion: agones.dev/v1
kind: GameServer
metadata:
  name: static-gameserver
spec:
  ports:
  - name: default
    portPolicy: Static
    hostPort: 7777      # Fixed, must be available
    containerPort: 7654
    protocol: UDP
  template:
    spec:
      containers:
      - name: game-server
        image: my-game:latest

status:
  ports:
  - name: default
    port: 7777  # Exactly as specified
  state: Ready
  address: 203.0.113.42

apiVersion: agones.dev/v1
kind: GameServer
metadata:
  name: passthrough-gameserver
spec:
  ports:
  - name: default
    portPolicy: Passthrough  # containerPort = hostPort (dynamic)
    # No containerPort specified - will be set dynamically
    protocol: UDP
  template:
    spec:
      containers:
      - name: game-server
        image: my-game:latest

status:
  ports:
  - name: default
    port: 7234  # Both hostPort and containerPort are 7234
  state: Ready

import "agones.dev/agones/sdks/go"

sdk, err := sdk.NewSDK()
if err != nil {
    log.Fatal(err)
}

// Get the allocated port
gs, err := sdk.GameServer()
if err != nil {
    log.Fatal(err)
}

port := gs.Status.Ports[0].Port  // The assigned port

// Bind to the assigned port
addr := fmt.Sprintf("0.0.0.0:%d", port)
listener, err := net.Listen("tcp", addr)

if p.PortPolicy == agonesv1.Passthrough {
    gs.Spec.Ports[i].ContainerPort = a.port
}

apiVersion: agones.dev/v1
kind: GameServer
metadata:
  name: none-gameserver
spec:
  ports:
  - name: default
    portPolicy: None
    containerPort: 7654  # Optional, for documentation
    protocol: UDP
  template:
    spec:
      containers:
      - name: game-server
        image: my-game:latest

status:
  ports:
  - name: default
    port: 7654  # containerPort, not a hostPort
  state: Ready
  address: 10.244.1.42  # Pod IP, not node IP
  nodeName: game-node-1

apiVersion: agones.dev/v1
kind: GameServer
spec:
  ports:
  - name: game
    portPolicy: Dynamic
    containerPort: 7654
    protocol: UDP
  - name: query
    portPolicy: Static
    hostPort: 27015
    containerPort: 27015
    protocol: TCP
  - name: rcon
    portPolicy: None
    containerPort: 27016
    protocol: TCP

helm install agones agones/agones \
  --set agones.controller.portRange=7000-8000

ports:
- name: game
  portPolicy: Dynamic
  range: default  # Uses 7000-8000
  containerPort: 7654
- name: voice
  portPolicy: Dynamic
  range: voice    # Uses custom range (configured separately)
  containerPort: 8654

Max GameServers per Node = (MaxPort - MinPort + 1) / Ports per GameServer

Example:
- Range: 7000-8000 (1001 ports)
- Ports per GameServer: 1
- Max per Node: 1001 GameServers

Example with 2 ports:
- Range: 7000-8000 (1001 ports)  
- Ports per GameServer: 2
- Max per Node: 500 GameServers

ports:
- name: dual
  portPolicy: Dynamic
  containerPort: 7654
  protocol: TCPUDP  # Allocates for both TCP and UDP

// create a port for TCP when using TCPUDP protocol
if p.Protocol == agonesv1.ProtocolTCPUDP {
    var duplicate = p
    duplicate.HostPort = a.port

    if duplicate.PortPolicy == agonesv1.Passthrough {
        duplicate.ContainerPort = a.port
    }

    extraPorts = append(extraPorts, duplicate)

    gs.Spec.Ports[i].Name = p.Name + "-tcp"
    gs.Spec.Ports[i].Protocol = corev1.ProtocolTCP
}

// create the UDP port when using TCPUDP protocol
for _, p := range extraPorts {
    p.Name += "-udp"
    p.Protocol = corev1.ProtocolUDP
    gs.Spec.Ports = append(gs.Spec.Ports, p)
}

# Check port allocator logs
kubectl logs -n agones-system deploy/agones-controller \
  | grep portallocator

# Check GameServer events
kubectl describe gameserver <name>

# Get allocated port
kubectl get gameserver my-gs -o jsonpath='{.status.ports[0].port}'

# Get full status
kubectl get gameserver my-gs -o yaml

# Test UDP port
nc -u <node-ip> <port>

# Test TCP port
telnet <node-ip> <port>