Install: Implement suggestions by CodeRabbit

Author: amotl

docs/feature/cloud/index.md

@@ -65,7 +65,6 @@ needs.
 
 :::{rubric} CrateDB Cloud
 :::
-- {ref}`cloud:index`
 - {ref}`Documentation <cloud:index>`
 - [Web Console]
 

docs/install/cloud/aws/aws-terraform-setup.md

@@ -2,7 +2,7 @@
 
 # Deploy using Terraform
 
-In {ref}`ec2_setup`, we elaborated on how to leverage EC2's functionality to set
+In {ref}`ec2-setup`, we elaborated on how to leverage EC2's functionality to set
 up a CrateDB cluster. Here, we will explore how to automate this kind of setup.
 
 [Terraform] is an infrastructure as code tool, often used as an abstraction

docs/install/cloud/aws/s3-setup.md

@@ -25,10 +25,10 @@ instances.
 
 ### Authentication
 
-It is recommended to restrict the permissions of CrateDB on the S3 to only the
-required extend. First, an IAM role is required. This [AWS guide] gives a
-short description of how to create a policy offer using the CLI or the AWS
-management console. Further, access of the snapshot to the S3 bucket needs to
+It is recommended to restrict the permissions of CrateDB on S3 to only the
+required extent. First, an IAM role is required. This [AWS IAM policy guide]
+explains how to create a policy by using the CLI or the AWS Management Console.
+Further, access of the snapshot to the S3 bucket needs to
 be restricted. An example policy file granting anybody access to a bucket
 called `snaps.example.com` is attached below:
 
@@ -92,7 +92,7 @@ within the policy:
 ```
 
 [amazon s3]: https://aws.amazon.com/s3/
-[aws guide]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html
+[AWS IAM policy guide]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html
 [aws policy examples]: https://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html
 [aws principals]: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html
 [iam roles]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html

docs/install/cloud/azure/terraform.md

@@ -2,7 +2,7 @@
 
 # Deploy using Terraform
 
-In {ref}`azure_vm_setup`, we elaborated on how to leverage Azure's functionality to
+In {ref}`azure-vm-setup`, we elaborated on how to leverage Azure's functionality to
 set up a CrateDB cluster. Here, we will explore how to automate this kind of
 setup.
 

docs/install/cloud/azure/vm.md

@@ -23,7 +23,7 @@ under the *new* left hand panel of the Azure portal.
 ### Create a network security group
 
 CrateDB uses two ports, one for inter-node communication (`4300`) and one for
-it's http endpoint (`4200`), so access to these needs to be opened.
+its HTTP endpoint (`4200`), so access to these needs to be opened.
 
 Create a *New Security Group*, giving it a name and assigning it to the
 'Resource Group' just created.
@@ -32,7 +32,7 @@ Create a *New Security Group*, giving it a name and assigning it to the
 :alt: Create New Security Group
 ```
 
-Find that security group in your resources list and open it's settings,
+Find that security group in your resources list and open its settings,
 navigating to the *Inbound security rules* section.
 
 ```{image} /_assets/img/install/cloud/azure-nsg-inbound.png
@@ -71,7 +71,7 @@ earlier to the subnet.
 ### Create virtual machines
 
 Next create virtual machines to act as your CrateDB nodes. In this tutorial, I
-chose two low-specification Ubuntu 14.04 servers, but you likely have your own
+chose two low-specification Ubuntu servers, but you likely have your own
 preferred configurations.
 
 Most importantly, make sure you select the Virtual Network created earlier.
@@ -142,14 +142,14 @@ the same steps as for Azure and Linux.
 ### Create virtual machines
 
 Similar steps to creating Virtual Machines for Azure and Linux, but create the
-VM based on the 'Windows Server 2012 R2 Datacenter' image.
+VM based on a recent "Windows Server LTS" image.
 
 ### Install CrateDB
 
 *Note that these instructions should be followed on each VM in your cluster.*
 
 To install CrateDB on Windows Server, you will need a [Java JDK installed].
-Ensure that the `JAVA*HOME` environment variable is set.
+Ensure that the `JAVA_HOME` environment variable is set.
 
 ```{image} /_assets/img/install/cloud/azure-envvar.png
 :alt: Environment Variables
