GameServer Pod: Stable Network ID

This change sets the hostName (if not already set) on the Pod of the
GameServer, if an end user would like a DNS entry to communicate
directly to the GameServer Pod in the cluster.

Since this is a relatively minor change, no FeatureFlag was created.

Closes googleforgames#2704

pkg/apis/agones/v1/gameserver.go

@@ -594,6 +594,10 @@ func (gs *GameServer) Pod(sidecars ...corev1.Container) (*corev1.Pod, error) {
 		Spec:       *gs.Spec.Template.Spec.DeepCopy(),
 	}
 
+	if len(pod.Spec.Hostname) == 0 {
+		pod.Spec.Hostname = gs.ObjectMeta.Name
+	}
+
 	gs.podObjectMeta(pod)
 	for _, p := range gs.Spec.Ports {
 		cp := corev1.ContainerPort{

pkg/apis/agones/v1/gameserver_test.go

@@ -25,6 +25,7 @@ import (
 	"agones.dev/agones/pkg/apis/agones"
 	"agones.dev/agones/pkg/util/runtime"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 	corev1 "k8s.io/api/core/v1"
 	"k8s.io/apimachinery/pkg/api/resource"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
@@ -1154,6 +1155,7 @@ func TestGameServerPodNoErrors(t *testing.T) {
 	pod, err := fixture.Pod()
 	assert.Nil(t, err, "Pod should not return an error")
 	assert.Equal(t, fixture.ObjectMeta.Name, pod.ObjectMeta.Name)
+	assert.Equal(t, fixture.ObjectMeta.Name, pod.Spec.Hostname)
 	assert.Equal(t, fixture.ObjectMeta.Namespace, pod.ObjectMeta.Namespace)
 	assert.Equal(t, "gameserver", pod.ObjectMeta.Labels[agones.GroupName+"/role"])
 	assert.Equal(t, fixture.ObjectMeta.Name, pod.ObjectMeta.Labels[GameServerPodLabel])
@@ -1165,6 +1167,18 @@ func TestGameServerPodNoErrors(t *testing.T) {
 	assert.True(t, metav1.IsControlledBy(pod, fixture))
 }
 
+func TestGameServerPodWithHostName(t *testing.T) {
+	t.Parallel()
+	fixture := defaultGameServer()
+	fixture.ApplyDefaults()
+	expected := "ORANGE"
+	fixture.Spec.Template.Spec.Hostname = expected
+	pod, err := fixture.Pod()
+
+	require.NoError(t, err)
+	assert.Equal(t, expected, pod.Spec.Hostname)
+}
+
 func TestGameServerPodContainerNotFoundErrReturned(t *testing.T) {
 	t.Parallel()
 

site/content/en/docs/Reference/gameserver.md

@@ -131,6 +131,21 @@ The `spec` field is the actual GameServer specification and it is composed as fo
 The GameServer resource does not support updates. If you need to make regular updates to the GameServer spec, consider using a [Fleet]({{< ref "/docs/Reference/fleet.md" >}}).
 {{< /alert >}}
 
+## Stable Network ID
+
+Each Pod attached to a `GameServer` derives its hostname from the name of the `GameServer`. 
+A group of `Pods` attached to `GameServers` can use a 
+[Headless Service](https://kubernetes.io/docs/concepts/services-networking/service/#headless-services) to control 
+the domain of the Pods. The domain managed by this Service takes the form: 
+$(service name).$(namespace).svc.cluster.local, where "cluster.local" is the cluster domain. As each Pod is created,
+it gets a matching [DNS subdomain](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/), 
+taking the form: $(podname).$(governing service domain), where the governing service is defined by the serviceName 
+field in front of the `GameServer` Pods.
+
+You are responsible for setting the labels on the `GameServer.Spec.Template.Metadata` to set the labels on the 
+created Pods and creating the Headless Service responsible for the network identity of the pods, Agones will not do 
+this for you, as a stable DNS record is not required for all use cases. 
+
 ## GameServer State Diagram
 
 The following diagram shows the lifecycle of a `GameServer`.