# Minikube

> Follow these steps to create a [Minikube](https://github.com/kubernetes/minikube) cluster for your Agones install.

---

LLMS index: [llms.txt](/site/llms.txt)

---

## Installing Minikube

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

[minikube]: https://minikube.sigs.k8s.io/docs/start/
[vb]: https://www.virtualbox.org

## 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.

```bash
minikube start --kubernetes-version v1.34.6 -p agones
```

For testing scenarios that require multiple nodes, you can add the `--nodes` parameter to create a multi-node cluster.
```bash
minikube start --kubernetes-version v1.34.6 -p agones --nodes 3
```

Check the official [minikube start](https://minikube.sigs.k8s.io/docs/commands/start/) reference for more options that
may be required for your platform of choice.

<div class="alert alert-info" role="alert"><div class="h4 alert-heading" role="heading">Note</div>


You may need to increase the `--cpu` or `--memory` values for your minikube instance, depending on what resources are
available on the host and/or how many GameServers you wish to run locally.

Depending on your Operating System, you may also need to change the `--driver`
([driver list](https://minikube.sigs.k8s.io/docs/drivers/)) to enable `GameServer` connectivity with or without
some workarounds listed below. 
</div>


### 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)**
* Docker (default) with [this workaround](#minikube-start---ports-docker-only)
* VirtualBox: You might need [this command](https://github.com/kubernetes/minikube/issues/3900) 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:

```bash
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:

```bash
# 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.

```bash
minikube start --kubernetes-version v1.34.6 -p agones --ports 7000-7100:7000-7100/udp
```

When installing Agones on the new cluster (using [Helm](/site/docs/installation/install-agones/helm/)), update the port range accordingly:

```bash
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`).

<div class="alert alert-info" role="alert"><div class="h4 alert-heading" role="heading">Note</div>


The port range 7000-7100 will likely allow Minikube to start consistently, but you can narrow or widen this range
to whatever works on your system. Make sure it is consistent between both the `minikube start` command shown above and
the Helm configuration.
</div>


### 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:

```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.

<div class="alert alert-warning" role="alert"><div class="h4 alert-heading" role="heading">Warning</div>


`minikube tunnel` ([docs](https://minikube.sigs.k8s.io/docs/handbook/accessing/))
does not support UDP ([Github Issue](https://github.com/kubernetes/minikube/issues/12362)) on some combination of
operating system, platforms and drivers, but is required when using the `Service` workaround.
</div>


### Use a different driver

If you cannot connect through the `Service`or use other workarounds, you may want to try a different
[minikube driver](https://minikube.sigs.k8s.io/docs/drivers/), 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](https://kubernetes.io/docs/tasks/tools/) or use a cloud hosted Kubernetes cluster.

## Next Steps

- Continue to [Install Agones](/site/docs/installation/install-agones/).