release-v0.6.1

DEVELOPER.md

@@ -3,7 +3,6 @@
 This documentation will guide you through the process of setting up your dev environment for running Plugin for Terraform Provider for Citrix® server locally on your dev machine.
 
 ## Table of Contents
-
 - [Plugin for Terraform Provider for Citrix® Developer Guide](#plugin-for-terraform-provider-for-citrix-developer-guide)
   - [Table of Contents](#table-of-contents)
   - [Install Dependencies](#install-dependencies)
@@ -13,9 +12,13 @@ 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)
+    - [Converting to Go native types](#converting-to-go-native-types)
+    - [Preserving order in lists](#preserving-order-in-lists)
   - [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)
+
 ## Install Dependencies
 * Install Go on your local system: https://go.dev/doc/install
   * `choco install golang`
@@ -85,6 +88,35 @@ 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
+### 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. 
+
+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.
+
+| From | To | Function | Notes |
+|------|----|----------|-------|
+| `types.Object` | `T` | `ObjectValueToTypedObject` | `T` must implement `ModelWithAttributes` |
+| `T` | `types.Object` | `TypedObjectToObjectValue` | `T` must implement `ModelWithAttributes` |
+| `types.List` | `T[]` | `ObjectListToTypedArray[T]` | `T` must implement `ModelWithAttributes`. For a list of nested objects |
+| `T[]` | `types.List` | `TypedArrayToObjectList[T]` | `T` must implement `ModelWithAttributes`. For a list of nested objects |
+| `types.List` | `string[]` | `StringListToStringArray` | For a list of strings |
+| `string[]` | `types.List` | `StringArrayToStringList` | For a list of strings |
+| `types.Set` | `string[]` | `StringSetToStringArray` | For a set of strings |
+| `string[]` | `types.Set` | `StringArrayToStringSet` | For a set of strings |
+
+In order to use the first 4 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.
+
+### 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. 
+
+| Function | Input | Notes |
+|----------|-------|-------|
+| `RefreshList` | `[]string` | |
+| `RefreshUsersList` | `types.Set` | Will ensure users are not duplicated by UPN or SAMname |
+| `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 |
+
 ## Running the tests
 
 Before running the tests, you need to provide values for environment variables required by the test files. 

README.md

@@ -2,9 +2,9 @@
 
 Citrix has developed a custom Terraform provider for automating Citrix product deployments and configurations. Using [Terraform](https://www.terraform.io) with Citrix provider, you can manage your Citrix products via Infrastructure as Code, giving you higher efficiency and consistency on infrastructure management, as well as better reusability on infrastructure configuration. The provider is developed and maintained by Citrix. Please note that this provider is still in tech preview.
 
-## Table of Content
+## Table of Contents
 - [Plugin for Terraform Provider for Citrix®](#plugin-for-terraform-provider-for-citrix)
-  - [Table of Content](#table-of-content)
+  - [Table of Contents](#table-of-contents)
   - [Contacting the Maintainers](#contacting-the-maintainers)
   - [Plugin for Terraform Provider for Citrix® Documentation](#plugin-for-terraform-provider-for-citrix-documentation)
     - [Navigating the repository](#navigating-the-repository)
@@ -24,7 +24,7 @@ Citrix has developed a custom Terraform provider for automating Citrix product d
     - [Configure Global App Configuration (GAC) Settings](#configure-global-app-configuration-gac-settings)
     - [Create Citrix Cloud Resource Locations](#create-citrix-cloud-resource-locations)
     - [Managing StoreFront resources](#managing-storefront-resources)
-  - [Deployment Guides](#deployment-guides)
+  - [Examples and Deployment Guides](#examples-and-deployment-guides)
   - [Frequently Asked Questions](#frequently-asked-questions)
       - [What resource is supported for different connection types?](#what-resource-is-supported-for-different-connection-types)
       - [What provisioning types are supported for machine catalog?](#what-provisioning-types-are-supported-for-machine-catalog)
@@ -66,24 +66,19 @@ Example for Cloud site:
 
 ```hcl
 provider "citrix" {
-    region        = "US"  # Optionally set with `CITRIX_REGION` environment variable.
-    environment   = "Production"  # Optionally set with `CITRIX_ENVIRONMENT` environment variable.
     customer_id   = "${var.customer_id}"  # Optionally set with `CITRIX_CUSTOMER_ID` environment variable.
     client_id     = "${var.api_key_clientId}"  # Optionally set with `CITRIX_CLIENT_ID` environment variable.
     client_secret = "${var.api_key_clientSecret}"  # Optionally set with `CITRIX_CLIENT_SECRET` environment variable.
 }
 ```
 
-You can also set `hostname` for cloud site to force override the Citrix DaaS service URL for a cloud customer. 
-
 You can use environment variables as stated in the comments above. When running Go tests, always use environment variables so that no credentials or other sensitive information are checked-in to the code.
 
 Below is a table to show the difference between on-premises and Cloud provider configuration:
 
 |              | Cloud                             | On-Premises                           |
 |--------------|-----------------------------------|---------------------------------------|
-| region       | `US` / `EU` / `AP-S` / `JP`       | N/A                                   |
-| environment  | `Production` / `Staging`          | N/A                                   |
+| environment  | `Production`, `Japan`, `Gov`      | N/A                                   |
 | customerId   | Cloud Customer Id                 | N/A                                   |
 | hostname     | (Optional) Cloud DDC hostname     | On-Premises DDC Hostname / IP address |
 | clientId     | Citrix Cloud API Key clientId     | Domain Admin Username                 |
@@ -162,9 +157,10 @@ Resource locations contain the resources (e.g. cloud connectors) required to del
 ### Managing StoreFront resources
 Please refer to the [StoreFront.md](StoreFront.md) to configure StoreFront resources via terraform.
 
-## Deployment Guides
-Detailed instructions on setting up deployments on different cloud providers.
+## Examples and Deployment Guides
+Basic example templates for getting started: [/examples](/examples)
 
+Detailed instructions on setting up deployments on different cloud providers from Citrix Tech Zone:
 - [AWS EC2](https://community.citrix.com/tech-zone/build/deployment-guides/terraform-daas-aws/)
 - [Azure](https://community.citrix.com/tech-zone/build/deployment-guides/citrix-daas-terraform-azure/)
 - [GCP](https://community.citrix.com/tech-zone/build/deployment-guides/terraform-daas-gcp/)
@@ -211,4 +207,4 @@ This project is Licensed under the Apache License, Version 2.0 (the "License");
 
 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 
-<sub>Copyright © 2023. Citrix Systems, Inc.</sub>
+<sub>Copyright © 2024. Citrix Systems, Inc.</sub>

StoreFront.md

@@ -3,7 +3,6 @@
 This Terraform module allows you to manage resources in Citrix StoreFront.
 
 ## Table of Contents
-
 - [Terraform Module for Citrix StoreFront](#terraform-module-for-citrix-storefront)
   - [Table of Contents](#table-of-contents)
   - [Prerequisites](#prerequisites)
@@ -26,9 +25,9 @@ This Terraform module allows you to manage resources in Citrix StoreFront.
 If running the StoreFront provider on a machine other than the machine where StoreFront is installed, please provide the Active Directory Admin credentials in either environment variables or provider configuration
   - `SF_COMPUTER_NAME`: 
       - The name of the remote computer where the StoreFront server is running.
-  - `SF_AD_ADMAIN_USERNAME`: 
+  - `SF_AD_ADMIN_USERNAME`: 
       - The Active Directory Admin username to connect to the remote PowerShell of the StoreFront Server machine.
-  - `SF_AD_ADMAIN_PASSWORD`: 
+  - `SF_AD_ADMIN_PASSWORD`: 
       - The Active Directory Admin password to connect to the remote PowerShell of the StoreFront server machine.
 
 

docs/data-sources/application_folder_details.md

@@ -30,7 +30,7 @@ Data source for retrieving details of applications belonging to a specific folde
 Read-Only:
 
 - `application_folder_path` (String) The path of the folder which the application belongs to
-- `delivery_groups` (List of String) The delivery groups which the application is associated with.
+- `delivery_groups` (Set of String) The delivery groups which the application is associated with.
 - `description` (String) The description of the application.
 - `installed_app_properties` (Attributes) The installed application properties of the application. (see [below for nested schema](#nestedatt--applications_list--installed_app_properties))
 - `name` (String) The name of the application.

docs/index.md

@@ -33,8 +33,8 @@ provider "citrix" {
 
 ### Optional
 
-- `client_id` (String) Client Id for Citrix DaaS service authentication. <br />For Citrix On-Premises customers: Use this to specify Domain Admin Username. <br />For Citrix Cloud customers: Use this to specify Cloud API Key Client Id.<br />Can be set via Environment Variable **CITRIX_CLIENT_ID**.
-- `client_secret` (String, Sensitive) Client Secret for Citrix DaaS service authentication. <br />For Citrix on-premises customers: Use this to specify Domain Admin Password. <br />For Citrix Cloud customers: Use this to specify Cloud API Key Client Secret.<br />Can be set via Environment Variable **CITRIX_CLIENT_SECRET**.
+- `client_id` (String) Client Id for Citrix DaaS service authentication. <br />For Citrix On-Premises customers: Use this to specify a DDC administrator username. <br />For Citrix Cloud customers: Use this to specify Cloud API Key Client Id.<br />Can be set via Environment Variable **CITRIX_CLIENT_ID**.
+- `client_secret` (String, Sensitive) Client Secret for Citrix DaaS service authentication. <br />For Citrix on-premises customers: Use this to specify a DDC administrator password. <br />For Citrix Cloud customers: Use this to specify Cloud API Key Client Secret.<br />Can be set via Environment Variable **CITRIX_CLIENT_SECRET**.
 - `customer_id` (String) Citrix Cloud customer ID. Only applicable for Citrix Cloud customers.<br />Can be set via Environment Variable **CITRIX_CUSTOMER_ID**.
 - `disable_ssl_verification` (Boolean) Disable SSL verification against the target DDC. <br />Only applicable to on-premises customers. Citrix Cloud customers should omit this option. Set to true to skip SSL verification only when the target DDC does not have a valid SSL certificate issued by a trusted CA. <br />When set to true, please make sure that your provider config is set for a known DDC hostname. <br />[It is recommended to configure a valid certificate for the target DDC](https://docs.citrix.com/en-us/citrix-virtual-apps-desktops/install-configure/install-core/secure-web-studio-deployment) <br />Can be set via Environment Variable **CITRIX_DISABLE_SSL_VERIFICATION**.
 - `environment` (String) Citrix Cloud environment of the customer. Only applicable for Citrix Cloud customers. Available options: `Production`, `Staging`, `Japan`, `JapanStaging`, `Gov`, `GovStaging`. <br />Can be set via Environment Variable **CITRIX_ENVIRONMENT**.
@@ -46,6 +46,6 @@ provider "citrix" {
 
 Required:
 
-- `ad_admin_password` (String) Active Directory Admin Password to connect to storefront server <br />Only applicable for Citrix on-premises customers. Use this to specify AD admin password<br />Can be set via Environment Variable **SF_AD_ADMAIN_PASSWORD**.
-- `ad_admin_username` (String) Active Directory Admin Username to connect to storefront server <br />Only applicable for Citrix on-premises customers. Use this to specify AD admin username <br />Can be set via Environment Variable **SF_AD_ADMAIN_USERNAME**.
+- `ad_admin_password` (String) Active Directory Admin Password to connect to storefront server <br />Only applicable for Citrix on-premises customers. Use this to specify AD admin password<br />Can be set via Environment Variable **SF_AD_ADMIN_PASSWORD**.
+- `ad_admin_username` (String) Active Directory Admin Username to connect to storefront server <br />Only applicable for Citrix on-premises customers. Use this to specify AD admin username <br />Can be set via Environment Variable **SF_AD_ADMIN_USERNAME**.
 - `computer_name` (String) StoreFront server computer Name <br />Only applicable for Citrix on-premises customers. Use this to specify StoreFront server computer name <br />Can be set via Environment Variable **SF_COMPUTER_NAME**.

docs/resources/admin_role.md

@@ -38,7 +38,7 @@ resource "citrix_admin_role" "cloud_example_role" {
 ### Required
 
 - `name` (String) Name of the admin role.
-- `permissions` (List of String) List of permissions to be associated with the admin role. To get a list of supported permissions, please refer to [Admin Predefined Permissions for Cloud](https://developer-docs.citrix.com/en-us/citrix-daas-service-apis/citrix-daas-rest-apis/apis/#/Admin-APIs/Admin-GetPredefinedPermissions) and [Admin Predefined Permissions for On-Premise](https://developer-docs.citrix.com/en-us/citrix-virtual-apps-desktops/citrix-cvad-rest-apis/apis/#/Admin-APIs/Admin-GetPredefinedPermissions).
+- `permissions` (Set of String) Permissions to be associated with the admin role. To get a list of supported permissions, please refer to [Admin Predefined Permissions for Cloud](https://developer-docs.citrix.com/en-us/citrix-daas-service-apis/citrix-daas-rest-apis/apis/#/Admin-APIs/Admin-GetPredefinedPermissions) and [Admin Predefined Permissions for On-Premise](https://developer-docs.citrix.com/en-us/citrix-virtual-apps-desktops/citrix-cvad-rest-apis/apis/#/Admin-APIs/Admin-GetPredefinedPermissions).
 
 ### Optional
 

docs/resources/admin_scope.md

@@ -16,16 +16,6 @@ Manages an administrator scope.
 resource "citrix_admin_scope" "example-admin-scope" {
     name        = "example-admin-scope"
     description = "Example admin scope for delivery group and machine catalog"
-    scoped_objects    = [
-        {
-            object_type = "DeliveryGroup",
-            object = "<Name of existing Delivery Group to be added to the scope>"
-        },
-        {
-            object_type = "MachineCatalog",
-            object = "<Name of existing Machine Catalog to be added to the scope>"
-        }
-    ]
 }
 ```
 
@@ -39,20 +29,11 @@ resource "citrix_admin_scope" "example-admin-scope" {
 ### Optional
 
 - `description` (String) Description of the admin scope.
-- `scoped_objects` (Attributes List) List of scoped objects to be associated with the admin scope. (see [below for nested schema](#nestedatt--scoped_objects))
 
 ### Read-Only
 
 - `id` (String) ID of the admin scope.
 
-<a id="nestedatt--scoped_objects"></a>
-### Nested Schema for `scoped_objects`
-
-Required:
-
-- `object` (String) Name of an existing object under the object type to be added to the scope.
-- `object_type` (String) Type of the scoped object. Allowed values are: `HypervisorConnection`, `MachineCatalog`, `DeliveryGroup`, `ApplicationGroup`, `Tag`, `PolicySet` and `Unknown`.
-
 ## Import
 
 Import is supported using the following syntax:

docs/resources/admin_user.md

@@ -33,7 +33,7 @@ resource "citrix_admin_user" "example-admin-user" {
 
 - `domain_name` (String) Name of the domain that the user is a part of. For example, if the domain is `example.com`, then provide the value `example` for this field.
 - `name` (String) Name of an existing user in the active directory.
-- `rights` (Attributes List) List of rights to be associated with the admin user. (see [below for nested schema](#nestedatt--rights))
+- `rights` (Attributes List) Rights to be associated with the admin user. (see [below for nested schema](#nestedatt--rights))
 
 ### Optional
 

docs/resources/application.md

@@ -24,6 +24,8 @@ resource "citrix_application" "example-application" {
     working_directory       = "<Working directory path for the executable>"
   }
   delivery_groups = [citrix_delivery_group.example-delivery-group.id]
+  icon            = citrix_application_icon.example-application-icon.id
+  limit_visibility_to_users = ["example\\user1"]
 }
 ```
 
@@ -32,7 +34,7 @@ resource "citrix_application" "example-application" {
 
 ### Required
 
-- `delivery_groups` (List of String) The delivery group id's to which the application should be added.
+- `delivery_groups` (Set of String) The delivery group IDs to which the application should be added.
 - `installed_app_properties` (Attributes) The install application properties. (see [below for nested schema](#nestedatt--installed_app_properties))
 - `name` (String) Name of the application.
 - `published_name` (String) A display name for the application that is shown to users.
@@ -41,6 +43,8 @@ resource "citrix_application" "example-application" {
 
 - `application_folder_path` (String) The application folder path in which the application should be created.
 - `description` (String) Description of the application.
+- `icon` (String) The Id of the icon to be associated with the application.
+- `limit_visibility_to_users` (Set of String) By default, the application is visible to all users within a delivery group. However, you can restrict its visibility to only certain users by specifying them in the 'limit_visibility_to_users' list. Must be in `DOMAIN\UserOrGroupName` or `[email protected]` format
 
 ### Read-Only