From 9825240ba899e2b015f08d99f26df90145ea88be Mon Sep 17 00:00:00 2001 From: Niamh Hennigan Date: Thu, 5 Dec 2024 11:06:35 -0800 Subject: [PATCH] [Docs] implement vale spellchecker (#868) * implement vale spellchecker add config files for vale, update github action for spellcheck and fix some spelling mistakes --- .github/workflows/docs-spelling-checks.yml | 32 +- docs/canonicalk8s/.vale.ini | 8 + docs/canonicalk8s/Makefile.sp | 4 +- .../config/vocabularies/Canonical/accept.txt | 365 ++++++++++++++++++ docs/src/capi/explanation/capi-ck8s.md | 2 +- docs/src/capi/howto/custom-ck8s.md | 9 +- docs/src/snap/howto/cis-hardening.md | 52 +-- docs/src/snap/howto/install/multipass.md | 8 +- docs/src/snap/howto/install/offline.md | 4 +- docs/src/snap/howto/storage/cloud.md | 4 +- docs/src/snap/reference/troubleshooting.md | 10 +- 11 files changed, 438 insertions(+), 60 deletions(-) create mode 100644 docs/canonicalk8s/.vale.ini create mode 100644 docs/canonicalk8s/styles/config/vocabularies/Canonical/accept.txt diff --git a/.github/workflows/docs-spelling-checks.yml b/.github/workflows/docs-spelling-checks.yml index 913ab75a8..24e20af51 100644 --- a/.github/workflows/docs-spelling-checks.yml +++ b/.github/workflows/docs-spelling-checks.yml @@ -2,9 +2,9 @@ name: Documentation Spelling Check on: workflow_dispatch: - # pull_request: - # paths: - # - 'docs/**' + pull_request: + paths: + - 'docs/**' permissions: contents: read @@ -13,20 +13,20 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - name: Install aspell - run: sudo apt-get install aspell aspell-en + - name: Install vale + run: sudo snap install vale - id: spell-check name: Spell Check - run: make spelling + run: vale --glob='*.{md,txt,rst}' . working-directory: docs/canonicalk8s - continue-on-error: true + # continue-on-error: true # - if: ${{ github.event_name == 'pull_request' && steps.spell-check.outcome == 'failure' }} - # uses: actions/github-script@v6 - # with: - # script: | - # github.rest.issues.createComment({ - # issue_number: context.issue.number, - # owner: context.repo.owner, - # repo: context.repo.repo, - # body: 'Hi, looks like pyspelling job found some issues, you can check it [here](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})' - # }) + # uses: actions/github-script@v6 + # with: + # script: | + # github.rest.issues.createComment({ + # issue_number: context.issue.number, + # owner: context.repo.owner, + # repo: context.repo.repo, + # body: 'Hi, looks like the vale spelling job found some issues, you can check it [here](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})' + # }) diff --git a/docs/canonicalk8s/.vale.ini b/docs/canonicalk8s/.vale.ini new file mode 100644 index 000000000..05286ebb6 --- /dev/null +++ b/docs/canonicalk8s/.vale.ini @@ -0,0 +1,8 @@ +StylesPath = styles +MinAlertLevel = warning +Vocab = Canonical +IgnoredScopes = + +[*.{md,rst,html}] + +Vale.Spelling = YES diff --git a/docs/canonicalk8s/Makefile.sp b/docs/canonicalk8s/Makefile.sp index 6b98451f5..9e0b69fe3 100644 --- a/docs/canonicalk8s/Makefile.sp +++ b/docs/canonicalk8s/Makefile.sp @@ -112,7 +112,7 @@ sp-vale: sp-install @. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \; @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt - @cat $(SOURCEDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt + @cat ./src/.wordlist.txt ./src/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt @echo "" @echo "Running Vale against $(TARGET). To change target set TARGET= with make command" @echo "" @@ -148,7 +148,7 @@ sp-allmetrics: sp-html @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \; @eval '$(METRICSDIR)/scripts/source_metrics.sh $(PWD)' @eval '$(METRICSDIR)/scripts/build_metrics.sh $(PWD) $(METRICSDIR)' - + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/docs/canonicalk8s/styles/config/vocabularies/Canonical/accept.txt b/docs/canonicalk8s/styles/config/vocabularies/Canonical/accept.txt new file mode 100644 index 000000000..c696480ae --- /dev/null +++ b/docs/canonicalk8s/styles/config/vocabularies/Canonical/accept.txt @@ -0,0 +1,365 @@ +ACLs +APIs +AWS EKS +Anbox +Anbox Cloud +Canonical Observability Stack +Ceph +COS +Charmed +Charmed Kubeflow +Charmhub +Data Integrator +Grafana +Juju +K8s +Kafka +Kratos +Kubeflow +Kubernetes +Kyuubi +LXD +Landscape +Launchpad +MAAS +Mattermost +MicroCeph +MicroCloud +MicroK8s +MicroOVN +MicroStack +Mir +Multipass +NVIDIA +Nota +Oathkeeper +OpenStack +PostgreSQL +Pushgateway +Python +Requirer +S3 +Snapcraft +Spark +Spark History Server +Spark Job +Spark Submit +Squashfs +Terraform +TLS +Traefik +Transport Layer Security +Ubuntu Core +Ubuntu Pro +Ubuntu Server +VMs +VMware +ZooKeeper +[Cc]onfig +[Dd]owntime +[Ee]ksctl +[Kk]eystore +[Nn]amespace +[Pp]arallelisation +[Rr]ebalance +[Rr]ebalancing +[Ss]napd +[Ss]torage +[Ss]ysctl +[Tt]ruststore +[Uu]nencrypted +[Uu]psert +adapter's +adapters +aescbc +allocatable +allocator +AlwaysPullImages +api +apiserver +apparmor +AppArmor +args +ARP +asn +ASN +autostart +autosuspend +aws +backend +backported +balancers +benoitblanchon +bgp +BGP +bootloader +BPF +CABPCK +CACPCK +capi +CAPI +CAs +Center +ceph +Ceph +cephcsi +cephx +cgroup +cgroups +cidr +CIDR +cidrs +CIDRs +CIS +CK8sControlPlane +CLI +CLIs +CloudFormation +ClusterAPI +clusterctl +ClusterRole +ClusterRoleBinding +CMK +CNI +Commenter +config +configMap +ConfigMap +containerd +CoreDNS +Corosync +CPUs +cpuset +crt +csi +CSI +CSRs +cyclictest +daemonset +DaemonSet +datastore +datastores +dbus +de +deallocation +deployable +discoverable +DMA +dns +DNS +DPDK +DRBD +drv +dqlite +EAL +EasyRSA +eBPF +enp +enum +etcd +eth +EventRateLimit +ExternalIP +failover +Furo +gapped +GCP +ghcr +Gi +github +gops +GPLv +Graber +Graber's +grafana +haircommander +Harbor +hostname +hostpath +HPC +html +http +https +HugePage +HugePages +iavf +init +initialise +integrations +InternalIP +io +IOMMU +IOV +ip +IPIP +IPIPCrossSubnet +IPv +IPv4 +IPv6 +IRQs +Jinja +jitter +juju +Juju's +KMS +kube +kube-apiserver +kube-controller-manager +kube-proxy +kube-scheduler +kube-system +kubeconfig +kubectl +kubelet +kubepods +kubernetes +latencies +Latencies +libcontainer +lifecycle +linux +Lite's +LoadBalancer +localhost +Lookaside +lookups +loopback +LPM +lxc +LxcSecurity +LXD +MAAS +macOS +Maskable +MCE +MetalLB +Microbot +MicroCluster +MicroK +MicroK8s +MinIO +modprobe +Moonray +mq +mtu +MTU +multicast +MULTICAST +Multipass +Multus +nameservers +Netplan +NetworkAttachmentDefinition +NFD +NFV +nginx +NGINX +NIC +NMI +NodeInternalIP +nodeport +nohz +no_proxy +NUMA +numactl +OCI +OOM +OpenStack +OSDs +ParseDuration +passthrough +passwordless +pci +PEM +performant +PID +PMD +PMDs +powershell +PPA +proc +programmatically +provisioner +PRs +PV +qdisc +qlen +QoS +RADOS +rbac +RBAC +RBD +rc +RCU +README +regctl +regsync +roadmap +Rockcraft +rollout +Runtime +runtimes +rw +sandboxed +SANs +scalable +SCHED +sControlPlane +sd +seccomp +secretbox +SELinux +ServiceAccount +Snapcraft +snapd +SR-IOV +src +stackexchange +stgraber +STONITH +StorageClass +sudo +sys +systemd +taskset +Telco +throughs +tickless +TLB +tls +TLS +toml +TSC +TTL +ttyS +ubuntu +UIDs +unix +unschedulable +unsquashed +Velero +vf +VF +vfio +VFIO +VFs +virtualised +VLAN +VLANs +VMs +VMware +VNFs +VPCs +VSphere +VXLAN +VXLANCrossSubnet +WIP +wordlist +www +yaml +YAMLs +zsh +_How +_Example +_parts +_Read diff --git a/docs/src/capi/explanation/capi-ck8s.md b/docs/src/capi/explanation/capi-ck8s.md index 5ba3487b3..08dd47fd7 100644 --- a/docs/src/capi/explanation/capi-ck8s.md +++ b/docs/src/capi/explanation/capi-ck8s.md @@ -22,7 +22,7 @@ distribution that seamlessly integrates with Cluster API. With {{product}} CAPI you can: - provision a cluster with: - - Kubernetes version 1.31 onwards + - Kubernetes version 1.31 onward - risk level of the track you want to follow (stable, candidate, beta, edge) - deploy behind proxies - upgrade clusters with no downtime: diff --git a/docs/src/capi/howto/custom-ck8s.md b/docs/src/capi/howto/custom-ck8s.md index 79e92162f..6a68fc1ba 100644 --- a/docs/src/capi/howto/custom-ck8s.md +++ b/docs/src/capi/howto/custom-ck8s.md @@ -18,9 +18,10 @@ In this guide we call the generated cluster spec manifest `cluster.yaml`. ## Overwrite the existing `install.sh` script The installation of the {{product}} snap is done via running the `install.sh` script in the cloud-init. -While this file is automatically placed in every workload cluster machine which hard-coded content by {{product}} providers, you can overwrite this file to make sure your desired content is available in the script. +While this file is automatically placed in every workload cluster machine which hard-coded content by {{product}} providers, you can overwrite this file to make sure your desired content is available in the script. As an example, let's overwrite the `install.sh` for our control plane nodes. Inside the `cluster.yaml`, add the new file content: + ```yaml apiVersion: controlplane.cluster.x-k8s.io/v1beta2 kind: CK8sControlPlane @@ -37,11 +38,12 @@ spec: permissions: "0500" ``` -Now the new control plane nodes that are created using this manifest will have the `1.31-classic/candidate` {{product}} snap installed on them! +Now the new control plane nodes that are created using this manifest will have +the `1.31-classic/candidate` {{product}} snap installed on them! ## Use `preRunCommands` -As mentioned above, the `install.sh` script is responsible for installing {{product}} snap on machines. `preRunCommands` are executed before `install.sh`. You can also add an install command to the `preRunCommands` in order to install your desired {{product}} version. +As mentioned above, the `install.sh` script is responsible for installing {{product}} snap on machines. `preRunCommands` are executed before `install.sh`. You can also add an install command to the `preRunCommands` in order to install your desired {{product}} version. ```{note} Installing the {{product}} snap via the `preRunCommands`, does not prevent the `install.sh` script from running. Instead, the installation process in the `install.sh` will fail with a message indicating that `k8s` is already installed. @@ -49,6 +51,7 @@ This is not considered a standard way and overwriting the `install.sh` script is ``` Edit the `cluster.yaml` to add the installation command: + ```yaml apiVersion: controlplane.cluster.x-k8s.io/v1beta2 kind: CK8sControlPlane diff --git a/docs/src/snap/howto/cis-hardening.md b/docs/src/snap/howto/cis-hardening.md index fd213c3ed..385b94216 100644 --- a/docs/src/snap/howto/cis-hardening.md +++ b/docs/src/snap/howto/cis-hardening.md @@ -1,4 +1,4 @@ -# CIS compliance +# CIS compliance CIS Hardening refers to the process of implementing security configurations that align with the benchmarks set by the [Center for Internet Security (CIS)][]. @@ -43,7 +43,7 @@ Configuring log auditing requires the cluster administrator's input and may incurr performance penalties in the form of disk I/O. ``` -Create an audit-policy.yaml file under `/var/snap/k8s/common/etc/` and specify +Create an audit-policy.yaml file under `/var/snap/k8s/common/etc/` and specify the level of auditing you desire based on the [upstream instructions][]. Here is a minimal example of such a policy file. @@ -83,7 +83,7 @@ in assessing the hardware and workload specifications/requirements. ``` -Create a configuration file with the [rate limits][] and place it under +Create a configuration file with the [rate limits][] and place it under `/var/snap/k8s/common/etc/`. For example: @@ -110,7 +110,7 @@ plugins: EOL' ``` -Make sure the EventRateLimit admission plugin is loaded in the +Make sure the EventRateLimit admission plugin is loaded in the `/var/snap/k8s/common/args/kube-apiserver` . ``` @@ -138,8 +138,8 @@ Configuring the AlwaysPullImages admission control plugin may have performance impact in the form of increased network traffic and may hamper offline deployments that use image sideloading. ``` - -Make sure the AlwaysPullImages admission plugin is loaded in the + +Make sure the AlwaysPullImages admission plugin is loaded in the `/var/snap/k8s/common/args/kube-apiserver` ``` @@ -211,7 +211,7 @@ Restart `kubelet`. ``` sudo systemctl restart snap.k8s.kubelet -``` +``` Reload the system daemons: @@ -223,7 +223,7 @@ sudo systemctl daemon-reload ```{note} Fully complying with the spirit of this hardening recommendation calls for -systemd configuration that is out of the scope of this documentation page. +systemd configuration that is out of the scope of this documentation page. ``` Ensure that only the owner of `/etc/systemd/system/snap.k8s.kubelet.service` @@ -238,11 +238,11 @@ Restart `kubelet`. ``` sudo systemctl restart snap.k8s.kubelet -``` +``` -## Assess CIS hardening with kube-bench +## Assess CIS hardening with kube-bench Download the latest [kube-bench release][] on your Kubernetes nodes. Make sure to select the appropriate binary version. @@ -250,7 +250,7 @@ to select the appropriate binary version. For example, to download the Linux binary, use the following command. Replace `KB` by the version listed in the releases page. -``` +``` KB=8.0 mkdir kube-bench cd kube-bench @@ -262,20 +262,20 @@ Extract the downloaded tarball and move the binary to a directory in your PATH: ``` tar -xvf kube-bench_0.$KB\_linux_amd64.tar.gz sudo mv kube-bench /usr/local/bin/ -``` +``` Verify kube-bench installation. ``` kube-bench version -``` +``` The output should list the version installed. Install `kubectl` and configure it to interact with the cluster. ```{warning} -This will override your ~/.kube/config if you already have kubectl installed in your cluster. +This will override your ~/.kube/config if you already have kubectl installed in your cluster. ``` ``` @@ -291,13 +291,13 @@ Get CIS hardening checks applicable for {{product}}: git clone -b ck8s-dqlite https://github.com/canonical/kube-bench.git kube-bench-ck8s-cfg ``` -Test-run kube-bench against {{product}}: +Test-run kube-bench against {{product}}: ``` sudo -E kube-bench --version ck8s-cis-1.24 --config-dir ./kube-bench-ck8s-cfg/cfg/ --config ./kube-bench-ck8s-cfg/cfg/config.yaml ``` -Review the warnings detected and address any failing checks you see fit. +Review the warnings detected and address any failing checks you see fit. ``` [INFO] 1 Control Plane Security Configuration @@ -363,7 +363,7 @@ hardening state of a cluster. **Description:** Ensure that the API server configuration file permissions -are set to 600 +are set to 600 **Remediation:** @@ -1247,7 +1247,7 @@ set **Remediation:** Edit the API server configuration file /var/snap/k8s/common/args/kube-apiserver -on the control plane node and set the +on the control plane node and set the --enable-admission-plugins parameter to include AlwaysPullImages. @@ -2300,7 +2300,7 @@ implemented in place of client certificates. **Description:** -Ensure that a minimal audit policy is created +Ensure that a minimal audit policy is created **Remediation:** @@ -3347,10 +3347,10 @@ assigned **Remediation:** -Review the use of capabilites in applications running on +Review the use of capabilities in applications running on your cluster. Where a namespace contains applicaions which do not require any Linux -capabities to operate consider adding +capabilities to operate consider adding a PSP which forbids the admission of containers which do not drop all capabilities. @@ -3450,7 +3450,7 @@ from environment variables. **Description:** -Consider external secret storage +Consider external secret storage **Remediation:** @@ -3467,7 +3467,7 @@ secrets management solution. **Description:** Configure Image Provenance using ImagePolicyWebhook -admission controller +admission controller **Remediation:** @@ -3483,7 +3483,7 @@ provenance. **Description:** Create administrative boundaries between resources using -namespaces +namespaces **Remediation:** @@ -3506,10 +3506,12 @@ your Pod definitions Use `securityContext` to enable the docker/default seccomp profile in your pod definitions. An example is as follows: + +``` securityContext: seccompProfile: type: RuntimeDefault - +``` ##### Control 5.7.3 diff --git a/docs/src/snap/howto/install/multipass.md b/docs/src/snap/howto/install/multipass.md index d008b9815..28776bbc5 100644 --- a/docs/src/snap/howto/install/multipass.md +++ b/docs/src/snap/howto/install/multipass.md @@ -13,7 +13,7 @@ Choose your OS for the install procedure ```{group-tab} Ubuntu/Linux -Multipass is shipped as a snap for Ubuntu and other OSes which support the +Multipass is shipped as a snap for Ubuntu and other OSes which support the [snap package system][snap-support]. sudo snap install multipass @@ -24,7 +24,7 @@ Multipass is shipped as a snap for Ubuntu and other OSes which support the ```{group-tab} Windows Windows users should download and install the Multipass installer from the -website. +website. The [latest Windows version][] is available to download, though you may wish to visit the [Multipass website][] for more details. @@ -35,7 +35,7 @@ though you may wish to visit the [Multipass website][] for more details. ```{group-tab} macOS Users running macOS should download and install the Multipass installer from the -website. +website. The [latest macOS version] is available to download, though you may wish to visit the [Multipass website][] for more details, including @@ -113,7 +113,7 @@ multipass purge [Multipass]:https://multipass.run/ [snap-support]: https://snapcraft.io/docs/installing-snapd -[Multipass-options]: https://multipass.run/docs/get-started-with-multipass-linux#heading--create-a-customised-instance +[Multipass-options]: https://multipass.run/docs/tutorial#p-71169-create-a-customised-instance [install instructions]: ./snap [Getting started]: ../../tutorial/getting-started [Multipass website]: https://multipass.run/docs diff --git a/docs/src/snap/howto/install/offline.md b/docs/src/snap/howto/install/offline.md index 4933d78e1..18d64cb4f 100644 --- a/docs/src/snap/howto/install/offline.md +++ b/docs/src/snap/howto/install/offline.md @@ -250,8 +250,8 @@ Choose one of the following options: Create or edit the `/etc/systemd/system/snap.k8s.containerd.service.d/http-proxy.conf` -file on each node and set the appropriate http_proxy, https_proxy and -no_proxy variables as described in the +file on each node and set the appropriate `http_proxy`, `https_proxy` and +`no_proxy` variables as described in the [adding proxy configuration section][proxy]. #### Container Runtime Option B: Configure registry mirrors diff --git a/docs/src/snap/howto/storage/cloud.md b/docs/src/snap/howto/storage/cloud.md index 920b297dc..a38f0dfd1 100644 --- a/docs/src/snap/howto/storage/cloud.md +++ b/docs/src/snap/howto/storage/cloud.md @@ -15,7 +15,7 @@ This guide is for AWS and assumes the following: ## Set IAM Policies -Your instance will need a few IAM policies to be able to communciate with the +Your instance will need a few IAM policies to be able to communicate with the AWS APIs. The policies provided here are quite open and should be scoped down based on your security requirements. @@ -402,7 +402,7 @@ policy you are using for the instance. } ``` -Then, add the Helm repo for the EBS CSI Driver. +Then, add the Helm repository for the EBS CSI Driver. ```bash sudo k8s helm repo add aws-ebs-csi-driver https://kubernetes-sigs.github.io/aws-ebs-csi-driver diff --git a/docs/src/snap/reference/troubleshooting.md b/docs/src/snap/reference/troubleshooting.md index 7f341744c..441aefc22 100644 --- a/docs/src/snap/reference/troubleshooting.md +++ b/docs/src/snap/reference/troubleshooting.md @@ -49,7 +49,7 @@ E0125 00:20:56.003890 2172 kubelet.go:1466] "Failed to start ContainerManager ### Explanation -An excellent deep-dive of the issue exists at +An excellent deep-dive of the issue exists at [kubernetes/kubernetes #122955][kubernetes-122955]. Commenter [@haircommander][] [states][kubernetes-122955-2020403422] @@ -58,7 +58,7 @@ Commenter [@haircommander][] [states][kubernetes-122955-2020403422] > initially calls into it to do so. This happens because there isn't a cpuset > defined on the top level of the cgroup. however, we fail to validate all of > the cgroup controllers we need are present. It's possible this is a -> limitation in the dbus API: how do you ask systemd to create a cgroup that +> limitation in the dbus API: how do you ask systemd to create a cgroup that > is effectively empty? > if we delegate: we are telling systemd to leave our cgroups alone, and not @@ -67,7 +67,7 @@ Commenter [@haircommander][] [states][kubernetes-122955-2020403422] ### Solution -This is in the process of being fixed upstream via +This is in the process of being fixed upstream via [kubernetes/kubernetes #125923][kubernetes-125923]. In the meantime, the best solution is to create a `Delegate=yes` configuration @@ -92,7 +92,7 @@ installation of containerd on the system. ### Explanation -In classic confinment mode, {{product}} uses the default containerd +In classic confinement mode, {{product}} uses the default containerd paths. This means that a {{product}} installation will conflict with any existing system configuration where containerd is already installed. For example, if you have Docker installed, or another Kubernetes distribution @@ -111,4 +111,4 @@ you can create a LXD container for your installation. See [kubernetes-122955]: https://github.com/kubernetes/kubernetes/issues/122955 [kubernetes-125923]: https://github.com/kubernetes/kubernetes/pull/125923 [kubernetes-122955-2020403422]: https://github.com/kubernetes/kubernetes/issues/122955#issuecomment-2020403422 -[@haircommander]: https://github.com/haircommander \ No newline at end of file +[@haircommander]: https://github.com/haircommander