Added headers example

.gitignore

@@ -10,13 +10,6 @@
 crash.log
 crash.*.log
 
-# Exclude all .tfvars files, which are likely to contain sensitive data, such as
-# password, private keys, and other secrets. These should not be part of version 
-# control as they are data points which are potentially sensitive and subject 
-# to change depending on the environment.
-*.tfvars
-*.tfvars.json
-
 # Ignore override files as they are usually used to override resources locally and so
 # are not checked in
 override.tf

README.md

@@ -33,6 +33,7 @@ Additional optional module variables names are the same as the underlying resour
 |[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)|
 |[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)|
 |[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)|
 |[solacebroker_msg_vpn_rest_delivery_point_rest_consumer_oauth_jwt_claim](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_rest_delivery_point_rest_consumer_oauth_jwt_claim#optional)|
 
 Most optional variables' default value is `null`, meaning that if not provided then the resource default value will be provisioned on the broker.
@@ -43,6 +44,8 @@ Most optional variables' default value is `null`, meaning that if not provided t
 
 [Module outputs](https://developer.hashicorp.com/terraform/language/values/outputs) provide reference to created resources. Any reference to a resource that has not been created will be set to `(null)`.
 
+Note that the "rest consumer" and the "protected request headers" outputs are [sensitive](https://developer.hashicorp.com/terraform/language/values/outputs#sensitive-suppressing-values-in-cli-output).
+
 ## Providers
 
 | Name | Version |
@@ -59,6 +62,7 @@ The following table shows the resources created. "X" denotes a resource always c
 | solacebroker_msg_vpn_rest_delivery_point_rest_consumer | X |
 | solacebroker_msg_vpn_rest_delivery_point_queue_binding | X |
 | solacebroker_msg_vpn_rest_delivery_point_queue_binding_request_header | O |
+| solacebroker_msg_vpn_rest_delivery_point_queue_binding_protected_request_header | O |
 | solacebroker_msg_vpn_rest_delivery_point_rest_consumer_oauth_jwt_claim | O |
 
 ## Examples
@@ -68,8 +72,8 @@ Refer to the following configuration examples:
 - [Basic](examples/basic)
 - [Substitution Expressions](examples/using-substitution-expressions)
 - [Adding headers](examples/adding-headers)
-- [Multiple queue bindings](examples/multiple-queue-bindings)
 - [Adding JWT claims (workaround)](examples/adding-oauth-jwt-claims-workaround)
+- [Multiple queue bindings](examples/multiple-queue-bindings)
 - [Amazon AWS consumer](examples/aws)
 - [Microsoft Azure consumer](examples/azure)
 - [Google Cloud consumer](examples/gcp)

ci/scripts/test-module.sh

@@ -1,17 +1,17 @@
 #!/bin/bash
 # Basic terraform test on a config.
-# Params: $1 is the directory name, $2 (optional), the module registry URL, $3 (optional), the module version
+# Params: $1 is the directory name, @2 (optional) additional argument to pass to terraform commands, $3 (optional), the module registry URL, $4 (optional), the module version
 set -e
 pushd "$1"
-if [ -n "$2" ] ; then sed -i "s@source =.*@source = \"$2\"@g" main.tf; fi
-if [ -n "$3" ] ; then sed -i "s@# version =.*@version = \"$3\"@g" main.tf; fi
+if [ -n "$3" ] ; then sed -i "s@source =.*@source = \"$3\"@g" main.tf; fi
+if [ -n "$4" ] ; then sed -i "s@# version =.*@version = \"$4\"@g" main.tf; fi
 cat main.tf
 terraform init
 terraform validate
 # Create
-terraform plan
-terraform apply -auto-approve
-terraform plan | grep "No changes"
+terraform plan "$2"
+terraform apply -auto-approve "$2"
+terraform plan "$2" | grep "No changes"
 sleep 1
 terraform destroy -auto-approve
 popd

examples/adding-headers/README.md

@@ -0,0 +1,83 @@
+# Adding REST Request Headers in REST Delivery Configuration Example
+
+Configuration in this directory demonstrates how to specify [request headers](https://docs.solace.com/Services/Managing-RDPs.htm#configuring-request-headers) when configuring [REST messaging](https://docs.solace.com/API/REST/REST-Consumers.htm) on the PubSub+ event broker, leveraging the Rest Delivery Terraform module.
+
+There are two types of request header resources:
+
+* "Request headers" - HTTP headers that don't contain sensitive data
+* "Protected request headers" - their value contain sensitive data and must be handled accordingly
+
+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.
+
+## Module Configuration in the Example
+
+### 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.
+* `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/<rest_delivery_point_name>` 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
+
+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)
+</br></br>
+* `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 -var-file="secret.tfvars"
+terraform apply -var-file="secret.tfvars"
+```
+
+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.

examples/adding-headers/main.tf

@@ -0,0 +1,65 @@
+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/<rest_delivery_point_name>`
+#   # 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                     = "https://example.com/test"
+  # 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 = "value1"
+    },
+    {
+      header_name  = "header2"
+      header_value = "value2"
+    }
+  ]
+  protected_request_headers = var.protected_request_headers
+}
+
+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
+}

examples/adding-headers/providers.tf

@@ -0,0 +1,10 @@
+# Terraform configuration
+
+terraform {
+  required_providers {
+    solacebroker = {
+      source = "registry.terraform.io/solaceproducts/solacebroker"
+    }
+  }
+  required_version = "~> 1.2"
+}

examples/adding-headers/secret.tfvars

@@ -0,0 +1,10 @@
+  protected_request_headers = [
+    {
+      header_name  = "protected_header1"
+      header_value = "protected_value1"
+    },
+    {
+      header_name  = "protected_header2"
+      header_value = "protected_value2"
+    }
+  ]

examples/adding-headers/variables.tf

@@ -0,0 +1,7 @@
+  variable "protected_request_headers" {
+    type    = list(object({
+      header_name  = string
+      header_value = string
+    }))
+    default = []
+  }

examples/using-substitution-expressions/README.md

@@ -25,6 +25,8 @@ Important: The REST delivery point must have permission to consume messages from
 
 * `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_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.