From 8f4b4dd3b2f22ea3e937fef9c2e5d69df6eb6912 Mon Sep 17 00:00:00 2001 From: Balazs Czoma Date: Wed, 4 Oct 2023 15:58:46 -0400 Subject: [PATCH] Additional doc updates from QA review --- README.md | 2 ++ docs/guides/config-generator.md | 51 ++++++++++++++++------------ docs/guides/provider.md | 2 +- docs/index.md | 6 +++- internal/broker/provider.go | 2 +- templates/guides/config-generator.md | 51 ++++++++++++++++------------ templates/guides/provider.md | 2 +- templates/index.md.tmpl | 4 +++ 8 files changed, 74 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 48e7614e..1dc545bd 100644 --- 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 index bda45554..7dec49be 100644 --- 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 - `` 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 index eb956dd6..49d6411b 100644 --- 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 index 791fd58f..f1490838 100644 --- 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 index 90629c5c..0a50f1a9 100644 --- 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 index bda45554..7dec49be 100644 --- 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 - `` 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 index eb956dd6..49d6411b 100644 --- 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 index 0c25e258..67c3e418 100644 --- 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" }}