add some new sections for README.md

README.md

@@ -6,6 +6,12 @@ By default, the image is pulled from [WebSpellChecker Docker Hub](https://hub.do
 however, many users would require building their own local images with custom configuration. 
 Please refer to [our other repository](https://github.com/WebSpellChecker/wproofreader-docker/) to get started with building your own docker image.
 
+## Pre-requisites
+
+To deploy WProofreader service on a Kubernetes cluster, a machine with 
+`kubectl` tool configured to communicate with your cluster, see [here](https://kubernetes.io/docs/tasks/tools/), and
+Helm executable itself is required (see [here](https://helm.sh/docs/intro/quickstart/#install-helm)).
+
 ## Basic installation
 
 The chart uses `nodeAffinity` for mounting Persistent Volume of type `local`.
@@ -59,6 +65,13 @@ There are three ways the service can be activated:
 ```
 provided that `LICENSE_TICKET_ID` is set in your environment.
 
+IMPORTANT: unactivated images (e.g. those from WebSpellChecker Docker Hub) 
+will require new activation each time the container is started. Due to the limit 
+on activation attempts for each license (25 by default), it might fail eventually 
+and one would have to contact WebSpellChecker Support Team for a reset. 
+It is therefore not recommended to use unactivated images with License ID CLI flags
+for production, only for testing, development, and evaluation purposes.
+
 ## HTTPS
 
 By default, the server is set to communicate via HTTP, which is fine for 
@@ -126,3 +139,43 @@ so that it's not overwritten with the (empty) value from `values.yaml`.
 Please make sure that all values arguments passed as `--set` CLI arguments 
 were duplicated with your latest `helm upgrade` call, or simply use `--reuse-values` flag. 
 Otherwise, they are overwritten with the contents of `values.yaml`.
+
+## Example manifests
+
+For illustration purposes, Kubernetes manifests generated by Helm 
+(with Helm labels removed) are provided in the `manifests` folder. 
+The generator command used was:
+```shell
+helm template --namespace wsc wsc-app-sample wproofreader \
+  --set licenseTicketID=qWeRtY123 \
+  --set useHTTPS=true \
+  --set certFile=cert.pem \
+  --set keyFile=key.pem \
+  --set dictionaries.localPath=/var/local/dictionaries \
+  > manifests/manifests.yaml
+```
+
+## Troubleshooting
+
+A service might fail to start up properly if misconfigured. For troubleshooting, 
+it could be beneficial to get the full configuration that was attempted to be deployed,
+which later can be studied or shared with a developer or WebSpellChecker Support Team. 
+
+There are two ways one could go about achieving this. First would be to query 
+the values (user-configurable options) that Helm uses to generate Kubernetes manifests:
+```shell
+helm get values --all --namespace wsc wsc-app-5-25-0 > wsc-app-5-25-0-values.yaml
+```
+where `wsc` is the namespace and `wsc-app-5-25-0` – the name of your release, 
+and `wsc-app-5-25-0-values.yaml` – name of the file the data will be written to.
+
+Second option is to get the full Kubernetes manifests themselves. Similarly:
+```shell
+helm get manifest --namespace wsc wsc-app-5-25-0 > manifests.yaml
+```
+
+If, for any reason, you do not have access to `helm`, same can be accomplished using 
+`kubectl`. To get manifests for all resources in `wsc` namespace, use:
+```shell
+kubectl get all --namespace wsc -o yaml > manifests.yaml
+```

manifests/deployment.yaml

@@ -0,0 +1,83 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: wsc-app-sample-wproofreader
+  labels:
+    app.kubernetes.io/name: wproofreader
+    app.kubernetes.io/instance: wsc-app-sample
+    app.kubernetes.io/version: "5.25.0"
+spec:
+  replicas: 1
+  strategy:
+    rollingUpdate:
+      maxSurge: 25%
+      maxUnavailable: 25%
+    type: RollingUpdate
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: wproofreader
+      app.kubernetes.io/instance: wsc-app-sample
+  template:
+    metadata:
+      annotations:
+        checksum/secrets: 3d370016ca764dcc4fbace6c41ec622b592a9cd42d3da47118149693c2b2b5e0
+      labels:
+        app.kubernetes.io/name: wproofreader
+        app.kubernetes.io/instance: wsc-app-sample
+    spec:
+      serviceAccountName: wsc-app-sample-wproofreader
+      securityContext:
+        fsGroup: 2000
+      containers:
+        - name: wproofreader
+          securityContext:
+            {}
+          image: "webspellchecker/wproofreader:5.25.0"
+          imagePullPolicy: IfNotPresent
+          ports:
+            - name: container-port
+              containerPort: 8443
+              protocol: TCP
+          livenessProbe:
+            httpGet:
+              path: /wscservice
+              port: container-port
+              scheme: HTTPS
+          readinessProbe:
+            httpGet:
+              path: "/wscservice/api?cmd=ver"
+              port: container-port
+              scheme: HTTPS
+          resources:
+            {}
+          volumeMounts:
+            - mountPath: /certificate
+              name: tls-secret-volume
+            - mountPath: /dictionaries
+              name: dictionaries-volume
+          env:
+            - name: PROTOCOL
+              value: "1"
+            - name: WEB_PORT
+              value: "443"
+            - name: VIRTUAL_DIR
+              value: wscservice
+            - name: LICENSE_TICKET_ID
+              valueFrom:
+                secretKeyRef:
+                  name: wsc-app-sample-wproofreader-lic
+                  key: license
+      volumes:
+        - name: tls-secret-volume
+          secret:
+            secretName: wsc-app-sample-wproofreader-cert
+        - name: dictionaries-volume
+          persistentVolumeClaim:
+            claimName: wsc-app-sample-wproofreader-dict
+      affinity:
+        nodeAffinity:
+          requiredDuringSchedulingIgnoredDuringExecution:
+            nodeSelectorTerms:
+              - matchExpressions:
+                  - key: proofreader.company-domain.com/app
+                    operator: Exists

manifests/secrets.yaml

@@ -0,0 +1,24 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: wsc-app-sample-wproofreader-lic
+  labels:
+    app.kubernetes.io/name: wproofreader
+    app.kubernetes.io/instance: wsc-app-sample
+    app.kubernetes.io/version: "5.25.0"
+type: Opaque
+data:
+  license: "cVdlUnRZMTIz"
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: wsc-app-sample-wproofreader-cert
+  labels:
+    app.kubernetes.io/name: wproofreader
+    app.kubernetes.io/instance: wsc-app-sample
+    app.kubernetes.io/version: "5.25.0"
+type: Opaque
+data:
+  cert.pem: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVnRENDQXVpZ0F3SUJBZ0lSQU1DVFFQSUFadERzNW94R25YRWEwd1l3RFFZSktvWklodmNOQVFFTEJRQXcKZ2FzeEhqQWNCZ05WQkFvVEZXMXJZMlZ5ZENCa1pYWmxiRzl3YldWdWRDQkRRVEZBTUQ0R0ExVUVDd3czWVc1MApiMjR1YjNaamFHRnlaVzVyYjBCM2IzSnJMV052YlhCMWRHVnlMbXh2WTJGc0lDaEJiblJ2YmlCUGRtTm9ZWEpsCmJtdHZLVEZITUVVR0ExVUVBd3crYld0alpYSjBJR0Z1ZEc5dUxtOTJZMmhoY21WdWEyOUFkMjl5YXkxamIyMXcKZFhSbGNpNXNiMk5oYkNBb1FXNTBiMjRnVDNaamFHRnlaVzVyYnlrd0hoY05Nakl4TVRFM01qQXlNVEkwV2hjTgpNalV3TWpFM01qQXlNVEkwV2pCck1TY3dKUVlEVlFRS0V4NXRhMk5sY25RZ1pHVjJaV3h2Y0cxbGJuUWdZMlZ5CmRHbG1hV05oZEdVeFFEQStCZ05WQkFzTU4yRnVkRzl1TG05MlkyaGhjbVZ1YTI5QWQyOXlheTFqYjIxd2RYUmwKY2k1c2IyTmhiQ0FvUVc1MGIyNGdUM1pqYUdGeVpXNXJieWt3Z2dFaU1BMEdDU3FHU0liM0RRRUJBUVVBQTRJQgpEd0F3Z2dFS0FvSUJBUURWNXVhZDlqS0lIRXlnTG95RFdtVFlhNDhDbWVxTE5MU3hLdG1vSXFSMXUvSERRUE1RCnpQNncvb3pjd0U2aE1tZ3Y0Qjd5Z0MwcEIxTTlLVjA5TkFoNnJGZGVwdjFJYlNWRVNQVnV5WXcyVUVLNVYzLzQKL2dDWnMxamJGNXJRWmV3a1RYblVQMjVwOVRlMEp0YUZvSUhxb3YwTFRudEpUc3Z5bXZJK1g5QUFNNTlnUDc0Qwo4ZEQydlFVYUI1d1pnVnAxc3VjVmw2UFRLanFqSFJkQ1owYTlmcFNuT3NBZ3hIOVVsRG11UVk5WTdvblZOQ3YrCjhzQnlwUnBjOVdqeVhFakIrSDdzNE81Q2U1ejBqbXVnYXlUczdaaklmVFlwcmdkdFozNGVxUnQ4NHoreWZCTXAKY281SCtpVDVPdmtVREV2UlJvTHNNbDN4ZWZOb2tLUkRLUm81QWdNQkFBR2pYakJjTUE0R0ExVWREd0VCL3dRRQpBd0lGb0RBVEJnTlZIU1VFRERBS0JnZ3JCZ0VGQlFjREFUQWZCZ05WSFNNRUdEQVdnQlRsY3FhaTNLa1owSW56CmptNjY0MjN2TnNMcnlqQVVCZ05WSFJFRURUQUxnZ2xzYjJOaGJHaHZjM1F3RFFZSktvWklodmNOQVFFTEJRQUQKZ2dHQkFIdkdMUFJyVlhYcmNVUWFuZlJkZ050MXdUZU1mYkxoS3g2TW9JKzBzaHdLZlF3ZTNlQXRWeUtyRHFSRgpMcCtIQ1d2cHZaTVREZnFxWHFVTkFwdEt6TjNKTHlUNHkwTXpXRTZQRXh1ZFBFNEtMaHhMK3RWSDVqY2VkWE84CisvN3JHUlNHMVpOb0pJam0yVDE1K3FuNmtnMjQvM1QwUmhxQlhmRGVTRTdtQno3Q1loMWNzN2VLb3lVYUtGVGwKUXNzSy9lQmxkbkxlMEsxSkE5UzN3TVNGVWFUanpnLytBLzNaaHJxRXpLVjdEL1FjWFVzL2JkSUJaa05VOHowUApJZ0hYU1QyMGc2V0RMMXJ6OTMyV2tHelQwN25YQWxzTVZLTC9STGI4bUtEMXl1UU5jZzAzNENjcTAwZFJkWXY2CjJvcExMZE8xRm5RTkVSd0t1OC9TNnBEZkhIU2p1NFlDUXFueXBnRDc5aHRubHZwR1JHWHRiUDgvM2xIay9iZW4KVDlmMVFZMTlneTVlMThpTXp4YktJN1pqOXNjS0hxVFczN0FXVDRnOFV5YTUrQTBRME14SGJXcW5ZRnJyR0N0awpQelVPTmgwOG9xYUNuR2V5aCtzd0JXY3hxY1Uwa3kzaHdmajJjWDliaFdLMlMwaDVLUmRaenNtcThoTTBNbXZwCjBBSko1UT09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K"
+  key.pem: "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2d0lCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktrd2dnU2xBZ0VBQW9JQkFRRFY1dWFkOWpLSUhFeWcKTG95RFdtVFlhNDhDbWVxTE5MU3hLdG1vSXFSMXUvSERRUE1RelA2dy9vemN3RTZoTW1ndjRCN3lnQzBwQjFNOQpLVjA5TkFoNnJGZGVwdjFJYlNWRVNQVnV5WXcyVUVLNVYzLzQvZ0NaczFqYkY1clFaZXdrVFhuVVAyNXA5VGUwCkp0YUZvSUhxb3YwTFRudEpUc3Z5bXZJK1g5QUFNNTlnUDc0QzhkRDJ2UVVhQjV3WmdWcDFzdWNWbDZQVEtqcWoKSFJkQ1owYTlmcFNuT3NBZ3hIOVVsRG11UVk5WTdvblZOQ3YrOHNCeXBScGM5V2p5WEVqQitIN3M0TzVDZTV6MApqbXVnYXlUczdaaklmVFlwcmdkdFozNGVxUnQ4NHoreWZCTXBjbzVIK2lUNU92a1VERXZSUm9Mc01sM3hlZk5vCmtLUkRLUm81QWdNQkFBRUNnZ0VCQUxlQXFqR3poM0JMVHRWUWVjMHFIRCtxTG5yZHpsLzBMRnVkVmpLdTNZWC8KWVkzUFIzY1BWaVJEakZiSlIrdDBVZnRZZTFRdzhBMDFzb3hTMHlGeFpTRFFmdmU5ckthWXRCTGJ3R3AxejZxOAp1akZFeG8yMllvOTVVKzVKVnRBWDBEam9tbTZpcURlUVhtUlh1VXZVQWdCb0tVdXMzWWxyWnYzUFBhaVRDOTlPCjEwT21HUVA5OXcyL1AvSDd5LzVGa1o2SzBhMUV6NG9qVmlCM0VrRVJzSUtkSFBkaGp6YkhWa2ZzbUNVN2lWZDgKSG12cyt0VG1DSDh1WkUvYXhjbEVZNE5GTDlYbTdRdll5TkFCekxQNUVYOVlROElFSkV0bnduQlV2aVVmTEpPcwpmSzN6czN2WFdVZktJUy9IaUpzVW5zd1dxRThjSkRLMk5FWFRINXh5OXdFQ2dZRUExNzdjUHd6M0Q2K1pQS1RKCnd4M3ljS042N1lua20xVnhnSUFBc2ZlbzhNNk1SY0dFSjBESGdJU0VIa0xpcEZUdUNUMUVvcEswS3NhaDBDMXMKODRZRVNpTDE4ZHk4bWlXcDdQdWtzcWRLR1hteHh1TFp2Unl3N1JkV2crVGh6QXBlSXcyYmRDUTEzSTcwdjQ5awpsQU5SK1N0QjJsWU44NEVJNUcxS0RHL1ZaV0VDZ1lFQS9jLzdHOHg3R1RzTnoyczlPbnRwaWxlemUySHZMYlNXCjRaalFENWtwSHhzVEFMWGRaY3lRNGJGM0lBaGVzVHJLS0wzekI4RXRmN2NISE1CelQyei9wTGp1NllSd1VaclEKYXllZEJOK0RaZm9WenZ0TWp1Qnl0ZStDOTVFelRXQlVTaktpSzdTci9FQWV2V3BZRzNzMHBLWndpSTlHR1lPZgpjcFNKdE9qTEM5a0NnWUVBa1VwNGVvR1p0RmVXUTgvYURHdVRoS1dqdUdwL3FOZyt5c0hwTmZES05mbHpYOXExCnk5V0ZSUmg0L1FRZ0sza0NvUGhBeTVjdWZBd3Vsc3F3cjhOV0NqTkhIQzJDV2ZENVlaNEtTVUg5MWZBdGQvbjMKbHJMR3Q3UmEwQklJdWVkVmhCZTYwOWs2NktEaFZFd1YrTlBQbFpTN0VYV1lpWjhoUk93UXpSVlhTYUVDZ1lFQQp2VCt3dXArVFFkTFlqMG9rMDFCbDkzTkJMc1J0TktVc3czWFAzWEdVU2M5RU1nbG8xWmpjaG94dWlJSDFLU3p1Cnc4WXVTaC91THdabjFUWmlSRnkvbVRFVFl5Y1BJS25Rc2JWTnpPNWo2VXU1cXlXUmhnOHhPUnNuaWpUSURlKy8KcWJ0clZDOVk5Yk5SdUdaczM4RFVGZGpNbStaSW5JbWFBRE5sSW5GWnhMRUNnWUE5VjhBclhObFFzbExiNlQwTwpaZWw2aVNod01QT2Z4NTVaeVRmQ2k1YWtMSlNyUTBRc3NBbmJ6TTFQN2VEdzRrVXU4ZTFINTdJSjN2T2gyNlJQCno1QVM4MTk4WkRKN2JFMEFUOXAzU3VhcHdxRFVxVm1keHh4endYZjVYNXJtNXgvUllubjBwQUUzdFVYUXlzSFIKS1g2YXhhY0ZXcjdMaS9PcnVML0xEWVY2Nmc9PQotLS0tLUVORCBQUklWQVRFIEtFWS0tLS0tCg=="

manifests/service.yaml

@@ -0,0 +1,17 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: wsc-app-sample-wproofreader
+  labels:
+    app.kubernetes.io/name: wproofreader
+    app.kubernetes.io/instance: wsc-app-sample
+    app.kubernetes.io/version: "5.25.0"
+spec:
+  type: ClusterIP
+  ports:
+    - port: 443
+      targetPort: container-port
+      protocol: TCP
+  selector:
+    app.kubernetes.io/name: wproofreader
+    app.kubernetes.io/instance: wsc-app-sample

manifests/serviceaccount.yaml

@@ -0,0 +1,8 @@
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: wsc-app-sample-wproofreader
+  labels:
+    app.kubernetes.io/name: wproofreader
+    app.kubernetes.io/instance: wsc-app-sample
+    app.kubernetes.io/version: "5.25.0"

manifests/volumes.yaml

@@ -0,0 +1,39 @@
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: wsc-app-sample-wproofreader-dict
+  labels:
+    app.kubernetes.io/name: wproofreader
+    app.kubernetes.io/instance: wsc-app-sample
+    app.kubernetes.io/version: "5.25.0"
+spec:
+  storageClassName: standard
+  capacity:
+    storage: 20Gi
+  volumeMode: Filesystem
+  accessModes:
+    - ReadWriteMany
+  local:
+    path: /var/local/dictionaries
+  nodeAffinity:
+    required:
+      nodeSelectorTerms:
+        - matchExpressions:
+            - key: proofreader.company-domain.com/app
+              operator: Exists
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: wsc-app-sample-wproofreader-dict
+  labels:
+    app.kubernetes.io/name: wproofreader
+    app.kubernetes.io/instance: wsc-app-sample
+    app.kubernetes.io/version: "5.25.0"
+spec:
+  storageClassName: standard
+  accessModes:
+    - ReadWriteMany
+  resources:
+    requests:
+      storage: 20Gi