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.
- Plugin for Terraform Provider for Citrix® Developer Guide
- Table of Contents
- Install Dependencies
- Load project in VSCode for Go Development
- Debugging Provider code in VSCode
- Debugging with citrix-daas-rest-go client code in Visual Studio Code
- Handling Terraform lists/sets and nested objects
- Running the tests
- Commonly faced errors
- Plugin for Terraform Provider for StoreFront Developer Guide
- Install Go on your local system: https://go.dev/doc/install
choco install golang
- Install latest version of Terraform (installing via Chocolatey recommended)
choco install terraform
Visual Studio Code requires the Go extension to be able to load go projects, resolve internal references and even cross package references. Once the Go extension is installed, you should be able to load terraform-provider-citrix in VSCode. Go plugin requires the go.mod file to be in the root work directory when you load the project.
In order to debug the terraform provider module locally, you will need to setup a VS debugger config for the go project. Create terraform-provider-citrix/.vscode/launch.json and add the following configuration block:
{
"configurations": [
{
"name": "Debug Terraform Provider",
"type": "go",
"request": "launch",
"mode": "debug",
// this assumes your workspace is the terraform-provider-citrix directory
"program": "${workspaceFolder}",
"env": {},
"args": [
"-debug",
]
}
]
}Once you have the debug config setup, you can hit Run on the VSCode debugger. You should see the following output on the debugger console:
Starting: C:\Users\{local user}\go\bin\dlv.exe dap --listen=127.0.0.1:54615 from {Root of repo}\terraform-provider-citrix
DAP server listening at: 127.0.0.1:54615
Type 'dlv help' for list of commands.
{"@level":"debug","@message":"plugin address","@timestamp":"2023-05-22T15:21:11.753013-04:00","address":"127.0.0.1:54834","network":"tcp"}
Provider started. To attach Terraform CLI, set the TF_REATTACH_PROVIDERS environment variable with the following:
Command Prompt: set "TF_REATTACH_PROVIDERS={"registry.terraform.io/citrix/citrix":{"Protocol":"grpc","ProtocolVersion":6,"Pid":38724,"Test":true,"Addr":{"Network":"tcp","String":"127.0.0.1:54834"}}}"
PowerShell: $env:TF_REATTACH_PROVIDERS='{"registry.terraform.io/citrix/citrix":{"Protocol":"grpc","ProtocolVersion":6,"Pid":38724,"Test":true,"Addr":{"Network":"tcp","String":"127.0.0.1:54834"}}}'Start a PowerShell session for running your terraform cli for debugging, and copy paste the following command:
$env:TF_REATTACH_PROVIDERS='{"registry.terraform.io/citrix/citrix":{"Protocol":"grpc","ProtocolVersion":6,"Pid":38724,"Test":true,"Addr":{"Network":"tcp","String":"127.0.0.1:54834"}}}'
Now you are good to run terraform jobs to debug the provider code. Make sure to re-attach the provider server everytime you restart the debugger as the port can change per debugging session.
Optionally, you can also debug citrix-daas-rest-go client, which is the Citrix DaaS Rest client for Go. By debugging with the go client, you can inspect the raw response and error message from Citrix DaaS APIs by setting up breakpoints in provider. You can also check the function implementation and models the provider server uses.
Clone the Go client from https://github.com/citrix/citrix-daas-rest-go. Go to terraform-provider-citrix/go.mod and uncomment the following line to intercept citrix-daas-rest-go client with local package:
replace github.com/citrix/citrix-daas-rest-go => {your local repo directory}/citrix-daas-rest-go
Run Debugging Provider code in Visual Studio Code again and you will be able to step into the client functions.
Set a breakpoint in terraform-provider-citrix/internal/provider/provider.go::Configure
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 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.Set |
T[] |
ObjectSetToTypedArray[T] |
T must implement ModelWithAttributes. For a set of nested objects |
T[] |
types.Set |
TypedArrayToObjectSet[T] |
T must implement ModelWithAttributes. For a set 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 6 of these methods, the struct T needs to implement the ModelWithAttributes 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.
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 |
Before running the tests, you need to provide values for environment variables required by the test files. The environment parameters that need to be specified can be found in the following template files:
- To Run Tests for the Cloud Environment:
settings.cloud.example.json - To Run Tests for the On-Premise environment:
setings.onprem.example.json
Copy the environment parameters from the appropriate template file and paste them in the GO settings.json file.
To navigate to settings.json file, follow the steps below:
-
Click on the
Extensionsicon on the left panel of VS Code. -
Search for the
Goextension and click on thegearicon next to it.
-
In the search bar, type in
go.testEnvVars. From the search result, click onEdit in settings.jsonunderGo: Test Env Vars. -
Paste the contents of the template file that you copied earlier.
-
Update the missing values in the file and run the commands mentioned below
➥ cd {Root of repo}/terraform-provider-citrix
➥ $env:TF_ACC = 1
➥ go test -count=1 -run='{name of resource to test}' -v ./internal/test error obtaining VCS status: exit status 128
Use -buildvcs=false to disable VCS stamping.
exit status 1To solve this issue, run the following command at the root of the repository:
git config --global --add safe.directory [path to dir/repo]The test running process is the same as Running the tests with additional parameter in the settings.cloud.example.json or settings.onprem.example.json StoreFront env variable section