Skip to main content
Gate’s Docker images are designed for Kubernetes deployments, providing scalable and reliable proxy infrastructure for your Minecraft network.

​
Prerequisites

Before deploying Gate to Kubernetes, ensure you have:

Kubernetes Cluster

Running cluster (kind, minikube, k3s, k3d, GKE, EKS, AKS, etc.)

kubectl

Kubernetes CLI tool installed and configured

Kustomize

(Optional) For advanced manifest management

Lens Desktop

(Optional) Kubernetes IDE for easier management
New to Kubernetes? Try kind for local development or k3d for lightweight clusters.

​
Quick Start: All-in-One Example

Deploy a complete Gate proxy with two Minecraft servers in one command: 
kubectl apply -f https://raw.githubusercontent.com/minekube/gate/master/.examples/kubernetes/bundle.yaml
This creates:
  • Gate proxy deployment
  • Two Minecraft server pods (StatefulSet)
  • NodePort service on port 32556
  • ConfigMaps for configuration
1

Deploy the bundle

kubectl apply -f https://raw.githubusercontent.com/minekube/gate/master/.examples/kubernetes/bundle.yaml
2

Wait for pods to be ready

kubectl get pods -w
Wait until all pods show Running status.
3

Connect to Gate

Connect your Minecraft client to <node-ip>:32556Find your node IP:
kubectl get nodes -o wide
4

Test server switching

In-game, use /server server-0 or /server server-1 to switch between servers.Try deleting a server pod to see Gate automatically reconnect players:
kubectl delete pod server-0
The bundle includes everything needed for a complete Minecraft network:
apiVersion: v1
data:
  config.yml: |
    config:
      bind: 0.0.0.0:25565
      servers:
        server-0: server-0.servers:25565
        server-1: server-1.servers:25565
      try:
        - server-0
        - server-1
kind: ConfigMap
metadata:
  name: gate-config
---
apiVersion: v1
kind: Service
metadata:
  name: gate
spec:
  type: NodePort
  ports:
  - port: 25565
    targetPort: minecraft
    protocol: TCP
    nodePort: 32556
  selector:
    app.kubernetes.io/component: proxy
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gate
spec:
  selector:
    matchLabels:
      app.kubernetes.io/component: proxy
  template:
    metadata:
      labels:
        app.kubernetes.io/component: proxy
    spec:
      containers:
      - name: gate
        image: ghcr.io/minekube/gate:latest
        ports:
        - containerPort: 25565
          name: minecraft
        volumeMounts:
        - name: config
          mountPath: /config.yml
          subPath: config.yml
      volumes:
      - name: config
        configMap:
          name: gate-config
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: server
spec:
  replicas: 2
  serviceName: servers
  selector:
    matchLabels:
      app.kubernetes.io/component: server
  template:
    metadata:
      labels:
        app.kubernetes.io/component: server
    spec:
      containers:
      - name: minecraft-server
        image: itzg/minecraft-server:latest
        env:
        - name: EULA
          value: "TRUE"
        - name: TYPE
          value: "PUFFERFISH"
        - name: ONLINE_MODE
          value: "FALSE"
        ports:
        - containerPort: 25565
          name: minecraft
Kustomize provides a structured way to manage Kubernetes manifests. Gate’s examples use Kustomize for easier customization.
1

Clone the repository

git clone https://github.com/minekube/gate.git
cd gate/.examples/kubernetes
2

Review the structure

The example includes:
  • kustomization.yaml - Main Kustomize configuration
  • deploy.yaml - Gate deployment
  • svc.yaml - Gate service
  • config.yml - Gate configuration
  • servers/ - Minecraft server manifests
3

Customize for your needs

Edit the files to match your environment:
config.yml
config:
  bind: 0.0.0.0:25565
  servers:
    lobby: lobby.minecraft.svc:25565
    survival: survival.minecraft.svc:25565
  try:
    - lobby
4

Preview the generated manifests

kustomize build .
This shows what will be deployed without actually deploying.
5

Deploy to Kubernetes

kubectl apply -k .
6

Clean up when done

kubectl delete -k .

​
Overlay Your Own Kustomize

Create your own Kustomize that extends Gate’s example:
kustomization.yaml
resources:
  - https://raw.githubusercontent.com/minekube/gate/master/.examples/kubernetes

