Skip to content

Commit

Permalink
Ported documentation updates from sw module
Browse files Browse the repository at this point in the history
  • Loading branch information
@bczoma
bczoma committed Jul 9, 2024
1 parent cc39306 commit 7f396e1
Show file tree
Hide file tree
Showing 7 changed files with 140 additions and 140 deletions.
4 changes: 2 additions & 2 deletions .github/workflows/verify-registry-release.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,10 +50,10 @@ jobs:
MODULENAME=service
if [ "${{ github.event.inputs.public_release }}" == "false" ] ; then
echo Internal release
MODULE_REF="app.terraform.io/SolaceDev/$MODULENAME/solacebroker"
MODULE_REF="app.terraform.io/SolaceDev/$MODULENAME/solacebrokerappliance"
else
echo Public release
MODULE_REF="SolaceProducts/$MODULENAME/solacebroker"
MODULE_REF="SolaceProducts/$MODULENAME/solacebrokerappliance"
fi
ci/scripts/test-module.sh ci/module-test/ "" $MODULE_REF "${{ github.event.inputs.release_version }}"
62 changes: 31 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,82 +1,82 @@
# Solace PubSub+ Software Event Broker Service Terraform Module
# Solace PubSub+ Appliance 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/SolaceProducts/client/solacebrokerappliance/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 |
|---------------|
|[solacebroker_msg_vpn](https://registry.terraform.io/providers/solaceproducts/solacebrokerappliance/latest/docs/resources/msg_vpn#optional)|
|[solacebroker_msg_vpn_acl_profile](https://registry.terraform.io/providers/solaceproducts/solacebrokerappliance/latest/docs/resources/msg_vpn_acl_profile#optional)|
|[solacebroker_msg_vpn_client_profile](https://registry.terraform.io/providers/solaceproducts/solacebrokerappliance/latest/docs/resources/msg_vpn_client_profile#optional)|
|[solacebroker_msg_vpn_authentication_oauth_profile](https://registry.terraform.io/providers/solaceproducts/solacebrokerappliance/latest/docs/resources/msg_vpn_authentication_oauth_profile#optional)|
|[solacebroker_msg_vpn](https://registry.terraform.io/providers/SolaceProducts/solacebrokerappliance/latest/docs/resources/msg_vpn#optional)|
|[solacebroker_msg_vpn_acl_profile](https://registry.terraform.io/providers/SolaceProducts/solacebrokerappliance/latest/docs/resources/msg_vpn_acl_profile#optional)|
|[solacebroker_msg_vpn_client_profile](https://registry.terraform.io/providers/SolaceProducts/solacebrokerappliance/latest/docs/resources/msg_vpn_client_profile#optional)|
|[solacebroker_msg_vpn_authentication_oauth_profile](https://registry.terraform.io/providers/SolaceProducts/solacebrokerappliance/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:

| Input variable | Default value | Note |
|----------------|---------------|------|
| `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

| Name | Version |
|------|---------|
| <a name="provider_solacebroker"></a> [solacebroker](https://registry.terraform.io/providers/solaceproducts/solacebrokerappliance/latest) | >= 1.0 |
| <a name="provider_solacebrokerappliance"></a> [solacebrokerappliance](https://registry.terraform.io/providers/SolaceProducts/solacebrokerappliance/latest) | >= 1.0 |

## 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 AOuth profile and it will be assigned to that |
| solacebroker_msg_vpn_authentication_oauth_profile_resource_server_required_claim | O | Requires above AOuth 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)
Expand All @@ -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

Expand Down
44 changes: 22 additions & 22 deletions examples/basic-vpn/README.md
View file
Original file line number Diff line number Diff line change
@@ -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/SolaceProducts/client/solacebrokerappliance/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/solacebrokerappliance/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/solacebrokerappliance/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:

Expand All @@ -52,13 +52,13 @@ git clone https://github.com/SolaceProducts/terraform-solacebrokerappliance-serv
cd examples/basic-vpn
```

### Adjust Provider Configuration
### Adjust the Provider Configuration

Adjust the [provider parameters](https://registry.terraform.io/providers/solaceproducts/solacebrokerappliance/latest/docs#schema) in `main.tf` according to your broker. The example configuration shows settings for a local broker running in Docker.
Adjust the [provider parameters](https://registry.terraform.io/providers/SolaceProducts/solacebrokerappliance/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:

Expand All @@ -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.
Loading

0 comments on commit 7f396e1

Please sign in to comment.