From ec78d6217df62a5013c8932dee36ea32f38d9ad7 Mon Sep 17 00:00:00 2001 From: Vincent Burckhardt Date: Wed, 17 Jan 2024 14:27:43 +0000 Subject: [PATCH] Edit markdown documents --- README.md | 4 +-- docs/README.md | 39 +++++++++++++++--------------- docs/access-ocp-api-through-cis.md | 20 +++++++-------- examples/complete/README.md | 6 ++--- tests/README.md | 2 +- 5 files changed, 35 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index ee5d926d..df5ed869 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,11 @@ [![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 provisions an IBM Cloud Internet Services (CIS) instance and configures domain to the CIS instance. The module includes the submodules to add the following features to a CIS instance. +This module provisions an IBM Cloud Internet Services (CIS) instance and configures the domain to the CIS instance. The module includes submodules to add the following features to a CIS instance: * Domain * DNS records -* Global load balancer (GLB) including load balancers, origin pools and health checks +* Global load balancer (GLB), including load balancers, origin pools, and health checks * Web Application Firewall (WAF) For more information about the module, see, read [Features of IBM Cloud Internet Services module](https://github.com/terraform-ibm-modules/terraform-ibm-cis/tree/main/docs/README.md). diff --git a/docs/README.md b/docs/README.md index 20f60575..98609690 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,33 +1,33 @@ # Features of IBM Cloud Internet Services module -IBM Cloud Internet Services (CIS), powered by Cloudflare, provides security, reliability and performance for customers running their business on IBM Cloud. +IBM Cloud Internet Services (CIS), powered by Cloudflare, provides security, reliability, and performance for customers running their business on IBM Cloud. Through this CIS module, you can configure the domain, manage DNS records, set up a global load balancer, activate the Web Application Firewall (WAF), and complete other tasks. For more information, see [About IBM Cloud Internet Services](https://cloud.ibm.com/docs/cis?topic=cis-about-ibm-cloud-internet-services-cis). -## Activating DDOS protection +### Activating DDoS Protection CIS can provide protection against distributed denial of service (DDoS) attacks by proxying traffic for some types of DNS records, such as `A`, `AAAA`, and `CNAME` records. For more information, see the [DNS record](https://cloud.ibm.com/docs/cli?topic=cli-cis-cli#dns-record) section of the CIS CLI reference. Activating DDoS protection requires that you set the following conditions: - * The domain must be active. - * The global load balancer( GLB) or DNS records must be proxied. +* The domain must be active. +* The global load balancer (GLB) or DNS records must be proxied. For more information about proxy options, see [About IBM Cloud Internet Services](https://cloud.ibm.com/docs/cis?topic=cis-about-ibm-cloud-internet-services-cis). -## About the CIS submodules +## About the CIS Submodules -The CIS module has a number of submodules to configure a domain to the CIS instance, add and manage DNS records, set up a load balancer with origin pool and health checks, and enable or disable a web application firewall. +The CIS module has several submodules to configure a domain to the CIS instance, add and manage DNS records, set up a load balancer with origin pool and health checks, and enable or disable a web application firewall. -### Domain submodule +### Domain Submodule -The [domain submodule](https://github.com/terraform-ibm-modules/terraform-ibm-cis/blob/main/modules/domain/) provides the Terraform resources that are required to add and configure a domain in a CIS instance. For more information, see [Domain lifecycle concepts](https://cloud.ibm.com/docs/cis?topic=cis-domain-lifecycle-concepts). +The [domain submodule](https://github.com/terraform-ibm-modules/terraform-ibm-cis/blob/main/modules/domain/) offers the Terraform resources required to add and configure a domain in a CIS instance. For further information, refer to [Domain Lifecycle Concepts](https://cloud.ibm.com/docs/cis?topic=cis-domain-lifecycle-concepts). After this module runs successfully, the status of the domain that is configured in the CIS instance is set to `pending`. You then configure the name servers that are assigned to the domain at the DNS provider or registrar. You can find the assigned name servers in the `name_servers` variable of the module output. The status changes to `active` after the name servers are configured correctly at the DNS provider or registrar. -### DNS submodule +### DNS Submodule -The [Domain name system (DNS) submodule](https://github.com/terraform-ibm-modules/terraform-ibm-cis/tree/main/modules/dns) provides the Terraform resources to create and manage DNS records in a CIS instance. For more information, see [Setting up your Domain Name System for CIS](https://cloud.ibm.com/docs/cis?topic=cis-set-up-your-dns-for-cis). +The [Domain Name System (DNS) submodule](https://github.com/terraform-ibm-modules/terraform-ibm-cis/tree/main/modules/dns) provides the Terraform resources to create and manage DNS records in a CIS instance. For more information, see [Setting up your Domain Name System for CIS](https://cloud.ibm.com/docs/cis?topic=cis-set-up-your-dns-for-cis). If you add an SRV record, it is stored as `_service._proto.record_name.domain_name TTL class type of record priority weight port target`. This is true even though the record name is provided in the variable. For more information, see [What is a DNS SRV record?](https://www.cloudflare.com/en-gb/learning/dns/dns-records/dns-srv-record/). @@ -38,13 +38,12 @@ The changed name means that when you run a `terraform plan` command after a succ id = "a5177ec049fc2973a33df1441e869a27:9684838a87ecxxx5518:crn:v1:bluemix:public:internet-svcs:global:a/abac0df06b644axxx4f55b3880e:6ee7ec9a-5e68-4b6f-af9a-5714xxx4d::" ~ name = "_sip._udp.test-example.srv.test**.**.com" -> "test-example.srv" # (13 unchanged attributes hidden) - } If you add a CAA record, a `flags` parameter is returned in the data object. The work is being tracked [here](https://github.com/IBM-Cloud/terraform-provider-ibm/issues/4792). The returned `flags` parameter means that when you run a `terraform plan` command after a successful `terraform apply`, the output shows that the DNS record requires an update, as shown in the following example. You can ignore that message. Your infrastructure will not be affected. - # module.cis_dns_records.ibm_cis_dns_record.dns_records["test-exmple.caa/CAA"] will be updated in-place + # module.cis_dns_records.ibm_cis_dns_record.dns_records["test-example.caa/CAA"] will be updated in-place ~ resource "ibm_cis_dns_record" "dns_records" { ~ data = { - "flags" = "0" -> null @@ -54,18 +53,18 @@ The returned `flags` parameter means that when you run a `terraform plan` comman # (12 unchanged attributes hidden) } -This module allows you to import DNS records from a file in the following two ways: +This module enables you to import DNS records from a file in two ways: -- By specifying the file path directly -- By using a base64-encoded string representation of the file +- Specifying the file path directly +- Utilizing a base64-encoded string representation of the file -To convert the records text file to base64 encoded string, run the following command: +To transform the records text file into a base64-encoded string, execute the following command: ```sh cat dns_records.txt | base64 ``` -If you successfully import the DNS records using the base64 encoded string method and then run a `terraform plan` command, you receive a message that the `ibm_cis_dns_records_import` resource and the `local_file` resource need to be forcefully replaced, as shown in the following example. This happens because the `local_file` resource block generates a unique filename every time, and needs to be updated. However, if you run `terraform apply`, then the DNS records are not duplicated, and the infrastructure remains the same. +If you successfully import the DNS records using the base64 encoded string method and then run a `terraform plan` command, you receive a message indicating that the `ibm_cis_dns_records_import` resource and the `local_file` resource need to be forcefully replaced, as shown in the following example. This occurs because the `local_file` resource block generates a unique filename every time, and needs to be updated. However, if you run `terraform apply`, then the DNS records are not duplicated, and the infrastructure remains unchanged. # module.cis_dns_records.ibm_cis_dns_records_import.import_dns_records[0] must be replaced -/+ resource "ibm_cis_dns_records_import" "import_dns_records" { @@ -75,7 +74,7 @@ If you successfully import the DNS records using the base64 encoded string metho } # module.cis_dns_records.local_file.dns_record_file[0] must be replaced -/+ resource "local_file" "dns_record_file" { - ~ filename = "../../modules/dns/dns_records_2023-12-10T09:29:24Z.txt"-> (known after apply) # forces replacement + ~ filename = "../../modules/dns/dns_records_2023-12-10T09:29:24Z.txt" -> (known after apply) # forces replacement ~ id = "de87dcxxxxfec671eexxxxxxxxx30accaxxxxa13" -> (known after apply) # (3 unchanged attributes hidden) } @@ -95,9 +94,9 @@ It shows the following changes to the output in the following example. You can i ] } -### GLB submodule +### GLB Submodule -The [Global load balancer (GLB) submodule](https://github.com/terraform-ibm-modules/terraform-ibm-cis/blob/main/modules/glb/) provides Terraform resources to create and manage global load balancers in a CIS instance. It also allows you to configure health checks, origin pools, and proxy settings. For more information, see [Global load balancer concepts](https://cloud.ibm.com/docs/cis?topic=cis-global-load-balancer-glb-concepts). +The [Global Load Balancer (GLB) Submodule](https://github.com/terraform-ibm-modules/terraform-ibm-cis/blob/main/modules/glb/) provides Terraform resources to create and manage global load balancers in a CIS instance. It also allows you to configure health checks, origin pools, and proxy settings. For more information, see [Global Load Balancer Concepts](https://cloud.ibm.com/docs/cis?topic=cis-global-load-balancer-glb-concepts). When `glb_proxied` is set as `true`, then `ttl` is automatically set and cannot be updated. diff --git a/docs/access-ocp-api-through-cis.md b/docs/access-ocp-api-through-cis.md index efa804ca..f5b41616 100644 --- a/docs/access-ocp-api-through-cis.md +++ b/docs/access-ocp-api-through-cis.md @@ -1,13 +1,13 @@ -# Configuring access to an application deployed on Red Hat OpenShift through CIS +# Configuring Access to an Application Deployed on Red Hat OpenShift through CIS Hosting web applications is a common deployment pattern for public cloud. You can use Cloud Internet Services to provide secure access over the internet to your application deployed in a Red Hat OpenShift cluster. -## Before you begin +## Before You Begin -- You need a Red Hat OpenShift cluster on IBM Cloud with an app deployed in the cluster. For more information, see [Deploying apps in Red Hat OpenShift clusters](https://cloud.ibm.com/docs/openshift?topic=openshift-deploy_app&interface=ui). +- You need a Red Hat OpenShift cluster on IBM Cloud with an app deployed in the cluster. For more information, see [Deploying Apps in Red Hat OpenShift Clusters](https://cloud.ibm.com/docs/openshift?topic=openshift-deploy_app&interface=ui). - You also need an instance of Cloud Internet Services with an active domain name. You can use this [CIS module](https://github.com/terraform-ibm-modules/terraform-ibm-cis) to create and configure the instance. -- Make sure that you have the [OpenShift CLI installed](https://cloud.ibm.com/docs/openshift?topic=openshift-cli-install). +- Ensure that you have the [OpenShift CLI installed](https://cloud.ibm.com/docs/openshift?topic=openshift-cli-install). - Make sure that you have the [IBM Cloud CLI installed](https://cloud.ibm.com/docs/cli?topic=cli-getting-started). ## Add a DNS entry @@ -26,15 +26,15 @@ Hosting web applications is a common deployment pattern for public cloud. You ca For example, the CIS domain is `example.com`, the DNS record name is `test`, and the application endpoint is `/healthz`. The URL to access will be `https://test.example.com/healthz`. If you try to connect to your URL, you get an SSL handshake error because the SSL certificates are not yet set up. -## Configuring your SSL certificate +## Configuring your SSL Certificate -To establish a secure connection between the client and server, you need to an SSL certificate. You can generate the certificate can be generated by using IBM Cloud [Secrets Manager](https://cloud.ibm.com/catalog/services/secrets-manager). +To establish a secure connection between the client and server, you need to obtain an SSL certificate. You can generate the certificate using IBM Cloud [Secrets Manager](https://cloud.ibm.com/catalog/services/secrets-manager). -1. Order a certificate in Secrets Manager: +1. Order a Certificate in Secrets Manager: 1. Open the Secrets Manager service and select `Secrets` on the left. 1. Click **Add**. - 1. If you are using a new Secrets Manager instance, you need to configure it before you order your certificate. Follow the steps that are outlined under [Preparing to order public certificates](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-prepare-order-certificates&interface=ui). + 1. If you are using a new Secrets Manager instance, you need to configure it before you order your certificate. Follow the steps outlined under [Preparing to order public certificates](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-prepare-order-certificates&interface=ui). 1. Click **Public certificate**, and then click **Next**. 1. Complete the form. Add a name and description. 1. Click **Next**. @@ -47,8 +47,8 @@ To establish a secure connection between the client and server, you need to an S 1. Add the domains to include in your request. Check the subdomain, and then click **Done**. 1. Click **Next**. 1. Review your selections and click **Add**. -1. Download the certificates in Secrets Manager. It has `.key` and `.pem` file. -1. Run the following commands on the command line to create secrets in your cluster that use the downloaded certificates. +1. Download the certificates in Secrets Manager, which include `.key` and `.pem` files. +1. Run the following commands on the command line to create secrets in your cluster using the downloaded certificates. ```sh ibmcloud login --apikey diff --git a/examples/complete/README.md b/examples/complete/README.md index e2712e4c..33ee128a 100644 --- a/examples/complete/README.md +++ b/examples/complete/README.md @@ -1,11 +1,11 @@ -# End-to-end example +# End-to-End Example An end-to-end example that provisions the following infrastructure: - Creates a new resource group, if one is not passed in. - Creates a Cloud Internet Services (CIS) instance. - Adds a domain to the CIS instance. - Adds DNS records to the CIS instance. -- Adds a global load balancer including the origin pools and health checks to the CIS instance. +- Adds a global load balancer, including the origin pools and health checks, to the CIS instance. -For information about accessing an application through CIS, see [Configuring access to an application deployed on Red Hat OpenShift through CIS](https://github.com/terraform-ibm-modules/terraform-ibm-cis/tree/main/docs/access-ocp-api-through-cis.md). +For information about accessing an application through CIS, see [Configuring Access to an Application Deployed on Red Hat OpenShift through CIS](https://github.com/terraform-ibm-modules/terraform-ibm-cis/tree/main/docs/access-ocp-api-through-cis.md). diff --git a/tests/README.md b/tests/README.md index dfd68426..7565d4c1 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1,5 +1,5 @@ # 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.