@@ -171,7 +171,7 @@ We need to allow the ports CrateDB uses through the Windows Firewall
 :alt: Firewall configuration
 ```
 
-Start crate by running `bin/crate`.
+Start CrateDB by running `.\bin\crate.bat` (PowerShell) or `bin\crate.bat` (CMD).
 
 [3.3]: https://github.com/crate/crate/blob/3.3/blackbox/docs/config/cluster.rst#discovery
 [java jdk installed]: https://www.oracle.com/java/technologies/downloads/#java8

docs/install/container/docker.md

@@ -22,6 +22,8 @@ The official [CrateDB Docker image].
 
 ## Quick start
 
+(container-create-cluster)=
+
 ### Creating a cluster
 
 To get started with CrateDB and Docker, you will create a three-node cluster
@@ -38,8 +40,10 @@ sh$ docker network create crate
 
 You should then be able to see something like this:
 
-```text
+```shell
 sh$ docker network ls
+```
+```text
 NETWORK ID          NAME                DRIVER              SCOPE
 1bf1b7acd66f        bridge              bridge              local
 51cebbdf7d2b        crate               bridge              local
@@ -55,7 +59,7 @@ container `crate03` will run cluster node `crate03`.
 
 You can then create your first CrateDB container and node, like this:
 
-```
+```shell
 sh$ docker run --rm -d \
       --name=crate01 \
       --net=crate \
@@ -82,25 +86,26 @@ Breaking the command down:
 - Defines the environment variable {ref}`CRATE_HEAP_SIZE <crate-reference:conf-env-heap-size>`,
   which is used by CrateDB to allocate 1 GB for its heap memory.
 - Runs the command `crate` inside the container with parameters:
-  : - `network.host`: The `_site_` value results in the binding of the
-      CrateDB process to a site-local IP address.
-    - `node.name`: Defines the node's name as `crate01` (used by
-      master election).
-    - `discovery.seed_hosts`: This parameter lists the other hosts in the
-      cluster. The format is a comma-separated list of `host:port` entries,
-      where port defaults to setting `transport.tcp.port`. Each node must
-      contain the name of all the other hosts in this list. Notice also that
-      any node in the cluster might be started at any time, and this will
-      create connection exceptions in the log files, however all nodes will
-      eventually be running and interconnected.
-    - `cluster.initial_master_nodes`: Defines the list of master-eligible
-      node names which will participate in the vote of the first master
-      (first bootstrap). If this parameter is not defined, then it is expected
-      that the node will join an already formed cluster. This parameter is only
-      relevant for the first election.
-    - `gateway.expected_data_nodes` and `gateway.recover_after_data_nodes`:
-      Specifies how many nodes you expect in the cluster and how many nodes must
-      be discovered before the cluster state is recovered.
+
+  - `network.host`: The `_site_` value results in the binding of the
+    CrateDB process to a site-local IP address.
+  - `node.name`: Defines the node's name as `crate01` (used by
+    master election).
+  - `discovery.seed_hosts`: This parameter lists the other hosts in the
+    cluster. The format is a comma-separated list of `host:port` entries,
+    where port defaults to setting `transport.tcp.port`. Each node must
+    contain the name of all the other hosts in this list. Notice also that
+    any node in the cluster might be started at any time, and this will
+    create connection exceptions in the log files, however all nodes will
+    eventually be running and interconnected.
+  - `cluster.initial_master_nodes`: Defines the list of master-eligible
+    node names which will participate in the vote of the first master
+    (first bootstrap). If this parameter is not defined, then it is expected
+    that the node will join an already formed cluster. This parameter is only
+    relevant for the first election.
+  - `gateway.expected_data_nodes` and `gateway.recover_after_data_nodes`:
+    Specifies how many nodes you expect in the cluster and how many nodes must
+    be discovered before the cluster state is recovered.
 
 :::{NOTE}
 If this command aborts with an error, consult the
@@ -250,10 +255,11 @@ The CrateDB Shell, `crash`, is bundled with the Docker image.
 
 If you wanted to run `crash` inside a user-defined network called `crate`
 and connect to three hosts named `crate01`, `crate02`, and `crate03`
-(i.e. the example covered in the [Creating a Cluster] section) you could run:
+(i.e. the example covered in the {ref}`container-create-cluster` section)
+you could run:
 
 ```shell
