diff --git a/README.md b/README.md index afdead0..769f48e 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # Solace PubSub+ Software Event Broker REST Delivery Terraform Module -Terraform module to support the setup of a [REST consumer](https://docs.solace.com/API/REST/REST-Consumers.htm) on the [Solace PubSub+ Event Broker](https://solace.com/products/event-broker/). +This Terraform module supports the setup of a [REST consumer](https://docs.solace.com/API/REST/REST-Consumers.htm) on the [Solace PubSub+ Event Broker](https://solace.com/products/event-broker/). Given a queue on the broker, as a destination for messages to be forwarded to a REST consumer application, this module configures a [REST delivery point](https://docs.solace.com/API/REST/REST-Consumers.htm#_Toc433874658) between the queue and the application. -Specific use case details are provided in the [Examples](#examples). +Specific use case details are provided in the [Examples](#examples) section. ## Limitations @@ -25,12 +25,12 @@ Important: The REST delivery point must have permission to consume messages from ### Optional -* `client_profile_name` - the [client profile associated](https://docs.solace.com/Services/Managing-RDPs.htm#associating-client-profiles-with-REST-delivery-points). If not provided, the `default` client profile for the Message VPN will be associated. -* `request_headers` - A set of request headers to be added to the HTTP request -* `protected_request_headers` - A set of protected request headers with sensitive value to be added to the HTTP request +* `client_profile_name` - The [client profile associated](https://docs.solace.com/Services/Managing-RDPs.htm#associating-client-profiles-with-REST-delivery-points). If not provided, the `default` client profile for the Message VPN will be associated. +* `request_headers` - A set of request headers to be added to the HTTP request. +* `protected_request_headers` - A set of protected request headers with sensitive value to be added to the HTTP request. * `rest_consumer_name` - The name of the REST consumer to be created. The default is `consumer`. -Additional optional module variables names are the same as the underlying resource attributes. The recommended approach to determine variable name mappings is to look up the resource's documentation for matching attribute names: +Additional optional module variables names are the same as the underlying resource attributes. To determine the variable name mappings, we recommend that you look for matching attribute names in the documentation for the resource: | Resource name | |---------------| @@ -40,7 +40,7 @@ Additional optional module variables names are the same as the underlying resour |[solacebroker_msg_vpn_rest_delivery_point_queue_binding_request_header](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_rest_delivery_point_queue_binding_request_header#optional)| |[solacebroker_msg_vpn_rest_delivery_point_queue_binding_protected_request_header](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_rest_delivery_point_queue_binding_protected_request_header#optional)| -Most optional variables' default value is `null`, meaning that if not provided then the resource default value will be provisioned on the broker. +The default value for most of the optional variables is `null`, meaning that if you don’t provide a value then the default value of the resource is provisioned on the event broker. -> The module default for the `enabled` optional variable is `true`, which differ from the resource attribute default. @@ -58,7 +58,7 @@ Note that the "rest consumer" and the "protected request headers" outputs are [s ## Resources -The following table shows the resources created. "X" denotes a resource always created, "O" is a resource that may be created optionally +The following table shows the resources created. "X" denotes a resource that is always created, "O" denotes a resource that you have the option to create. | Name | | |------|------| @@ -70,7 +70,7 @@ The following table shows the resources created. "X" denotes a resource always c ## Examples -Refer to the following configuration examples: +The following examples demonstrate several specific use cases for this module: - [Basic](examples/basic) - [Substitution expressions](examples/using-substitution-expressions) diff --git a/examples/adding-headers/README.md b/examples/adding-headers/README.md index d282b86..7ffc95a 100644 --- a/examples/adding-headers/README.md +++ b/examples/adding-headers/README.md @@ -9,25 +9,25 @@ There are two types of request header resources: The REST Delivery module supports a set of "Request headers" and "Protected request headers" to be passed as input variables. -The example shows setting the sensitive `protected_request_headers` variable with a `.tfvars` file, as described in the [Protect sensitive input variables](https://developer.hashicorp.com/terraform/tutorials/configuration-language/sensitive-variables#set-values-with-a-tfvars-file) Terraform tutorial. +The example shows how to set the sensitive `protected_request_headers` variable with a `.tfvars` file, as described in the [Protect sensitive input variables](https://developer.hashicorp.com/terraform/tutorials/configuration-language/sensitive-variables#set-values-with-a-tfvars-file) Terraform tutorial. ## Module Configuration in the Example ### Required Inputs -* `msg_vpn_name` - set to `default` in the example +* `msg_vpn_name` - Set to `default` in the example. * `rest_delivery_point_name` -* `url` - set to `https://example.com/test` in the example. -* `queue_name` - `rdp_queue`, the queue that has been created to be used with the RDP +* `url` - Set to `https://example.com/test` in the example. +* `queue_name` - Set to `rdp_queue`, the queue that has been created to be used with the RDP. Important: The REST delivery point must have permission to consume messages from the queue — to achieve this, the queue’s owner must be set to `#rdp/` or the queue’s permissions for non-owner clients must be set to at least `consume` level access. Queue ingress and egress must also be enabled. ### Optional Inputs -* `request_headers` - provided as a set of objects in the example. Also check the [using-substitution-expressions](/examples/using-substitution-expressions) example for additional samples. -* `protected_request_headers` - provided as a set of objects in the example +* `request_headers` - Provided as a set of objects in the example. Also check the [using-substitution-expressions](/examples/using-substitution-expressions) example for additional samples. +* `protected_request_headers` - Provided as a set of objects in the example. -Optional module input variables have the same name as the attributes of the underlying provider resource. If omitted then the default for the related resource attribute will be configured on the broker. For attributes and defaults, refer to the [documentation of "solacebroker_msg_vpn_rest_delivery_point_queue_binding"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_rest_delivery_point_queue_binding#optional). +Optional module input variables have the same name as the attributes of the underlying provider resource. If omitted, then the default for the related resource attribute will be configured on the broker. For a list of attributes and the corresponding defaults, see the [documentation of "solacebroker_msg_vpn_rest_delivery_point_queue_binding"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_rest_delivery_point_queue_binding#optional). The module default for the `enabled` variable is true, which enables both the RDP and the REST consumer resources. @@ -35,9 +35,9 @@ The module default for the `enabled` variable is true, which enables both the RD The module `rdp`, `consumer` and `queue_binding` outputs refer to the created REST delivery point, REST consumer and queue binding. -## Created resources +## Created Resources -This example will create following resources: +This example will create the following resources: * `solacebroker_msg_vpn_queue` (created before the module, as pre-requisite)

