This page shows you how to expose a random port in a Pod running in a Google Kubernetes Engine (GKE) Autopilot cluster.
Exposing a port in a Pod lets the Pod accept incoming connections directly,
without a load balancer. GKE chooses a random port to open
from a range that you specify in the Pod specification. This type of random
port exposure is useful when your workload requires direct incoming connections
but doesn't rely on a persistent port number. An example of this type of workload is an Agones GameServer resource with the
default Dynamic
port policy.
When you request a random port, GKE overrides the value in the
hostPort
field in the container specification to the port that
GKE selected for you.
Before you begin
Before you start, make sure you have performed the following tasks:
- Enable the Google Kubernetes Engine API. Enable Google Kubernetes Engine API
- If you want to use the Google Cloud CLI for this task,
install and then
initialize the
gcloud CLI. If you previously installed the gcloud CLI, get the latest
version by running
gcloud components update
.
- Ensure that you have a GKE Autopilot cluster running version 1.24.7-gke.1200 and later or 1.25.3-gke.1100 and later.
Limitations
You can only assign random hostPorts for static Pods or for Pods that are managed by a custom controller, such as Agones. This functionality isn't supported on Kubernetes managed controllers such as Deployments.
Request a random port
Save the following manifest as
host-port-pod.yaml
:apiVersion: v1 kind: Pod metadata: name: game-pod annotations: autopilot.gke.io/host-port-assignment: '{"min":MIN_PORT,"max":MAX_PORT}' spec: containers: - name: local-chat image: ubuntu ports: - containerPort: 80 hostPort: HOST_PORT1 protocol: tcp - name: game-server image: ubuntu ports: - containerPort: 80 hostPort: HOST_PORT2 protocol: udp
Replace the following:
MIN_PORT
: the minimum port number for the range from which GKE chooses a random port.MAX_PORT
: the maximum port number for the range from which GKE chooses a random port.HOST_PORT1, HOST_PORT2
: any valid port number. When the Pod is scheduled, GKE updates this field with the randomly assigned port. If you have multiple containers, use different port numbers for each container.
The port range (the difference between
MAX_PORT
andMIN_PORT
) must be at least 1000 ports.Apply the manifest:
kubectl apply -f host-port-pod.yaml
When you apply the manifest, GKE selects a random port from your range and assigns the port to your container. If GKE assigns the same port value to two Pods, GKE automatically places the Pods on separate nodes to avoid port conflict.
Check the assigned port
To find the port number that GKE assigned to your containers, inspect the Pod:
kubectl get pod game-pod --output=yaml
The output is similar to the following:
apiVersion: v1
kind: Pod
metadata:
annotations:
autopilot.gke.io/host-port-assignment: '{"min":MIN_PORT,"max":MAX_PORT,"portsAssigned":{"HOST_PORT1":7300,"HOST_PORT2":7450}}'
name: game-pod
namespace: default
spec:
containers:
- name: local-chat
image: ubuntu
imagePullPolicy: IfNotPresent
ports:
- containerPort: 80
hostPort: 7300
protocol: TCP
- name: game-server
image: ubuntu
imagePullPolicy: IfNotPresent
ports:
- containerPort: 80
hostPort: 7450
protocol: UDP
In this output:
metadata.annotations.autopilot.gke.io/host-port-assignment
: the port assignments, showing the original value forhostPort
that you set for each container and the updated value forhostPort
that GKE assigned. This field is useful if you requested multiple ports in your Pod specification.spec.containers.ports.hostPort
: the opened port that GKE assigned to each container.
What's next
Track Agones support on Autopilot on GitHub.