Minikube

Installing Minikube

First, install Minikube, which may also require you to install a virtualisation solution, such as VirtualBox as well.

Starting Minikube

Minikube will need to be started with the supported version of Kubernetes that is supported with Agones, via the --kubernetes-version command line flag.

Optionally, we also recommend starting with an agones profile, using -p to keep this cluster separate from any other clusters you may have running with Minikube.

minikube start --kubernetes-version v1.32.5 -p agones

For testing scenarios that require multiple nodes, you can add the --nodes parameter to create a multi-node cluster.

minikube start --kubernetes-version v1.32.5 -p agones --nodes 3

Check the official minikube start reference for more options that may be required for your platform of choice.

Known working drivers

Other operating systems and drivers may work, but at this stage have not been verified to work with UDP connections via Agones exposed ports.

Linux (amd64)

• Docker (default)
• kvm2

Mac (amd64)

• Docker (default)
• Hyperkit

Windows (amd64 - Windows 10 Enterprise or Pro)

• Hyper-V: You might need to refer to this blog post and/or this comment for WSL support.

Windows (amd64)

• Docker (default) with this workaround
• VirtualBox: You might need this command to disable hardware virtualization checks before starting the VM.

If you have successfully tested with other platforms and drivers, please click “edit this page” in the top right hand side and submit a pull request to let us know.

Local connection workarounds

Depending on your operating system and virtualization platform that you are using with Minikube, it may not be possible to connect directly to a GameServer hosted on Agones as you would on a cloud hosted Kubernetes cluster.

If you are unable to do so, the following workarounds are available, and may work on your platform:

Setting up LoadBalancer Support with MetalLB

By default, Minikube doesn’t provide LoadBalancer’s that are exteranally available without some form of tunneling such as minikube tunnel, which means services of type LoadBalancer will remain in a “Pending” state. For Agones, LoadBalancer services are often used for the allocator and ping services to provide external access. If you want an external IP for those services without a need to tunnel, you need to install MetalLB.

Installing MetalLB

First, add the MetalLB Helm repository and install it:

helm repo add metallb https://metallb.github.io/metallb
helm repo update
helm install metallb metallb/metallb --namespace metallb-system --create-namespace

Configuring MetalLB

After installation, you need to configure MetalLB with an IP address range. Create a configuration file:

# Get the minikube IP to determine the network range
MINIKUBE_IP=$(minikube ip -p agones)
NETWORK_PREFIX=$(echo "$MINIKUBE_IP" | cut -d '.' -f 1-3)
METALLB_IP_RANGE="$NETWORK_PREFIX.50-$NETWORK_PREFIX.250"

# Create MetalLB configuration
cat <<EOF | kubectl apply -f -
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: default-pool
  namespace: metallb-system
spec:
  addresses:
  - ${METALLB_IP_RANGE}
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
  name: default
  namespace: metallb-system
spec:
  ipAddressPools:
  - default-pool
EOF

Once MetalLB is installed and configured, LoadBalancer services will receive external IP addresses from the configured range, allowing external access to Agones services.

minikube ip

Rather than using the published IP of a GameServer to connect, run minikube ip -p agones to get the local IP for the minikube node, and connect to that address.

minikube start --ports (Docker only)

Since you cannot connect to minikube’s private IP on Windows, a more reliable option is to publish the GameServer’s port range directly through Docker by making use of Minikube’s --ports option. Unfortunately, exposing Agones’ entire default port range (7000-8000) may cause Minikube to crash upon startup, so you will likely need to set a narrower port range as shown below.

This method requires a fresh Minikube cluster, so you may need to run minikube delete -p agones before continuing.

minikube start --kubernetes-version v1.32.5 -p agones --ports 7000-7100:7000-7100/udp

When installing Agones on the new cluster (using Helm), update the port range accordingly:

helm install my-release --namespace agones-system --create-namespace \
  --set gameservers.minPort=7000,gameservers.maxPort=7100 agones/agones

Once you have a GameServer running, try connecting to its port either on 127.0.0.1 or WSL’s IP (wsl hostname -I).

Create a service

This would only be for local development, but if none of the other workarounds work, creating a Service for the GameServer you wish to connect to is a valid solution, to tunnel traffic to the appropriate GameServer container.

Use the following yaml:

apiVersion: v1
kind: Service
metadata:
  name: agones-gameserver
spec:
  type: LoadBalancer
  selector:
    agones.dev/gameserver: ${GAMESERVER_NAME}
  ports:
  - protocol: UDP
    port: 7000 # local port
    targetPort: ${GAMESERVER_CONTAINER_PORT}

Where ${GAMESERVER_NAME} is replaced with the GameServer you wish to connect to, and ${GAMESERVER_CONTAINER_PORT} is replaced with the container port GameServer exposes for connection.

Running minikube service list -p agones will show you the IP and port to connect to locally in the URL field.

To connect to a different GameServer, run kubectl edit service agones-gameserver and edit the ${GAMESERVER_NAME} value to point to the new GameServer instance and/or the ${GAMESERVER_CONTAINER_PORT} value as appropriate.

Use a different driver

If you cannot connect through the Serviceor use other workarounds, you may want to try a different minikube driver, and if that doesn’t work, connection via UDP may not be possible with minikube, and you may want to try either a different local Kubernetes tool or use a cloud hosted Kubernetes cluster.

Next Steps

• Continue to Install Agones.