diff --git a/README.md b/README.md index 6e0bfa8..d246d3b 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,31 @@ # Solace PubSub+ Software Event Broker Service Terraform Module -Terraform module that encapsulates a [message VPN](https://docs.solace.com/Features/VPN/Managing-Message-VPNs.htm) including client and ACL profiles, resource limits and service on the [Solace PubSub+ Event Broker](https://solace.com/products/event-broker/). +This Terraform module encapsulates a [Message VPN](https://docs.solace.com/Features/VPN/Managing-Message-VPNs.htm) including client and ACL profiles, resource limits and service on the [Solace PubSub+ Event Broker](https://solace.com/products/event-broker/). -The basic use case is to create a new message VPN with a permissive `default` ACL and client profile, ready for messaging. Optionally, an additional fully customizable ACL profile and a client profile can be defined. The module also adds advanced client certificate authentication and OAuth authentication configuration support. +You can use this module to create a new Message VPN with a permissive `default` ACL and client profile, ready for messaging. You can also define an optional additional fully customizable ACL and client profile. The module also adds advanced client certificate authentication and OAuth authentication configuration support. -Note: the `default` client username that is automatically created with the new VPN is disabled. It is recommended to use the [Client Module](https://registry.terraform.io/modules/SolceProducts/client/solacebroker/latest) to setup a client username if required. Also, services that require message VPN specific ports, including REST, MQTT etc. are disabled by default and need to be enabled/configured through optional variables. +Note: the `default` client username that is automatically created with the new Message VPN is disabled. We recommend that you use the [Client Module](https://registry.terraform.io/modules/SolceProducts/client/solacebroker/latest) to setup a client username if required. In addition, services that require Message VPN specific ports, including REST, MQTT etc. are disabled by default and need to be enabled/configured through optional variables. -Use case details are provided in the [Examples](#examples). +Use case details are provided in the [Examples](#examples) section. ## Module input variables ### Required -* `msg_vpn_name` - the name of the new message VPN to be created +* `msg_vpn_name` - The name of the new Message VPN to be created. ### Optional -* `acl_profile_name` - the name of the optionally added ACL profile. A `default` profile is always created and if left at default empty then no additional ACL profile will be created. -* `client_profile_name` - the name of the optionally added client profile. A `default` profile is always created and if left at default empty then no additional ACL profile will be created. -* `oauth_profile_name` - the name of an optionally added OAuth profile. Note that there will be no OAuth profile created unless a non-empty name is provided. -* `oauth_profile_client_required_claims` - a set of optional client-required claims. -* `oauth_profile_resource_server_required_claims` - a set of optional server-required claims. -* `cert_matching_rule_name` - the name of an optionally added certificate matching rule. Note that there will be no certificate matching rule created unless a non-empty name is provided. -* `cert_matching_rule_conditions` - a set of optional certificate matching rule conditions. -* `cert_matching_rule_attribute_filters` - a set of optional certificate matching rule attribute filters. +* `acl_profile_name` - The name of the optionally added ACL profile. A `default` profile is always created and if left at default empty then no additional ACL profile will be created. +* `client_profile_name` - The name of the optionally added client profile. A `default` profile is always created and if left at default empty then no additional ACL profile will be created. +* `oauth_profile_name` - The name of an optionally added OAuth profile. Note that there will be no OAuth profile created unless a non-empty name is provided. +* `oauth_profile_client_required_claims` - A set of optional client-required claims. +* `oauth_profile_resource_server_required_claims` - A set of optional server-required claims. +* `cert_matching_rule_name` - The name of an optionally added certificate matching rule. Note that there will be no certificate matching rule created unless a non-empty name is provided. +* `cert_matching_rule_conditions` - A set of optional certificate matching rule conditions. +* `cert_matching_rule_attribute_filters` - A set of optional certificate matching rule attribute filters. -Additional optional module variable 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 variable 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 | |---------------| @@ -34,7 +34,7 @@ Additional optional module variable names are the same as the underlying resourc |[solacebroker_msg_vpn_client_profile](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_client_profile#optional)| |[solacebroker_msg_vpn_authentication_oauth_profile](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_authentication_oauth_profile#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. Exceptions: the following optional variables' default value differ from the resource attribute defaults: @@ -42,15 +42,15 @@ Exceptions: the following optional variables' default value differ from the reso |----------------|---------------|------| | `authentication_basic_type` | `internal` | | `dmr_enabled` | `true` | -| `enabled` | `true` | the Message VPN and underlying created objects | +| `enabled` | `true` | The Message VPN and underlying created objects | | `jndi_enabled` | `true` | -| `max_msg_spool_usage` | 1500 | MB, message VPN | +| `max_msg_spool_usage` | 1500 | MB, Message VPN | ## Module outputs [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 "message VPN" output is [sensitive](https://developer.hashicorp.com/terraform/language/values/outputs#sensitive-suppressing-values-in-cli-output) due to some sensitive attributes it contains. +Note that the "Message VPN" output is [sensitive](https://developer.hashicorp.com/terraform/language/values/outputs#sensitive-suppressing-values-in-cli-output) due to some sensitive attributes it contains. ## Providers @@ -60,23 +60,23 @@ Note that the "message VPN" output is [sensitive](https://developer.hashicorp.co ## 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 | | Notes | |------|------|------| | solacebroker_msg_vpn | X | | -| solacebroker_msg_vpn_acl_profile | O | This is an additional configurable profile. A default ACL profile is always created | -| solacebroker_msg_vpn_client_profile | O | This is an additional configurable profile. A default client profile is always created | +| solacebroker_msg_vpn_acl_profile | O | This is an additional configurable profile. A default ACL profile is always created. | +| solacebroker_msg_vpn_client_profile | O | This is an additional configurable profile. A default client profile is always created. | | solacebroker_msg_vpn_authentication_oauth_profile | O | | -| solacebroker_msg_vpn_authentication_oauth_profile_client_required_claim | O | Requires above OAuth profile and it will be assigned to that | -| solacebroker_msg_vpn_authentication_oauth_profile_resource_server_required_claim | O | Requires above OAuth profile and it will be assigned to that | +| solacebroker_msg_vpn_authentication_oauth_profile_client_required_claim | O | This requires the above certificate matching rule and will be assigned to that rule upon creation. | +| solacebroker_msg_vpn_authentication_oauth_profile_resource_server_required_claim | O | This requires the above certificate matching rule and will be assigned to that rule upon creation. | | solacebroker_msg_vpn_cert_matching_rule | O | | | solacebroker_msg_vpn_cert_matching_rule_condition | O | Requires above certification matching rule and it will be assigned to that | | solacebroker_msg_vpn_cert_matching_rule_attribute_filter | O | Requires above certification matching rule and it will be assigned to that | ## Examples -Refer to the following configuration examples: +The following examples demonstrate several specific use cases for this module: - [Basic VPN](examples/basic-vpn) - [Services and listen ports](examples/services-and-listen-ports) @@ -86,7 +86,7 @@ Refer to the following configuration examples: ## Module use recommendations -This module is expected to be used primarily by middleware teams. It is primarily concerned with setting an environment and constraints where application developer teams may add their specific requirements through the Solace Client, Queues & Endpoints, JNDI or REST delivery modules. This module may be forked and adjusted with private defaults. +This module is expected to be used primarily by middleware teams. It is primarily concerned with setting an environment and constraints where application developer teams may add their specific requirements through the Solace Client, Queues & Endpoints, JNDI or REST Delivery modules. This module may be forked and adjusted with private defaults. ## Resources diff --git a/examples/basic-vpn/README.md b/examples/basic-vpn/README.md index a3557ba..1f10284 100644 --- a/examples/basic-vpn/README.md +++ b/examples/basic-vpn/README.md @@ -1,49 +1,49 @@ # Message VPN Configuration Example -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. +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 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 created Message VPN enables SMF and Web Transport messaging services with a message spool of 1500 MB assigned by default, as well as the use of JNDI and DMR. See 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). +The VPN includes a `default` permissive ACL profile and a client profile, like the ones in the `default` Message VPN. +These profiles enable ready-to-go messaging on the VPN for development and demo purposes. For production use you should specify a customized ACL and client profile as in [this example](examples/customized-client-and-acl-profiles). The default authentication method will be set to basic authentication with internal database. - A `default` client username will also be created, however it will be shutdown and it is left to the user to setup a client username that meets their security requirements. The recommended way is to use the [Client Module](https://registry.terraform.io/modules/SolceProducts/client/solacebroker/latest) to setup a client username. + A `default` client username is also created, however it will be shutdown and it is left to the user to setup a client username that meets their security requirements. We recommended that you use the [Client Module](https://registry.terraform.io/modules/SolceProducts/client/solacebroker/latest) to setup a client username. - Note: while not part of this module, it is strongly recommended to have the broker `default` message VPN, which allows unauthenticated access with any client username, shutdown. + Note: while not part of this module, we strongly recommend that you shutdown the `default` Message VPN on the event broker, because it allows unauthenticated access with any client username. ## Module Configuration in the Example ### Required Inputs -* `msg_vpn_name` - set to `myvpn` in the example +* `msg_vpn_name` - Set to `myvpn` in the example. ### 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"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn#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"](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. +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. +The module `created_vpn` output refers to the created Message VPN. -## Created resources +## Created Resources -This example will create following resources: +This example will create the 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. +Note that `default` ACL profile, client profile and client username objects will also be automatically created as part of the new Message VPN but are only available by referencing their name. ## 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: @@ -52,13 +52,13 @@ git clone https://github.com/SolaceProducts/terraform-solacebroker-service.git cd examples/basic-vpn ``` -### 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: @@ -68,8 +68,8 @@ 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. +Run `terraform destroy` to clean up the created resources when they are 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. +For more information, see [Configuring Message VPNs](https://docs.solace.com/Features/VPN/Configuring-VPNs.htm) section in the PubSub+ documentation. diff --git a/examples/client-certificate-authentication/README.md b/examples/client-certificate-authentication/README.md index 6577628..9202bac 100644 --- a/examples/client-certificate-authentication/README.md +++ b/examples/client-certificate-authentication/README.md @@ -2,34 +2,34 @@ This example shows how to configure [client certificate authentication](https://docs.solace.com/Security/Configuring-Client-Authentication.htm#Client-Cert) (or mTLS) for clients connecting to a PubSub+ event broker at the Message VPN level, leveraging the Service Terraform module. -Note: a pre-requisite for client certificate authentication is broker-level server key, certificate and certificate authorities configured, which is outside the scope of this module. +Note: before you can enable client certificate authentication, you need an event broker-level server key, certificate, and you must configure certificate authorities. These prerequisites are outside the scope of this module. -The module exposes [client certificate authentication related message VPN configuration](https://docs.solace.com/Security/Configuring-Client-Authentication.htm#Client-CERT-VPNs) through input variables. It also supports the setup of a [message VPN matching](https://docs.solace.com/Security/Configuring-Client-Authentication.htm#Configur) rule with a set of conditions or a set of attribute filters. Note that if more matching rules are required then these will need to be configured outside the module. +The module exposes [client certificate authentication related Message VPN configuration](https://docs.solace.com/Security/Configuring-Client-Authentication.htm#Client-CERT-VPNs) through input variables. It also supports the setup of a [Message VPN matching](https://docs.solace.com/Security/Configuring-Client-Authentication.htm#Configur) rule with a set of conditions or a set of attribute filters. Note that if more matching rules are required then you need to configure them outside the module. ## Module Configuration in the Example ### Required Inputs -* `msg_vpn_name` - set to `vpn-with-mtls` in the example +* `msg_vpn_name` - Set to `vpn-with-mtls` in the example. ### Optional Inputs -* `authentication_client_cert_enabled` - set to `true` for client certificate authentication in the example. Automatically enabled if VPN matching is configured -* `cert_matching_rule_name` - specified if message VPN matching is required -* `cert_matching_rule_conditions` - a set of conditions for above certificate matching rule -* `cert_matching_rule_attribute_filters` - a set of filters for above certificate matching rule +* `authentication_client_cert_enabled` - Set to `true` for client certificate.authentication in the example. Automatically enabled if VPN matching is configured. +* `cert_matching_rule_name` - Specified if Message VPN matching is required. +* `cert_matching_rule_conditions` - A set of conditions for above certificate matching rule. +* `cert_matching_rule_attribute_filters` - A set of filters for above certificate matching rule. -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). +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 a list of attributes and the corresponding defaults, see 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. +The module default for the `enabled` variable is true, which enables the Message VPN and underlying resources. ### Output -The module `created_vpn` and `created_cert_matching_rule` outputs refer to the created message VPN and the certificate matching rule. There are also outputs for the list of conditions and attribute filters. +The module `created_vpn` and `created_cert_matching_rule` outputs refer to the created Message VPN and the certificate matching rule. There are also outputs for the list of conditions and attribute filters. -## Created resources +## Created Resources -This example will create following resources: +This example will create the following resources: * `solacebroker_msg_vpn` * `solacebroker_msg_vpn_cert_matching_rule` @@ -38,11 +38,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: @@ -51,13 +51,13 @@ git clone https://github.com/SolaceProducts/terraform-solacebroker-service.git cd examples/client-certificate-authentication ``` -### 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: @@ -67,8 +67,8 @@ 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. +Run `terraform destroy` to clean up the created resources when they are 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 [OAuth Authentication](https://docs.solace.com/Security/Configuring-Client-Authentication.htm#OAuth) section in the PubSub+ documentation. +For more information, see [OAuth Authentication](https://docs.solace.com/Security/Configuring-Client-Authentication.htm#OAuth) section in the PubSub+ documentation. diff --git a/examples/customized-acl-and-client-profiles/README.md b/examples/customized-acl-and-client-profiles/README.md index 50cbe3a..09ca11d 100644 --- a/examples/customized-acl-and-client-profiles/README.md +++ b/examples/customized-acl-and-client-profiles/README.md @@ -1,47 +1,47 @@ # Customized ACL and Client Profile Configuration Example -Configuration in this directory shows how to create a customized [ACL profile](https://docs.solace.com/Security/Granting-Clients-Access.htm) or a [client profile](https://docs.solace.com/Security/Assigning-Client-Profiles.htm) on a new message VPN on the PubSub+ event broker, leveraging the Service Terraform module. +Configuration in this directory shows how to create a customized [ACL profile](https://docs.solace.com/Security/Granting-Clients-Access.htm) or a [client profile](https://docs.solace.com/Security/Assigning-Client-Profiles.htm) on a new Message VPN on the PubSub+ event broker, leveraging the Service Terraform module. -A new message VPN will automatically include a permissive `default` ACL profile and a `default` client profile that support development and demo purposes. They are not configurable through module variables. If profiles are required to meet specific requirements, the module enables creating an additional customizable ACL and client profile. At a minimum, a name for the profile must be provided and any non-default attribute values. +A new Message VPN automatically includes a permissive `default` ACL profile and a `default` client profile for development and demo purposes. They are not configurable through module variables. If you need profiles to meet specific requirements, the module enables creating an additional customizable ACL and client profile. At a minimum, a name for the profile must be provided and any non-default attribute values. ## Module Configuration in the Example ### Required Inputs -* `msg_vpn_name` - set to `vpn-with-acl-and-client-profiles` in the example +* `msg_vpn_name` - Set to `vpn-with-acl-and-client-profiles` in the example. ### Optional Inputs -* `acl_profile_name` - an additional ACL profile will only be created if a name is provided -* `client_connect_default_action` - a random attribute demonstrating setting a non-default value -* `client_profile_name` - an additional client profile will only be created if a name is provided -* `compression_enabled` - a random attribute demonstrating setting a non-default value +* `acl_profile_name` - An additional ACL profile will only be created if a name is provided. +* `client_connect_default_action` - A random attribute demonstrating setting a non-default value. +* `client_profile_name` - An additional client profile will only be created if a name is provided. +* `compression_enabled` - A random attribute demonstrating setting a non-default value. -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), ["solacebroker_msg_vpn_acl_profile"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_acl_profile#optional) and ["solacebroker_msg_vpn_client_profile"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_client_profile#optional). +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 a list of attributes and the corresponding defaults, see the documentation of ["solacebroker_msg_vpn"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn#optional), ["solacebroker_msg_vpn_acl_profile"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_acl_profile#optional) and ["solacebroker_msg_vpn_client_profile"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_client_profile#optional). -The module default for the `enabled` variable is true, which enables the message VPN and underlying resources. +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_acl_profile` and `created_client_profile` refer to the additional ACL and client profiles included in the VPN. +The module `created_vpn` output refers to the created Message VPN, `created_acl_profile` and `created_client_profile` refer to the additional ACL and client profiles included in the VPN. -## Created resources +## Created Resources -This example will create following resources: +This example will create the following resources: * `solacebroker_msg_vpn` * `solacebroker_msg_vpn_acl_profile` * `solacebroker_msg_vpn_client_profile` -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. +Note that `default` ACL profile, client profile and client username objects will also be automatically created as part of the new Message VPN but are only available by referencing their name. ## 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: @@ -50,13 +50,13 @@ git clone https://github.com/SolaceProducts/terraform-solacebroker-service.git cd examples/customized-acl-and-client-profiles ``` -### 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: @@ -66,8 +66,8 @@ 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. +Run `terraform destroy` to clean up the created resources when they are 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. +For more information, see [Configuring Message VPNs](https://docs.solace.com/Features/VPN/Configuring-VPNs.htm) section in the PubSub+ documentation. diff --git a/examples/oauth-authentication/README.md b/examples/oauth-authentication/README.md index 122db0b..e29e76f 100644 --- a/examples/oauth-authentication/README.md +++ b/examples/oauth-authentication/README.md @@ -2,34 +2,34 @@ This example shows how to configure OAuth authentication for clients connecting to a PubSub+ event broker at the Message VPN level, leveraging the Service Terraform module. -To set this up, OAuth authentication must be enabled on the new message VPN and an OAuth profile must be created. With specifying the `oauth_profile_name` variable, the module will take care of both. Necessary [OAuth profile attributes](https://docs.solace.com/Security/Configuring-Client-Authentication.htm#Managing-OAuth-Profiles) can be set through module variables. It is also possible to provide a list of required claim values for both client or resource server roles of the event broker. +To set this up, you must enable OAuth authentication on the new Message VPN and create an OAuth profile.. With specifying the `oauth_profile_name` variable, the module will take care of both. Necessary [OAuth profile attributes](https://docs.solace.com/Security/Configuring-Client-Authentication.htm#Managing-OAuth-Profiles) can be set through module variables. It is also possible to provide a list of required claim values for both client or resource server roles of the event broker. -Note that the module supports creating one OAuth profile, which will also be set as the default for the message VPN. Additional OAuth profiles may be configured outside the module. +Note that the module supports creating one OAuth profile, which will also be set as the default for the Message VPN. Additional OAuth profiles may be configured outside the module. ## Module Configuration in the Example ### Required Inputs -* `msg_vpn_name` - set to `vpn-with-oauth` in the example +* `msg_vpn_name` - Set to `vpn-with-oauth` in the example. ### Optional Inputs -* `oauth_profile_name` - set to `sampleVpnOauthProfile`, must be provided to get an OAuth profile created. This profile will be set as the default VPN OAuth profile. This will also enable OAuth authentication for the VPN. -* `oauth_role` - an example module input variable for the OAuth profile -* `oauth_profile_client_required_claims` - a set of required claims when the broker is acting as an OAuth client -* `oauth_profile_resource_server_required_claims` - a set of required claims when the broker is acting as an OAuth resource server +* `oauth_profile_name` - Set to `sampleVpnOauthProfile`, must be provided to get an OAuth profile created. This profile will be set as the default VPN OAuth profile. This will also enable OAuth authentication for the VPN. +* `oauth_role` - An example module input variable for the OAuth profile. +* `oauth_profile_client_required_claims` - A set of required claims when the event broker is acting as an OAuth client. +* `oauth_profile_resource_server_required_claims` - A set of required claims when the event broker is acting as an OAuth resource server. -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_authentication_oauth_profile"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_authentication_oauth_profile#optional). +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 a list of attributes and the corresponding defaults, see the documentation of ["solacebroker_msg_vpn_authentication_oauth_profile"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_authentication_oauth_profile#optional). -The module default for the `enabled` variable is true, which enables the message VPN and underlying resources. +The module default for the `enabled` variable is true, which enables the Message VPN and underlying resources. ### Output -The module `created_vpn` and `created_oauth_profile` outputs refer to the created message VPN and the OAuth profile. The claims outputs provide the list of the created required claims. +The module `created_vpn` and `created_oauth_profile` outputs refer to the created Message VPN and the OAuth profile. The claims outputs provide the list of the created required claims. -## Created resources +## Created Resources -This example will create following resources: +This example will create the following resources: * `solacebroker_msg_vpn` * `solacebroker_msg_vpn_authentication_oauth_profile` @@ -38,11 +38,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: @@ -51,13 +51,13 @@ git clone https://github.com/SolaceProducts/terraform-solacebroker-service.git cd examples/oauth-authentication ``` -### 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: @@ -67,8 +67,8 @@ 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. +Run `terraform destroy` to clean up the created resources when they are 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 [OAuth Authentication](https://docs.solace.com/Security/Configuring-Client-Authentication.htm#OAuth) section in the PubSub+ documentation. +For more information, see [OAuth Authentication](https://docs.solace.com/Security/Configuring-Client-Authentication.htm#OAuth) section in the PubSub+ documentation. diff --git a/examples/services-and-listen-ports/README.md b/examples/services-and-listen-ports/README.md index 645cba3..459f514 100644 --- a/examples/services-and-listen-ports/README.md +++ b/examples/services-and-listen-ports/README.md @@ -1,45 +1,45 @@ # 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. +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. +SMF and Web Transport messaging services are configured at the event 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. +A service may also use plain text or secure transport. Although in general we recommend that you 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 +* `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 `9001` in this example. Note that the port number must be unique for the broker, port 9000 is already used by the default VPN +* `service_rest_incoming_plain_text_enabled` - Set to `true` in this example. +* `service_rest_incoming_plain_text_listen_port` - Set to `9001` in this example. Note that the port number must be unique for the broker, port 9000 is already used by the default VPN. -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). +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 a list of attributes and the corresponding defaults, see 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. +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. +The module `created_vpn` output refers to the created Message VPN. -## Created resources +## Created Resources -This example will create following resources: +This example will create the 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. +Note that `default` ACL profile, client profile and client username objects will also be automatically created as part of the new Message VPN but are only available by referencing their name. ## 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-service.git cd examples/services-and-listen-ports ``` -### 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. Note that as part of this command there may be a warning about default objects cannot be deleted, this is normal and expected here. +Run `terraform destroy` to clean up the created resources when they are 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. +For more information, see [Configuring Message VPNs](https://docs.solace.com/Features/VPN/Configuring-VPNs.htm) section in the PubSub+ documentation.