Update markdown documents

README.md

@@ -1,14 +1,14 @@
-# Context-based restrictions module
+# Context-based Restrictions Module
 
 [![Graduated (Supported)](https://img.shields.io/badge/Status-Graduated%20(Supported)-brightgreen)](https://terraform-ibm-modules.github.io/documentation/#/badge-status)
 [![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)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
 [![latest release](https://img.shields.io/github/v/release/terraform-ibm-modules/terraform-ibm-cbr?logo=GitHub&sort=semver)](https://github.com/terraform-ibm-modules/terraform-ibm-cbr/releases/latest)
 [![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com/)
 
-This module can be used to provision and configure [Context Based Restrictions](https://cloud.ibm.com/docs/account?topic=account-context-restrictions-create&interface=ui).
+This module can be used to provision and configure [Context-Based Restrictions](https://cloud.ibm.com/docs/account?topic=account-context-restrictions-create&interface=ui).
 
-See in particular the [fscloud module](./modules/fscloud/) that enables creating an opiniated account-level coarse-grained set of CBR rules and zones aligned with the "secure by default" principles.
+See in particular the [fscloud module](./modules/fscloud/) that creates an opinionated account-level set of CBR rules and zones that are aligned with "secure by default" principles.
 
 :information_source: **Tip:** Changes to context-based restriction rules are propagated worldwide and have a TTL value of 10 minutes. Rule changes might not take effect until the propagation process is complete and the TTL cache is updated.
 
@@ -21,11 +21,11 @@ See in particular the [fscloud module](./modules/fscloud/) that enables creating
     * [cbr-zone-module](./modules/cbr-zone-module)
     * [fscloud](./modules/fscloud)
 * [Examples](./examples)
-    * [CBR multi service profile](./examples/multi-service-profile)
-    * [Multi resource rule example](./examples/multi-resource-rule)
-    * [Multi-zone example](./examples/multizone-rule)
-    * [Pre-wired CBR configuration for FS Cloud example](./examples/fscloud)
-    * [Zone example](./examples/zone)
+    * [CBR Multi Service Profile](./examples/multi-service-profile)
+    * [Multi-Resource Rule Example](./examples/multi-resource-rule)
+    * [Multi-zone Example](./examples/multizone-rule)
+    * [Pre-wired CBR Configuration for FS Cloud Example](./examples/fscloud)
+    * [Zone Example](./examples/zone)
 * [Contributing](#contributing)
 <!-- END OVERVIEW HOOK -->
 
@@ -149,4 +149,4 @@ You need the following permissions to run this module.
 
 You can report issues and request features for this module in GitHub issues in the module repo. See [Report an issue or request a feature](https://github.com/terraform-ibm-modules/.github/blob/main/.github/SUPPORT.md).
 
-To set up your local development environment, see [Local development setup](https://terraform-ibm-modules.github.io/documentation/#/local-dev-setup) in the project documentation.
+To set up your local development environment, see [Local Development Setup](https://terraform-ibm-modules.github.io/documentation/#/local-dev-setup) in the project documentation.

examples/fscloud/README.md

@@ -1,20 +1,22 @@
-# Pre-wired CBR configuration for FS Cloud example
+# Pre-wired CBR Configuration for FS Cloud Example
 
 This example demonstrates how to use the [fscloud profile](../../profiles/fscloud/) module to lay out a complete "secure by default" coarse-grained CBR topology in a given account.
 
-This examples is designed to show case some of the key customization options for the module. In addition to the pre-wired CBR rules documented at [fscloud profile](../../profiles/fscloud/), this examples show how to customize the module to:
-1. Open up network traffic flow from ICD mongodb, ICD Postgresql to the Key Protect private endpoints.
-2. Open up network traffic flow from Schematics to Key Protect public endpoints.
-3. Open up network traffic flow from a block of IPs to the Schematics public endpoint.
-4. Open up network traffic flow from the VPC created in this example to ICD postgresql private endpoints.
+This example showcases some of the key customization options for the module. In addition to the pre-wired CBR rules documented at [fscloud profile](../../profiles/fscloud/), this example includes the following customizations:
+1. Allow network traffic flow from ICD MongoDB, ICD PostgreSQL to the Key Protect private endpoints.
+2. Allow network traffic flow from Schematics to Key Protect public endpoints.
+3. Allow network traffic flow from a block of IPs to the Schematics public endpoint.
+4. Allow network traffic flow from the VPC created in this example to ICD PostgreSQL private endpoints.
 5. Customize the rule description for `kms` and the zone name for `codeengine`.
 
-Context: this examples covers a "pseudo" real-world scenario where:
-1. ICD Mongodb and Postgresql instances are encrypted using keys storage in Key Protect.
-2. Schematics is used to execute terraform that create Key Protect keys and key ring over its public endpoint.
-3. Operators use machines with a set list of public IPs to interact with Schematics.
-4. Applications are running the VPC and need access to PostgreSQL via the private endpoint - eg: a VPE.
-5. Skips creation of zones for these two service references ["user-management", "iam-groups"].
+
+The example covers the following example scenario:
+
+- The instances of Databases for MongoDB and Databases for Postgresql are encrypted with keys that are stored in Key Protect.
+- Schematics is used to execute the Terraform logic that creates Key Protect keys and key rings over its public endpoint.
+- Operators use machines with a set list of public IPs to interact with Schematics.
+- Applications are running in the VPC and need access to PostgreSQL via the private endpoint. For example with a VPE.
+- Skips creation of zones for these two service references ["user-management", "iam-groups"].
 
 ## Note
-- The services 'compliance', 'directlink', 'iam-groups', 'containers-kubernetes', 'user-management' do not support restriction per location for zone creation.
+- The services 'compliance', 'directlink', 'iam-groups', 'containers-kubernetes', 'user-management' do not support location-based restrictions for zone creation.

examples/multi-resource-rule/README.md

@@ -1,9 +1,9 @@
-# Multi resource rule example
+# Multi-Resource Rule Example
 
-An end-to-end example to show how to apply a rule to multiple resources. This example uses the IBM Cloud Provider to automate the following infrastructure:
+An end-to-end example to demonstrate how to apply a rule to multiple resources. This example leverages the IBM Cloud Provider to automate the following infrastructure:
 
 - Creates a VPC
 - Creates a VPC Subnet
 - Creates a CBR Zone for the VPC
 - Creates a COS Instance and a COS Bucket
-- Applies a single CBR rule to only allow access form the VPC zone to the COS Instance and the same rule for the Bucket
+- Applies a single CBR rule to allow access only from the VPC zone to the COS Instance and to the bucket

examples/multi-service-profile/README.md

@@ -1,12 +1,12 @@
-# CBR multi service profile
+# CBR Multi Service Profile
 
-An end-to-end example that uses the submodule cbr-service-profile. This example uses the IBM Cloud Provider to automate the following infrastructure::
+An end-to-end example that uses the submodule cbr-service-profile. This example leverages the IBM Cloud Provider to automate the following infrastructure:
 
- - Create a VPC and create a CBR zone to allowlist the VPC.
- - Create a service reference based CBR zone.
- - Create a set of CBR rules.
-   - Based on the list of target service details provided, create rules for each of them.
-   - Target service instances access is granted based on the following parameters.
-     - Based on the account.
-     - Based on the access tags.
-     - Based on the resource group.
+- Create a VPC and create a CBR zone to allow access to the VPC.
+- Create a service reference-based CBR zone.
+- Create a set of CBR rules.
+  - Based on the list of target service details provided, create rules for each of them.
+  - Target service instances access is granted based on the following parameters:
+    - Based on the account.
+    - Based on the access tags.
+    - Based on the resource group.

examples/multizone-rule/README.md

@@ -1,6 +1,6 @@
-# Multi-zone example
+# Multi-zone Example
 
-An end-to-end example that uses the module's default variable values. This example uses the IBM Cloud Provider to automate the following infrastructure::
+An end-to-end example that utilizes the module's default variable values. This example leverages the IBM Cloud Provider to automate the following infrastructure:
 
- - Create two zones for context-based restrictions.
- - Create a rule for context-based restrictions that uses the zone and attaches the service to it.
+* Create two zones for context-based restrictions.
+* Create a rule for context-based restrictions that uses the zone and attaches the service to it.

examples/zone/README.md

@@ -1,3 +1,3 @@
-# Zone example
+# Zone Example
 
 Example that creates a zone for context-based restrictions.

modules/fscloud/README.md

@@ -1,27 +1,29 @@
 # Pre-wired CBR configuration for FS Cloud
 
-This module creates default coarse-grained CBR rules in a given account following a "secure by default" approach - that is: deny all flows by default, except known documented communication in the [Financial Services Cloud Reference Architecture](https://cloud.ibm.com/docs/framework-financial-services?topic=framework-financial-services-vpc-architecture-about):
+This module creates default coarse-grained CBR rules in a given account, following a "secure by default" approach. By default, the rules deny all flows except for the documented communication in the [reference architecture for IBM Cloud for Financial Services](https://cloud.ibm.com/docs/framework-financial-services?topic=framework-financial-services-vpc-architecture-about).
+
+The module creates the following rules:
 - Cloud Object Storage (COS) -> Key Management Service (KMS)
 - Block Storage -> Key Management Service (KMS)
 - IBM Cloud Kubernetes Service (IKS) -> Key Management Service (KMS)
 - All IBM Cloud Databases (ICD) services -> Key Management Service (KMS)
 - Activity Tracker route -> Cloud Object Storage (COS)
 - Virtual Private Clouds (VPCs) where clusters are deployed -> Cloud Object Storage (COS)
 - IBM Cloud VPC Infrastructure Services (IS) -> Cloud Object Storage (COS)
-- Virtual Private Cloud workload (eg: Kubernetes worker nodes) -> IBM Cloud Container Registry
+- Virtual Private Cloud workload (e.g., Kubernetes worker nodes) -> IBM Cloud Container Registry
 - IBM Cloud Databases (ICD) -> Hyper Protect Crypto Services (HPCS)
 - IBM Cloud Kubernetes Service (IKS) -> IS (VPC Infrastructure Services)
 
 
-**Note on KMS**: the module supports setting up rules for Key Protect, and Hyper Protect Crypto Services. By default the modules set rules for Hyper Protect Crypto Services, but this can be modified to use Key Protect, Hyper Protect, or both Key Protect and Hyper Protect Crypto Services using the input variable `kms_service_targeted_by_prewired_rules`.
+**Note on KMS**: The module supports setting up rules for Key Protect and Hyper Protect Crypto Services. By default, the module sets rules for Hyper Protect Crypto Services, but this can be modified to use Key Protect, Hyper Protect, or both Key Protect and Hyper Protect Crypto Services using the input variable `kms_service_targeted_by_prewired_rules`.
 
-**Note on containers-kubernetes**: the module supports the pseudo-service names `containers-kubernetes-management` and `containers-kubernetes-cluster` to distinguish between the cluster and management APIs (see [details](https://cloud.ibm.com/docs/containers?topic=containers-cbr&interface=ui#protect-api-types-cbr) ). The module creates separates CBR rules for the two types of APIs by default to align with common real-world scenarios. `containers-kubernetes` can be used to create a CBR targetting both the cluster and management APIs.
+**Note on containers-kubernetes**: The module supports the pseudo-service names `containers-kubernetes-management` and `containers-kubernetes-cluster` to distinguish between the cluster and management APIs. For more information, see the [Protecting specific APIs](https://cloud.ibm.com/docs/containers?topic=containers-cbr&interface=ui#protect-api-types-cbr) section of Protecting cluster resources with context-based restrictions. By default, the module creates separate CBR rules for the two types of APIs to align with common real-world scenarios. `containers-kubernetes` can be used to create a CBR that targets both the cluster and management APIs.
 
 This module is designed to allow the consumer to add additional custom rules to open up additional flows necessarity for their usage. See the `custom_rule_contexts_by_service` input variable, and an [usage example](../../examples/fscloud/) demonstrating how to open up more flows.
 
-The module also pre-create CBR zone for each service in the account as a best practice. CBR rules associated with these CBR zone can be set by using the `custom_rule_contexts_by_service` variable.
+As a best practice, the module also creates CBR zones for each service in the account. You can set CBR rules for these CBR zones by using the `custom_rule_contexts_by_service` variable.
 
-Important: In order to avoid unexpected breakage in the account against which this module is executed, the CBR rule enforcement mode is set to 'report' (or 'disabled' for services not supporting 'report' mode) by default. It is recommended to test out this module first with these default, and then use the `target_service_details` variable to set the enforcement mode to "enabled" gradually by service. The [usage example](../../examples/fscloud/) demonstrates how to set the enforcement mode to 'enabled' for the key protect ("kms") service.
+Important: To avoid failures in the account against which this module is executed, be default, the CBR rule enforcement mode is set to 'report' mode (or to 'disabled' for services that don't support 'report' mode). Test the module with these default settings. Then, service by service, update the enforcement mode in the `target_service_details` variable to "enabled". The [usage example](../../examples/fscloud/) demonstrates how to set the enforcement mode to 'enabled' for the Key Protect ("kms") service.
 
 ## Note
 The services 'compliance', 'directlink', 'iam-groups', 'containers-kubernetes', 'user-management' does not support restriction per location.

tests/README.md

@@ -2,7 +2,7 @@
 
 # Tests
 
-For information about how to create and run tests, see [Validation tests](https://terraform-ibm-modules.github.io/documentation/#/tests) in the project documentation.
+For information about how to create and run tests, see [Validation Tests](https://terraform-ibm-modules.github.io/documentation/#/tests) in the project documentation.
 
 <!-- Add any more steps that are specific to testing this module and that are not in the docs. -->
 <!-- END TESTS HOOK -->