diff --git a/README.md b/README.md index 94839190..48e7614e 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,23 @@ -# Terraform provider for Solace PubSub+ Software Event Broker +# Terraform Provider for Solace PubSub+ Software Event Broker -This provider is a plugin for Terraform that allows for the configuration of the PubSub+ Software Event Broker and it is maintained by Solace. +This provider, maintained by Solace, is a plugin for Terraform that enables you to configure PubSub+ Software Event Brokers. The provider is available from the [Terraform Providers Registry](https://registry.terraform.io/providers/solaceproducts/solacebroker/latest). ## Quick Start -1. Ensure you have admin access to a Solace PubSub+ Software Event Broker. Options include [locally 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). +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). 2. Install the [Terraform CLI](https://www.terraform.io/downloads) -3. Create the [`examples/sampleconfig.tf`](examples/sampleconfig.tf) sample file in a new directory, adjust `url`, and the management credential parameters `username` and `password` to your broker's setup. +3. Create the [`examples/sampleconfig.tf`](examples/sampleconfig.tf) sample file in a new directory, adjust the `url`, and the management credential parameters `username` and `password` to your broker's setup. 4. From this directory run `terraform plan`, then `terraform apply`. -5. Open the `url` link in your browser to access the broker's web managment UI. The creadentials are the same as used in the Terraform config. Observe the new objects created: a new message-vpn and a messaging queue under that message-vpn. -6. Run `terraform delete` from your command line and observe the message-vpn deleted. +5. Open the `url` link in your browser to access the broker's web management UI. The credentials are the same as used in the Terraform config. Observe the new objects created: a new Message VPN and a messaging queue under that Message VPN. +6. Run `terraform delete` from your command line and observe that the Message VPN is deleted. -Note that the provider also offers the unique functionality of generating a config file from an already configured broker. Refer to the documentation for more details on that. +Note that the provider also offers the unique ability to generate a config file from an already configured broker. For more information, refer to the full documentation. ## Documentation -Full documentation is available on the [Terraform Providers Registry website](https://registry.terraform.io/providers/confluentinc/confluent/latest/docs). +Full documentation is available on the [Terraform Providers Registry website](https://registry.terraform.io/providers/solaceproducts/solacebroker/latest/docs). It is recommended to familiarize yourself with Solace technology and broker management, refer to the [Resources section](#resources). @@ -31,13 +31,13 @@ It is recommended to familiarize yourself with Solace technology and broker mana ### Building -1. `git clone` this repository and `cd` into its directory +1. `git clone` this repository and `cd` into its directory. 2. `make install` will trigger the Golang build of the provider in your [`${GOBIN}`](https://pkg.go.dev/cmd/go#hdr-Compile_and_install_packages_and_dependencies) (defaults to `${GOPATH}/bin` or `${HOME}/go/bin` if `${GOPATH}` is not set). Repeat this every time you make changes to the provider locally. -The provided `makefile` defines additional commands generally useful during development. +The provided `makefile` defines additional commands that are useful during development. -### Using a development build +### Using a Development Build Create or update your `${HOME}/.terraformrc` (Unix) / `%APPDATA%\terraform.rc` (Windows) configuration with a `provider_installation` section that contains the following `dev_overrides`: diff --git a/docs/guides/config-generator.md b/docs/guides/config-generator.md index 1a776b89..bda45554 100644 --- a/docs/guides/config-generator.md +++ b/docs/guides/config-generator.md @@ -2,26 +2,23 @@ page_title: "Command-line Terraform Configuration Generator Guide" --- -# Command-line Terraform configuration generator - -The `solacebroker` provider offers this feature outside of Terraform CLI. +# Command-Line Terraform Configuration Generator Normally, provider binaries are not run standalone, they are started and their services are used by Terraform CLI. -The `solacebroker` provider can also be run standalone: the generate command on the provider binary generates a Terraform HLC configuration file for the specified object and all child objects known to the provider. +The `solacebroker` provider, however, includes an additional feature where you can run its binary outside of Terraform CLI. In this case, you can use the "generate" command on the provider binary to generate a Terraform HLC configuration file for a specified object and all child objects known to the provider. -This is not a Terraform CLI command. The provider binary can be located in the .terraform/providers directory of an existing Terraform configuration directory that uses the `solacebroker` provider, or can be downloaded from the Solace GitHub repository (TBD: add link). +You can [locate](https://terra-farm.github.io/main/installation.html) the provider binary in the `.terraform/providers` directory of an existing Terraform configuration directory that uses the `solacebroker` provider. -The provider binary can be run directly with the `generate` command to generate a Terraform configuration file from the current configuration of a PubSubPlus broker. +You can run the provider binary directly with the `generate` command to generate a Terraform configuration file from the current configuration of a PubSub+ broker. ` generate ` -- `` is the broker provider binary +- `` is the broker provider binary. - `` is the broker address, for example `https://mybroker.example.org:1943/`. - `` are the similar to the Terraform Import command. This is the resource name and possible values to find a specific resource. - `` 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) +- There are also supported options, which mirror the configuration options for the provider object. These can be found [here](#supported-options). ### Usage @@ -32,7 +29,7 @@ Usage: terraform-provider-solacebroker [command] Available Commands: -generate Generates a Terraform configuration file for a specified PubSubPlus Broker object and all child objects known to the provider +generate Generates a Terraform configuration file for a specified PubSub+ Broker object and all child objects known to the provider help Help about any command version Provides version information about the current binary ``` @@ -44,16 +41,16 @@ are listed [here](#supported-options). For example: `SOLACEBROKER_USERNAME=admin SOLACEBROKER_PASSWORD=admin terraform-provider-solacebroker generate --url=https://localhost:8080 solacebroker_msg_vpn.mq default my-messagevpn.tf` -This command would create a file `my-messagevpn.tf` that contains a resource definition for the default message VPN resource and +This command would create a file `my-messagevpn.tf` that contains a resource definition for the default Message VPN resource and any child objects, assuming the appropriate broker credentials were set in environment variables. -Note: For objects with no child object, the file will only contain resource definition for that object. +Note: For objects with no child object, the file will only contain a resource definition for that object. For example: `SOLACEBROKER_USERNAME=admin SOLACEBROKER_PASSWORD=admin terraform-provider-solacebroker generate --url=https://localhost:8080 solacebroker_msg_vpn_queue.q default/test my-message-vpn-queue.tf` 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`. +Message VPN, `default`, assuming a msg_vpn_queue resource called `test` exists for the Message VPN, `default`. ### Troubleshooting @@ -61,37 +58,37 @@ The following issues may arise while using the generator. | Error | SEMP call failed. unexpected status 401 (401 Unauthorized) | |-----------------|----------------------------------------------------------------------------| -| Explanation | Configurations to connect to the PubSubPlus Broker not accurate. | -| Possible Action | Check and confirm, configuration details to PubSubPlus Broker are accurate | +| Explanation | Configurations to connect to the PubSub+ Broker not accurate. | +| Possible Action | Check and confirm, configuration details to PubSub+ Broker are accurate. | | Error | SOLACEBROKER_xxx is mandatory but not available | |-----------------|------------------------------------------------------------------------------------| -| Explanation | A mandatory parameter which is required to connect to PubSubPlus broker is missing | +| Explanation | A mandatory parameter which is required to connect to PubSub+ broker is missing. | | Possible Action | Confirm if all [mandatory parameters](#supported-options) are correctly set. | -| Error | Error: Too many provider specific identifiers. Required identifiers: [{xxx}] | -|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Explanation | This indicates that identifiers specific to the provider are set in an ambiguous manner. | -| Possible Action | Ensure all identifiers are available and separated by `/` where needed. For example a msgVpnName will require `msgVpnName`, however a specific queueName under a specific msgVpnName will be `msgVpnName/queueName` | +| Error | Error: Too many provider specific identifiers. Required identifiers: [{xxx}] | +|-----------------|------------------------------------------------------------------------------| +| Explanation | This indicates that identifiers specific to the provider are set in an ambiguous manner. | +| Possible Action | Ensure all identifiers are available and separated by `/` where needed. For example a msgVpnName will require `msgVpnName`, however a specific queueName under a specific msgVpnName will be `msgVpnName/queueName`. | | Error | SEMP called failed. resource not found on path /xxx/xxx | |-----------------|------------------------------------------------------------------------------------------| -| Explanation | This indicates the resource attributes attempted to be fetch could not be read | -| Possible Action | Ensure identifiers values are consistent as set on the PubSubPlus broker configured with | +| Explanation | This indicates the resource attributes attempted to be fetch could not be read. | +| Possible Action | Ensure identifiers values are consistent as set on the PubSub+ broker configured with. | | Error | Error: Broker resource not found by terraform name xxx | |-----------------|------------------------------------------------------------------------------------------------------------| -| Explanation | This indicates the resource by name _xxx_ is not recognized by 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 -These parameters could be set as ENVIRONMENT VARIABLES. When used as environment variables -each parameter should be preceded with _SOLACEBROKER__. For example for a PubSubPlus broker using username and password -_**admin/admin**_ -will be: +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=admin` +`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. diff --git a/docs/guides/provider.md b/docs/guides/provider.md index f49583a7..eb956dd6 100644 --- a/docs/guides/provider.md +++ b/docs/guides/provider.md @@ -4,33 +4,37 @@ page_title: "Solacebroker Provider Guide" # Solace PubSub+ Software Event Broker (solacebroker) Provider -The `solacebroker` provider (Provider) supports Terraform CLI operations including basic CRUD (create, read, update, and delete) and import. +The `solacebroker` provider supports Terraform CLI operations including basic CRUD (create, read, update, and delete) and import. -The Provider is leveraging the [SEMP (Solace Element Management Protocol)](https://docs.solace.com/Admin/SEMP/Using-SEMP.htm) REST API to configure the PubSub+ event broker. The API reference is available from the [Solace Documentation](https://docs.solace.com/API-Developer-Online-Ref-Documentation/swagger-ui/software-broker/config/index.html). +The provider leverages the [SEMP (Solace Element Management Protocol)](https://docs.solace.com/Admin/SEMP/Using-SEMP.htm) REST API to configure the PubSub+ event broker. The API reference is available from the [Solace PubSub+ Documentation](https://docs.solace.com/API-Developer-Online-Ref-Documentation/swagger-ui/software-broker/config/index.html). -## Broker SEMP API access +## Mapping of SEMP API and Provider Names + +Terraform uses the [snake case](https://en.wikipedia.org/wiki/Snake_case) naming scheme, while SEMP uses camel case. Resources and datasource are also prefixed with the provider local name, `solacebroker_`. For example, `solacebroker_msg_vpn` is the message-vpn resource name and `max_subscription_count` is the attribute for the maximum subscription count, since `MsgVpn` is the SEMP API object name and `maxSubscriptionCount` is the name of the SEMP attribute. + +## Broker SEMP API Access The broker SEMP service, by default at port 8080 for HTTP and TLS port 1943 for HTTPS, must be accessible to the console running Terraform CLI. -The supported access credentials are basic authentication using username and password, and OAuth using a token. The two options are mutually exclusive and the provider will fail if both configured. +The supported access credentials are basic authentication using username and password, and OAuth using a token. The two options are mutually exclusive and the provider will fail if both are configured. --> The [user access levels](https://docs.solace.com/Admin/CLI-User-Access-Levels.htm) associated with the credentials used must be properly configured on the broker so desired actions are authorized. +-> The [user access levels](https://docs.solace.com/Admin/CLI-User-Access-Levels.htm) associated with the credentials used must be properly configured on the broker so that the desired actions are authorized. -## SEMP API versioning and Provider broker compatibility +## SEMP API Versioning and Provider Broker Compatibility The SEMP API minor version reflects the supported set of objects, attributes, their properties and possible deprecations. -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 documentation](https://docs.solace.com/Admin/SEMP/SEMP-API-Versions.htm#SEMP_v2_to_SolOS_Version_Mapping). +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, see the release notes in the GitHub repo. -* 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, with the exception of 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. -* Broker versions at a higher SEMP API version level than the Provider can be configured for objects or attributes that are included in the Provider's SEMP version. Objects or attributes that have been introduced in a later SEMP version will be unknown to the Provider. Objects or attributes that have been deprecated in the broker SEMP version may result in configuration failure. +* 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. +* Broker versions at a higher SEMP API version level than the provider can be configured for objects or attributes that are included in the provider's SEMP version. Objects or attributes that have been introduced in a later SEMP version will be unknown to the provider. Objects or attributes that have been deprecated in the broker SEMP version may result in configuration failure. -## Object relationships +## Object Relationships -Broker inter-object references must be correctly encoded in Terraform configuration to have the apply work. It requires understanding of the PubSub+ event broker objects: it is recommended to consult the [SEMP API reference](https://docs.solace.com/API-Developer-Online-Ref-Documentation/swagger-ui/software-broker/config/index.htm) and especially "Identifying" attributes that give a hint to required already configured objects. +Broker inter-object references must be correctly encoded in Terraform configuration to have the apply operation work. This requires an understanding of the PubSub+ event broker objects. For more information about each object consult the [SEMP API reference](https://docs.solace.com/API-Developer-Online-Ref-Documentation/swagger-ui/software-broker/config/index.htm) and especially look for "Identifying" attributes that give a hint to required already configured objects. For example: ```terraform @@ -48,25 +52,36 @@ resource "solacebroker_msg_vpn_queue" "q" { } ``` -## The Broker object +## The Broker Object The Broker object is the `solacebroker_broker` resource. This object contains global configuration for the PubSub+ event broker. The Broker object differs from all other objects as it always exists for a given broker and can only be updated. --> Important: only attributes that are specified will be set to their configured value. Unspecified attributes will not be set to their default-attribute value. This may result in `terraform plan` indicating a change to set attributes to default even after an `apply`, for example after removing an attribute from the config. +-> Important: only attributes that are specified will be set to their configured value. Unspecified attributes will not be set to their default-attribute value. This may result in `terraform plan` indicating a change to set attributes to default even after an `apply`, for example after removing an attribute from the configuration. -## Default objects +## Default Objects -There are objects that are preexisting defaults and cannot be created or destroyed, only updated. The default VPN and the default client profile are examples of this. Delete of these resources will fail. +There are objects that are preexisting defaults and cannot be created or destroyed, only updated. The default Message VPN and the default client profile are examples of this. Any attempt to remove these resources will fail. -## Broker-defined attributes +## Broker-Defined Attributes -Some attributes don't have a default value, however is not specified their value will be determined by the broker. Typically these defaults depend on the broker scaling settings. While Terraform plan and apply operations work like for any other attributes, import will set the broker value in the state (instead of null), even if they were set at default. Subsequent plan and apply can be used to fix this. +Some attributes don't have a default value. In this case their value will be determined by the broker. Typically, these defaults depend on the broker scaling settings. While Terraform plan and apply operations function the same way as with other attributes, import will set the Terraform state of the attribute to the broker value (instead of null), even if they were set at default. You can use subsequent plan and apply operations to fix this. -## Mapping of SEMP API and Provider names +## Importing Resources -Terraform uses the [snake case](https://en.wikipedia.org/wiki/Snake_case) naming scheme, while SEMP uses camel case. Resources and datasource are also prefixed with the provider local name, `solacebroker_`. For example, `solacebroker_msg_vpn` is the message-vpn resource name and `max_subscription_count` is the attribute for the maximum subscription count, since `MsgVpn` is the SEMP API object name and `maxSubscriptionCount` is the name of the SEMP attribute. +When [importing resources to Terraform](https://developer.hashicorp.com/terraform/language/import#syntax) an `id` is required. Note that this `id` is not the same as the internal `id` attribute of resources. + +The `id` to be used shall be constructed as a path from the highest parent object down to the resource. + +For example, when importing a `solacebroker_msg_vpn_queue_subscription`, the parent relationship is `msg_vpn` > `msg_vpn_queue` > `msg_vpn_queue_subscription`. To construct the `id`, concatenate the identifications of parents and the particular resource identification, separated by `/` (slash). Also note that elements containing `/` must be URL-encoded. + +For this example: +``` +id = // +# using my-vpn, my-queue, a/b/c +id = my-vpn/my-queue/a%2Fb%2Fc +``` ## Notes diff --git a/docs/index.md b/docs/index.md index af734697..791fd58f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,9 +16,9 @@ to dynamically share events across the distributed enterprise. ## Overview -The _solacebroker_ provider enables configuration of a PubSub+ Software Event Broker using Terraform. +The _solacebroker_ provider enables you to configure a PubSub+ Software Event Broker using Terraform. -This provider also offers the possibility to generate [HCL configuration](https://developer.hashicorp.com/terraform/language) file from an already configured event broker. +This provider also offers the possibility to generate an [HCL configuration](https://developer.hashicorp.com/terraform/language) file from a preconfigured event broker. Use the navigation to the left for more information in the guides and for the available provider resources and data sources. @@ -76,7 +76,7 @@ resource "solacebroker_msg_vpn_queue" "q" { - `username` (String) The username to connect to the broker with. Requires password and conflicts with bearer_token. -> All provider configuration values can also be set as environment variables with the same name but uppercase and with the `SOLACEBROKER_` prefix. -For example the password attribute can be set via the `SOLACEBROKER_PASSWORD` environment variable. Values in the configuration take precedence over environment variables. +For example, the password attribute can be set via the `SOLACEBROKER_PASSWORD` environment variable. Values in the configuration take precedence over environment variables. # Release Notes and History diff --git a/templates/guides/config-generator.md b/templates/guides/config-generator.md index 1a776b89..bda45554 100644 --- a/templates/guides/config-generator.md +++ b/templates/guides/config-generator.md @@ -2,26 +2,23 @@ page_title: "Command-line Terraform Configuration Generator Guide" --- -# Command-line Terraform configuration generator - -The `solacebroker` provider offers this feature outside of Terraform CLI. +# Command-Line Terraform Configuration Generator Normally, provider binaries are not run standalone, they are started and their services are used by Terraform CLI. -The `solacebroker` provider can also be run standalone: the generate command on the provider binary generates a Terraform HLC configuration file for the specified object and all child objects known to the provider. +The `solacebroker` provider, however, includes an additional feature where you can run its binary outside of Terraform CLI. In this case, you can use the "generate" command on the provider binary to generate a Terraform HLC configuration file for a specified object and all child objects known to the provider. -This is not a Terraform CLI command. The provider binary can be located in the .terraform/providers directory of an existing Terraform configuration directory that uses the `solacebroker` provider, or can be downloaded from the Solace GitHub repository (TBD: add link). +You can [locate](https://terra-farm.github.io/main/installation.html) the provider binary in the `.terraform/providers` directory of an existing Terraform configuration directory that uses the `solacebroker` provider. -The provider binary can be run directly with the `generate` command to generate a Terraform configuration file from the current configuration of a PubSubPlus broker. +You can run the provider binary directly with the `generate` command to generate a Terraform configuration file from the current configuration of a PubSub+ broker. ` generate ` -- `` is the broker provider binary +- `` is the broker provider binary. - `` is the broker address, for example `https://mybroker.example.org:1943/`. - `` are the similar to the Terraform Import command. This is the resource name and possible values to find a specific resource. - `` 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) +- There are also supported options, which mirror the configuration options for the provider object. These can be found [here](#supported-options). ### Usage @@ -32,7 +29,7 @@ Usage: terraform-provider-solacebroker [command] Available Commands: -generate Generates a Terraform configuration file for a specified PubSubPlus Broker object and all child objects known to the provider +generate Generates a Terraform configuration file for a specified PubSub+ Broker object and all child objects known to the provider help Help about any command version Provides version information about the current binary ``` @@ -44,16 +41,16 @@ are listed [here](#supported-options). For example: `SOLACEBROKER_USERNAME=admin SOLACEBROKER_PASSWORD=admin terraform-provider-solacebroker generate --url=https://localhost:8080 solacebroker_msg_vpn.mq default my-messagevpn.tf` -This command would create a file `my-messagevpn.tf` that contains a resource definition for the default message VPN resource and +This command would create a file `my-messagevpn.tf` that contains a resource definition for the default Message VPN resource and any child objects, assuming the appropriate broker credentials were set in environment variables. -Note: For objects with no child object, the file will only contain resource definition for that object. +Note: For objects with no child object, the file will only contain a resource definition for that object. For example: `SOLACEBROKER_USERNAME=admin SOLACEBROKER_PASSWORD=admin terraform-provider-solacebroker generate --url=https://localhost:8080 solacebroker_msg_vpn_queue.q default/test my-message-vpn-queue.tf` 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`. +Message VPN, `default`, assuming a msg_vpn_queue resource called `test` exists for the Message VPN, `default`. ### Troubleshooting @@ -61,37 +58,37 @@ The following issues may arise while using the generator. | Error | SEMP call failed. unexpected status 401 (401 Unauthorized) | |-----------------|----------------------------------------------------------------------------| -| Explanation | Configurations to connect to the PubSubPlus Broker not accurate. | -| Possible Action | Check and confirm, configuration details to PubSubPlus Broker are accurate | +| Explanation | Configurations to connect to the PubSub+ Broker not accurate. | +| Possible Action | Check and confirm, configuration details to PubSub+ Broker are accurate. | | Error | SOLACEBROKER_xxx is mandatory but not available | |-----------------|------------------------------------------------------------------------------------| -| Explanation | A mandatory parameter which is required to connect to PubSubPlus broker is missing | +| Explanation | A mandatory parameter which is required to connect to PubSub+ broker is missing. | | Possible Action | Confirm if all [mandatory parameters](#supported-options) are correctly set. | -| Error | Error: Too many provider specific identifiers. Required identifiers: [{xxx}] | -|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Explanation | This indicates that identifiers specific to the provider are set in an ambiguous manner. | -| Possible Action | Ensure all identifiers are available and separated by `/` where needed. For example a msgVpnName will require `msgVpnName`, however a specific queueName under a specific msgVpnName will be `msgVpnName/queueName` | +| Error | Error: Too many provider specific identifiers. Required identifiers: [{xxx}] | +|-----------------|------------------------------------------------------------------------------| +| Explanation | This indicates that identifiers specific to the provider are set in an ambiguous manner. | +| Possible Action | Ensure all identifiers are available and separated by `/` where needed. For example a msgVpnName will require `msgVpnName`, however a specific queueName under a specific msgVpnName will be `msgVpnName/queueName`. | | Error | SEMP called failed. resource not found on path /xxx/xxx | |-----------------|------------------------------------------------------------------------------------------| -| Explanation | This indicates the resource attributes attempted to be fetch could not be read | -| Possible Action | Ensure identifiers values are consistent as set on the PubSubPlus broker configured with | +| Explanation | This indicates the resource attributes attempted to be fetch could not be read. | +| Possible Action | Ensure identifiers values are consistent as set on the PubSub+ broker configured with. | | Error | Error: Broker resource not found by terraform name xxx | |-----------------|------------------------------------------------------------------------------------------------------------| -| Explanation | This indicates the resource by name _xxx_ is not recognized by 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 -These parameters could be set as ENVIRONMENT VARIABLES. When used as environment variables -each parameter should be preceded with _SOLACEBROKER__. For example for a PubSubPlus broker using username and password -_**admin/admin**_ -will be: +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=admin` +`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. diff --git a/templates/guides/provider.md b/templates/guides/provider.md index 9511b6af..eb956dd6 100644 --- a/templates/guides/provider.md +++ b/templates/guides/provider.md @@ -4,37 +4,37 @@ page_title: "Solacebroker Provider Guide" # Solace PubSub+ Software Event Broker (solacebroker) Provider -The `solacebroker` provider (Provider) supports Terraform CLI operations including basic CRUD (create, read, update, and delete) and import. +The `solacebroker` provider supports Terraform CLI operations including basic CRUD (create, read, update, and delete) and import. -The Provider is leveraging the [SEMP (Solace Element Management Protocol)](https://docs.solace.com/Admin/SEMP/Using-SEMP.htm) REST API to configure the PubSub+ event broker. The API reference is available from the [Solace Documentation](https://docs.solace.com/API-Developer-Online-Ref-Documentation/swagger-ui/software-broker/config/index.html). +The provider leverages the [SEMP (Solace Element Management Protocol)](https://docs.solace.com/Admin/SEMP/Using-SEMP.htm) REST API to configure the PubSub+ event broker. The API reference is available from the [Solace PubSub+ Documentation](https://docs.solace.com/API-Developer-Online-Ref-Documentation/swagger-ui/software-broker/config/index.html). -## Broker SEMP API access +## Mapping of SEMP API and Provider Names -The broker SEMP service, by default at port 8080 for HTTP and TLS port 1943 for HTTPS, must be accessible to the console running Terraform CLI. +Terraform uses the [snake case](https://en.wikipedia.org/wiki/Snake_case) naming scheme, while SEMP uses camel case. Resources and datasource are also prefixed with the provider local name, `solacebroker_`. For example, `solacebroker_msg_vpn` is the message-vpn resource name and `max_subscription_count` is the attribute for the maximum subscription count, since `MsgVpn` is the SEMP API object name and `maxSubscriptionCount` is the name of the SEMP attribute. -The supported access credentials are basic authentication using username and password, and OAuth using a token. The two options are mutually exclusive and the provider will fail if both configured. +## Broker SEMP API Access --> The [user access levels](https://docs.solace.com/Admin/CLI-User-Access-Levels.htm) associated with the credentials used must be properly configured on the broker so desired actions are authorized. +The broker SEMP service, by default at port 8080 for HTTP and TLS port 1943 for HTTPS, must be accessible to the console running Terraform CLI. -## SEMP API versioning and Provider broker compatibility +The supported access credentials are basic authentication using username and password, and OAuth using a token. The two options are mutually exclusive and the provider will fail if both are configured. -The SEMP API minor version reflects the supported set of objects, attributes, their properties and possible deprecations. +-> The [user access levels](https://docs.solace.com/Admin/CLI-User-Access-Levels.htm) associated with the credentials used must be properly configured on the broker so that the desired actions are authorized. -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 documentation](https://docs.solace.com/Admin/SEMP/SEMP-API-Versions.htm#SEMP_v2_to_SolOS_Version_Mapping). +## SEMP API Versioning and Provider Broker Compatibility -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. +The SEMP API minor version reflects the supported set of objects, attributes, their properties and possible deprecations. -* 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, with the exception of 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. -* Broker versions at a higher SEMP API version level than the Provider can be configured for objects or attributes that are included in the Provider's SEMP version. Objects or attributes that have been introduced in a later SEMP version will be unknown to the Provider. Objects or attributes that have been deprecated in the broker SEMP version may result in configuration failure. +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). -## Mapping of SEMP API and Provider names +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. -Terraform uses the [snake case](https://en.wikipedia.org/wiki/Snake_case) naming scheme, while SEMP uses camel case. Resources and datasource are also prefixed with the provider local name, `solacebroker_`. For example, `solacebroker_msg_vpn` is the message-vpn resource name and `max_subscription_count` is the attribute for the maximum subscription count, since `MsgVpn` is the SEMP API object name and `maxSubscriptionCount` is the name of the SEMP attribute. +* 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. +* Broker versions at a higher SEMP API version level than the provider can be configured for objects or attributes that are included in the provider's SEMP version. Objects or attributes that have been introduced in a later SEMP version will be unknown to the provider. Objects or attributes that have been deprecated in the broker SEMP version may result in configuration failure. -## Object relationships +## Object Relationships -Broker inter-object references must be correctly encoded in Terraform configuration to have the apply work. It requires understanding of the PubSub+ event broker objects: it is recommended to consult the [SEMP API reference](https://docs.solace.com/API-Developer-Online-Ref-Documentation/swagger-ui/software-broker/config/index.htm) and especially "Identifying" attributes that give a hint to required already configured objects. +Broker inter-object references must be correctly encoded in Terraform configuration to have the apply operation work. This requires an understanding of the PubSub+ event broker objects. For more information about each object consult the [SEMP API reference](https://docs.solace.com/API-Developer-Online-Ref-Documentation/swagger-ui/software-broker/config/index.htm) and especially look for "Identifying" attributes that give a hint to required already configured objects. For example: ```terraform @@ -52,23 +52,23 @@ resource "solacebroker_msg_vpn_queue" "q" { } ``` -## The Broker object +## The Broker Object The Broker object is the `solacebroker_broker` resource. This object contains global configuration for the PubSub+ event broker. The Broker object differs from all other objects as it always exists for a given broker and can only be updated. --> Important: only attributes that are specified will be set to their configured value. Unspecified attributes will not be set to their default-attribute value. This may result in `terraform plan` indicating a change to set attributes to default even after an `apply`, for example after removing an attribute from the config. +-> Important: only attributes that are specified will be set to their configured value. Unspecified attributes will not be set to their default-attribute value. This may result in `terraform plan` indicating a change to set attributes to default even after an `apply`, for example after removing an attribute from the configuration. -## Default objects +## Default Objects -There are objects that are preexisting defaults and cannot be created or destroyed, only updated. The default VPN and the default client profile are examples of this. Delete of these resources will fail. +There are objects that are preexisting defaults and cannot be created or destroyed, only updated. The default Message VPN and the default client profile are examples of this. Any attempt to remove these resources will fail. -## Broker-defined attributes +## Broker-Defined Attributes -Some attributes don't have a default value, however is not specified their value will be determined by the broker. Typically these defaults depend on the broker scaling settings. While Terraform plan and apply operations work like for any other attributes, import will set the broker value in the state (instead of null), even if they were set at default. Subsequent plan and apply can be used to fix this. +Some attributes don't have a default value. In this case their value will be determined by the broker. Typically, these defaults depend on the broker scaling settings. While Terraform plan and apply operations function the same way as with other attributes, import will set the Terraform state of the attribute to the broker value (instead of null), even if they were set at default. You can use subsequent plan and apply operations to fix this. -## Importing resources +## Importing Resources When [importing resources to Terraform](https://developer.hashicorp.com/terraform/language/import#syntax) an `id` is required. Note that this `id` is not the same as the internal `id` attribute of resources. diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl index 0a605d37..0c25e258 100644 --- a/templates/index.md.tmpl +++ b/templates/index.md.tmpl @@ -16,9 +16,9 @@ to dynamically share events across the distributed enterprise. ## Overview -The _solacebroker_ provider enables configuration of a PubSub+ Software Event Broker using Terraform. +The _solacebroker_ provider enables you to configure a PubSub+ Software Event Broker using Terraform. -This provider also offers the possibility to generate [HCL configuration](https://developer.hashicorp.com/terraform/language) file from an already configured event broker. +This provider also offers the possibility to generate an [HCL configuration](https://developer.hashicorp.com/terraform/language) file from a preconfigured event broker. Use the navigation to the left for more information in the guides and for the available provider resources and data sources. @@ -29,7 +29,7 @@ Use the navigation to the left for more information in the guides and for the av {{ .SchemaMarkdown | trimspace }} -> All provider configuration values can also be set as environment variables with the same name but uppercase and with the `SOLACEBROKER_` prefix. -For example the password attribute can be set via the `SOLACEBROKER_PASSWORD` environment variable. Values in the configuration take precedence over environment variables. +For example, the password attribute can be set via the `SOLACEBROKER_PASSWORD` environment variable. Values in the configuration take precedence over environment variables. # Release Notes and History