release-v1.0.4

.github/ISSUE_TEMPLATE/bug_report.md

@@ -7,7 +7,7 @@ assignees: ''
 
 ---
 
-*Thanks for taking the time to fill out this bug report! Before submitting this issue please check the [open bugs](https://github.com/citrix/terraform-provider-citrix/issues?q=is%3Aissue+is%3Aopen+label%3Abug) to ensure the bug has not already been reported.  If it has been reported give it a 👍*
+*Thanks for taking the time to fill out this bug report! Before submitting this issue please check the [open bugs](https://github.com/citrix/terraform-provider-citrix/issues?q=is%3Aissue+is%3Aopen+label%3Abug) to ensure the bug has not already been reported. If it has been reported give it a 👍*
 
 *If this bug is present when using the Citrix service UI or REST APIs then it is not a bug in the provider but rather a bug in the underlying service or the environment. In some cases there can be an enhancement in the provider to handle the error better. Please open a feature request instead of a bug in this case. For more information see [CONTRIBUTING.md#provider-issue-vs-product-issue-vs-configuration-issue](https://github.com/citrix/terraform-provider-citrix/blob/main/CONTRIBUTING.md#provider-issue-vs-product-issue-vs-configuration-issue).*
 

.github/workflows/gotest-cloud.yml

@@ -138,9 +138,13 @@ jobs:
           echo "TEST_ADMIN_USER_DOMAIN=${{secrets.TEST_ADMIN_USER_DOMAIN}}" >> $GITHUB_ENV
 
       # Test PreCheck
-      - name: Test
+      - name: Test Precheck
         run: go test -v ./internal/test -run "^TestAzureMcsSuitePreCheck$"
 
       # Test
       - name: Test
-        run: go test -v ./internal/test -run "^TestAzureMcs$" -timeout 1h
+        run: go test -v ./internal/test -run "^TestAzureMcs$" -timeout 1h
+
+      # Sweep
+      - name: Sweep
+        run: go test -v ./internal/test -run "^TestAzureMcs$" -timeout 1h -sweep-run "citrix_zone,citrix_zone,citrix_admin_folder,citrix_admin_role,citrix_admin_scope" -sweep="azure"

.github/workflows/gotest-onprem.yml

@@ -132,9 +132,13 @@ jobs:
           echo "TEST_ADMIN_USER_DOMAIN=${{secrets.TEST_ADMIN_USER_DOMAIN}}" >> $GITHUB_ENV
 
       # Test PreCheck
-      - name: Test
+      - name: Test Precheck
         run: go test -v ./internal/test -run "^TestAzureMcsSuitePreCheck$"
 
       # Test
       - name: Test
-        run: go test -v ./internal/test -run "^TestAzureMcs$" -timeout 1h
+        run: go test -v ./internal/test -run "^TestAzureMcs$" -timeout 1h
+
+      # Sweep
+      - name: Sweep
+        run: go test -v ./internal/test -run "^TestAzureMcs$" -timeout 1h -sweep-run "citrix_zone,citrix_zone,citrix_admin_folder,citrix_admin_role,citrix_admin_scope" -sweep="azure"

DEVELOPER.md

@@ -12,12 +12,20 @@ This documentation will guide you through the process of setting up your dev env
     - [Start Debugger](#start-debugger)
     - [Attach Local Provider to PowerShell](#attach-local-provider-to-powershell)
   - [Debugging with citrix-daas-rest-go client code in Visual Studio Code](#debugging-with-citrix-daas-rest-go-client-code-in-visual-studio-code)
-  - [Handling Terraform lists/sets and nested objects](#handling-terraform-listssets-and-nested-objects)
+  - [Handling Terraform lists, sets, and nested objects](#handling-terraform-lists-sets-and-nested-objects)
     - [Converting to Go native types](#converting-to-go-native-types)
+    - [Initalizing Terraform types](#initalizing-terraform-types)
     - [Preserving order in lists](#preserving-order-in-lists)
+  - [Regenerate the documentation](#regenerate-the-documentation)
   - [Running the tests](#running-the-tests)
   - [Commonly faced errors](#commonly-faced-errors)
   - [Plugin for Terraform Provider for StoreFront Developer Guide](#plugin-for-terraform-provider-for-storefront-developer-guide)
+- [Plugin for Terraform Provider for Citrix® Debugging Guide](#plugin-for-terraform-provider-for-citrix-debugging-guide)
+  - [Orchestration TransactionId](#orchestration-transactionid)
+  - [Error: Provider produced inconsistent result after apply](#error-provider-produced-inconsistent-result-after-apply)
+    - [Single attribute](#single-attribute)
+    - [Inconsistent values for sensitive attribute](#inconsistent-values-for-sensitive-attribute)
+  - [Error: Value Conversion Error](#error-value-conversion-error)
 
 ## Install Dependencies
 * Install Go on your local system: https://go.dev/doc/install
@@ -88,11 +96,11 @@ Run [Debugging Provider code in Visual Studio Code](#debugging-provider-code-in-
 
 Set a breakpoint in `terraform-provider-citrix/internal/provider/provider.go::Configure`
 
-## Handling Terraform lists/sets and nested objects
+## Handling Terraform lists, sets, and nested objects
 ### Converting to Go native types
-When the Terraform configuration, state, or plan is being converted into a Go model we must use `types.List` and `types.Object` for lists and nested objects rather than go native slices and structs. This is in order to support Null/Unknown values. Unknown is especially important because any variables in the .tf configuration files can be unknown in `ValidateConfig` and `ModifyPlan`. However, handling these Terraform List and Object types is cumbersome as they are dynamically typed at runtime. See [this doc](https://developer.hashicorp.com/terraform/plugin/framework/handling-data/accessing-values) for more information. 
+When the Terraform configuration, state, or plan is being converted into a Go model we must use `types.List`, `types.Set`, and `types.Object` rather than go native slices and structs. This is in order to support Null/Unknown values. Unknown is especially important because any variables in the .tf configuration files can be unknown in `ValidateConfig` and `ModifyPlan`. However, handling these Terraform List and Object types is cumbersome as they are dynamically typed at runtime. See [this doc](https://developer.hashicorp.com/terraform/plugin/framework/handling-data/accessing-values) for more information. 
 
-In order to reduce errors this project has introduced a system to convert between Terraform List/Object and Go native slices/structs. When data needs to be operated on it should be first converted to the Go native representation, then converted back to the Terraform representation. The following helper methods can handle this for you.
+In order to reduce errors this project has introduced a system to convert between Terraform List/Set/Object and Go native slices/structs. When data needs to be operated on it should be first converted to the Go native representation, then converted back to the Terraform representation. The following helper methods can handle this for you.
 
 | From | To | Function | Notes |
 |------|----|----------|-------|
@@ -109,6 +117,24 @@ In order to reduce errors this project has introduced a system to convert betwee
 
 In order to use the first 6 of these methods, the struct `T` needs to implement the [ModelWithAttributes](internal/util/types.go) interface which is ultimately populated from the attribute's Schema. This gives the Terraform type system the necessary information to populate a `types.Object` or `types.List` with a nested object.
 
+### Initalizing Terraform types
+When dealing with a struct that contains nested `types.List/Set/Object`, it is important to never work with an empty struct, but instead start with one that has all of the nested objects initialized to Terraform's `ListNull/SetNull/ObjectNull`. There are helpers to assist with this:
+```
+// Do not do this:
+tfObject := ComplexTerraformObject{}
+// or this:
+tfObject ComplexTerraformObject
+
+// Instead:
+if attributesMap, err := util.AttributeMapFromObject(ComplexTerraformObject{}); err == nil {
+    tfObject := types.ObjectNull(attributesMap)
+} else {
+    diagnostics.AddWarning("Error when creating null ComplexTerraformObject", err.Error())
+}
+```
+
+The issue is that the `AttributeMap` for nested objects, and the `ElementType` for nested lists/sets will not be configured. This will lead to hard to debug errors like `Error: Value Conversion Error` (see its debugging section below). Terraform cannot work with `nil`s on attribute, it must be wrapped in a Terraform null object.
+
 ### Preserving order in lists
 Often time the order of elements in a list does not matter to the service. In this case one of the following helper functions should be used. These functions will get state list in sync with the remote list while preserving the order in the state when possible. 
 
@@ -119,6 +145,13 @@ Often time the order of elements in a list does not matter to the service. In th
 | `RefreshListValues` | `types.List` of `string` | |
 | `RefreshListValueProperties` | `types.List` of `types.Object` | Each element will have its `RefreshListItem` method called. The element's type must implement the `RefreshableListItemWithAttributes` interface |
 
+## Regenerate the documentation
+This project uses [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs) to autogenerate its documentation from the source code. Whenever names, descriptions, or examples change be sure to run the following command to update the [docs/](docs/).
+```powershell
+➥ cd {Root of repo}/terraform-provider-citrix
+➥ go generate ./...
+```
+
 ## Running the tests
 
 Before running the tests, you need to provide values for environment variables required by the test files. 
@@ -157,4 +190,69 @@ To solve this issue, run the following command at the root of the repository:
 
 ## Plugin for Terraform Provider for StoreFront Developer Guide
 
-The test running process is the same as  [Running the tests](#running-the-tests) with additional parameter in the settings.cloud.example.json or settings.onprem.example.json  `StoreFront env variable` section
+The test running process is the same as [Running the tests](#running-the-tests) with additional parameter in the settings.cloud.example.json or settings.onprem.example.json  `StoreFront env variable` section
+
+
+# Plugin for Terraform Provider for Citrix® Debugging Guide
+If not running in VSCode enable Terraform logs using:
+```
+$env:TF_LOG="DEBUG"
+$env:TF_LOG_PATH="./citrix-provider-issue.txt"
+terraform <command>
+```
+
+## Orchestration TransactionId
+Filter the logs for `Orchestration API request` and find the request in question. On the same line is a `transactionId`. On-premises customers can search the [CDF logs](https://support.citrix.com/s/article/CTX127131-how-to-collect-a-citrix-diagnostic-facility-cdf-trace-at-system-startup?language=en_US) for the `transactionId` to find more information about what may have gone wrong. For cloud customers, Citrix support or the developers on this GitHub repository can use the `transactionId`.
+
+## Error: Provider produced inconsistent result after apply
+This error comes from the Terraform framework and indicates that after a Create or Update call, there are some properties in the plan which do not match the state.
+
+### Single attribute
+Usually the error will contain the exact attribute which has the issue, for example from #52:
+```
+│ Error: Provider produced inconsistent result after apply
+│
+│ When applying changes to citrix_machine_catalog.example, provider "provider[\"citrix/citrix\"]" produced an unexpected new value: .minimum_functional_level: was cty.StringVal("L7_34"),    
+│ but now cty.StringVal("L7_20").
+```
+
+In this case check the given attribute in the result from the final `RefreshPropertyValues` before it is saved to the state. It should not match what was in the plan. Trace backwards in the function to find where it is getting set and figure out why that isn't working. Or if it isn't being set write code to set it.
+
+### Inconsistent values for sensitive attribute
+If the error is from a deeply nested attribute, Terraform might return something like this from #120:
+```
+│ Error: Provider produced inconsistent result after apply
+│
+│ When applying changes to citrix_machine_catalog.DaaSMachineCatalog, provider "provider["registry.
+| terraform.io/citrix/citrix"]" produced an unexpected new value: .provisioning_scheme: inconsistent
+| values for sensitive attribute.
+```
+
+Because there is a sensitive attribute somewhere in the object, Terraform will not show us more details. If you are able to reproduce this locally, try doing a `plan` after the failure. The resource should be tainted and the properties which were inconsistent will be in the plan output.
+
+Looking at the logs alone there is some information to be found. Filter for `Value switched to prior value due to semantic equality logic`. These are the attributes which have successfully been saved. Using process of elimination on the `tf_attribute_path`, it is possible to see which attribute failed and is not present. If there are nested objects, when the object itself (not its attributes) is listed in `tf_attribute_path` that means the entire object was able to be saved. For example if you see:
+```
+tf_attribute_path=provisioning_scheme.azure_machine_config.writeback_cache.wbc_disk_storage_type
+tf_attribute_path=provisioning_scheme.azure_machine_config.writeback_cache.writeback_cache_disk_size_gb
+tf_attribute_path=provisioning_scheme.azure_machine_config.writeback_cache.writeback_cache_memory_size_mb
+```
+But not `provisioning_scheme.azure_machine_config.writeback_cache`, that means some other attributes of `writeback_cache` had an issue.
+
+## Error: Value Conversion Error
+When using our custom types system (see the `Handling Terraform lists/sets and nested objects` section), if something is wrong with the object the provider writes to the state file, Terraform will return something like this from #118:
+```
+│ Error: Value Conversion Error
+│
+│ An unexpected error was encountered while verifying an attribute value matched its expected type to prevent unexpected behavior or panics. This is always an
+│ error in the provider. Please report the following to the provider developer:
+│
+│ Expected framework type from provider logic: types.ObjectType["reboot_duration":basetypes.Int64Type, "warning_duration":basetypes.Int64Type,
+│ "warning_message":basetypes.StringType, "warning_repeat_interval":basetypes.Int64Type] / underlying type: tftypes.Object["reboot_duration":tftypes.Number,    
+│ "warning_duration":tftypes.Number, "warning_message":tftypes.String, "warning_repeat_interval":tftypes.Number]
+│ Received framework type from provider logic: types.ObjectType[] / underlying type: tftypes.Object[]
+│ Path: image_update_reboot_options
+```
+
+If `Received framework type from provider logic` looks empty, that means that an attribute map was not used to create the object. See the `Initalizing Terraform types` section on how to properly initialize an empty object.
+
+Otherwise the expected framework type and received framework type may closely match. Find where they differ and that is likely an attribute that is not being set, similiar to the `inconsistent result after apply/single attribute` section above.

docs/data-sources/cloud_google_identity_provider.md

@@ -0,0 +1,39 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "citrix_cloud_google_identity_provider Data Source - citrix"
+subcategory: "Citrix Cloud"
+description: |-
+  Data Source of a Citrix Cloud Google Cloud Identity Provider instance. Note that this feature is in Tech Preview.
+---
+
+# citrix_cloud_google_identity_provider (Data Source)
+
+Data Source of a Citrix Cloud Google Cloud Identity Provider instance. Note that this feature is in Tech Preview.
+
+## Example Usage
+
+```terraform
+# Get Citrix Cloud Google Identity Provider data source by ID
+data "citrix_cloud_google_identity_provider" "example_google_identity_provider" {
+  id = "00000000-0000-0000-0000-000000000000"
+}
+
+# Get Citrix Cloud Google Identity Provider data source by name
+data "citrix_cloud_google_identity_provider" "example_google_identity_provider" {
+  name = "exampleGoogleIdentityProvider"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Optional
+
+- `id` (String) ID of the Citrix Cloud Google Cloud Identity Provider instance.
+- `name` (String) Name of the Citrix Cloud Google Cloud Identity Provider instance.
+
+### Read-Only
+
+- `auth_domain_name` (String) User authentication domain name for Google Cloud Identity Provider.
+- `google_customer_id` (String) Customer ID of the configured  Google Cloud Identity Provider.
+- `google_domain` (String) Domain of the configured Google Cloud Identity Provider.

docs/data-sources/delivery_group.md

@@ -32,6 +32,8 @@ data "citrix_delivery_group" "example_delivery_group" {
 ### Read-Only
 
 - `id` (String) GUID identifier of the delivery group.
+- `tags` (Set of String) A set of identifiers of tags to associate with the delivery group.
+- `tenants` (Set of String) A set of identifiers of tenants to associate with the delivery group.
 - `vdas` (Attributes List) The VDAs associated with the delivery group. (see [below for nested schema](#nestedatt--vdas))
 
 <a id="nestedatt--vdas"></a>

docs/data-sources/hypervisor.md

@@ -28,4 +28,5 @@ data "citrix_hypervisor" "azure-hypervisor" {
 
 ### Read-Only
 
-- `id` (String) GUID identifier of the hypervisor.
+- `id` (String) GUID identifier of the hypervisor.
+- `tenants` (Set of String) A set of identifiers of tenants to associate with the hypervisor connection.

docs/data-sources/machine_catalog.md

@@ -32,6 +32,8 @@ data "citrix_machine_catalog" "example_machine_catalog" {
 ### Read-Only
 
 - `id` (String) GUID identifier of the machine catalog.
+- `tags` (Set of String) A set of identifiers of tags to associate with the machine catalog.
+- `tenants` (Set of String) A set of identifiers of tenants to associate with the machine catalog.
 - `vdas` (Attributes List) The VDAs associated with the machine catalog. (see [below for nested schema](#nestedatt--vdas))
 
 <a id="nestedatt--vdas"></a>

docs/data-sources/tag.md

@@ -0,0 +1,43 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "citrix_tag Data Source - citrix"
+subcategory: "CVAD"
+description: |-
+  Data source of a tag.
+---
+
+# citrix_tag (Data Source)
+
+Data source of a tag.
+
+## Example Usage
+
+```terraform
+# Get Tag detail by name
+data "citrix_tag" "example_tag_by_name" {
+    name = "exampleTag"
+}
+
+# Get Tag detail by id
+data "citrix_tag" "example_tag_by_id" {
+    id = "00000000-0000-0000-0000-000000000000"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Optional
+
+- `id` (String) GUID identifier of the tag.
+- `name` (String) Name of the tag.
+
+### Read-Only
+
+- `associated_application_count` (Number) Number of applications associated with the tag.
+- `associated_application_group_count` (Number) Number of application groups associated with the tag.
+- `associated_delivery_group_count` (Number) Number of delivery groups associated with the tag.
+- `associated_machine_catalog_count` (Number) Number of machine catalogs associated with the tag.
+- `associated_machine_count` (Number) Number of machines associated with the tag.
+- `description` (String) Description of the tag.
+- `scopes` (Set of String)