docs: document auto service discovery example

.goreleaser.yml

@@ -45,3 +45,4 @@ changelog:
   filters:
     exclude:
       - '^ci:'
+      - '^docs:'

README.md

@@ -31,22 +31,20 @@ Flags:
   
 ## Example kubernetes deployment
 
-[These deployments](docs/k8s-example.yaml) declare an `mc-router` that exposes a node port service 
+[This example deployment](docs/k8s-example-auto.yaml) 
-on the standard Minecraft server port 25565. Two "backend" Minecraft servers are declared as example
+* Declares an `mc-router` service that exposes a node port 25565
-where users can choose stable/vanilla or snapshot simply based on the hostname they used.
+* Declares a service account with access to watch and list services
+* Declares `--in-kube-cluster` in the `mc-router` container arguments
+* Two "backend" Minecraft servers are declared each with an 
+  `"mc-router.itzg.me/externalServerName"` annotation that declares their external server name
 
 ```bash
-kubectl apply -f https://raw.githubusercontent.com/itzg/mc-router/master/docs/k8s-example.yaml
+kubectl apply -f https://raw.githubusercontent.com/itzg/mc-router/master/docs/k8s-example-auto.yaml
 ```
 
-![](docs/example-deployment.drawio.png)
+![](docs/example-deployment-auto.drawio.png)
 
 #### Notes
 * This deployment assumes two persistent volume claims: `mc-stable` and `mc-snapshot`
 * I extended the allowed node port range by adding `--service-node-port-range=25000-32767` 
   to `/etc/kubernetes/manifests/kube-apiserver.yaml` 
-
-## Coming Soon
-
-* Make `mc-router` kubernetes service aware. It would watch for backend instances with well known annotations
-  and dynamically create/remove routes accordingly

docs/k8s-example-auto.yaml

@@ -0,0 +1,167 @@
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: mc-router
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: services-watcher
+rules:
+- apiGroups: [""]
+  resources: ["services"]
+  verbs: ["watch","list"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: mc-router-services-watcher
+subjects:
+- kind: ServiceAccount
+  name: mc-router
+  namespace: default
+roleRef:
+  kind: ClusterRole
+  name: services-watcher
+  apiGroup: rbac.authorization.k8s.io
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: mc-router
+spec:
+  type: NodePort
+  ports:
+  - targetPort: web
+    name: web
+    port: 8080
+    nodePort: 25580
+  - targetPort: proxy
+    name: proxy
+    port: 25565
+    nodePort: 25565
+  selector:
+    run: mc-router
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    run: mc-router
+  name: mc-router
+spec:
+  selector:
+    matchLabels:
+      run: mc-router
+  strategy:
+    type: Recreate
+  template:
+    metadata:
+      labels:
+        run: mc-router
+    spec:
+      serviceAccountName: mc-router
+      containers:
+      - image: itzg/mc-router:1.1.1
+        name: mc-router
+        args: ["--api-binding", ":8080", "--in-kube-cluster"]
+        ports:
+        - name: proxy
+          containerPort: 25565
+        - name: web
+          containerPort: 8080
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: mc-stable
+  annotations:
+    "mc-router.itzg.me/externalServerName": "mc.your.domain"
+spec:
+  ports:
+  - port: 25565
+  selector:
+    run: mc-stable
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    run: mc-stable
+  name: mc-stable
+spec:
+  selector:
+    matchLabels:
+      run: mc-stable
+  template:
+    metadata:
+      labels:
+        run: mc-stable
+    spec:
+      securityContext:
+        runAsUser: 1000
+        fsGroup: 1000
+      containers:
+      - image: itzg/minecraft-server
+        name: mc-stable
+        env:
+        - name: EULA
+          value: "TRUE"
+        ports:
+        - containerPort: 25565
+        volumeMounts:
+        - name: data
+          mountPath: /data
+      volumes:
+      - name: data
+        persistentVolumeClaim:
+          claimName: mc-stable
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: mc-snapshot
+  annotations:
+    "mc-router.itzg.me/externalServerName": "snapshot.your.domain"
+spec:
+  ports:
+  - port: 25565
+  selector:
+    run: mc-snapshot
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    run: mc-snapshot
+  name: mc-snapshot
+spec:
+  selector:
+    matchLabels:
+      run: mc-snapshot
+  template:
+    metadata:
+      labels:
+        run: mc-snapshot
+    spec:
+      securityContext:
+        runAsUser: 1000
+        fsGroup: 1000
+      containers:
+      - image: itzg/minecraft-server
+        name: mc-snapshot
+        env:
+        - name: EULA
+          value: "TRUE"
+        - name: VERSION
+          value: "SNAPSHOT"
+        ports:
+        - containerPort: 25565
+        volumeMounts:
+        - name: data
+          mountPath: /data
+      volumes:
+      - name: data
+        persistentVolumeClaim:
+          claimName: mc-snapshot

docs/k8s-example.yaml

@@ -1,5 +1,32 @@
 ---
 apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: mc-router
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: services-watcher
+rules:
+- apiGroups: [""]
+  resources: ["services"]
+  verbs: ["watch","list"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: mc-router-services-watcher
+subjects:
+- kind: ServiceAccount
+  name: mc-router
+  namespace: default
+roleRef:
+  kind: ClusterRole
+  name: services-watcher
+  apiGroup: rbac.authorization.k8s.io
+---
+apiVersion: v1
 kind: Service
 metadata:
   name: mc-router
@@ -27,15 +54,18 @@ spec:
   selector:
     matchLabels:
       run: mc-router
+  strategy:
+    type: Recreate
   template:
     metadata:
       labels:
         run: mc-router
     spec:
+      serviceAccountName: mc-router
       containers:
-      - image: itzg/mc-router:1.0.1
+      - image: itzg/mc-router:1.1.1
         name: mc-router
-        args: ["--api-binding", ":8080"]
+        args: ["--api-binding", ":8080", "--in-kube-cluster"]
         ports:
         - name: proxy
           containerPort: 25565
@@ -46,6 +76,8 @@ apiVersion: v1
 kind: Service
 metadata:
   name: mc-stable
+  annotations:
+    "mc-router.itzg.me/externalServerName": "mc.your.domain"
 spec:
   ports:
   - port: 25565
@@ -90,6 +122,8 @@ apiVersion: v1
 kind: Service
 metadata:
   name: mc-snapshot
+  annotations:
+    "mc-router.itzg.me/externalServerName": "mc-snapshot.your.domain"
 spec:
   ports:
   - port: 25565