Skip to content

Commit c97d083

Browse files
solovyovksolovyovk
authored
Promoted Helm chart version to 1.0.0 (#2)
* Promoted Helm chart version to 1.0.0
1 parent 0cbc1bc commit c97d083

16 files changed

Lines changed: 374 additions & 119 deletions

‎README.md‎

Lines changed: 102 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -15,39 +15,23 @@ Before you begin, make sure you have the required environment:
1515

1616
## Basic installation
1717

18-
The chart uses `nodeAffinity` for mounting Persistent Volume of type `local`.
19-
This also allows the user to specify which node will host the WProofreader Server
20-
on a cluster (even a single-node one).
21-
22-
To assign this role to a node, one has to attach a label to it. It can be whatever you want it to be,
23-
e.g. `proofreader.your-company.com/app`:
24-
```shell
25-
kubectl label node <name-of-the-node> proofreader.company-domain.com/app=
26-
```
27-
Note that `=` is required, but the value after it is not important (empty in this example).
28-
29-
Keep in mind that your custom label has to be either updated in `values.yaml`
30-
(`affinityLabel` key, recommended), or passed to `helm` calls using
31-
`--set affinityLabel=proofreader.company-domain.com/app`.
32-
33-
Now, the chart can be installed the usual way using all the defaults:
18+
The Chart can be installed the usual way using all the defaults:
3419
```shell
3520
git clone https://github.com/WebSpellChecker/wproofreader-helm.git
3621
cd wproofreader-helm
37-
helm install --create-namespace --namespace wsc wsc-app-5-x-x wproofreader --set affinityLabel=proofreader.company-domain.com/app
22+
helm install --create-namespace --namespace wsc wproofreader-app wproofreader
3823
```
39-
where `wsc` is the namespace the app should be installed to,
40-
`wsc-app-5-25-0` – the release name, where we specifically mention the product version 5.25.0,
41-
`wproofreader` – local chart directory,
42-
`--set affinityLabel=proofreader.company-domain.com/app` – optional affinity label, see previous paragraph.
24+
where `wsc` is the namespace where the app should be installed,
25+
`wproofreader-app` is the Helm release name,
26+
`wproofreader` is the local Chart directory.
4327

4428
API requests should be sent to the Kubernetes Service instance, reachable at
4529
```text
4630
http(s)://<service-name>.<namespace>.svc:<service-port>
4731
```
4832
where
4933
- `http` or `https` depends on the protocol used;
50-
- `<service-name>` is the name of the Service instance, which would be `wsc-app-5-25-0-wproofreader` with the above
34+
- `<service-name>` is the name of the Service instance, which would be `wproofreader-app` with the above
5135
command, unless overwritten using `fullnameOverride` `values.yaml` parameter;
5236
- `<namespace>` is the namespace where the chart was installed;
5337
- `.svc` can be omitted in most cases, but is recommended to keep;
@@ -88,30 +72,102 @@ The defaults for the DockerHub image are `cert.pem`, `key.pem`, and `/certificat
8872

8973
## Custom dictionaries
9074

91-
To allow WProofreader Server to use your custom dictionaries, you have to do the following:
92-
1. Upload the files to some directory on the node, where the chart will be deployed
93-
(remember, it's the one with the `proofreader.company-domain.com/app` label).
75+
To enable WProofreader Server to use your custom dictionaries, follow these steps:
76+
1. Upload the files to a directory on the node where the chart will be deployed.
77+
Ensure this node has `wproofreader.domain-name.com/app` label.
9478
2. Set `dictionaries.localPath` parameter to the absolute path of this directory.
9579
3. Optionally, edit `dictionaries.mountPath` value if non-default one was used in `Dockerfile`,
9680
as well as other `dictionaries` parameters if needed.
97-
4. Install the chart normally.
81+
4. Install the chart as usual.
82+
83+
The Chart uses `nodeAffinity` for mounting Persistent Volume of type `local`.
84+
This allows the user to specify which node will host WProofreader Server
85+
on a cluster, even a single-node one.
9886

87+
To assign this role to a node, you need to attach a label to it. It can be any label you choose,
88+
e.g. `wproofreader.domain-name.com/app`:
89+
```shell
90+
kubectl label node <name-of-the-node> wproofreader.domain-name.com/app=
91+
```
92+
Note that `=` is required but the value after it is not important (empty in this example).
93+
94+
Keep in mind that your custom label has to be either updated in `values.yaml`
95+
(`nodeAffinityLabel` key, recommended), or passed to `helm` calls using
96+
`--set nodeAffinityLabel=wproofreader.domain-name.com/app`.
97+
98+
To install the Chart with custom dictionaries feature enabled and the local path set to the directory on the node where dictionaries are stored:
99+
```shell
100+
helm install --create-namespace --namespace wsc wproofreader-app wproofreader --set nodeAffinityLabel=wproofreader.domain-name.com/app --set dictionaries.enabled=true --set dictionaries.localPath=/dictionaries
101+
```
99102
The dictionary files can be uploaded after the chart installation, but the `dictionaries.localPath`
100-
folder has to exist on the node beforehand.
101-
Dictionaries can be uploaded to the node VM either the usual way (`scp`, `rsync`, `FTP` etc), or
102-
using `kubectl cp` command. With `kubectl cp` we have to use one of pods of the deployment.
103-
Once the files are uploaded, they will appear on all the pods automatically, and will persist
104-
if any or all the pods are restarted. The workflow for this would look something like this:
105-
1. Get the name of one of the pods. For the Helm release named `wsc-app-5-25-0` installed in the `wsc` namespace, we can use
103+
folder must exist on the node beforehand.
104+
Dictionaries can be uploaded to the node VM using standard methods (`scp`, `rsync`, `FTP` etc) or
105+
the `kubectl cp` command. With `kubectl cp`, you need to use one of the deployment's pods.
106+
Once uploaded, the files will automatically appear on all pods and persist
107+
even if the pods are restarted. Follow these steps:
108+
1. Get the name of one of the pods. For the Helm release named `wproofreader-app` in the `wsc` namespace, use
106109
```shell
107-
POD=$(kubectl get pods -n wsc -l app.kubernetes.io/instance=wsc-app-5-25-0 -o jsonpath="{.items[0].metadata.name}")
110+
POD=$(kubectl get pods -n wsc -l app.kubernetes.io/instance=wproofreader-app -o jsonpath="{.items[0].metadata.name}")
108111
```
109112
2. Upload the files to the pod
110113
```shell
111114
kubectl cp -n wsc <local path to files> $POD:/dictionaries
112115
```
113-
where `/dictionaries` should be changed to whatever non-default `dictionaries.mountPath` value was used if applicable.
116+
Replace `/dictionaries` with your custom `dictionaries.mountPath` value if applicable.
114117

118+
There is also a way in the Chart to specify an already existing Persistent Volume Claim (PVC) with dictionaries that can be configured to operate on multiple nodes (e.g., NFS). To do this, enable the custom dictionary feature by setting the `dictionaries.enabled` parameter to `true` and specifying the name of the existing PVC in the `dictionaries.existingClaim` parameter.
119+
120+
**Recommended approach:** Using an existing PVC is the recommended way because it ensures that your data will persist even if the Chart is uninstalled. This approach offers a reliable method to maintain data integrity and availability across deployments.
121+
122+
However, please note that provisioning the Persistent Volume (PV) and PVC for storage backends like NFS is outside the scope of this Chart. You will need to provision the PV and PVC separately according to your storage backend's documentation before using the `dictionaries.existingClaim` parameter.
123+
124+
## Use in production
125+
126+
For production deployments, it is highly recommended **to specify resource requests and limits for your Kubernetes pods**. This helps ensure that your applications have the necessary resources to run efficiently while preventing them from consuming excessive resources on the cluster which can impact other applications.
127+
This can be configured in the `values.yaml` file under the `resources` section.
128+
129+
### Recommended resource requests and limits
130+
131+
Below are the recommended resource requests and limits for deploying WProofreader Server v5.34.x with enabled English dialects (en_US, en_GB, en_CA, and en_AU) for spelling & grammar check using the English AI language model for enhanced and more accurate proofreading. It also includes such features as a style guide, spelling autocorrect, named-entity recognition (NER), and text autocomplete suggestions (text prediction). These values represent the minimum requirements for running WProofreader Server in a production environment.
132+
133+
**Note:** Depending on your specific needs and usage patterns, especially when deploying AI language models for enhanced proofreading in other languages, you may need to adjust these values to ensure optimal performance and resource utilization. Alternatively, you can choose the bare-minimum configuration without AI language models. In this case, only algorithmic engines will be used to provide basic spelling and grammar checks.
134+
135+
```yaml
136+
resources:
137+
requests:
138+
memory: "4Gi"
139+
cpu: "1"
140+
limits:
141+
memory: "8Gi"
142+
cpu: "4"
143+
```
144+
145+
### Readiness and liveness probes
146+
147+
The Helm chart includes readiness and liveness probes to help Kubernetes manage the lifecycle of the WProofreader Server pods. These probes are used to determine when the pod is ready to accept traffic and when it should be restarted if it becomes unresponsive.
148+
149+
You may thoughtfully modify the Chart default values based on your environment's resources and application needs in the `values.yaml` file under the `readinessProbeOptions` and `livenessProbeOptions` sections.
150+
Example:
151+
```yaml
152+
readinessProbeOptions:
153+
initialDelaySeconds: 10
154+
periodSeconds: 10
155+
timeoutSeconds: 5
156+
successThreshold: 1
157+
failureThreshold: 3
158+
```
159+
160+
### Application scaling
161+
WProofreader Server can be scaled horizontally by changing the number of replicas.
162+
This can be done by setting the `replicaCount` parameter in the `values.yaml` file.
163+
The default value is `1`. For example, to scale the application to 3 replicas, set the `--set replicaCount=3` flag when installing the Helm chart.
164+
165+
For dynamic scaling based on resource utilization, you can use Kubernetes Horizontal Pod Autoscaler (HPA).
166+
To use the HPA, you need to turn on the metrics server in your Kubernetes cluster. The HPA will then automatically change the number of pods in a deployment based on how much CPU is being used.
167+
The HPA is not enabled by default in the Helm chart. To enable it, set the `autoscaling.enabled` parameter to `true` in the `values.yaml` file.
168+
169+
**Important Note:** WProofreader Server can be scaled only based on CPU usage metric. The `targetMemoryUtilizationPercentage` is not supported.
170+
115171
## Common issues
116172
### Readiness probe failed
117173

@@ -141,7 +197,7 @@ Otherwise, they are overwritten with the contents of `values.yaml`.
141197
For illustration purposes, please find exported Kubernetes manifests in the `manifests` folder.
142198
If you need to export the manifest files from this sample Helm Chart, please use the following command:
143199
```shell
144-
helm template --namespace wsc wsc-app-sample wproofreader \
200+
helm template --namespace wsc wproofreader-app wproofreader \
145201
--set licenseTicketID=qWeRtY123 \
146202
--set useHTTPS=true \
147203
--set certFile=cert.pem \
@@ -154,21 +210,25 @@ helm template --namespace wsc wsc-app-sample wproofreader \
154210

155211
The service might fail to start up properly if misconfigured. For troubleshooting, it can be beneficial to get the full configuration you attempted to deploy. If needed, later it can be shared with the support team for further investigation.
156212

157-
There are several options for how to gather needed details:
213+
There are several ways to gather necessary details:
158214
1. Get the values (user-configurable options) used by Help to generate Kubernetes manifests:
159215
```shell
160-
helm get values --all --namespace wsc wsc-app-5-25-0 > wsc-app-5-25-0-values.yaml
216+
helm get values --all --namespace wsc wproofreader-app > wproofreader-app-values.yaml
161217
```
162-
where `wsc` is the namespace and `wsc-app-5-25-0` – the name of your release,
163-
and `wsc-app-5-25-0-values.yaml` – name of the file the data will be written to.
218+
where `wsc` is the namespace and `wproofreader-app` – the name of your release,
219+
and `wproofreader-app-values.yaml` – name of the file the data will be written to.
164220

165221
2. Extract the full Kubernetes manifest(s) as follows:
166222
```shell
167-
helm get manifest --namespace wsc wsc-app-5-25-0 > manifests.yaml
223+
helm get manifest --namespace wsc wproofreader-app > manifests.yaml
168224
```
169225

170-
If, for any reason, you do not have access to `helm`, same can be accomplished using
171-
`kubectl`. To get manifests for all resources in `wsc` namespace, use:
226+
If you do not have access to `helm`, same can be accomplished using
227+
`kubectl`. To get manifests for all resources in the `wsc` namespace, run:
172228
```shell
173229
kubectl get all --namespace wsc -o yaml > manifests.yaml
230+
```
231+
3. Retrieve the logs of all `wsproofreader-app` pods in the `wsc` namespace:
232+
```shell
233+
kubectl logs -n wsc -l app.kubernetes.io/instance=wproofreader-app
174234
```

‎manifests/deployment_http.yaml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
apiVersion: apps/v1
2+
kind: Deployment
3+
metadata:
4+
name: wproofreader-app
5+
labels:
6+
helm.sh/chart: wproofreader-1.0.0
7+
app.kubernetes.io/name: wproofreader
8+
app.kubernetes.io/instance: wproofreader-app
9+
app.kubernetes.io/version: "5.34.3"
10+
app.kubernetes.io/managed-by: Helm
11+
spec:
12+
replicas: 1
13+
strategy:
14+
rollingUpdate:
15+
maxSurge: 25%
16+
maxUnavailable: 25%
17+
type: RollingUpdate
18+
selector:
19+
matchLabels:
20+
app.kubernetes.io/name: wproofreader
21+
app.kubernetes.io/instance: wproofreader-app
22+
template:
23+
metadata:
24+
annotations:
25+
checksum/secrets: 3dc935bf0e71c4a7d9f2b3cf2c9743c0ad...
26+
labels:
27+
app.kubernetes.io/name: wproofreader
28+
app.kubernetes.io/instance: wproofreader-app
29+
spec:
30+
serviceAccountName: wproofreader-app
31+
securityContext:
32+
fsGroup: 2000
33+
containers:
34+
- name: wproofreader
35+
securityContext:
36+
{}
37+
image: "webspellchecker/wproofreader:5.34.3"
38+
imagePullPolicy: IfNotPresent
39+
ports:
40+
- name: container-port
41+
containerPort: 8080
42+
protocol: TCP
43+
livenessProbe:
44+
httpGet:
45+
path: /wscservice
46+
port: container-port
47+
scheme: HTTP
48+
readinessProbe:
49+
httpGet:
50+
path: "/wscservice/api?cmd=status"
51+
port: container-port
52+
scheme: HTTP
53+
resources:
54+
{}
55+
volumeMounts:
56+
- mountPath: /dictionaries
57+
name: dictionaries-volume
58+
env:
59+
- name: PROTOCOL
60+
value: "2"
61+
- name: WEB_PORT
62+
value: "80"
63+
- name: VIRTUAL_DIR
64+
value: wscservice
65+
- name: LICENSE_TICKET_ID
66+
valueFrom:
67+
secretKeyRef:
68+
name: wproofreader-app-lic
69+
key: license
70+
volumes:
71+
- name: dictionaries-volume
72+
persistentVolumeClaim:
73+
claimName: wproofreader-app-dict
74+
affinity:
75+
nodeAffinity:
76+
requiredDuringSchedulingIgnoredDuringExecution:
77+
nodeSelectorTerms:
78+
- matchExpressions:
79+
- key: wproofreader.domain-name.com/app
80+
operator: Exists

manifests/deployment.yaml renamed to manifests/deployment_https.yaml

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
apiVersion: apps/v1
22
kind: Deployment
33
metadata:
4-
name: wsc-app-sample-wproofreader
4+
name: wproofreader-app
55
labels:
6+
helm.sh/chart: wproofreader-1.0.0
67
app.kubernetes.io/name: wproofreader
7-
app.kubernetes.io/instance: wsc-app-sample
8-
app.kubernetes.io/version: "5.25.0"
8+
app.kubernetes.io/instance: wproofreader-app
9+
app.kubernetes.io/version: "5.34.3"
10+
app.kubernetes.io/managed-by: Helm
911
spec:
1012
replicas: 1
1113
strategy:
@@ -16,23 +18,23 @@ spec:
1618
selector:
1719
matchLabels:
1820
app.kubernetes.io/name: wproofreader
19-
app.kubernetes.io/instance: wsc-app-sample
21+
app.kubernetes.io/instance: wproofreader-app
2022
template:
2123
metadata:
2224
annotations:
23-
checksum/secrets: 3d370016ca764dcc4fbace6c41ec622b592a9cd42d3da47118149693c2b2b5e0
25+
checksum/secrets: 3d370016ca764dcc4fbace6c41e...
2426
labels:
2527
app.kubernetes.io/name: wproofreader
26-
app.kubernetes.io/instance: wsc-app-sample
28+
app.kubernetes.io/instance: wproofreader-app
2729
spec:
28-
serviceAccountName: wsc-app-sample-wproofreader
30+
serviceAccountName: wproofreader-app
2931
securityContext:
3032
fsGroup: 2000
3133
containers:
3234
- name: wproofreader
3335
securityContext:
3436
{}
35-
image: "webspellchecker/wproofreader:5.25.0"
37+
image: "webspellchecker/wproofreader:5.34.3"
3638
imagePullPolicy: IfNotPresent
3739
ports:
3840
- name: container-port
@@ -45,7 +47,7 @@ spec:
4547
scheme: HTTPS
4648
readinessProbe:
4749
httpGet:
48-
path: "/wscservice/api?cmd=ver"
50+
path: "/wscservice/api?cmd=status"
4951
port: container-port
5052
scheme: HTTPS
5153
resources:
@@ -65,19 +67,19 @@ spec:
6567
- name: LICENSE_TICKET_ID
6668
valueFrom:
6769
secretKeyRef:
68-
name: wsc-app-sample-wproofreader-lic
70+
name: wproofreader-app-lic
6971
key: license
7072
volumes:
7173
- name: tls-secret-volume
7274
secret:
73-
secretName: wsc-app-sample-wproofreader-cert
75+
secretName: wproofreader-app-cert
7476
- name: dictionaries-volume
7577
persistentVolumeClaim:
76-
claimName: wsc-app-sample-wproofreader-dict
78+
claimName: wproofreader-app-dict
7779
affinity:
7880
nodeAffinity:
7981
requiredDuringSchedulingIgnoredDuringExecution:
8082
nodeSelectorTerms:
8183
- matchExpressions:
82-
- key: proofreader.company-domain.com/app
83-
operator: Exists
84+
- key: wproofreader.domain-name.com/app
85+
operator: Exists

‎manifests/hpa.yaml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
apiVersion: autoscaling/v2
2+
kind: HorizontalPodAutoscaler
3+
metadata:
4+
name: wproofreader-app
5+
labels:
6+
helm.sh/chart: wproofreader-1.0.0
7+
app.kubernetes.io/name: wproofreader
8+
app.kubernetes.io/instance: wproofreader-app
9+
app.kubernetes.io/version: "5.34.3"
10+
app.kubernetes.io/managed-by: Helm
11+
spec:
12+
scaleTargetRef:
13+
apiVersion: apps/v1
14+
kind: Deployment
15+
name: wproofreader-app
16+
minReplicas: 1
17+
maxReplicas: 5
18+
metrics:
19+
- type: Resource
20+
resource:
21+
name: cpu
22+
target:
23+
type: Utilization
24+
averageUtilization: 80

0 commit comments

Comments
 (0)