Allow direct connections to Autopilot Pods using hostPort

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

  1. 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 and MIN_PORT) must be at least 1000 ports.

  2. 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 for hostPort that you set for each container and the updated value for hostPort 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.