Added support for client and initial documentation

.github/workflows/module-test-pipeline.yml

@@ -0,0 +1,40 @@
+name: Provider Test Pipeline
+
+on: push
+
+jobs:
+  test:
+    name: Run Provider setup and tests
+    runs-on: ubuntu-latest
+    steps:
+      # - name: Set up Go
+      #   uses: actions/setup-go@v3
+      #   with:
+      #     go-version: "1.21"
+
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Terraform latest
+        uses: hashicorp/setup-terraform@v2
+
+      - name: Setup test broker
+        run: |
+          mkdir -p $HOME/solace; chmod 777 $HOME/solace
+          docker run -d -p 8080:8080 -p 55555:55555 --shm-size=1g --env username_admin_globalaccesslevel=admin --env username_admin_password=admin --env system_scaling_maxkafkabridgecount="10" --name=solace \
+            --env system_scaling_maxconnectioncount="1000" --mount type=bind,source=$HOME/solace,destination=/var/lib/solace,ro=false solace/solace-pubsub-standard:latest
+          while ! curl -s localhost:8080 | grep aurelia ; do sleep 1 ; done
+
+      - name: Test module from template on test broker
+        run: |
+          ci/scripts/test-module.sh ci/template-test
+
+      - name: Test module root on test broker
+        run: |
+          ci/scripts/test-module.sh ci/module-test
+
+      - name: Test examples
+        run: |
+          shopt -s extglob
+          for d in examples/!(adding-headers)/; do (ci/scripts/test-module.sh "$d"); done
+          # ci/scripts/test-module.sh examples/adding-headers/ -var-file=secret.tfvars

.github/workflows/prep-internal-release.yml

