improve our kubernetes example documentation (#1005)

* improve our kubernetes example documentation

and add support for prometheus metrics to our helm chart

NEXT_CHANGELOG.md

@@ -23,10 +23,18 @@ Description! And a link to a [reference](http://url)
 -->
 
 # [v0.9.0-rc.1] - (unreleased)
-## ❗ BREAKING ❗
-
 ## ❗ BREAKING ❗
 ## 🚀 Features ( :rocket: )
+
+### helm chart now supports prometheus metrics [PR #1005](https://github.com/apollographql/router/pull/1005)
+The router has supported exporting prometheus metrics for a while. This change updates our helm chart to enable router deployment prometheus metrics. 
+
+Configure by updating your values.yaml or by specifying the value on your helm install command line.
+
+e.g.: helm install --set router.configuration.telemetry.metrics.prometheus.enabled=true <etc...>
+
+Note: prometheus metrics are not enabled by default in the helm chart.
+
 ## 🐛 Fixes ( :bug: )
 ## 🛠 Maintenance ( :hammer_and_wrench: )
 ## 📚 Documentation ( :books: )

docs/source/containerization/kubernetes.mdx

@@ -5,9 +5,177 @@ description: Using router images with kubernetes
 
 import { Link } from 'gatsby';
 
+## Sample Kubernetes Configuration
+
+### Helm
+
+[Helm](https://helm.sh) is the package manager for kubernetes.
+
+There is a complete [helm chart definition](https://github.com/apollographql/router/tree/main/helm/chart/router) in the repo which illustrates how to use helm to deploy the router in kubernetes.
+
+Here's an example which would use helm to install the router:
+ - into namespace "router-deploy" (create namespace if it doesn't exist)
+ - with helm install name "router-test"
+ - with support for prometheus enabled
+
+You would run this command from "repo"/helm/chart directory.
+
+(where "repo" is the directory containing your checked out router github repository)
+
+```bash
+helm install --set router.configuration.telemetry.metrics.prometheus.enabled=true --set managedFederation.apiKey="REDACTED" --set managedFederation.graphRef="REDACTED" --create-namespace --namespace router-deploy router-test router --values router/values.yaml
+```
+
+Once executed, you can check the status of the helm deploy:
+
+```bash
+helm list --namespace router-deploy
+```
+
+### Kubernetes Configuration
+
+If you aren't familiar with helm, the following example illustrates how you could do the same thing manually or as a base for kustomize.
+
+Note: This example is generated using the helm template capability to generate the required kubernetes configuration from our helm chart. After generation, it is edited to remove the Helm management annotations.
+
+```yaml
+---
+# Source: router/templates/serviceaccount.yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: router-test
+  labels:
+    app.kubernetes.io/name: router
+    app.kubernetes.io/instance: router-test
+    app.kubernetes.io/version: "v0.9.0-rc.0"
+---
+# Source: router/templates/secret.yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: router-test
+  labels:
+    app.kubernetes.io/name: router
+    app.kubernetes.io/instance: router-test
+    app.kubernetes.io/version: "v0.9.0-rc.0"
+data:
+  managedFederationApiKey: "REDACTED"
+---
+# Source: router/templates/configmap.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: router-test
+  labels:
+    app.kubernetes.io/name: router
+    app.kubernetes.io/instance: router-test
+    app.kubernetes.io/version: "v0.9.0-rc.0"
+data:
+  configuration.yaml: |
+    server:
+      listen: 0.0.0.0:80
+    telemetry:
+      metrics:
+        prometheus:
+          enabled: true
+---
+# Source: router/templates/service.yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: router-test
+  labels:
+    app.kubernetes.io/name: router
+    app.kubernetes.io/instance: router-test
+    app.kubernetes.io/version: "v0.9.0-rc.0"
+spec:
+  type: ClusterIP
+  ports:
+    - port: 80
+      targetPort: http
+      protocol: TCP
+      name: http
+  selector:
+    app.kubernetes.io/name: router
+    app.kubernetes.io/instance: router-test
+---
+# Source: router/templates/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: router-test
+  labels:
+    app.kubernetes.io/name: router
+    app.kubernetes.io/instance: router-test
+    app.kubernetes.io/version: "v0.9.0-rc.0"
+  annotations:
+    prometheus.io/path: /plugins/apollo.telemetry/prometheus
+    prometheus.io/port: "80"
+    prometheus.io/scrape: "true"
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: router
+      app.kubernetes.io/instance: router-test
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: router
+        app.kubernetes.io/instance: router-test
+    spec:
+      serviceAccountName: router-test
+      securityContext:
+        {}
+      containers:
+        - name: router
+          securityContext:
+            {}
+          image: "ghcr.io/apollographql/router:v0.9.0-rc.0"
+          imagePullPolicy: IfNotPresent
+          args:
+            - --hot-reload
+            - --config
+            - /app/configuration.yaml
+          env:
+            - name: APOLLO_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: router-test
+                  key: managedFederationApiKey
+            - name: APOLLO_GRAPH_REF
+              value: "REDACTED"
+          ports:
+            - name: http
+              containerPort: 80
+              protocol: TCP
+          livenessProbe:
+            httpGet:
+              path: /.well-known/apollo/server-health
+              port: http
+          readinessProbe:
+            httpGet:
+              path: /.well-known/apollo/server-health
+              port: http
+          resources:
+            {}
+          volumeMounts:
+            - name: router-configuration
+              mountPath: /app/configuration.yaml
+              subPath: configuration.yaml
+              readOnly: true
+      volumes:
+        - name: router-configuration
+          configMap:
+            name: router-test
+```
+
 ## The health endpoint
 
-The router supports a health endpoint. If you have a router running on your localhost at port 4000, you can access it using curl as follows:
+The router supports a health endpoint. You can see from the examples above how it can be used in a kubernetes deployment.
+
+If you had a router running on port 4000 on your localhost, you could exercise the health endpoint as follows:
 
 ```bash
 curl "http://localhost:4000/.well-known/apollo/server-health"

helm/chart/router/Chart.yaml

@@ -15,10 +15,10 @@ type: application
 # This is the chart version. This version number should be incremented each time you make changes
 # to the chart and its templates, including the app version.
 # Versions are expected to follow Semantic Versioning (https://semver.org/)
-version: 0.1.1
+version: 0.1.2
 
 # This is the version number of the application being deployed. This version number should be
 # incremented each time you make changes to the application. Versions are not expected to
 # follow Semantic Versioning. They should reflect the version the application is using.
 # It is recommended to use it with quotes.
-appVersion: "v0.1.0-preview.7"
+appVersion: "v0.9.0-rc.0"

helm/chart/router/templates/deployment.yaml

@@ -4,6 +4,12 @@ metadata:
   name: {{ include "router.fullname" . }}
   labels:
     {{- include "router.labels" . | nindent 4 }}
+  {{- if .Values.router.configuration.telemetry.metrics.prometheus.enabled }}
+  annotations:
+    prometheus.io/path: /plugins/apollo.telemetry/prometheus
+    prometheus.io/port: "{{ .Values.containerPorts.http }}"
+    prometheus.io/scrape: "true"
+  {{- end }}
 spec:
   {{- if not .Values.autoscaling.enabled }}
   replicas: {{ .Values.replicaCount }}