patchesStrategicMerge:
  - patch.yaml

namespace: minecraft

images:
  - name: ghcr.io/minekube/gate
    newTag: 0.42.2  # Pin to specific version
Create a patch file:
patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gate
spec:
  replicas: 3  # Scale Gate to 3 replicas
  template:
    spec:
      containers:
      - name: gate
        resources:
          limits:
            memory: 512Mi
            cpu: 500m
          requests:
            memory: 256Mi
            cpu: 250m

​
Manual Deployment

For more control, deploy Gate components individually:
1

Create ConfigMap for Gate configuration

kubectl create configmap gate-config --from-file=config.yml
2

Create Gate Deployment

gate-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gate
  labels:
    app: gate
spec:
  replicas: 2
  selector:
    matchLabels:
      app: gate
  template:
    metadata:
      labels:
        app: gate
    spec:
      containers:
      - name: gate
        image: ghcr.io/minekube/gate:latest
        ports:
        - containerPort: 25565
          name: minecraft
          protocol: TCP
        volumeMounts:
        - name: config
          mountPath: /config.yml
          subPath: config.yml
        resources:
          limits:
            memory: "512Mi"
            cpu: "500m"
          requests:
            memory: "256Mi"
            cpu: "250m"
      volumes:
      - name: config
        configMap:
          name: gate-config
Apply it:
kubectl apply -f gate-deployment.yaml
3

Create Gate Service

gate-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: gate
spec:
  type: LoadBalancer  # Use LoadBalancer for cloud, NodePort for local
  selector:
    app: gate
  ports:
  - port: 25565
    targetPort: 25565
    protocol: TCP
    name: minecraft
Apply it:
kubectl apply -f gate-service.yaml
4

Get the external IP

kubectl get service gate
For LoadBalancer, wait for EXTERNAL-IP to be assigned. For NodePort, use any node IP with the assigned node port.

​
Service Types

Choose the appropriate service type for your environment:
Best for: Cloud providers (GKE, EKS, AKS)
apiVersion: v1
kind: Service
metadata:
  name: gate
spec:
  type: LoadBalancer
  ports:
  - port: 25565
    targetPort: 25565
  selector:
    app: gate
Automatically provisions a cloud load balancer with external IP.

​
Bedrock Edition Support

For Bedrock Edition support, use the JRE variant image: 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gate
spec:
  template:
    spec:
      containers:
      - name: gate
        image: ghcr.io/minekube/gate/jre:latest  # JRE variant
        ports:
        - containerPort: 25565
          name: minecraft-java
          protocol: TCP
        - containerPort: 19132
          name: minecraft-bedrock
          protocol: UDP
Update the service to expose UDP port: 
apiVersion: v1
kind: Service
metadata:
  name: gate
spec:
  ports:
  - port: 25565
    protocol: TCP
    name: java
  - port: 19132
    protocol: UDP
    name: bedrock

​
Monitoring and Troubleshooting

kubectl get pods -l app=gate
kubectl describe pod <pod-name>

kubectl logs -f deployment/gate

# For specific pod:
kubectl logs -f <pod-name>

# Previous container logs (if crashed):
kubectl logs <pod-name> --previous

kubectl get endpoints gate
Verify that endpoints are listed (pods are ready).
kubectl run -it --rm debug --image=busybox --restart=Never -- sh
# Inside the pod:
nc -zv gate 25565
After updating a ConfigMap, restart the deployment:
kubectl rollout restart deployment/gate
Or use ConfigMap versioning in Kustomize with configMapGenerator.

​
Production Best Practices

Use resource limits

Set memory and CPU limits to prevent resource exhaustion:
resources:
  limits:
    memory: 512Mi
    cpu: 500m
  requests:
    memory: 256Mi
    cpu: 250m

Enable readiness probes

Ensure traffic only goes to ready pods:
readinessProbe:
  tcpSocket:
    port: 25565
  initialDelaySeconds: 5
  periodSeconds: 10

Use multiple replicas

Run multiple Gate instances for high availability:
spec:
  replicas: 3

Pin image versions

Avoid unexpected changes with specific versions:
image: ghcr.io/minekube/gate:0.42.2

​
Next Steps

Configuration

Customize Gate for your network

Scaling

Scale Gate for high player counts

Build docs developers (and LLMs) love

Get started for freeTalk to us