diff --git a/.github/workflows/module-test-pipeline.yml b/.github/workflows/module-test-pipeline.yml index 9bc924a..7c5362e 100644 --- a/.github/workflows/module-test-pipeline.yml +++ b/.github/workflows/module-test-pipeline.yml @@ -35,5 +35,7 @@ jobs: - name: Test examples run: | - for dir in examples/*; do (ci/scripts/test-module.sh "$dir"); done - # ci/scripts/test-module.sh examples/non-exclusive-queue + shopt -s extglob + for d in examples/!(adding-headers|adding-oauth-jwt-claims-workaround)/; do (ci/scripts/test-module.sh "$d"); done + ci/scripts/test-module.sh examples/adding-headers/ -var-file=secret.tfvars + ci/scripts/test-module.sh examples/adding-oauth-jwt-claims-workaround/ -var="enabled=false" diff --git a/.github/workflows/verify-registry-release.yml b/.github/workflows/verify-registry-release.yml index 11a5bc8..9cf2038 100644 --- a/.github/workflows/verify-registry-release.yml +++ b/.github/workflows/verify-registry-release.yml @@ -54,5 +54,5 @@ jobs: echo Public release MODULE_REF="SolaceProducts/jndi/solacebroker" fi - ci/scripts/test-module.sh ci/module-test/ $MODULE_REF "${{ github.event.inputs.release_version }}" + ci/scripts/test-module.sh ci/module-test/ "" $MODULE_REF "${{ github.event.inputs.release_version }}" diff --git a/README.md b/README.md index 0f64b6b..8e06a88 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Solace PubSub+ Software Event Broker Rest Delivery Terraform Module +# 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/). diff --git a/examples/adding-headers/README.md b/examples/adding-headers/README.md index b230cf5..707e91f 100644 --- a/examples/adding-headers/README.md +++ b/examples/adding-headers/README.md @@ -1,6 +1,6 @@ # 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. +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: @@ -44,6 +44,9 @@ This example will create following resources: * `solacebroker_msg_vpn_rest_delivery_point` * `solacebroker_msg_vpn_rest_delivery_point_rest_consumer` * `solacebroker_msg_vpn_rest_delivery_point_queue_binding` +* `solacebroker_msg_vpn_rest_delivery_point_queue_binding_request_header` +* `solacebroker_msg_vpn_rest_delivery_point_queue_binding_protected_request_header` + ## Running the Example @@ -57,7 +60,7 @@ The sample is available from the module GitHub repo: ```bash git clone https://github.com/SolaceProducts/terraform-solacebroker-rest-delivery.git -cd examples/basic +cd examples/adding-headers ``` ### Adjust Provider Configuration diff --git a/examples/adding-oauth-jwt-claims-workaround/README.md b/examples/adding-oauth-jwt-claims-workaround/README.md new file mode 100644 index 0000000..bafd4b8 --- /dev/null +++ b/examples/adding-oauth-jwt-claims-workaround/README.md @@ -0,0 +1,97 @@ +# Adding OAuth JWT Claims REST Delivery Configuration Example + +This example shows how to add optional additional OAuth JWT claims that the REST consumer will use to request access tokens when configuring [REST messaging](https://docs.solace.com/API/REST/REST-Consumers.htm) on the PubSub+ event broker, leveraging the REST Delivery Terraform module. + +## Issue and workaround + +The `enabled` module input variable controls if the `rest_delivery_point` and the `rest_delivery_point_rest_consumer` resources are administratively enabled. +The module default is `true`. While this default ensures that the broker is ready for outgoing REST messaging after configuration, it conflicts with a current capability of the Solace provider: optional additional OAuth JWT claims can only be configured on administratively disabled REST consumer resources. + +To work around this until the provider capability is added, if using the `oauth_jwt_claims` module input variable, apply the module in two passes: first with `enabled` set to `false`, then with `enabled` set to true. To conveniently do this, define an input variable with default set to `true` for the root configuration, pass its value to the module `enabled` input, and then control the variable from the Terraform CLI: + +```bash +terraform apply -var="enabled=false" # applies the config with adminstratively disabled RDP and REST consumer +terraform apply # only changes the admin status of the RDP and the REST consumer (enabled default is true) +``` + +When modifying or deleting the config, first apply the current config to adminstratively disable the RDP and the REST consumer: +```bash +terraform apply -var="enabled=false" # only changes the admin status of the RDP and the REST consumer (assuming the config has not changed) +terraform destroy # this one deletes the config. To modify the config, use above two-pass apply +``` + +To clarify, this workaround is only required when changing the `oauth_jwt_claims` module input variable. + +## Module Configuration in the Example + +Note: the focus of this example is adding optional additional OAuth JWT claims. While there are some + +### 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` - `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 + +* `oauth_jwt_claims` - the set of additional claims, `scope` and `iss` 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) +

+* `solacebroker_msg_vpn_rest_delivery_point` +* `solacebroker_msg_vpn_rest_delivery_point_rest_consumer` +* `solacebroker_msg_vpn_rest_delivery_point_queue_binding` +* `solacebroker_msg_vpn_rest_delivery_point_rest_consumer_oauth_jwt_claim` + +## 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/adding-oauth-jwt-claims-workaround +``` + +### 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 -var="enabled=false" +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/adding-oauth-jwt-claims-workaround/main.tf b/examples/adding-oauth-jwt-claims-workaround/main.tf new file mode 100644 index 0000000..15a7d2e --- /dev/null +++ b/examples/adding-oauth-jwt-claims-workaround/main.tf @@ -0,0 +1,71 @@ +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 = "https://example.com/test" + # queue_name = module.rdp_queue.queue.queue_name + queue_name = solacebroker_msg_vpn_queue.rdp_queue.queue_name + enabled = var.enabled + + # Example additional config required for proper OAuth setup + # authentication_scheme = "oauth-jwt" + # authentication_oauth_jwt_secret_key = "-----BEGIN PRIVATE KEY-----test-----END PRIVATE KEY-----\n" + # authentication_oauth_jwt_token_endpoint = "https://www.googleapis.com/oauth2/v4/token" + # authentication_oauth_jwt_token_expiry_default = "3600" + oauth_jwt_claims = [ + { + oauth_jwt_claim_name = "scope" + oauth_jwt_claim_value = "\"https://www.googleapis.com/auth/pubsub\"" + }, + { + oauth_jwt_claim_name = "iss" + oauth_jwt_claim_value = "\"111400995554822290197\"" + } + ] +} + +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/adding-oauth-jwt-claims-workaround/providers.tf b/examples/adding-oauth-jwt-claims-workaround/providers.tf new file mode 100644 index 0000000..d1de478 --- /dev/null +++ b/examples/adding-oauth-jwt-claims-workaround/providers.tf @@ -0,0 +1,10 @@ +# Terraform configuration + +terraform { + required_providers { + solacebroker = { + source = "registry.terraform.io/solaceproducts/solacebroker" + } + } + required_version = "~> 1.2" +} diff --git a/examples/adding-oauth-jwt-claims-workaround/variables.tf b/examples/adding-oauth-jwt-claims-workaround/variables.tf new file mode 100644 index 0000000..ddea9e7 --- /dev/null +++ b/examples/adding-oauth-jwt-claims-workaround/variables.tf @@ -0,0 +1,4 @@ + variable "enabled" { + type = bool + default = true + } diff --git a/examples/basic/README.md b/examples/basic/README.md index e91f461..3cb3790 100644 --- a/examples/basic/README.md +++ b/examples/basic/README.md @@ -1,6 +1,6 @@ # Basic 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, with minimum configuration, 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 diff --git a/examples/using-substitution-expressions/README.md b/examples/using-substitution-expressions/README.md index 4651b59..b0d6f5d 100644 --- a/examples/using-substitution-expressions/README.md +++ b/examples/using-substitution-expressions/README.md @@ -1,6 +1,6 @@ # 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. +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. @@ -57,7 +57,7 @@ The sample is available from the module GitHub repo: ```bash git clone https://github.com/SolaceProducts/terraform-solacebroker-rest-delivery.git -cd examples/basic +cd examples/using-substitution-expressions ``` ### Adjust Provider Configuration diff --git a/internal/gen-template/variables.tf b/internal/gen-template/variables.tf index 3d280f0..12032c6 100644 --- a/internal/gen-template/variables.tf +++ b/internal/gen-template/variables.tf @@ -25,9 +25,9 @@ variable "queue_name" { # Optional variables variable "enabled" { - description = "Enable or disable the REST Delivery Point." + description = "Enable or disable the REST Delivery Point and the underlying REST Consumer." type = bool - default = null + default = true } variable "rest_consumer_name" { diff --git a/variables.tf b/variables.tf index 3d7cfe8..02f77be 100644 --- a/variables.tf +++ b/variables.tf @@ -39,9 +39,9 @@ variable "queue_name" { # Optional variables variable "enabled" { - description = "Enable or disable the REST Delivery Point." + description = "Enable or disable the REST Delivery Point and the underlying REST Consumer." type = bool - default = null + default = true } variable "rest_consumer_name" {