From 56d5a83769ffc5a3d1f96859acdfd9124c90dc6c Mon Sep 17 00:00:00 2001 From: Balazs Czoma Date: Thu, 29 Feb 2024 04:50:31 -0500 Subject: [PATCH] Added substitution expressions example --- README.md | 2 +- ci/module-test/main.tf | 2 +- ci/template-test/main.tf | 2 +- examples/basic/README.md | 6 +- examples/basic/main.tf | 6 +- .../using-substitution-expressions/README.md | 81 +++++++++++++++++++ .../using-substitution-expressions/main.tf | 60 ++++++++++++++ .../providers.tf | 10 +++ 8 files changed, 160 insertions(+), 9 deletions(-) create mode 100644 examples/using-substitution-expressions/README.md create mode 100644 examples/using-substitution-expressions/main.tf create mode 100644 examples/using-substitution-expressions/providers.tf diff --git a/README.md b/README.md index f857f6c..60affa9 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ Refer to the following configuration examples: - [Basic](examples/basic) - [Substitution Expressions](examples/using-substitution-expressions) -- [Adding protected headers](examples/adding-protected-headers) +- [Adding headers](examples/adding-headers) - [Multiple queue bindings](examples/multiple-queue-bindings) - [Adding JWT claims (workaround)](examples/adding-oauth-jwt-claims-workaround) - [Amazon AWS consumer](examples/aws) diff --git a/ci/module-test/main.tf b/ci/module-test/main.tf index 027d34e..040af93 100644 --- a/ci/module-test/main.tf +++ b/ci/module-test/main.tf @@ -6,7 +6,7 @@ provider "solacebroker" { resource "solacebroker_msg_vpn_queue" "myqueue" { msg_vpn_name = "default" - queue_name = "my_queue" + queue_name = "rdp_queue" permission = "consume" } diff --git a/ci/template-test/main.tf b/ci/template-test/main.tf index 49c6a06..266aeca 100644 --- a/ci/template-test/main.tf +++ b/ci/template-test/main.tf @@ -6,7 +6,7 @@ provider "solacebroker" { resource "solacebroker_msg_vpn_queue" "myqueue" { msg_vpn_name = "default" - queue_name = "my_queue" + queue_name = "rdp_queue" permission = "consume" } diff --git a/examples/basic/README.md b/examples/basic/README.md index 4cdba9a..e91f461 100644 --- a/examples/basic/README.md +++ b/examples/basic/README.md @@ -1,15 +1,15 @@ # Basic REST Delivery Configuration Example -Configuration in this directory creates a [connection factory](https://docs.solace.com/API/Solace-JMS-API/Connection-Factories.htm) object in the JNDI store on the PubSub+ event broker, leveraging the Rest Delivery Terraform module. +Configuration in this directory creates a [REST delivery point and child objects](https://docs.solace.com/API/REST/REST-Consumers.htm#_Toc433874658) on the PubSub+ event broker, with minimum configuration, leveraging the Rest Delivery Terraform module. ## Module Configuration in the Example -### Mandatory Inputs +### Required Inputs * `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` - the name of an existing queue to bind to +* `queue_name` - `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. diff --git a/examples/basic/main.tf b/examples/basic/main.tf index 4b2058c..ccc03f2 100644 --- a/examples/basic/main.tf +++ b/examples/basic/main.tf @@ -12,11 +12,11 @@ provider "solacebroker" { # # msg_vpn_name = "default" # endpoint_type = "queue" -# endpoint_name = "my_queue" +# endpoint_name = "rdp_queue" # # # The REST delivery point must have permission to consume messages from the queue # # — to achieve this, either the queue’s owner must be set to `#rdp/` -# # owner = "#rdp/my_rdp" +# # owner = "#rdp/basic_rdp" # # or the queue’s permissions for non-owner clients must be set to at least `consume` level access # permission = "consume" # @@ -24,7 +24,7 @@ provider "solacebroker" { # } resource "solacebroker_msg_vpn_queue" "rdp_queue" { msg_vpn_name = "default" - queue_name = "my_queue" + queue_name = "rdp_queue" permission = "consume" ingress_enabled = true egress_enabled = true diff --git a/examples/using-substitution-expressions/README.md b/examples/using-substitution-expressions/README.md new file mode 100644 index 0000000..82075b6 --- /dev/null +++ b/examples/using-substitution-expressions/README.md @@ -0,0 +1,81 @@ +# Using Substitution Expressions in REST Delivery Configuration Example + +Configuration in this directory creates a [REST delivery point and child objects](https://docs.solace.com/API/REST/REST-Consumers.htm#_Toc433874658) on the PubSub+ event broker, leveraging the Rest Delivery Terraform module. + +It demonstrates the use of [substitution expressions](https://docs.solace.com/Messaging/Substitution-Expressions-Overview.htm) for flexible REST requests. + +Substitution expressions may be used in +* Request URI path component +* Request headers + +Strings containing substitution expressions must be [properly escaped](https://developer.hashicorp.com/terraform/language/expressions/strings#escape-sequences) in the Terraform configuration. + +## Module Configuration in the Example + +### Required Inputs + +* `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. +* `queue_name` - `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. + +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_queue"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_queue#optional). + +The module default for the `enabled` variable is true, which enables both the RDP and the REST consumer resources. + +### Output + +The module `rdp` output refers to the created REST delivery point. + +## Created resources + +This example will create following resources: + +* `solacebroker_msg_vpn_queue` (created before the module, as pre-requisite) +

+* `solacebroker_msg_vpn_rest_delivery_point` +* `solacebroker_msg_vpn_rest_delivery_point_rest_consumer` +* `solacebroker_msg_vpn_rest_delivery_point_queue_binding` + +## Running the Example + +### Access to a PubSub+ 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. + +### Sample source code + +The sample is available from the module GitHub repo: + +```bash +git clone https://github.com/SolaceProducts/terraform-solacebroker-rest-delivery.git +cd examples/basic +``` + +### Adjust 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 + +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) + +Execute from this folder: + +```bash +terraform init +terraform plan +terraform apply +``` + +Run `terraform destroy` to clean up created resources when 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. diff --git a/examples/using-substitution-expressions/main.tf b/examples/using-substitution-expressions/main.tf new file mode 100644 index 0000000..8fadcf2 --- /dev/null +++ b/examples/using-substitution-expressions/main.tf @@ -0,0 +1,60 @@ +provider "solacebroker" { + username = "admin" + password = "admin" + url = "http://localhost:8080" +} + +# The RDP requires a queue to bind to. +# Recommended: Use the queue-endpoint module to create the queue +# TODO: Uncomment the following block and replace the resource block once the queue-endpoint module is available +# module "rdp_queue" { +# source = SolaceProducts/queue-endpoint/solacebroker +# +# msg_vpn_name = "default" +# endpoint_type = "queue" +# endpoint_name = "rdp_queue" +# +# # The REST delivery point must have permission to consume messages from the queue +# # — to achieve this, either the queue’s owner must be set to `#rdp/` +# # owner = "#rdp/basic_rdp" +# # or the queue’s permissions for non-owner clients must be set to at least `consume` level access +# permission = "consume" +# +# # The queue must also be enabled for ingress and egress, which is the default for the rdp_queue module +# } +resource "solacebroker_msg_vpn_queue" "rdp_queue" { + msg_vpn_name = "default" + queue_name = "rdp_queue" + permission = "consume" + ingress_enabled = true + egress_enabled = true +} + +module "testrdp" { + source = "../.." + + msg_vpn_name = "default" + rest_delivery_point_name = "basic_rdp" + url = "http://example.com/$${msgId()}" + # queue_name = module.rdp_queue.queue.queue_name + queue_name = solacebroker_msg_vpn_queue.rdp_queue.queue_name + request_headers = [ + { + header_name = "header1" + header_value = "$${uuid()}" + } + ] +} + +output "rdp" { + value = module.testrdp.rest_delivery_point +} + +output "consumer" { + value = module.testrdp.rest_consumer + sensitive = true +} + +output "queue_binding" { + value = module.testrdp.queue_binding +} diff --git a/examples/using-substitution-expressions/providers.tf b/examples/using-substitution-expressions/providers.tf new file mode 100644 index 0000000..d1de478 --- /dev/null +++ b/examples/using-substitution-expressions/providers.tf @@ -0,0 +1,10 @@ +# Terraform configuration + +terraform { + required_providers { + solacebroker = { + source = "registry.terraform.io/solaceproducts/solacebroker" + } + } + required_version = "~> 1.2" +}