fix: documentation and variable description updates (#8)

Author: SirSpidey

README.md

@@ -1,5 +1,5 @@
 <!-- Update the title -->
-# Terraform IBM S2S Auth
+# Terraform IBM Service-to-service authorization module
 
 <!--
 Update status and "latest release" badges:
@@ -12,7 +12,7 @@ Update status and "latest release" badges:
 [![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com/)
 [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
 
-This module is responsible for generating authorization policies and CBR rules that enable access permissions and restrictions between a source service and a target service
+This module generates authorization policies and context-based restriction (CBR) rules to enable access and restrictions between a source service and a target service.
 
 <!-- Below content is automatically populated via pre-commit hook -->
 <!-- BEGIN OVERVIEW HOOK -->
@@ -109,11 +109,11 @@ You need the following permissions to run this module.
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_cbr_target_service_details"></a> [cbr\_target\_service\_details](#input\_cbr\_target\_service\_details) | Details of the target service for which the rule has to be created | <pre>list(object({<br>    target_service_name = string<br>    target_rg           = optional(string)<br>    enforcement_mode    = string<br>    tags                = optional(list(string))<br>  }))</pre> | `[]` | no |
-| <a name="input_prefix"></a> [prefix](#input\_prefix) | Prefix to append when creating CBR zones and CBR rules | `string` | `null` | no |
-| <a name="input_service_map"></a> [service\_map](#input\_service\_map) | Map of source service and the corresponding target service details | <pre>list(object({<br>    source_service_name         = string<br>    target_service_name         = string<br>    roles                       = list(string)<br>    description                 = optional(string, null)<br>    source_resource_instance_id = optional(string, null)<br>    target_resource_instance_id = optional(string, null)<br>    source_resource_group_id    = optional(string, null)<br>    target_resource_group_id    = optional(string, null)<br>  }))</pre> | `[]` | no |
-| <a name="input_zone_service_ref_list"></a> [zone\_service\_ref\_list](#input\_zone\_service\_ref\_list) | Service reference for the zone creation | `list(string)` | `[]` | no |
-| <a name="input_zone_vpc_crn_list"></a> [zone\_vpc\_crn\_list](#input\_zone\_vpc\_crn\_list) | VPC CRN for the zones | `list(string)` | `[]` | no |
+| <a name="input_cbr_target_service_details"></a> [cbr\_target\_service\_details](#input\_cbr\_target\_service\_details) | Details of the target service for which the rule has to be created. | <pre>list(object({<br>    target_service_name = string<br>    target_rg           = optional(string)<br>    enforcement_mode    = string<br>    tags                = optional(list(string))<br>  }))</pre> | `[]` | no |
+| <a name="input_prefix"></a> [prefix](#input\_prefix) | Prefix for new CBR zones and rules. | `string` | `null` | no |
+| <a name="input_service_map"></a> [service\_map](#input\_service\_map) | Map of source service and the corresponding target service details. | <pre>list(object({<br>    source_service_name         = string<br>    target_service_name         = string<br>    roles                       = list(string)<br>    description                 = optional(string, null)<br>    source_resource_instance_id = optional(string, null)<br>    target_resource_instance_id = optional(string, null)<br>    source_resource_group_id    = optional(string, null)<br>    target_resource_group_id    = optional(string, null)<br>  }))</pre> | `[]` | no |
+| <a name="input_zone_service_ref_list"></a> [zone\_service\_ref\_list](#input\_zone\_service\_ref\_list) | Service reference for the zone creation. | `list(string)` | `[]` | no |
+| <a name="input_zone_vpc_crn_list"></a> [zone\_vpc\_crn\_list](#input\_zone\_vpc\_crn\_list) | CRN of the VPC for the zones. | `list(string)` | `[]` | no |
 
 ### Outputs
 

examples/basic/README.md

@@ -6,8 +6,8 @@ Note, there is a pre-commit hook that will take the title of each example and in
 The text below should describe exactly what resources are provisioned / configured by the example.
 -->
 
-An end-to-end basic example that will provision the following:
+An end-to-end basic example that provisions the following resources:
 
-- A new resource group if one is not passed in.
-- An authorization policy for databases-for-postgresql -> kms.
-- A cbr rule for kms in the resource group.
+- A new resource group, if one is not passed in.
+- An authorization policy between the IBM Cloud Databases for PostgreSQL and Key Protect services.
+- A context-based restriction (CBR) rule for Key Protect in the resource group.

examples/basic/variables.tf

@@ -4,24 +4,24 @@
 
 variable "ibmcloud_api_key" {
   type        = string
-  description = "The IBM Cloud API Key"
+  description = "An IBM Cloud API key."
   sensitive   = true
 }
 
 variable "region" {
   type        = string
-  description = "Region to provision all resources created by this example"
+  description = "The region to provision all resources created by this example."
   default     = "us-south"
 }
 
 variable "prefix" {
   type        = string
-  description = "Prefix to append to all resources created by this example"
+  description = "The prefix for the resources created by this example."
   default     = "basic-s2s"
 }
 
 variable "resource_group" {
   type        = string
-  description = "The name of an existing resource group to provision resources in to. If not set a new resource group will be created using the prefix variable"
+  description = "The name of an existing resource group to provision the resources in. If not set, a resource group is created with the prefix variable."
   default     = null
 }

examples/complete/README.md

@@ -3,10 +3,10 @@
 <!-- There is a pre-commit hook that will take the title of each example add include it in the repos main README.md  -->
 <!-- Add text below should describe exactly what resources are provisioned / configured by the example  -->
 
-An example that creates authentication policies and context based restrictions
+An example that creates authentication policies and context-based restriction (CBR) rules.
 
-This example uses the IBM Cloud terraform provider to:
+This example uses the IBM Cloud terraform provider to provision the following resources:
 
-- Create resource groups if not provided
-- Create a Cloud Object Storage and Key protect instance instance
-- Create auth policies and CBR rules for the newly created services
+- Create resource groups, if not provided.
+- Create instances of the Cloud Object Storage and Key Protect services.
+- Create authorization policies and CBR rules for the newly created services.

examples/complete/variables.tf

@@ -1,35 +1,35 @@
 variable "ibmcloud_api_key" {
   type        = string
-  description = "The IBM Cloud API Key"
+  description = "An IBM Cloud API key."
   sensitive   = true
 }
 
 variable "region" {
   type        = string
-  description = "Region to provision all resources created by this example"
+  description = "The region to provision all resources created by this example."
   default     = "us-south"
 }
 
 variable "prefix" {
   type        = string
-  description = "Prefix to append to all resources created by this example"
+  description = "The prefix for the resources created by this example."
   default     = "complete-s2s"
 }
 
 variable "resource_group" {
   type        = string
-  description = "An existing resource group name to use for this example, if unset a new resource group will be created"
+  description = "The name of an existing resource group to provision the resources in. If not set, a resource group is created with the prefix variable."
   default     = null
 }
 
 variable "resource_tags" {
   type        = list(string)
-  description = "Optional list of tags to be added to created resources"
+  description = "Optional list of tags to add to new resources"
   default     = []
 }
 
 variable "enforcement_mode" {
   type        = string
-  description = "The rule enforcement mode"
+  description = "The CBR rule enforcement mode."
   default     = "report"
 }

variables.tf

@@ -4,12 +4,12 @@
 
 variable "prefix" {
   type        = string
-  description = "Prefix to append when creating CBR zones and CBR rules"
+  description = "Prefix for new CBR zones and rules."
   default     = null
 }
 
 variable "service_map" {
-  description = "Map of source service and the corresponding target service details"
+  description = "Map of source service and the corresponding target service details."
   type = list(object({
     source_service_name         = string
     target_service_name         = string
@@ -47,7 +47,7 @@ variable "service_map" {
         "kms", "internet-svcs", "atracker", "sql-query", "hs-crypto", "server-protect"],
       service.target_service_name)
     ])
-    error_message = "Provide a valid service for auth policy creation"
+    error_message = "Provide a valid service for authorization policy creation."
   }
 
   validation {
@@ -76,18 +76,18 @@ variable "cbr_target_service_details" {
     enforcement_mode    = string
     tags                = optional(list(string))
   }))
-  description = "Details of the target service for which the rule has to be created"
+  description = "Details of the target service for which the rule has to be created."
   default     = []
 }
 
 variable "zone_service_ref_list" {
   type        = list(string)
   default     = []
-  description = "Service reference for the zone creation"
+  description = "Service reference for the zone creation."
 }
 
 variable "zone_vpc_crn_list" {
   type        = list(string)
   default     = []
-  description = "VPC CRN for the zones"
+  description = "CRN of the VPC for the zones."
 }