diff --git a/README.md b/README.md index ae5cae0..36559d9 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,30 @@ # Solace PubSub+ Software Event Broker Client Terraform Module -Terraform module to provision a client identifier for [authorization](https://docs.solace.com/Security/Client-Authorization-Overview.htm) when connecting to the [Solace PubSub+ Event Broker](https://solace.com/products/event-broker/). The module also provides the option to adjust the assigned ACL profile through defining ACL profile exceptions, and to define additional attributes for client usernames. +This Terraform module provisions a client identifier for [authorization](https://docs.solace.com/Security/Client-Authorization-Overview.htm) when connecting to the [Solace PubSub+ Event Broker](https://solace.com/products/event-broker/). The module also provides the option to adjust the assigned ACL profile through defining ACL profile exceptions, and to define additional attributes for client usernames. The identifier may be one of: * [Client username](https://docs.solace.com/Security/Configuring-Client-Usernames.htm); or * Authorization group (used for [OAuth](https://docs.solace.com/Security/Client-Authorization-Overview.htm#Authoriz2) or [LDAP](https://docs.solace.com/Security/Client-Authorization-Overview.htm#LDAP-Groups)) -Specific use case details are provided in the [Examples](#examples). +Specific use case details are provided in the [Examples](#examples) section. ## Module input variables ### Required -* `msg_vpn_name` - client usernames or authorization groups are specific to a Message VPN on the broker -* `client_identifier_type` - One of `client_username` or `authorization_group` -* `client_identifier_name` - The name of the client identifier -* `acl_profile_name` - The ACL profile to be assigned for authorization -* `client_profile_name` - The client profile to be assigned for authorization +* `msg_vpn_name` - Client usernames or authorization groups are specific to a Message VPN on the broker. +* `client_identifier_type` - One of `client_username` or `authorization_group`. +* `client_identifier_name` - The name of the client identifier. +* `acl_profile_name` - The ACL profile to be assigned for authorization. +* `client_profile_name` - The client profile to be assigned for authorization. ### Optional -* `password` - If using a client username to identify the client and configured basic authentication with internal database for the Message VPN, this variable provisions a password for authentication. -* `acl_profile_publish_topic_exceptions`, `acl_profile_subscribe_share_name_exceptions`, `acl_profile_subscribe_topic_exceptions`, `acl_profile_client_connect_exceptions` - Optional exceptions that may be added to modify the assigned ACL profile, to support specific needs of the client. -* `client_username_attributes` - A set of attributes that may be defined in case of using a client username. +* `password` - If you are using a client username to identify the client and configured basic authentication with internal database for the Message VPN, this variable provisions a password for authentication. +* `acl_profile_publish_topic_exceptions`, `acl_profile_subscribe_share_name_exceptions`, `acl_profile_subscribe_topic_exceptions`, `acl_profile_client_connect_exceptions` - Optional exceptions that you can add to modify the assigned ACL profile, to support specific needs of the client. +* `client_username_attributes` - A set of attributes that you can define in case of using a client username. -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 | |---------------| @@ -36,7 +36,7 @@ Additional optional module variable names are the same as the underlying resourc |[solacebroker_msg_vpn_acl_profile_client_connect_exception](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_acl_profile_client_connect_exception#optional)| |[solacebroker_msg_vpn_client_username_attribute](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_client_username_attribute#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. -> The module default for the `enabled` optional variable is `true`, which differs from the resource attribute default. @@ -54,7 +54,7 @@ Note that the "client username" and the "authorization group" outputs are [sensi ## Resources -The following table shows the resources created for each `client_identifier_type` value. "X" denotes a resource always created, "O" is a resource that may be created optionally +The following table shows the resources created for each `client_identifier_type` value. "X" denotes a resource that is always created, "O" denotes a resource that you have the option to create. | Name | client_username | authorization_group | |------|------|------| @@ -69,7 +69,7 @@ The following table shows the resources created for each `client_identifier_type ## Examples -Refer to the following configuration examples: +The following examples demonstrate several specific use cases for this module: - [Client username](examples/basic-client-username) - [Client username attributes](examples/client-username-attributes) diff --git a/examples/acl-profile-exceptions/README.md b/examples/acl-profile-exceptions/README.md index 1e48053..e7b1020 100644 --- a/examples/acl-profile-exceptions/README.md +++ b/examples/acl-profile-exceptions/README.md @@ -1,6 +1,6 @@ # ACL Profile Exceptions Configuration Example -This directory demonstrates configuration of a client username with [ACL profile exceptions](https://docs.solace.com/Security/Managing-Access-Control-Lists.htm) on the PubSub+ event broker, leveraging the Client Terraform module. +This directory demonstrates the configuration of a client username with [ACL profile exceptions](https://docs.solace.com/Security/Managing-Access-Control-Lists.htm) on the PubSub+ event broker, leveraging the Client Terraform module. One set of use cases is if the assigned ACL profile is restrictive (the default value is "disallow") and individual permissions are added as exceptions. Other cases need individual exceptions to a permissive profile. Both serve the configuration of specific requirements of the client being provisioned. @@ -16,17 +16,17 @@ Also note that topic exceptions may use [substitution variables](https://docs.so ### Required Inputs -* `msg_vpn_name` - set to `default` in the example -* `client_identifier_type` - set to `client_username` -* `client_identifier_name` - set to `myclient` in the example. -* `client_profile_name` - `default`, in the example -* `acl_profile_name` - `default`, in the example. The "default" ACL profile's default actions are "allow", so all exceptions defined will be denied. +* `msg_vpn_name` - Set to `default` in the example. +* `client_identifier_type` - Set to `client_username`. +* `client_identifier_name` - Set to `myclient` in the example. +* `client_profile_name` - Set to `default` in the example. +* `acl_profile_name` - Set to `default` in the example. The "default" ACL profile's default actions are "allow", so all exceptions defined will be denied. ### Optional Inputs * `acl_profile_publish_topic_exceptions`, `acl_profile_subscribe_topic_exceptions`, `acl_profile_subscribe_share_name_exceptions`, `acl_profile_client_connect_exceptions` - examples show how to define them in a list form. -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_client_username"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_client_username#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_client_username"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_client_username#optional). The module default for the `enabled` variable is true, which enables the client username. @@ -34,9 +34,9 @@ The module default for the `enabled` variable is true, which enables the client The module `client_username` output refers to the created client username and the exceptions outputs provide the list the created exceptions. -## Created resources +## Created Resources -This example will create following resources: +This example will create the following resources: * `solacebroker_msg_vpn_client_username` * `solacebroker_msg_vpn_acl_profile_publish_topic_exception` @@ -46,11 +46,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: @@ -59,13 +59,13 @@ git clone https://github.com/SolaceProducts/terraform-solacebroker-rest-delivery cd examples/acl-profile-exceptions ``` -### 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: @@ -75,8 +75,8 @@ terraform plan terraform apply ``` -Run `terraform destroy` to clean up created resources when no longer needed. +Run `terraform destroy` to clean up the created resources when they are no longer needed. ## Additional Documentation -Refer to the [Configuring Client Authorization](https://docs.solace.com/Security/Configuring-Client-Authorization.htm) section in the PubSub+ documentation. +For more information, see [Configuring Client Authorization](https://docs.solace.com/Security/Configuring-Client-Authorization.htm) section in the PubSub+ documentation. diff --git a/examples/authorization-group/README.md b/examples/authorization-group/README.md index 0f6af91..bc943ad 100644 --- a/examples/authorization-group/README.md +++ b/examples/authorization-group/README.md @@ -6,15 +6,15 @@ Configuration in this directory creates an authorization group on the PubSub+ ev ### Required Inputs -* `msg_vpn_name` - set to `default` in the example -* `client_identifier_type` - set to `authorization_group` -* `client_identifier_name` - set to `myauthgroup` in the example. -* `client_profile_name` - `default`, in the example -* `acl_profile_name` - `default`, in the example +* `msg_vpn_name` - Set to `default` in the example. +* `client_identifier_type` - Set to `authorization_group`. +* `client_identifier_name` - Set to `myauthgroup` in the example. +* `client_profile_name` - Set to `default` in the example. +* `acl_profile_name` - Set to `default` 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_authorization_group"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_authorization_group#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_authorization_group"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_authorization_group#optional). The module default for the `enabled` variable is true, which enables the authorization group. @@ -22,19 +22,19 @@ The module default for the `enabled` variable is true, which enables the authori The module `authorization_group` output refers to the created authorization group. -## Created resources +## Created Resources -This example will create following resources: +This example will create the following resources: * `solacebroker_msg_vpn_authorization_group` ## 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: @@ -43,13 +43,13 @@ git clone https://github.com/SolaceProducts/terraform-solacebroker-rest-delivery cd examples/authorization-group ``` -### 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: @@ -59,8 +59,8 @@ terraform plan terraform apply ``` -Run `terraform destroy` to clean up created resources when no longer needed. +Run `terraform destroy` to clean up the created resources when they are no longer needed. ## Additional Documentation -Refer to the [Configuring Client Authorization](https://docs.solace.com/Security/Configuring-Client-Authorization.htm) section in the PubSub+ documentation. +For more information, see [Configuring Client Authorization](https://docs.solace.com/Security/Configuring-Client-Authorization.htm) section in the PubSub+ documentation. diff --git a/examples/basic-client-username/README.md b/examples/basic-client-username/README.md index 7f2e06c..5d2c14a 100644 --- a/examples/basic-client-username/README.md +++ b/examples/basic-client-username/README.md @@ -2,23 +2,23 @@ Configuration in this directory creates a [client username](https://docs.solace.com/Admin/Broker-Manager/broker-manager-create-client-username.htm) on the PubSub+ event broker, leveraging the Client Terraform module. -The example shows setting the sensitive `password` 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. +The example shows how to set the sensitive `password` 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 -* `client_identifier_type` - set to `client_username` -* `client_identifier_name` - set to `myclient` in the example. -* `client_profile_name` - `default`, in the example -* `acl_profile_name` - `default`, in the example +* `msg_vpn_name` - Set to `default` in the example. +* `client_identifier_type` - Set to `client_username` in the example. +* `client_identifier_name` - Set to `myclient` in the example. +* `client_profile_name` - Set to `default` in the example. +* `acl_profile_name` - Set to `default` in the example. ### Optional Inputs * `password` - this example demonstrates when the client username is also used for authentication purposes if basic authentication with internal database has been configured for the Message VPN. In this case a password needs to be specified, which is shown 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_client_username"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_client_username#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_client_username"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_client_username#optional). The module default for the `enabled` variable is true, which enables the client username. @@ -26,19 +26,19 @@ The module default for the `enabled` variable is true, which enables the client The module `client_username` output refers to the created client username. -## Created resources +## Created Resources -This example will create following resources: +This example will create the following resources: * `solacebroker_msg_vpn_client_username` ## 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: @@ -47,13 +47,13 @@ git clone https://github.com/SolaceProducts/terraform-solacebroker-rest-delivery cd examples/basic-client-username ``` -### 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: @@ -63,8 +63,8 @@ terraform plan -var-file="secret.tfvars" terraform apply -var-file="secret.tfvars" ``` -Run `terraform destroy` to clean up created resources when no longer needed. +Run `terraform destroy` to clean up the created resources when they are no longer needed. ## Additional Documentation -Refer to the [Configuring Client Authorization](https://docs.solace.com/Security/Configuring-Client-Authorization.htm) section in the PubSub+ documentation. +For more information, see [Configuring Client Authorization](https://docs.solace.com/Security/Configuring-Client-Authorization.htm) section in the PubSub+ documentation. diff --git a/examples/client-username-attributes/README.md b/examples/client-username-attributes/README.md index a9904c0..3372571 100644 --- a/examples/client-username-attributes/README.md +++ b/examples/client-username-attributes/README.md @@ -1,22 +1,22 @@ # Client Username Attributes Configuration Example -This directory demonstrates configuration of a client username with additional [client username attributes](https://docs.solace.com/Security/Configuring-Client-Usernames.htm?Highlight=client%20username%20attributes#Setting) on the PubSub+ event broker, leveraging the Client Terraform module. +This directory demonstrates the configuration of a client username with additional [client username attributes](https://docs.solace.com/Security/Configuring-Client-Usernames.htm?Highlight=client%20username%20attributes#Setting) on the PubSub+ event broker, leveraging the Client Terraform module. ## Module Configuration in the Example ### Required Inputs -* `msg_vpn_name` - set to `default` in the example -* `client_identifier_type` - set to `client_username` -* `client_identifier_name` - set to `myclientwithattributes` in the example. -* `client_profile_name` - `default`, in the example -* `acl_profile_name` - `default`, in the example +* `msg_vpn_name` - Set to `default` in the example. +* `client_identifier_type` - Set to `client_username` in the example. +* `client_identifier_name` - Set to `myclientwithattributes` in the example. +* `client_profile_name` - Set to `default` in the example. +* `acl_profile_name` - Set to `default` in the example. ### Optional Inputs * `client_username_attributes` - a set of attributes in a list form. -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_client_username"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_client_username#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_client_username"](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_client_username#optional). The module default for the `enabled` variable is true, which enables the client username. @@ -24,20 +24,20 @@ The module default for the `enabled` variable is true, which enables the client The module `client_username` output refers to the created client username and the `attributes` output provides the list of created attributes. -## Created resources +## Created Resources -This example will create following resources: +This example will create the following resources: * `solacebroker_msg_vpn_client_username` * `solacebroker_msg_vpn_client_username_attribute` ## 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: @@ -46,13 +46,13 @@ git clone https://github.com/SolaceProducts/terraform-solacebroker-rest-delivery cd examples/client-username-attributes ``` -### 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: @@ -62,8 +62,8 @@ terraform plan terraform apply ``` -Run `terraform destroy` to clean up created resources when no longer needed. +Run `terraform destroy` to clean up the created resources when they are no longer needed. ## Additional Documentation -Refer to the [Configuring Client Authorization](https://docs.solace.com/Security/Configuring-Client-Authorization.htm) section in the PubSub+ documentation. +For more information, see [Configuring Client Authorization](https://docs.solace.com/Security/Configuring-Client-Authorization.htm) section in the PubSub+ documentation.