Additional doc updates from QA review

SolaceProducts · Oct 4, 2023 · 8f4b4dd · 8f4b4dd
1 parent 39ce22a
commit 8f4b4dd
Show file tree

Hide file tree

Showing 8 changed files with 74 additions and 46 deletions.
diff --git a/README.md b/README.md
@@ -4,6 +4,8 @@ This provider, maintained by Solace, is a plugin for Terraform that enables you
 
 The provider is available from the [Terraform Providers Registry](https://registry.terraform.io/providers/solaceproducts/solacebroker/latest).
 
+The minimum required PubSub+ Software Event Broker version 10.4.
+
 ## Quick Start
 
 1. Ensure you have admin access to a Solace PubSub+ Software Event Broker. Options include [local deployment of a containerized version](https://docs.solace.com/Software-Broker/SW-Broker-Set-Up/Containers/Set-Up-Container-Image.htm) or use of a free broker from [PubSub+ Cloud](https://docs.solace.com/Cloud/cloud-lp.htm).

diff --git a/docs/guides/config-generator.md b/docs/guides/config-generator.md
@@ -20,7 +20,16 @@ You can run the provider binary directly with the `generate` command to generate
 - `<filename>` is the desirable name of the generated filename.
 - There are also supported options, which mirror the configuration options for the provider object. These can be found [here](#supported-options).
 
-### Usage
+## Important notes
+
+The generated configuration shoud be reviewed for followings:
+
+* Provider configuration values (url, username, etc.) may need to be updated.
+* Write-only attributes, such as passwords, are omitted from the config as they cannot be read from the broker configuration. They need to be added manually.
+* Default resources may be present that may be omitted.
+* The generator uses a naming scheme for the resources. This may be updated by manually replacing the generated names.
+
+## Usage
 
 ```shell
 terraform-provider-solacebroker -h
@@ -52,7 +61,26 @@ For example:
 This command would create a file `my-message-vpn-queue.tf` that contains the msg_vpn_queue resource , `test`  for the
 Message VPN, `default`, assuming a msg_vpn_queue resource called `test` exists for the Message VPN, `default`.
 
-### Troubleshooting
+### Supported Options
+
+The following parameters can be set as ENVIRONMENT VARIABLES. When used as environment variables
+each parameter must be preceded with _SOLACEBROKER__. For example for a PubSub+ broker using username and password
+_**admin/password**_
+would be:
+
+`SOLACEBROKER_USERNAME=admin SOLACEBROKER_PASSWORD=password`
+
+- `bearer_token`, (String, Sensitive, Mandatory if `password` will not be provided)
+- `insecure_skip_verify` (Boolean) Disable validation of server SSL certificates, accept/ignore self-signed.
+- `password` (String, Sensitive, Mandatory is `bearer_token` will not be provided)
+- `request_min_interval` (String)
+- `request_timeout_duration` (String)
+- `retries` (Number)
+- `retry_max_interval` (String)
+- `retry_min_interval` (String)
+- `username` (String, Mandatory) The username for the broker request.
+
+## Troubleshooting
 
 The following issues may arise while using the generator.
 
@@ -80,22 +108,3 @@ The following issues may arise while using the generator.
 |-----------------|------------------------------------------------------------------------------------------------------------|
 | Explanation     | This indicates the resource by name _xxx_ is not recognized by the generator.                              |
 | Possible Action | Ensure the resource name used is available as a Terraform resource for the version of the provider in use. |
-
-### Supported Options
-
-The following parameters can be set as ENVIRONMENT VARIABLES. When used as environment variables
-each parameter must be preceded with _SOLACEBROKER__. For example for a PubSub+ broker using username and password
-_**admin/password**_
-would be:
-
-`SOLACEBROKER_USERNAME=admin SOLACEBROKER_PASSWORD=password`
-
-- `bearer_token`, (String, Sensitive, Mandatory if `password` will not be provided)
-- `insecure_skip_verify` (Boolean) Disable validation of server SSL certificates, accept/ignore self-signed.
-- `password` (String, Sensitive, Mandatory is `bearer_token` will not be provided)
-- `request_min_interval` (String)
-- `request_timeout_duration` (String)
-- `retries` (Number)
-- `retry_max_interval` (String)
-- `retry_min_interval` (String)
-- `username` (String, Mandatory) The username for the broker request.
diff --git a/docs/guides/provider.md b/docs/guides/provider.md
@@ -26,7 +26,7 @@ The SEMP API minor version reflects the supported set of objects, attributes, th
 
 New versions of the PubSub+ event broker with new features typically require a newer SEMP API version that supports the new or updated objects, attributes, etc. The SEMP API version of a broker version can be determined from the [Solace PubSub+ documentation](https://docs.solace.com/Admin/SEMP/SEMP-API-Versions.htm#SEMP_v2_to_SolOS_Version_Mapping).
 
-A given version of the provider is built to support a specific version of the SEMP API. For the SEMP API version of the provider, see the release notes in the GitHub repo.
+A given version of the provider is built to support a specific version of the SEMP API. For the SEMP API version of the provider and corresponding broker version, refer to the [Version Compatibility section](https://docs.solace.com/Admin/SEMP/Declarative-SEMP.htm#Version) of the Solace PubSub+ documentation.
 
 * Broker versions at the same SEMP API version level as the provider can be fully configured.
 * Broker versions at a lower SEMP API version level than the provider can be configured, except for objects or attributes that have been deprecated and removed in the provider's SEMP version. However, configuration will fail when attempting to configure objects or attributes that have been introduced in a later SEMP version than the broker supports.

diff --git a/docs/index.md b/docs/index.md
@@ -22,6 +22,10 @@ This provider also offers the possibility to generate an [HCL configuration](htt
 
 Use the navigation to the left for more information in the guides and for the available provider resources and data sources.
 
+## Minimum broker version
+
+The minimum required PubSub+ Software Event Broker version 10.4.
+
 ## Example Usage
 
 ```terraform
@@ -65,7 +69,7 @@ resource "solacebroker_msg_vpn_queue" "q" {
 
 ### Optional
 
-- `bearer_token` (String, Sensitive) A bearer token that will be sent in the Authorization header of SEMP requests. Conflicts with username and password.
+- `bearer_token` (String, Sensitive) A bearer token that will be sent in the Authorization header of SEMP requests. Requires TLS transport enabled. Conflicts with username and password.
 - `insecure_skip_verify` (Boolean) Disable validation of server SSL certificates, accept/ignore self-signed. The default value is false.
 - `password` (String, Sensitive) The password to connect to the broker with. Requires username and conflicts with bearer_token.
 - `request_min_interval` (String) A [duration](https://pkg.go.dev/maze.io/x/duration#ParseDuration) string indicating the minimum interval between requests; this serves as a rate limit. This setting does not apply to retries. Set to 0 for no rate limit. The default value is 100ms (which equates to a rate limit of 10 calls per second).

diff --git a/internal/broker/provider.go b/internal/broker/provider.go
@@ -65,7 +65,7 @@ func (p *BrokerProvider) Schema(_ context.Context, _ provider.SchemaRequest, res
 				Sensitive:           true,
 			},
 			"bearer_token": schema.StringAttribute{
-				MarkdownDescription: "A bearer token that will be sent in the Authorization header of SEMP requests. Conflicts with username and password.",
+				MarkdownDescription: "A bearer token that will be sent in the Authorization header of SEMP requests. Requires TLS transport enabled. Conflicts with username and password.",
 				Optional:            true,
 				Sensitive:           true,
 			},

diff --git a/templates/guides/config-generator.md b/templates/guides/config-generator.md
@@ -20,7 +20,16 @@ You can run the provider binary directly with the `generate` command to generate
 - `<filename>` is the desirable name of the generated filename.
 - There are also supported options, which mirror the configuration options for the provider object. These can be found [here](#supported-options).
 
-### Usage
+## Important notes
+
+The generated configuration shoud be reviewed for followings:
+
+* Provider configuration values (url, username, etc.) may need to be updated.
+* Write-only attributes, such as passwords, are omitted from the config as they cannot be read from the broker configuration. They need to be added manually.
+* Default resources may be present that may be omitted.
+* The generator uses a naming scheme for the resources. This may be updated by manually replacing the generated names.
+
+## Usage
 
 ```shell
 terraform-provider-solacebroker -h
@@ -52,7 +61,26 @@ For example:
 This command would create a file `my-message-vpn-queue.tf` that contains the msg_vpn_queue resource , `test`  for the
 Message VPN, `default`, assuming a msg_vpn_queue resource called `test` exists for the Message VPN, `default`.
 
-### Troubleshooting
+### Supported Options
+
+The following parameters can be set as ENVIRONMENT VARIABLES. When used as environment variables
+each parameter must be preceded with _SOLACEBROKER__. For example for a PubSub+ broker using username and password
+_**admin/password**_
+would be:
+
+`SOLACEBROKER_USERNAME=admin SOLACEBROKER_PASSWORD=password`
+
+- `bearer_token`, (String, Sensitive, Mandatory if `password` will not be provided)
+- `insecure_skip_verify` (Boolean) Disable validation of server SSL certificates, accept/ignore self-signed.
+- `password` (String, Sensitive, Mandatory is `bearer_token` will not be provided)
+- `request_min_interval` (String)
+- `request_timeout_duration` (String)
+- `retries` (Number)
+- `retry_max_interval` (String)
+- `retry_min_interval` (String)
+- `username` (String, Mandatory) The username for the broker request.
+
+## Troubleshooting
 
 The following issues may arise while using the generator.
 
@@ -80,22 +108,3 @@ The following issues may arise while using the generator.
 |-----------------|------------------------------------------------------------------------------------------------------------|
 | Explanation     | This indicates the resource by name _xxx_ is not recognized by the generator.                              |
 | Possible Action | Ensure the resource name used is available as a Terraform resource for the version of the provider in use. |
-
-### Supported Options
-
-The following parameters can be set as ENVIRONMENT VARIABLES. When used as environment variables
-each parameter must be preceded with _SOLACEBROKER__. For example for a PubSub+ broker using username and password
-_**admin/password**_
-would be:
-
-`SOLACEBROKER_USERNAME=admin SOLACEBROKER_PASSWORD=password`
-
-- `bearer_token`, (String, Sensitive, Mandatory if `password` will not be provided)
-- `insecure_skip_verify` (Boolean) Disable validation of server SSL certificates, accept/ignore self-signed.
-- `password` (String, Sensitive, Mandatory is `bearer_token` will not be provided)
-- `request_min_interval` (String)
-- `request_timeout_duration` (String)
-- `retries` (Number)
-- `retry_max_interval` (String)
-- `retry_min_interval` (String)
-- `username` (String, Mandatory) The username for the broker request.
diff --git a/templates/guides/provider.md b/templates/guides/provider.md
@@ -26,7 +26,7 @@ The SEMP API minor version reflects the supported set of objects, attributes, th
 
 New versions of the PubSub+ event broker with new features typically require a newer SEMP API version that supports the new or updated objects, attributes, etc. The SEMP API version of a broker version can be determined from the [Solace PubSub+ documentation](https://docs.solace.com/Admin/SEMP/SEMP-API-Versions.htm#SEMP_v2_to_SolOS_Version_Mapping).
 
-A given version of the provider is built to support a specific version of the SEMP API. For the SEMP API version of the provider, see the release notes in the GitHub repo.
+A given version of the provider is built to support a specific version of the SEMP API. For the SEMP API version of the provider and corresponding broker version, refer to the [Version Compatibility section](https://docs.solace.com/Admin/SEMP/Declarative-SEMP.htm#Version) of the Solace PubSub+ documentation.
 
 * Broker versions at the same SEMP API version level as the provider can be fully configured.
 * Broker versions at a lower SEMP API version level than the provider can be configured, except for objects or attributes that have been deprecated and removed in the provider's SEMP version. However, configuration will fail when attempting to configure objects or attributes that have been introduced in a later SEMP version than the broker supports.

diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl
@@ -22,6 +22,10 @@ This provider also offers the possibility to generate an [HCL configuration](htt
 
 Use the navigation to the left for more information in the guides and for the available provider resources and data sources.
 
+## Minimum broker version
+
+The minimum required PubSub+ Software Event Broker version 10.4.
+
 ## Example Usage
 
 {{ tffile "examples/sampleconfig.tf" }}