@@ -50,11 +50,11 @@ This example will create following resources: ## Running the Example -### Access to a PubSub+ broker +### Access to a PubSub+ Event Broker -If you don't already have access to a broker, refer to the [Developers page](https://www.solace.dev/) for options to get started. +If you don't already have access to a broker, see the [Developers page](https://www.solace.dev/) for options to get started. -### Sample source code +### Sample Source Code The sample is available from the module GitHub repo: @@ -63,13 +63,13 @@ git clone https://github.com/SolaceProducts/terraform-solacebroker-rest-delivery cd examples/adding-headers ``` -### Adjust Provider Configuration +### Adjust the Provider Configuration Adjust the [provider parameters](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs#schema) in `main.tf` according to your broker. The example configuration shows settings for a local broker running in Docker. -### Create the resource +### Create the Resource -Hint: You can verify configuration changes on the broker, before and after, using the [PubSub+ Broker Manager Web UI](https://docs.solace.com/Admin/Broker-Manager/PubSub-Manager-Overview.htm) +Tip: You can verify configuration changes on the broker, before and after, using the [PubSub+ Broker Manager Web UI](https://docs.solace.com/Admin/Broker-Manager/PubSub-Manager-Overview.htm). Execute from this folder: @@ -79,8 +79,8 @@ terraform plan -var-file="secret.tfvars" terraform apply -var-file="secret.tfvars" ``` -Run `terraform destroy` to clean up created resources when no longer needed. +Run `terraform destroy` to clean up the created resources when they are no longer needed. ## Additional Documentation -Refer to the [Managing REST Delivery Points](https://docs.solace.com/Services/Managing-RDPs.htm) section in the PubSub+ documentation. +For more information, see [Managing REST Delivery Points](https://docs.solace.com/Services/Managing-RDPs.htm) section in the PubSub+ documentation. diff --git a/examples/basic/README.md b/examples/basic/README.md index 9e67e94..6479a72 100644 --- a/examples/basic/README.md +++ b/examples/basic/README.md @@ -6,16 +6,16 @@ Configuration in this directory creates a [REST delivery point and child objects ### Required Inputs -* `msg_vpn_name` - set to `default` in the example +* `msg_vpn_name` - Set to `default` in the example. * `rest_delivery_point_name` -* `url` - set to `https://example.com/test` in the example. Note that it includes the endpoint path -* `queue_name` - `rdp_queue`, the queue that has been created to be used with the RDP +* `url` - Set to `https://example.com/test` in the example. Note that it includes the endpoint path. +* `queue_name` - Set to `rdp_queue`, the queue that has been created to be used with the RDP. Important: The REST delivery point must have permission to consume messages from the queue — to achieve this, the queue’s owner must be set to `#rdp/` or the queue’s permissions for non-owner clients must be set to at least `consume` level access. Queue ingress and egress must also be enabled. ### Optional Inputs -Optional module input variables have the same name as the attributes of the underlying provider resource. If omitted then the default for the related resource attribute will be configured on the broker. For attributes and defaults, refer to the [documentation of "solacebroker_msg_vpn_rest_delivery_point_rest_consumer"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_rest_delivery_point_rest_consumer#optional). +Optional module input variables have the same name as the attributes of the underlying provider resource. If omitted, then the default for the related resource attribute will be configured on the broker. For a list of attributes and the corresponding defaults, see the [documentation of "solacebroker_msg_vpn_rest_delivery_point_rest_consumer"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_rest_delivery_point_rest_consumer#optional). The module default for the `enabled` variable is true, which enables both the RDP and the REST consumer resources. @@ -23,9 +23,9 @@ The module default for the `enabled` variable is true, which enables both the RD The module `rdp`, `consumer` and `queue_binding` outputs refer to the created REST delivery point, REST consumer and queue binding. -## Created resources +## Created Resources -This example will create following resources: +This example will create the following resources: * `solacebroker_msg_vpn_queue` (created before the module, as pre-requisite)

