Skip to content

Commit

Permalink
Editorial updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@bczoma
bczoma committed Oct 4, 2023
1 parent 04048e0 commit 1adfd01
Show file tree
Hide file tree
Showing 7 changed files with 127 additions and 118 deletions.
22 changes: 11 additions & 11 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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).

Expand All @@ -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`:

Expand Down
53 changes: 25 additions & 28 deletions docs/guides/config-generator.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

`<binary> generate <broker URL> <provider-specific identifier> <filename>`

- `<binary>` is the broker provider binary
- `<binary>` is the broker provider binary.
- `<broker URL>` is the broker address, for example `https://mybroker.example.org:1943/`.
- `<provider-specific identifier>` are the similar to the Terraform Import command. This is the resource name and possible values to find a specific resource.
- `<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)
- There are also supported options, which mirror the configuration options for the provider object. These can be found [here](#supported-options).

### Usage

Expand All @@ -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
```
Expand All @@ -44,54 +41,54 @@ 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

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.
Expand Down
Loading

0 comments on commit 1adfd01

Please sign in to comment.