@@ -0,0 +1,121 @@
+# Launched manually
+on:
+  workflow_dispatch:
+    inputs:
+      prev_branch_name:
+        description: 'Prev branch name, must start with v'
+        required: true
+        default: 'v0.1.0-rc.1'
+      release_branch_name:
+        description: 'Release branch name, must start with v'
+        required: true
+        default: 'v0.1.0-rc.2'
+
+
+jobs:
+  build:
+    name: Prep release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: "1.21"
+
+      - name: Checkout the code
+        uses: actions/checkout@v2
+
+      - name: Check release version and set next version
+        run: |
+          if ! echo "${{ github.event.inputs.release_branch_name }}" | grep ^v ; then
+            echo "Incorrect release branch name ${{ github.event.inputs.release_branch_name }}, must start with 'v'" ; exit 1
+          fi
+          if echo "${{ github.ref_name }}" | grep ^dev ; then
+            # set next dev version GH env, otherwise set it empty
+            echo "NEXT_DEV_VERSION=$(echo ${{ github.ref_name }} | awk -F. -v OFS=. '{$NF += 1 ; print}')" >> $GITHUB_ENV
+          fi
+
+      - name: Code format, dependencies, checks
+        run: |
+          find . -type d -print0 | xargs -0 -n1 terraform fmt
+
+      - name: Setup test broker
+        run: |
+          mkdir -p $HOME/solace; chmod 777 $HOME/solace
+          docker run -d -p 8080:8080 -p 55555:55555 --shm-size=1g --env username_admin_globalaccesslevel=admin --env username_admin_password=admin --env system_scaling_maxkafkabridgecount="10" --name=solace \
+            --env system_scaling_maxconnectioncount="1000" --mount type=bind,source=$HOME/solace,destination=/var/lib/solace,ro=false solace/solace-pubsub-standard:latest
+          while ! curl -s localhost:8080 | grep aurelia ; do sleep 1 ; done
+
+      - name: Check code builds and pass acceptance test
+        run: |
+          ci/scripts/test-module.sh ci/module-test
+          for dir in examples/*; do (ci/scripts/test-module.sh "$dir"); done
+
+      - name: Ensure version reflects release candidate version
+        run: |
+          VERSION=$(echo "${{ github.event.inputs.release_branch_name }}" | cut -d'v' -f2)
+          echo $VERSION > VERSION
+
+      - name: Add copyright headers where needed
+        run: |
+          go install github.com/google/addlicense@latest
+          addlicense -c 'Solace Corporation. All rights reserved.' -v -l apache ./*.tf
+          addlicense -c 'Solace Corporation. All rights reserved.' -v -l apache $(find ./examples -name "*.tf" -type f -print0 | xargs -0)
+
+      - name: Check changed files
+        uses: tj-actions/verify-changed-files@v17
+        id: check-changed-files
+
+      - name: Run step only when any of the files change
+        if: steps.check-changed-files.outputs.files_changed == 'true'
+        run: |
+          echo "Changed files: ${{ steps.check-changed-files.outputs.changed_files }}"
+
+      - name: Commit back updates when any of the files change
+        if: steps.check-changed-files.outputs.files_changed == 'true'
+        uses: EndBug/add-and-commit@v9
+        with:
+          committer_name: GitHub Actions
+          committer_email: [email protected]
+          message: 'Updating release candidate [skip ci]'
+          new_branch: GeneratedSourceUpdates-${{ github.ref_name }}
+
+      - name: Create pull request if needed, then break here because manual approval of the changes is required
+        if: steps.check-changed-files.outputs.files_changed == 'true'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          CURRENT_BRANCH=${GITHUB_REF_NAME}
+          gh pr create -B ${CURRENT_BRANCH} -H "GeneratedSourceUpdates-${CURRENT_BRANCH}" --title "Merge generated source updates into release candidate ${CURRENT_BRANCH}" --body 'Created by Github action'
+          echo Review and approve PR before release can continue
+          exit 1 // force actions stop here
+
+      - name: Create release branch starting point
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git fetch
+          git push origin refs/remotes/origin/${{ github.event.inputs.prev_branch_name }}:refs/heads/${{ github.event.inputs.release_branch_name }}
+
+      - name: Create PR to release branch
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          CURRENT_BRANCH=${GITHUB_REF_NAME}
+          gh pr create -B ${{ github.event.inputs.release_branch_name }} --title "New release ${{ github.event.inputs.release_branch_name }}" --body 'Created by Github action'
+
+      # - name: Create PR to release branch
+      #   uses: peterjgrainger/[email protected]
+      #   env:
+      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      #   with:
+      #     branch: "${{ github.event.inputs.release_branch_name }}"
+
+      # - name: Tag the release branch
+      #   if: env.NEXT_DEV_VERSION != ''
+      #   uses: peterjgrainger/[email protected]
+      #   env:
+      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      #   with:
+      #     branch: ${{ env.NEXT_DEV_VERSION }}
+

.github/workflows/verify-registry-release.yml

@@ -0,0 +1,59 @@
+# Launched manually to test new release from registry
+on:
+  workflow_dispatch:
+    inputs:
+      release_version:
+        description: 'The version of the release in the Terraform registry (expecting semver format)'
+        required: true
+        default: '0.1.0-rc.1'
+      public_release:
+        type: boolean
+        description: 'Check if this is a public release (from registry.terraform.io). Private release is from app.terraform.io'
+        required: true
+        default: false
+
+jobs:
+  build:
+    name: Verify registry release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Go
+        uses: actions/setup-go@v3
+        with:
+          go-version: "1.21"
+
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Setup test broker
+        run: |
+          mkdir -p $HOME/solace; chmod 777 $HOME/solace
+          docker run -d -p 8080:8080 -p 55555:55555 --shm-size=1g --env username_admin_globalaccesslevel=admin --env username_admin_password=admin --env system_scaling_maxkafkabridgecount="10" --name=solace \
+            --mount type=bind,source=$HOME/solace,destination=/var/lib/solace,ro=false solace/solace-pubsub-standard:"10.6.1.52"
+          while ! curl -s localhost:8080 | grep aurelia ; do sleep 1 ; done
+
+      - name: Set up Terraform latest - public
+        if: ${{ github.event.inputs.public_release != 'false' }}
+        uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_wrapper: true
+
+      - name: Set up Terraform latest - private, with token
+        if: ${{ github.event.inputs.public_release == 'false' }}
+        uses: hashicorp/setup-terraform@v3
+        with:
+          cli_config_credentials_token: ${{ secrets.TF_API_TOKEN }}
+          terraform_wrapper: true
+
+      - name: Setup token and patch module with release information
+        run: |
+          MODULENAME=client
+          if [ "${{ github.event.inputs.public_release }}" == "false" ] ; then
+            echo Internal release
+            MODULE_REF="app.terraform.io/SolaceDev/$MODULENAME/solacebroker"
+          else
+            echo Public release
+            MODULE_REF="SolaceProducts/$MODULENAME/solacebroker"
+          fi
+          ci/scripts/test-module.sh ci/module-test/ "" $MODULE_REF "${{ github.event.inputs.release_version }}"
+

.gitignore

@@ -4,18 +4,12 @@
 # .tfstate files
 *.tfstate
 *.tfstate.*
+*.lock.hcl
 
 # Crash log files
 crash.log
 crash.*.log
 
-# Exclude all .tfvars files, which are likely to contain sensitive data, such as
-# password, private keys, and other secrets. These should not be part of version 
-# control as they are data points which are potentially sensitive and subject 
-# to change depending on the environment.
-*.tfvars
-*.tfvars.json
-
 # Ignore override files as they are usually used to override resources locally and so
 # are not checked in
 override.tf

README.md

@@ -1,2 +1,91 @@
-# terraform-solacebroker-client
-Solace software broker Terraform module to abstract an application client user configuration
+# Solace PubSub+ Software Event Broker Client Terraform Module
+
+Terraform module to provision a client identifier for [authorization](https://docs.solace.com/Security/Client-Authorization-Overview.htm) when connecting to the [Solace PubSub+ Event Broker](https://solace.com/products/event-broker/). The module also provides the option to adjust the assigned ACL profile through defining ACL profile exceptions, and to define additinal attributes for client usernames.
+
+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))
+
+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.
+
+### 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 purposes.
+* `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.
+* `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:
+
+| Resource name |
+|---------------|
+|[solacebroker_msg_vpn_client_username](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_client_username#optional)|
+|[solacebroker_msg_vpn_authorization_group](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_authorization_group#optional)|
+|[solacebroker_msg_vpn_acl_profile_publish_topic_exception](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_acl_profile_publish_topic_exception#optional)|
+|[solacebroker_msg_vpn_acl_profile_subscribe_share_name_exception](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_acl_profile_subscribe_share_name_exception#optional)|
+|[solacebroker_msg_vpn_acl_profile_subscribe_topic_exception](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_acl_profile_subscribe_topic_exception#optional)|
+|[solacebroker_msg_vpn_acl_profile_client_connect_exception](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_acl_profile_client_connect_exception#optional)|
+|[solacebroker_msg_vpn_client_username_attribute](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest/docs/resources/msg_vpn_client_username_attribute#optional)|
+
+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.
+
+## Module outputs
+
+[Module outputs](https://developer.hashicorp.com/terraform/language/values/outputs) provide reference to created resources. Any reference to a resource that has not been created will be set to `(null)`.
+
+Note that the "client username" and the "authorization group" outputs are [sensitive](https://developer.hashicorp.com/terraform/language/values/outputs#sensitive-suppressing-values-in-cli-output).
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_solacebroker"></a> [solacebroker](https://registry.terraform.io/providers/SolaceProducts/solacebroker/latest) | ~> 0.9 |
+
+## Resources
+
+The following table shows the resources created for each `client_identifier_type` value. "X" denotes a resource always created, "O" is a resource that may be created optionally  
+
+| Name | client_username | authorization_group |
+|------|------|------|
+| solacebroker_msg_vpn_client_username | X | |
+| solacebroker_msg_vpn_client_username_attribute | O | |
+| solacebroker_msg_vpn_authorization_group | | X |
+| solacebroker_msg_vpn_acl_profile_publish_topic_exception | O | O |
+| solacebroker_msg_vpn_acl_profile_subscribe_share_name_exception | O | O |
+| solacebroker_msg_vpn_acl_profile_subscribe_topic_exception | O | O |
+| solacebroker_msg_vpn_acl_profile_client_connect_exception | O | O |
+
+
+## Examples
+
+Refer to the following configuration examples:
+
+- [Client username](examples/client-username)
+- [Client username attributes](examples/client-username-attributes)
+- [Authorization group](examples/authorization-group)
+- [ACL profile exeptions](examples/acl-profile-exceptions)
+
+## 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.
+
+## Resources
+
+For more information about Solace technology in general please visit these resources:
+
+- Solace [Technical Documentation](https://docs.solace.com/)
+    - [Client Authorization](https://docs.solace.com/Security/Client-Authorization-Overview.htm)
+- The Solace Developer Portal website at: [solace.dev](//solace.dev/)
+- Understanding [Solace technology](//solace.com/products/platform/)
+- Ask the [Solace community](//dev.solace.com/community/).

VERSION

@@ -0,0 +1 @@
+0.1.0-rc.1