@@ -35,11 +35,11 @@ This example will create following resources: ## Running the Example -### Access to a PubSub+ broker +### Access to a PubSub+ Event Broker -If you don't already have access to a broker, refer to the [Developers page](https://www.solace.dev/) for options to get started. +If you don't already have access to a broker, see the [Developers page](https://www.solace.dev/) for options to get started. -### Sample source code +### Sample Source Code The sample is available from the module GitHub repo: @@ -48,13 +48,13 @@ git clone https://github.com/SolaceProducts/terraform-solacebroker-rest-delivery cd examples/basic ``` -### Adjust Provider Configuration +### Adjust the Provider Configuration Adjust the [provider parameters](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs#schema) in `main.tf` according to your broker. The example configuration shows settings for a local broker running in Docker. -### Create the resource +### Create the Resource -Hint: You can verify configuration changes on the broker, before and after, using the [PubSub+ Broker Manager Web UI](https://docs.solace.com/Admin/Broker-Manager/PubSub-Manager-Overview.htm) +Tip: You can verify configuration changes on the broker, before and after, using the [PubSub+ Broker Manager Web UI](https://docs.solace.com/Admin/Broker-Manager/PubSub-Manager-Overview.htm). Execute from this folder: @@ -64,8 +64,8 @@ terraform plan terraform apply ``` -Run `terraform destroy` to clean up created resources when no longer needed. +Run `terraform destroy` to clean up the created resources when they are no longer needed. ## Additional Documentation -Refer to the [Managing REST Delivery Points](https://docs.solace.com/Services/Managing-RDPs.htm) section in the PubSub+ documentation. +For more information, see [Managing REST Delivery Points](https://docs.solace.com/Services/Managing-RDPs.htm) section in the PubSub+ documentation. diff --git a/examples/using-substitution-expressions/README.md b/examples/using-substitution-expressions/README.md index 9cd88c7..38db70b 100644 --- a/examples/using-substitution-expressions/README.md +++ b/examples/using-substitution-expressions/README.md @@ -14,20 +14,20 @@ Strings containing substitution expressions must be [properly escaped](https://d ### Required Inputs -* `msg_vpn_name` - set to `default` in the example +* `msg_vpn_name` - Set to `default` in the example. * `rest_delivery_point_name` -* `url` - set to `http://example.com/$${msgId()}` in the example. Notice the escape sequence, which results in `${msgId()}` configured on the broker. Substitution expressions are only suported in the path component. -* `queue_name` - `rdp_queue`, the queue that has been created to be used with the RDP +* `url` - Set to `http://example.com/$${msgId()}` in the example. Notice the escape sequence, which results in `${msgId()}` configured on the broker. Substitution expressions are only suported in the path component. +* `queue_name` - Set to `rdp_queue`, the queue that has been created to be used with the RDP. Important: The REST delivery point must have permission to consume messages from the queue — to achieve this, the queue’s owner must be set to `#rdp/` or the queue’s permissions for non-owner clients must be set to at least `consume` level access. Queue ingress and egress must also be enabled. ### Optional Inputs -* `request_headers` - here `{ header_name = "header1", header_value = "$${uuid()}" }`, notice again the use of the escape sequence. +* `request_headers` - Here `{ header_name = "header1", header_value = "$${uuid()}" }`, notice again the use of the escape sequence. Note that substitution expressions are not supported for `protected_request_headers`. -Optional module input variables have the same name as the attributes of the underlying provider resource. If omitted then the default for the related resource attribute will be configured on the broker. For attributes and defaults, refer to the [documentation of "solacebroker_msg_vpn_rest_delivery_point_rest_consumer"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_rest_delivery_point_rest_consumer#optional). +Optional module input variables have the same name as the attributes of the underlying provider resource. If omitted, then the default for the related resource attribute will be configured on the broker. For a list of attributes and the corresponding defaults, see the [documentation of "solacebroker_msg_vpn_rest_delivery_point_rest_consumer"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_rest_delivery_point_rest_consumer#optional). The module default for the `enabled` variable is true, which enables both the RDP and the REST consumer resources. @@ -35,9 +35,9 @@ The module default for the `enabled` variable is true, which enables both the RD The module `rdp`, `consumer` and `queue_binding` outputs refer to the created REST delivery point, REST consumer and queue binding. -## Created resources +## Created Resources -This example will create following resources: +This example will create the following resources: * `solacebroker_msg_vpn_queue` (created before the module, as pre-requisite)