-$ docker run --rm -ti \
+sh$ docker run --rm -ti \
     --net=crate crate \
     crash --hosts crate01 crate02 crate03
 ```
@@ -266,7 +272,7 @@ Docker's Compose tool allows developers to define and run multi-container
 Docker applications that can be started with a single `docker-compose up`
 command.
 
-Read about Docker Compose specifics [here](https://docs.docker.com/compose/).
+Read about Docker Compose specifics in the [Docker Compose documentation](https://docs.docker.com/compose/).
 
 You can define the services that make up your app in a `docker-compose.yml`
 file. To recreate the three-node cluster in the previous example, you can
@@ -357,6 +363,11 @@ In the file above:
 - The start order of the containers is not deterministic and you want all
   three containers to be up and running before the election of the master node.
 
+:::{NOTE}
+The `deploy` section is used by Docker Swarm (`docker stack deploy`) and is
+ignored by `docker compose up`.
+:::
+
 ## Best Practices
 
 ### One container per host
@@ -368,7 +379,7 @@ If you are running one container per machine, you can map the container ports
 to the host ports so that the host acts like a native installation. For example:
 
 ```shell
-$ docker run -d -p 4200:4200 -p 4300:4300 -p 5432:5432 --env CRATE_HEAP_SIZE=1g crate \
+sh$ docker run -d -p 4200:4200 -p 4300:4300 -p 5432:5432 --env CRATE_HEAP_SIZE=1g crate \
     crate -Cnetwork.host=_site_
 ```
 
@@ -380,7 +391,7 @@ this reason, you should mount a persistent `data` directory on your host
 machine to the `/data` directory inside the container:
 
 ```shell
-$ docker run -d -v /srv/crate/data:/data --env CRATE_HEAP_SIZE=1g crate \
+sh$ docker run -d -v /srv/crate/data:/data --env CRATE_HEAP_SIZE=1g crate \
     crate -Cnetwork.host=_site_
 ```
 
@@ -399,7 +410,7 @@ removed.
 Here is an example of how you could mount the `crate.yml` config file:
 
 ```shell
-$ docker run -d \
+sh$ docker run -d \
     -v /srv/crate/config/crate.yml:/crate/config/crate.yml \
     --env CRATE_HEAP_SIZE=1g crate \
     crate -Cnetwork.host=_site_
@@ -408,7 +419,7 @@ $ docker run -d \
 Here, `/srv/crate/config/crate.yml` is an example path, and should be
 replaced with the path to your host machine's `crate.yml` file.
 
-## Troubleshooting
+## Healthcheck troubleshooting
 
 The official [CrateDB Docker image] ships with a liveness [healthcheck]
 configured.
@@ -468,9 +479,9 @@ memory, with a heap size of 1 GB, you could configure everything at once. For
 example:
 
 ```shell
-$ docker run -d \
+sh$ docker run -d \
     --cpus 1.5 \
-    --memory 1g \
+    --memory 2g \
     --env CRATE_HEAP_SIZE=1g \
     crate \
     crate -Cnetwork.host=_site_

docs/install/container/kubernetes/kubernetes.md

@@ -6,7 +6,7 @@
 CrateDB and Kubernetes are a great match.
 :::
 
-CrateDB’s [horizontally scalable] `shared-nothing architecture` lends itself
+CrateDB’s [horizontally scalable] [shared-nothing architecture] lends itself
 well to [containerization].
 
 [Kubernetes] is an open-source container orchestration system for the
@@ -15,8 +15,8 @@ management, deployment, and scaling of containerized systems.
 Together, Docker and Kubernetes are a fantastic way to deploy and scale CrateDB.
 
 :::{NOTE}
-While Kubernetes works with a variety of container technologies, this
-document only covers its use with Docker.
+While Kubernetes supports multiple container runtimes, this document
+uses Docker-compatible container images.
 :::
 
 :::{SEEALSO}
@@ -41,7 +41,7 @@ You can create a resource like so:
 
 ```console
 sh$ kubectl create -f crate-controller.yaml --namespace crate
