Terraform: Implement suggestions by CodeRabbit

Author: amotl

docs/integrate/terraform/tutorial.md

@@ -3,30 +3,31 @@
 
 ## Introduction
 
-CrateDB already has a wide variety of deployment options, ranging from
-{ref}`docker-compose` to {ref}`cloud setups <install-cloud>` on AWS and Azure.
+CrateDB offers multiple deployment options, from {ref}`docker-compose` to
+{ref}`cloud setups <install-cloud>` on AWS and Azure.
 
-To make cloud setups more manageable and predictable, we today add another
-option using [Terraform], an infrastructure-as-code tool.
-Terraform eliminates the need to create resources manually via the cloud console.
-Instead, it is based on a configuration language describing resources based
-on a given parametrization.
+To make cloud setups more manageable and predictable, this guide presents
+another option using [Terraform], an infrastructure-as-code tool.
+Terraform eliminates manual console steps to create resources.
+Instead, Terraform uses a configuration language that describes resources
+based on a given parametrization.
 
 ## Example
 
-The example below shows a 3 node cluster across several availability zones on AWS.
-Currently, AWS and Azure are supported as target platforms.
-The setup for Azure is very similar, please see the [README].
+This example deploys a 3‑node cluster across multiple Availability Zones on AWS.
+The module currently supports AWS and Azure.
+For Azure, see the [README].
 
 ## Configuration
 
-First, we create a new Terraform configuration file named `main.tf`.
-That file references the [crate/crate-terraform](https://github.com/crate/crate-terraform) repository with the underlying logic of the deployment. Several variables need to be specified regarding the target environment.
+First, create a new Terraform configuration file named `main.tf`.
+That file references the [crate/cratedb-terraform](https://github.com/crate/cratedb-terraform) repository with the underlying logic of the deployment.
+Specify several variables regarding the target environment.
 
 
 ```hcl
 module "cratedb-cluster" {
-  source = "[email protected]:crate/crate-terraform.git//aws"
+  source = "[email protected]:crate/cratedb-terraform.git//aws"
 
   # Global configuration items for naming/tagging resources
   config = {
@@ -38,38 +39,38 @@ module "cratedb-cluster" {
 
   # CrateDB-specific configuration
   crate = {
-    # Java Heap size in GB available to CrateDB
+    # Java heap size in GB available to CrateDB
     heap_size_gb = 2
 
     cluster_name = "crate-cluster"
 
-    # The number of nodes the cluster will consist of
+    # Number of nodes in the cluster
     cluster_size = 3
 
-    # Enables a self-signed SSL certificate
+    # Enable a self-signed TLS certificate
     ssl_enable = true
   }
 
-  # The AWS region
+  # AWS region
   region = "eu-central-1"
 
-  # The VPC to deploy to
+  # Target VPC
   vpc_id = "vpc-1234567"
 
-  # Applicable subnets of the VPC
+  # Subnets in the VPC
   subnet_ids = ["subnet-123456", "subnet-123457"]
 
-  # The corresponding availability zones of above subnets
+  # Availability Zones for the subnets above
   availability_zones = ["eu-central-1b", "eu-central-1a"]
 
-  # The SSH key pair for EC2 instances
+  # SSH key pair name for EC2 instances
   ssh_keypair = "cratedb-cluster"
 
   # Enable SSH access to EC2 instances
   ssh_access = true
 }
 
-# Connection information on the newly created cluster
+# Connection information for the newly created cluster
 output "cratedb" {
   value     = module.cratedb-cluster
   sensitive = true
@@ -78,12 +79,11 @@ output "cratedb" {
 
 ## Execution
 
-Once all variables are adjusted, we initialize Terraform by installing needed plugins:
-
+Once you adjust all variables, initialize Terraform by installing the needed plugins.
 ```bash
 $ terraform init   
 Initializing modules...
-Downloading [email protected]:crate/crate-terraform.git for cratedb-cluster...
+Downloading [email protected]:crate/cratedb-terraform.git for cratedb-cluster...
 - cratedb-cluster in .terraform/modules/cratedb-cluster/aws
 
 Initializing the backend...
@@ -112,7 +112,8 @@ Terraform has been successfully initialized!
 [...]
 ```
 
-Before deploying anything to the cloud, we can optionally print the planned resource creation that Terraform derived from the configuration (the output below is shortened):
+Before deploying, optionally print the planned resource creation derived from the
+configuration (shortened output below):
 ```bash
 $ terraform plan   
 
@@ -255,7 +256,8 @@ cratedb = <sensitive>
 ```
 
 ## Connecting to CrateDB
-The `cratedb` output element contains information on the newly created cluster, such as URL and credentials. Since it contains the admin password, the output is marked as sensitive and not immediately shown by Terraform. It can be made visible via the `terraform output` command:
+The `cratedb` output element contains information on the newly created cluster, such as URL and credentials.
+Since it contains the admin password, Terraform marks the output as sensitive and does not immediately display it. Use the `terraform output` command to display it:
 ```bash
 $ terraform output cratedb
 {
@@ -267,7 +269,13 @@ $ terraform output cratedb
 
 ## Teardown
 
-If you no longer need the deployed cluster, a simple `terraform destroy` from the same directory will suffice.
+:::{caution}
+This tutorial creates billable AWS resources. Destroy the stack when finished
+to avoid ongoing costs.
+:::
+
+If you no longer need the deployed cluster, a simple `terraform destroy` from
+the same directory will suffice.
 
 ```bash
 $ terraform destroy
@@ -291,16 +299,23 @@ Changes to Outputs:
 Destroy complete! Resources: 22 destroyed.
 ```
 
-For optimal security, a self-signed SSL certificate was automatically generated and deployed. After adding an exception in your browser to accept the certificate, the HTTP Basic Auth dialog of CrateDB’s Admin UI will show. Authenticate with the credentials retrieved from above.
+Terraform generates and deploys a self‑signed TLS certificate. After adding a
+browser exception, CrateDB’s Admin UI prompts for HTTP Basic Auth. Authenticate
+with the credentials shown above.
 
-If the credentials are rejected, or no authentication prompt appears, please wait for a couple of minutes and try again. Provisioning the virtual machines might not be complete yet and can take several minutes.
+If authentication fails or no prompt appears, wait a few minutes and retry;
+VM provisioning and service initialization can take several minutes.
 
 ## Final Remarks
 
-Please note that (as of now) the provided Terraform configuration is meant for development or testing purposes and doesn’t fulfill all requirements of a production-ready setup (i.e. regarding high availability, encryption, or backups). For production-ready setups, please consider [CrateDB Cloud](https://crate.io/products/cratedb-cloud/).
+This Terraform configuration targets development or testing and is not
+production‑ready (e.g. it does not touch high availability, encryption, backups).
+For production, consider using [CrateDB Cloud].
 
-If you have any feedback or requests to extend the configuration, please feel free to [open an issue on GitHub](https://github.com/crate/crate-terraform/issues) or let us know in this thread!
+To request enhancements or share feedback, [open an issue on GitHub].
 
 
+[CrateDB Cloud]: https://crate.io/products/cratedb-cloud/
+[open an issue on GitHub]: https://github.com/crate/cratedb-terraform/issues
 [README]: https://github.com/crate/cratedb-terraform/blob/main/azure/README.md
-[Terraform]: https://www.terraform.io/
+[Terraform]: https://developer.hashicorp.com/terraform