ADjusted client identifier var name, added README to basic example

SolaceProducts · Mar 11, 2024 · 4b8afa7 · 4b8afa7
1 parent 1859387
commit 4b8afa7
Show file tree

Hide file tree

Showing 12 changed files with 93 additions and 23 deletions.
diff --git a/README.md b/README.md
@@ -4,24 +4,24 @@ Terraform module to provision a client identifier for [authorization](https://do
 
 The identifier may be one of:
 * [Client username](https://docs.solace.com/Security/Configuring-Client-Usernames.htm); or
-* Authorization group (when using [OAuth](https://docs.solace.com/Security/Client-Authorization-Overview.htm#Authoriz2) or [LDAP](https://docs.solace.com/Security/Client-Authorization-Overview.htm#LDAP-Groups))
+* 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).
 
 ## Module input variables
 
 ### Required
 
-* `msg_vpn_name` - REST delivery points are specific to a Message VPN on the broker.
-* `client_identifier_type` - One of `client_username` or `authorization_group`.
-* `client_name` - The name of the client identifier.
-* `acl_profile_name` - The ACL profile to be used for authorization of the client.
-* `client_profile_name` - The client profile to be used for authorization of the client.
+* `msg_vpn_name` - REST delivery points 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` - A set of exceptions that may be added to the ACL profile, to support specific needs of the client.
+* `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.
 
 Additional optional module variables 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:
@@ -38,7 +38,7 @@ Additional optional module variables names are the same as the underlying resour
 
 Most optional variables' default value is `null`, meaning that if not provided then the resource default value will be provisioned on the broker.
 
--> The module default for the `enabled` optional variable is `true`, which differ from the resource attribute default.
+-> The module default for the `enabled` optional variable is `true`, which differs from the resource attribute default.
 
 ## Module outputs
 
@@ -78,7 +78,7 @@ Refer to the following configuration examples:
 
 ## Module use recommendations
 
-This module is expected to be used primarily by application teams. It supports provisioning a client username or an authorization group required by a specific application. It may be forked and adjusted with private defaults.
+This module is expected to be used primarily by application teams. It supports provisioning a client username or an authorization group with possible adjustments, required by a specific application. It may be forked and adjusted with private defaults.
 
 ## Resources
 

diff --git a/ci/module-test/main.tf b/ci/module-test/main.tf
@@ -8,7 +8,7 @@ module "testclientusername" {
   source = "../.."
 
   msg_vpn_name             = "default"
-  client_name              = "myclient"
+  client_identifier_name              = "myclient"
   client_identifier_type   = "client_username"
   client_profile_name      = "default"
   acl_profile_name         = "default"
@@ -85,7 +85,7 @@ module "testauthorizationgroup" {
   source = "../../internal/gen-template"
 
   msg_vpn_name             = "default"
-  client_name              = "myauthorizationgroup"
+  client_identifier_name              = "myauthorizationgroup"
   client_identifier_type   = "authorization_group"
   client_profile_name      = "default"
   acl_profile_name         = "default"

diff --git a/ci/template-test/main.tf b/ci/template-test/main.tf
@@ -8,7 +8,7 @@ module "testclientusername" {
   source = "../../internal/gen-template"
 
   msg_vpn_name             = "default"
-  client_name              = "myclient"
+  client_identifier_name              = "myclient"
   client_identifier_type   = "client_username"
   client_profile_name      = "default"
   acl_profile_name         = "default"
@@ -84,7 +84,7 @@ module "testauthorizationgroup" {
   source = "../../internal/gen-template"
 
   msg_vpn_name             = "default"
-  client_name              = "myauthorizationgroup"
+  client_identifier_name              = "myauthorizationgroup"
   client_identifier_type   = "authorization_group"
   client_profile_name      = "default"
   acl_profile_name         = "default"

diff --git a/examples/acl-profile-exceptions/main.tf b/examples/acl-profile-exceptions/main.tf
@@ -23,7 +23,7 @@ module "testclient" {
 
   msg_vpn_name             = "default"
   client_identifier_type   = "client_username"
-  client_name              = "myclient"
+  client_identifier_name              = "myclient"
   client_profile_name      = "default"
   acl_profile_name         = "default"
 

diff --git a/examples/authorization-group/main.tf b/examples/authorization-group/main.tf
@@ -23,7 +23,7 @@ module "testauthgroup" {
 
   msg_vpn_name             = "default"
   client_identifier_type   = "authorization_group"
-  client_name              = "myauthgroup"
+  client_identifier_name              = "myauthgroup"
   client_profile_name      = "default"
   acl_profile_name         = "default"
 

diff --git a/examples/basic-client-username/README.md b/examples/basic-client-username/README.md
@@ -0,0 +1,70 @@
+# Client Username Configuration Example
+
+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.
+
+## 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
+
+### 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 (this is the case for the `default` 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).
+
+The module default for the `enabled` variable is true, which enables both the RDP and the REST consumer resources.
+
+### Output
+
+The module `client_username` output refers to the created client username.
+
+## Created resources
+
+This example will create following resources:
+
+* `solacebroker_msg_vpn_client_username`
+
+## Running the Example
+
+### Access to a PubSub+ broker
+
+If you don't already have access to a broker, refer to the [Developers page](https://www.solace.dev/) for options to get started.
+
+### Sample source code
+
+The sample is available from the module GitHub repo:
+
+```bash
+git clone https://github.com/SolaceProducts/terraform-solacebroker-rest-delivery.git
+cd examples/adding-headers
+```
+
+### Adjust Provider Configuration
+
+Adjust the [provider parameters](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs#schema) in `main.tf` according to your broker. The example configuration shows settings for a local broker running in Docker.
+
+### Create the resource
+
+Hint: You can verify configuration changes on the broker, before and after, using the [PubSub+ Broker Manager Web UI](https://docs.solace.com/Admin/Broker-Manager/PubSub-Manager-Overview.htm)
+
+Execute from this folder:
+
+```bash
+terraform init
+terraform plan -var-file="secret.tfvars"
+terraform apply -var-file="secret.tfvars"
+```
+
+Run `terraform destroy` to clean up created resources when 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.
diff --git a/examples/basic-client-username/main.tf b/examples/basic-client-username/main.tf
@@ -23,7 +23,7 @@ module "testclient" {
 
   msg_vpn_name             = "default"
   client_identifier_type   = "client_username"
-  client_name              = "myclient"
+  client_identifier_name   = "myclient"
   client_profile_name      = "default"
   acl_profile_name         = "default"
 

diff --git a/examples/client-username-attributes/main.tf b/examples/client-username-attributes/main.tf
@@ -23,7 +23,7 @@ module "testclient" {
 
   msg_vpn_name             = "default"
   client_identifier_type   = "client_username"
-  client_name              = "myclient"
+  client_identifier_name              = "myclient"
   client_profile_name      = "default"
   acl_profile_name         = "default"
 

diff --git a/internal/gen-template/main.tf b/internal/gen-template/main.tf
@@ -9,7 +9,7 @@ resource "solacebroker_msg_vpn_client_username" "main" {
   count = var.client_identifier_type == "client_username" ? 1 : 0
 
   msg_vpn_name    = var.msg_vpn_name
-  client_username = var.client_name
+  client_username = var.client_identifier_name
   client_profile_name     = var.client_profile_name
   acl_profile_name = var.acl_profile_name
   enabled = var.enabled
@@ -21,7 +21,7 @@ resource "solacebroker_msg_vpn_authorization_group" "main" {
   count = var.client_identifier_type == "authorization_group" ? 1 : 0
 
   msg_vpn_name    = var.msg_vpn_name
-  authorization_group_name = var.client_name
+  authorization_group_name = var.client_identifier_name
   client_profile_name     = var.client_profile_name
   acl_profile_name = var.acl_profile_name
   enabled = var.enabled

diff --git a/internal/gen-template/variables.tf b/internal/gen-template/variables.tf
@@ -16,7 +16,7 @@ variable "client_identifier_type" {
   }
 }
 
-variable "client_name" {
+variable "client_identifier_name" {
   description = "The name of the client identifier"
   type        = string
 }

diff --git a/main.tf b/main.tf
@@ -23,7 +23,7 @@ resource "solacebroker_msg_vpn_client_username" "main" {
   count = var.client_identifier_type == "client_username" ? 1 : 0
 
   msg_vpn_name        = var.msg_vpn_name
-  client_username     = var.client_name
+  client_username     = var.client_identifier_name
   client_profile_name = var.client_profile_name
   acl_profile_name    = var.acl_profile_name
   enabled             = var.enabled
@@ -37,7 +37,7 @@ resource "solacebroker_msg_vpn_authorization_group" "main" {
   count = var.client_identifier_type == "authorization_group" ? 1 : 0
 
   msg_vpn_name             = var.msg_vpn_name
-  authorization_group_name = var.client_name
+  authorization_group_name = var.client_identifier_name
   client_profile_name      = var.client_profile_name
   acl_profile_name         = var.acl_profile_name
   enabled                  = var.enabled

diff --git a/variables.tf b/variables.tf
@@ -30,7 +30,7 @@ variable "client_identifier_type" {
   }
 }
 
-variable "client_name" {
+variable "client_identifier_name" {
   description = "The name of the client identifier"
   type        = string
 }