diff --git a/README.md b/README.md index 88198a4..d030631 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ Exceptions: the following optional variables' default value differ from the reso | `dmr_enabled` | `true` | | `enabled` | `true` | the Message VPN and underlying created objects | | `jndi_enabled` | `true` | -| `max_msg_spool_usage` | 1500 | message VPN | +| `max_msg_spool_usage` | 1500 | MB, message VPN | -> The module default for the optional variable is `true`, which diff --git a/examples/basic-vpn/README.md b/examples/basic-vpn/README.md index fe8a281..855268e 100644 --- a/examples/basic-vpn/README.md +++ b/examples/basic-vpn/README.md @@ -2,7 +2,7 @@ Configuration in this directory creates a basic [message VPN](https://docs.solace.com/Features/VPN/Managing-Message-VPNs.htm) on the PubSub+ event broker, leveraging the Service Terraform module. -The created VPN will enable SMF and WebSocket messaging services with a message spool of 1500 MB assigned by default, as well as use of JNDI and DMR. Refer to the example [Services and listen ports](examples/services-and-listen-ports) how to enable and configure other services including REST, MQTT and AMQP. +The created VPN will enable SMF and Web Transport messaging services with a message spool of 1500 MB assigned by default, as well as use of JNDI and DMR. Refer to the example [Services and listen ports](examples/services-and-listen-ports) how to enable and configure other services including REST, MQTT and AMQP. The VPN will include a `default` permissive ACL profile and a client profile, similar to the ones in the `default` message VPN. These profiles will enable ready-to-go messaging on the VPN for development and demo purposes. For production use a customized ACL profile and a client profile should be specified as in [this example](examples/customized-client-and-acl-profiles). diff --git a/examples/services-and-listen-ports/README.md b/examples/services-and-listen-ports/README.md new file mode 100644 index 0000000..b55f6c0 --- /dev/null +++ b/examples/services-and-listen-ports/README.md @@ -0,0 +1,71 @@ +# Message VPN Services and Listen Ports Configuration Example + +The example in this directory demonstrates how to configure services including ports for a new message VPN on the PubSub+ event broker, leveraging the Service Terraform module. + +SMF and Web Transport messaging services are configured at the broker level and are enabled on the message VPN created by the Service module. Other services including REST, MQTT and AMQP are configured at the message VPN level and need to be individually setup for each VPN. They are disabled by default and need to be enabled, configured and a port assigned if required through module variables. The example will show how to do that. + +A service may also use plain text or secure transport. While it is generally recommended to use secure transport and disable plain text, secure transport requires a server certificate installed on the broker. For easier development and demo purposes, plain text SMF and Web Transport services are enabled by default on the message VPN and should be disabled through module variables to meet security requirements. + +## Module Configuration in the Example + +### Required Inputs + +* `msg_vpn_name` - set to `rest-enabled-vpn` in the example + +### Optional Inputs + +* `service_rest_incoming_plain_text_enabled` - set to `true` in this example +* `service_rest_incoming_plain_text_listen_port` - set to `9000` in this example + +Other 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"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn#optional). + +The module default for the `enabled` variable is true, which enables the message VPN and underlying resources. + +### Output + +The module `created_vpn` output refers to the created message VPN. + +## Created resources + +This example will create following resources: + +* `solacebroker_msg_vpn` + +Note that `default` ACL profile, client profile and client username objects will also be automatically created as part of the new VPN but are only available by referencing their name. + +## 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/services-and-listen-ports +``` + +### 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. Note that as part of this command there may be a warning about default objects cannot be deleted, this is normal and expected here. + +## Additional Documentation + +Refer to the [Configuring Message VPNs](https://docs.solace.com/Features/VPN/Configuring-VPNs.htm) section in the PubSub+ documentation. diff --git a/examples/services-and-listen-ports/main.tf b/examples/services-and-listen-ports/main.tf new file mode 100644 index 0000000..d118c27 --- /dev/null +++ b/examples/services-and-listen-ports/main.tf @@ -0,0 +1,26 @@ +provider "solacebroker" { + username = "admin" + password = "admin" + url = "http://localhost:8080" +} + +module "testvpn" { + source = "../.." + + msg_vpn_name = "rest-enabled-vpn" + + // Enable and configure incoming messaging protocols, for example REST. Note that plain text is not recommended for production use. + service_rest_incoming_plain_text_enabled = true + service_rest_incoming_plain_text_listen_port = 9000 + + // Uncomment to disable plain text SMF - however secure transport SMF requires a server certificate installed on the broker + // service_smf_plain_text_enabled = false + + // No need to set the VPN enabled, it defaults to true + // enabled = true +} + +output "created_vpn" { + value = module.testvpn.msg_vpn + sensitive = true +} diff --git a/examples/services-and-listen-ports/providers.tf b/examples/services-and-listen-ports/providers.tf new file mode 100644 index 0000000..6dd1008 --- /dev/null +++ b/examples/services-and-listen-ports/providers.tf @@ -0,0 +1,24 @@ +# Copyright 2024 Solace Corporation. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Terraform configuration + +terraform { + required_providers { + solacebroker = { + source = "registry.terraform.io/solaceproducts/solacebroker" + } + } + required_version = "~> 1.2" +}