Add vale (#1004)

.github/workflows/lint.yml

@@ -31,6 +31,9 @@ jobs:
       - name: Install Python requirements
         run: python3 -m pip install -r ./requirements.txt
 
+      - name: Check if vale is installed correctly
+        run: vale version
+
       - uses: pre-commit/[email protected]
         env:
           SKIP: no-commit-to-branch

.pre-commit-config.yaml

@@ -51,6 +51,10 @@ repos:
 
   - repo: local
     hooks:
+      - id: vale
+        name: "Vale: A linter for prose"
+        entry: ./scripts/vale.sh
+        language: script
       - id: svg-must-embed
         name: SVGs must embed all images
         entry: 'image[^>]* xlink:href="https'

CONTRIBUTING.md

@@ -30,9 +30,9 @@ Please observe a stable URL policy. This means:
 
 ## Code Snippets
 
-Code snippets should be written in a way that is transparent, predictable and flexible. They should be written with two roles in mind: devs and ops. Devs need commands that "mostly work", but need access to the underlying tools to select only the component they currently work on (e.g., Ansible `-t` or Helmfile `-l`). Ops need access to dry-run. Both these roles will be called "administrator" below.
+Code snippets should be written in a way that is transparent, predictable and flexible. They should be written with two roles in mind: contributors and platform administrators. Contributors need commands that "mostly work", but need access to the underlying tools to select only the component they currently work on (e.g., Ansible `-t` or Helmfile `-l`). Platform administrators need access to dry-run.
 
-- Separate pre-requisite installation snippets, config snippets (which includes init snippets), apply snippets and test snippets.
+- Separate pre-requisite installation snippets, configuration snippets (which includes init snippets), apply snippets and test snippets.
 - Apply snippets should not execute when copy-pasted, e.g., do not add a final newline. They should allow the administrator to review the command, potentially edit the command, before confirming execution by typing ENTER.
 - Apply snippets should be idempotent, i.e., running apply multiple times should give the same result as applying only once.
 - Avoid auto-approve in apply snippets. Encourage (but don't force) dry-running.
@@ -85,7 +85,7 @@ kubectl delete all --all --all-namespaces
 
 ## Diagrams
 
-### From diagrams.net (source of truth in this repo)
+### From diagrams.net (source of truth in this repository)
 
 Files ending in `*.drawio.svg` are produced using [diagrams.net](https://www.diagrams.net/). They are exported as follows:
 
@@ -107,7 +107,7 @@ Other diagrams are produced in graphviz. To regenerate them, edit the relevant `
 make -C docs/img
 ```
 
-For "live preview" open the output file (e.g., SVG or PNG) in a viewer supporting live refresh (e.g., eog), then type:
+For "live preview" open the output file (e.g., SVG or PNG) in a viewer supporting live refresh (e.g., `eog`), then type:
 
 ```bash
 make -C docs/img preview
@@ -117,7 +117,7 @@ The viewer's output should be updated live as you save the source `dot` file.
 
 ## Auto-generated documentation
 
-Welkin Apps config and secrets have auto-generated documentation from [the JSON schemas defined in it repository](https://github.com/elastisys/compliantkubernetes-apps/tree/main/config/schemas).
+Welkin Apps configuration and secrets have auto-generated documentation from [the JSON schemas defined in it repository](https://github.com/elastisys/compliantkubernetes-apps/tree/main/config/schemas).
 
 This is driven via a script using [adobe/jsonschema2md](https://github.com/adobe/jsonschema2md).
 

README.md

@@ -30,7 +30,7 @@ npm install -g sass
 ## Usage
 
 > [!NOTE]
-> For Mac users, you might have to install cairo: `brew install cairo`
+> For Mac users, you might have to install Cairo: `brew install cairo`
 
 To view locally:
 
@@ -66,7 +66,7 @@ GitHub Actions will deploy the `main` branch automatically.
 
 ## Known Issues
 
-### nodeenv provided with Ubuntu 24.04 is old
+### `nodeenv` provided with Ubuntu 24.04 is old
 
 If you get the following errors:
 
@@ -81,12 +81,12 @@ An unexpected error has occurred: CalledProcessError: command: ('/usr/bin/python
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 ```
 
-Then this could be caused by the version of nodeenv delivered with Ubuntu 24.04.
+Then this could be caused by the version of `nodeenv` delivered with Ubuntu 24.04.
 You have two options.
 
 #### Option 1: Run pre-commit from a virtual environment
 
-1. Remove Ubuntu's pre-commit and nodeenv: `sudo apt purge nodeenv --autoremove`.
+1. Remove Ubuntu's pre-commit and `nodeenv`: `sudo apt purge nodeenv --autoremove`.
 1. Activate the virtual environment you created above: `. .venv/bin/activate`.
 1. Install pre-commit in the virtual environment: `pip install pre-commit`.
 1. Run pre-commit from the virtual environment: `pre-commit run --all`.

ci/vale/styles/config/vocabularies/Elastisys/accept.txt

@@ -1,49 +1,154 @@
-# Brands, Organization and Project Names
-Alertmanager
+# Brands and Organization
 Atlassian
-Ceph
+Bitnami
+Carasent
+Datadog
 Datatilsynet
 (?i)Elastisys
 Elementor
+Entra
+Exoscale
+EU
+GMail
+IMY
+Inera
+JumpCloud
+Opsgenie
+Prorenata
+Qualys
+Safespring
+Schrems
+Socialstyrelsen
+Spotahome
+Sjunet
+Telavox
+Telia
+Tempus
+vSphere
+Yopass
+Zalando
+
+# Project Names
+Alertmanager
+Ansible
+Bazel
+Blackbox
+Ceph
+containerd
+Dex
+# 'Distro' as in 'Open Distro for Elasticsearch'
+Distro
+etcd
+Elasticdump
 Falco
 Fluentd
-GMail
 Grafana
-IMY
+Graphviz
+Gzip
+Helm
+Kafka
+Keycloak
+Kibana
 Kubespray
 Kured
+kustomization
+kustomize
+MkDocs
+Monokle
+NGINX
+OpenStack
+PGAudit
+pgvector
+Pulumni
+Pushgateway
+Rclone
+Strimzi
+Skaffold
+systemd
+Terraform
+Thanos
+timesyncd
 Tekton
-Telavox
 Trivy
 Velero
-Yopass
 
 # General technical terms
+ADR
 API
+allowlist
 (?i)allowlisting
 allowlisted
 (?i)autoscaling
+burstable
+chroot
+CI
+CISO
 colocation
 CPU
+CVE
 cyber
 cybersecurity
+discoverability
 Dockerfile
 (?i)downsampled
 downscaling
+DPO
 failover
+Gbps
+geospatial
+hostname
+ICT
+loopback
+lookup
 microsegmentation
-SLA
+multitenancy
+multitenant
+OAuth
+overcommitted
+queryable
+resync
+runbook
+runtime
+seccomp
 setgid
 setuid
+SLA
+# `snowflakiness` is rather informal, but it's rather used, so let's admit it.
+# See https://martinfowler.com/bliki/SnowflakeServer.html
+snowflakiness
 stdout
+subnet
+SVG
+syscall
+sysctl
+unencrypted
 upscaling
+upstreaming
+URI
+UI
 VM
 
 # Kubernetes terms
 Autoscaler
+autoscaled
+CRD
+CronJob
+finalizer
+kops
+kubeadm
 kubeconfig
+kubectl
+kubelet
+kubelogin
 Namespace
+PDB
+prober
+PVC
 RBAC
+toleration
+
+# OpenSearch terms
+Configurer
 
 # RabbitMQ terms
 vhost
@@ -54,24 +159,74 @@ alia
 decompile
 DPA
 facto
+# MDR class IIa
+IIa
 jure
 (?i)majeure
 kap
+nonfederal
+rulemaking
 (?i)severability
 subclause
 sublicense
 (?i)subprocessor
 
 # Swedish terms
+julafton
+kommuner
 midsommarafton
 midsommardagen
-julafton
+myndigheten
+nationell
+Patientdatalagen
+personuppgifter
+regioner
 skyddsklass
 
 # German terms
 Grundschutz
+Bundesamt
+Sicherheit
+Informationstechnik
 
 # No clue why Vale doesn't recognize these words
 approver
 auditability
+digitalization
+exfiltrate
+impactful
 learnings
+misconfiguration
+misconfigured
+mitigation
+offboarding
+onboarding
+onwards
+rollout
+schedulable
+timepoint
+untrusted
+
+# YAML terms
+frontmatter
+
+# Names used in some place
+Axel
+Cristian
+Ewnetu
+Forsberg
+Fredrik
+Geoff
+Gunda
+Harr
+Johan
+Karlton
+Kashyap
+Larsson
+Lennart
+Liv
+Olle
+Pradyumna
+Prady
+Ravi
+Viktor

ci/vale/styles/config/vocabularies/Elastisys/reject.txt

@@ -0,0 +1,5 @@
+# The likelihood of us using "helm" as in "a tiller or wheel for steering a
+# ship or boat" is really small.
+helm
+# Same for "terraform".
+terraform

docs/adr/0003-push-metrics-via-influxdb.md

@@ -9,7 +9,7 @@
 We want to support workload multi-tenancy, i.e., one Management Cluster -- hosting the tamper-proof logging environment -- and multiple Workload Clusters. Currently, the Management Cluster exposes two end-points for Workload Clusters:
 
 - Dex, for authentication;
-- Elastisearch, for pushing logs (append-only).
+- Elasticsearch, for pushing logs (append-only).
 
 Currently, the Management Cluster pulls metrics from the Workload Cluster. This makes it difficult to have multiple Workload Clusters connected to the same Management Cluster.
 

docs/adr/0006-use-standard-kubeconfig-mechanisms.md

@@ -1,12 +1,12 @@
 # Use Standard Kubeconfig Mechanisms
 
 - Status: accepted
-- Deciders: Architecture Meeing
+- Deciders: Architecture Meeting
 - Date: 2021-02-02
 
 ## Context and Problem Statement
 
-To increase adoption of Welkin, we were asked to observe the [Principle of Least Astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment). Currently, Welkin's handing of kubeconfig is astonishing. Most tools in the ecosystem use the standard `KUBECONFIG` environment variable and kubecontext implemented in the client-go library. These tools leave it up to the user to set `KUBECONFIG` or use the default `~/.kube/config`. Similarly, there is a default kubecontext which can be overwritten via command-line. Tools that get cluster credentials generate a context related to the name of the cluster.
+To increase adoption of Welkin, we were asked to observe the [Principle of Least Astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment). Currently, Welkin's handing of kubeconfig is astonishing. Most tools in the ecosystem use the standard `KUBECONFIG` environment variable and KUBECONFIG context implemented in the client-go library. These tools leave it up to the user to set `KUBECONFIG` or use the default `~/.kube/config`. Similarly, there is a default KUBECONFIG context which can be overwritten via command-line. Tools that get cluster credentials generate a context related to the name of the cluster.
 
 Tools that behave as such include:
 
@@ -41,4 +41,4 @@ Tools that consume Kubernetes contexts are expected to use an approach similar t
 ## Links
 
 - [Organizing Cluster Access Using kubeconfig Files](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
-- [kubectx / kubens](https://github.com/ahmetb/kubectx)
+- [`kubectx` / `kubens`](https://github.com/ahmetb/kubectx)