@@ -48,11 +48,11 @@ This example will create following resources: ## Running the Example -### Access to a PubSub+ broker +### Access to a PubSub+ Event Broker -If you don't already have access to a broker, refer to the [Developers page](https://www.solace.dev/) for options to get started. +If you don't already have access to a broker, see the [Developers page](https://www.solace.dev/) for options to get started. -### Sample source code +### Sample Source Code The sample is available from the module GitHub repo: @@ -61,13 +61,13 @@ git clone https://github.com/SolaceProducts/terraform-solacebroker-rest-delivery cd examples/using-substitution-expressions ``` -### Adjust Provider Configuration +### Adjust the Provider Configuration Adjust the [provider parameters](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs#schema) in `main.tf` according to your broker. The example configuration shows settings for a local broker running in Docker. -### Create the resource +### Create the Resource -Hint: You can verify configuration changes on the broker, before and after, using the [PubSub+ Broker Manager Web UI](https://docs.solace.com/Admin/Broker-Manager/PubSub-Manager-Overview.htm) +Tip: You can verify configuration changes on the broker, before and after, using the [PubSub+ Broker Manager Web UI](https://docs.solace.com/Admin/Broker-Manager/PubSub-Manager-Overview.htm). Execute from this folder: @@ -77,8 +77,8 @@ terraform plan terraform apply ``` -Run `terraform destroy` to clean up created resources when no longer needed. +Run `terraform destroy` to clean up the created resources when they are no longer needed. ## Additional Documentation -Refer to the [Managing REST Delivery Points](https://docs.solace.com/Services/Managing-RDPs.htm) section in the PubSub+ documentation. +For more information, see [Managing REST Delivery Points](https://docs.solace.com/Services/Managing-RDPs.htm) section in the PubSub+ documentation.