From ac442d6ba4d97096d8a41fc585d047f2c41b0c02 Mon Sep 17 00:00:00 2001
From: Pooneh Mortazavi <pooneh@google.com>
Date: Tue, 8 Sep 2020 16:47:21 -0700
Subject: [PATCH] Update allocator service documentation

---
 .../en/docs/Advanced/allocator-service.md       | 17 ++++++++++++-----
 .../docs/Advanced/multi-cluster-allocation.md   | 16 +++++++++-------
 2 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/site/content/en/docs/Advanced/allocator-service.md b/site/content/en/docs/Advanced/allocator-service.md
index 6bf3682458..0954efb6ee 100644
--- a/site/content/en/docs/Advanced/allocator-service.md
+++ b/site/content/en/docs/Advanced/allocator-service.md
@@ -10,7 +10,8 @@ To allocate a game server, Agones in addition to {{< ghlink href="pkg/apis/alloc
 
 The gRPC service is accessible through a Kubernetes service that is externalized using a load balancer. For the gRPC request to succeed, a client certificate must be provided that is in the authorization list of the allocator service.
 
-The remainder of this article describes how to manually make a successful allocation request using the gRPC API.
+The remainder of this article describes how to manually make a successful allocation request using the gRPC API. 
+The guide assumes you have command line tools installed for [jq](https://stedolan.github.io/jq/), [go](https://golang.org/) and [openssl](https://www.openssl.org/).
 
 ## Find the external IP
 
@@ -35,7 +36,10 @@ If the `agones-allocator` service is installed as a `LoadBalancer` [using a stat
 
 Replace the default server TLS certificate with a certificate with CN and subjectAltName. There are multiple approaches to generate a certificate. Agones recommends using [cert-manager.io](https://cert-manager.io/) solution for cluster level certificate management.
 
-In order to use cert-manager solution, first, [install cert-manager](https://cert-manager.io/docs/installation/kubernetes/) on the cluster. Then, [configure](https://cert-manager.io/docs/configuration/) an `Issuer`/`ClusterIssuer` resource and last configure a `Certificate` resource to manage allocator-tls `Secret`.
+In order to use the cert-manager solution, first [install cert-manager](https://cert-manager.io/docs/installation/kubernetes/) on the cluster.
+Then, [configure](https://cert-manager.io/docs/configuration/) an `Issuer`/`ClusterIssuer` resource and
+last [configure](https://cert-manager.io/docs/usage/certificate/) a `Certificate` resource to manage allocator-tls `Secret`.
+Make sure to configure the `Certificate` based on your system's requirements, including the validity `duration`.
 
 Here is an example of using a self-signed `ClusterIssuer` for configuring allocator-tls `Secret`:
 
@@ -43,7 +47,7 @@ Here is an example of using a self-signed `ClusterIssuer` for configuring alloca
 #!/bin/bash
 # Create a self-signed ClusterIssuer
 cat <<EOF | kubectl apply -f -
-apiVersion: cert-manager.io/v1alpha2
+apiVersion: cert-manager.io/v1
 kind: ClusterIssuer
 metadata:
   name: selfsigned
@@ -53,12 +57,15 @@ EOF
 
 EXTERNAL_IP=`kubectl get services agones-allocator -n agones-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}'`
 
+# for EKS use hostname
+# HOST_NAME=`kubectl get services agones-allocator -n agones-system -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'`
+
 # Create a Certificate with IP for the allocator-tls secret
 cat <<EOF | kubectl apply -f -
-apiVersion: cert-manager.io/v1alpha2
+apiVersion: cert-manager.io/v1
 kind: Certificate
 metadata:
-  name: allocator-selfsigned-cert
+  name: allocator-tls
   namespace: agones-system
 spec:
   commonName: ${EXTERNAL_IP}
diff --git a/site/content/en/docs/Advanced/multi-cluster-allocation.md b/site/content/en/docs/Advanced/multi-cluster-allocation.md
index 4bfdded10b..9dd2ca11f2 100644
--- a/site/content/en/docs/Advanced/multi-cluster-allocation.md
+++ b/site/content/en/docs/Advanced/multi-cluster-allocation.md
@@ -16,7 +16,9 @@ The remainder of this article describes how to enable multi-cluster allocation.
 
 ## Define Cluster Priority
 
-{{< ghlink href="pkg/apis/multicluster/v1/gameserverallocationpolicy.go" >}}GameServerAllocationPolicy{{< /ghlink >}} is the CRD defined by Agones for setting multi-cluster allocation rules. In addition to cluster priority, it describes the connection information for the target cluster, including the game server namespace, agones-allocator endpoint and client K8s secrets name for redirecting the allocation request. Here is an example of setting the priority for a cluster and it's connection rules. One such resource should be defined per cluster. For clusters with the same priority, the cluster is chosen with a probability relative to its weight.
+{{< ghlink href="pkg/apis/multicluster/v1/gameserverallocationpolicy.go" >}}GameServerAllocationPolicy{{< /ghlink >}} is the CRD defined by Agones for setting multi-cluster allocation rules. In addition to cluster priority, it describes the connection information for the target cluster, including the game server namespace, agones-allocator endpoint and client K8s secrets name for redirecting the allocation request. Game servers will be allocated from clusters with the lowest `priority` number. If there are no available game servers available in clusters with the lowest `priority` number, they will be allocated from clusters with the next lowest `priority` number. For clusters with the same priority, the cluster is chosen with a probability relative to its weight.
+
+Here is an example of setting the priority for a cluster and it's connection rules. One such resource should be defined per cluster.
 
 In the following example the policy is defined for cluster B in cluster A.
 
@@ -25,15 +27,15 @@ cat <<EOF | kubectl apply -f -
 apiVersion: multicluster.agones.dev/v1
 kind: GameServerAllocationPolicy
 metadata:
-  name: allocator-cluster-B
-  namespace: cluster-A-ns
+  name: allocator-cluster-b
+  namespace: cluster-a-ns
 spec:
   connectionInfo:
     allocationEndpoints:
     - 34.82.195.204
     clusterName: "clusterB"
-    namespace: cluster-B-ns
-    secretName: allocator-client-to-cluster-B
+    namespace: cluster-b-ns
+    secretName: allocator-client-to-cluster-b
     serverCa: c2VydmVyQ0E=
   priority: 1
   weight: 100
@@ -57,8 +59,8 @@ cat <<EOF | kubectl apply -f -
 apiVersion: v1
 kind: Secret
 metadata:
-  name: allocator-client-to-cluster-B
-  namespace: cluster-A-ns
+  name: allocator-client-to-cluster-b
+  namespace: cluster-a-ns
 type: Opaque
 data:
   tls.crt: <REDACTED>