-statefulset.apps/crate-controller created
+statefulset.apps/crate created
 ```
 
 Here, we are creating a [StatefulSet] controller in the `crate` namespace
@@ -149,6 +149,12 @@ load balancers.
 For local development, [Minikube] provides a LoadBalancer service.
 :::
 
+:::{WARNING}
+Ensure proper network controls and authentication are in place before
+exposing ports 4200 (HTTP) and 5432 (PostgreSQL) via a LoadBalancer.
+Restrict source IPs and configure users/roles to avoid unauthorized access.
+:::
+
 ### Controller
 
 A Kubernetes [pod] is a group of one or more containers. Pods are designed to
@@ -213,7 +219,7 @@ spec:
         # Use the CrateDB 5.1.1 Docker image.
         image: crate:5.1.1
         # Pass in configuration to CrateDB via command-line options.
-        # We are setting the name of the node's explicitly, which is
+        # We are setting the node name explicitly, which is
         # needed to determine the initial master nodes. These are set to
         # the name of the pod.
         # We are using the SRV records provided by Kubernetes to discover
@@ -228,9 +234,9 @@ spec:
           - -Cgateway.expected_data_nodes=${EXPECTED_NODES}
           - -Cpath.data=/data
         volumeMounts:
-              # Mount the `/data` directory as a volume named `data`.
+            # Mount the volume named `cratedb-data` to the `/data` directory.
             - mountPath: /data
-              name: data
+              name: cratedb-data
         resources:
           limits:
             # How much memory each pod gets.
@@ -247,7 +253,7 @@ spec:
           name: postgres
         # Environment variables passed through to the container.
         env:
-          # This is variable is detected by CrateDB.
+          # This variable is detected by CrateDB.
         - name: CRATE_HEAP_SIZE
           value: "256m"
           # The rest of these variables are used in the command-line
@@ -267,7 +273,7 @@ spec:
   volumeClaimTemplates:
     # Use persistent storage.
     - metadata:
-        name: data
+        name: cratedb-data
       spec:
         accessModes:
         - ReadWriteOnce
@@ -333,34 +339,31 @@ You can then use this in your controller configuration with something like this:
 [...]
   volumeClaimTemplates:
     - metadata:
-        name: persistant-data
+        name: cratedb-data
       spec:
         # This will create one 100GB read-write Azure Managed Disks volume
         # for every CrateDB pod.
         accessModes: [ "ReadWriteOnce" ]
         storageClassName: crate-premium
         resources:
           requests:
-            storage: 100g
+            storage: 100Gi
 ```
 
 [azure managed disks]: https://azure.microsoft.com/en-us/pricing/details/managed-disks/
 [configuration]: https://kubernetes.io/docs/concepts/configuration/overview/
 [containerization]: https://www.docker.com/resources/what-container
 [cratedb docker image]: https://hub.docker.com/_/crate/
-[docker]: https://www.docker.com/
 [horizontally scalable]: https://en.wikipedia.org/wiki/Scalability#Horizontal_(scale_out)_and_vertical_scaling_(scale_up)
 [ingress]: https://kubernetes.io/docs/concepts/services-networking/ingress/
 [kubernetes]: https://kubernetes.io/
 [loadbalancer]: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer
 [managed]: https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/
 [minikube]: https://kubernetes.io/docs/setup/minikube/
-[persistent volume]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/
 [persistent volumes]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/
 [pod]: https://kubernetes.io/docs/concepts/workloads/pods/
 [rolling update strategy]: https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#rolling-updates
 [service]: https://kubernetes.io/docs/concepts/services-networking/service/
-[services]: https://kubernetes.io/docs/concepts/services-networking/service/
 [setting up your first cratedb cluster on kubernetes]: https://cratedb.com/blog/run-your-first-cratedb-cluster-on-kubernetes-part-one
 [shared-nothing architecture]: https://en.wikipedia.org/wiki/Shared-nothing_architecture
 [statefulset]: https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/