From c53d313de90ac396d728d7ab1bfa1f2d56914b9c Mon Sep 17 00:00:00 2001 From: Fei Su Date: Tue, 5 Nov 2024 15:16:29 +0800 Subject: [PATCH] Update README for known issue Signed-off-by: Fei Su --- README.md | 32 +++++++++++++++---------- docs/resources/snapshot.md | 2 +- examples/pool-main/main.tf | 44 ++++++++++++++++++---------------- xenserver/snapshot_resource.go | 2 +- 4 files changed, 44 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 68bbca2..0e478e0 100644 --- a/README.md +++ b/README.md @@ -7,26 +7,25 @@ This repository is the [Terraform Provider of XenServer](https://registry.terraf - `xenserver/` The provider, resources, data sources and tests. - Miscellaneous meta files. -## Requirements +## Developing the Provider +### Requirements - [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.8 - [Go](https://golang.org/doc/install) >= 1.22.2 -## Developing the Provider -### Prepare +### Prepare Development Environment -If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (see [Requirements](#requirements) above). +The following instructions are based on Linux system. -To build the provider, you'll need to prepare the local XenServer module for Go. -- [Download](https://www.xenserver.com/downloads) the XenServer SDK zip package and unzip -- Create `goSDK/` directory under `terraform-provider-xenserver/` -- Copy all source files under `XenServer-SDK/XenServerGo/src/` to `terraform-provider-xenserver/goSDK/` folder +- Prepare the local XenServer SDK module + - [Download](https://www.xenserver.com/downloads) the XenServer SDK zip package and unzip + - Create `goSDK/` directory under `terraform-provider-xenserver/` + - Copy all source files under `XenServer-SDK/XenServerGo/src/` to `terraform-provider-xenserver/goSDK/` folder ### Build Run the commands as follows: - ```shell go get -u all go mod tidy @@ -34,6 +33,8 @@ go mod tidy To compile the provider, run `"go install"`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory. +In short, you can just run `make provider` instead. + ### Document To generate or update documentation, run `make doc`. @@ -44,10 +45,12 @@ Set up log with `github.com/hashicorp/terraform-plugin-log/tflog`. To enable log ```shell export TF_LOG_PROVIDER="DEBUG" +export TF_LOG_PATH=/tmp/terraform.log ``` -See https://developer.hashicorp.com/terraform/plugin/log/managing. -### Test +Find more details in [Managing Log Output](https://developer.hashicorp.com/terraform/plugin/log/managing). + +### Acceptance Test In order to run the full suite of acceptance tests, prepare a local `.env` file like: ```shell @@ -61,7 +64,7 @@ export SMB_SERVER_USERNAME= export SMB_SERVER_PASSWORD= ``` -Run `"make testacc"`. *Note:* Acceptance tests create real resources, and often cost money to run. +Run `"make testacc"`. *Note:* Acceptance tests generate actual resources and frequently incur costs when run. ```shell make testacc @@ -74,7 +77,7 @@ Terraform allows to use local provider builds by setting a `dev_overrides` block 1. Set `GOBIN` to the path where Go installs binaries or use the default path: ```shell -export GOBIN=/Users//go/bin +export GOBIN=$HOME/go/bin go env GOBIN ``` @@ -121,6 +124,9 @@ sudo docker run -it -v $(pwd):/app -w /app golangci/golangci-lint bash golangci-lint run --config=/app/.golangci.yml ``` +## Known Issue +1. If you are using Terraform provider v0.1.1, you might encounter compatibility issues after applying the XenServer 8 updates released to Early Access on 25 September 2024 and Normal on 2 October 2024. Terraform v0.1.2 resolves these compatibility issues. + ## Contributing See [DEVELOP.md](DEVELOP.md) diff --git a/docs/resources/snapshot.md b/docs/resources/snapshot.md index 666cfed..2a54328 100644 --- a/docs/resources/snapshot.md +++ b/docs/resources/snapshot.md @@ -88,7 +88,7 @@ resource "xenserver_snapshot" "snapshot" { - `revert` (Boolean) Set to `true` if you want to revert this snapshot to VM, default to be `false`. --> **Note:** When `revert` is true, the snapshot resource will be updated with new configuration first and then revert to VM. +-> **Note:** `revert` only works after the snapshot resource created. When `revert` is true, the snapshot resource attributes will be updated first, for example `name_label`. And then revert to VM. ~> **Warning:** After revert, the VM `hard_drive` will be updated. If snapshot revert to the VM resource defined in 'main.tf', it'll cause issue when continue execute terraform commands. There's a suggest solution to resolve this issue, follow the steps:
1. run `terraform state show xenserver_snapshot.`, get the revert VM's UUID 'vm_uuid' and revert VDIs' UUID 'vdi_uuid'.
2. run `terraform state rm xenserver_vm.` to remove the VM resource state.
3. run `terraform import xenserver_vm. ` to import the VM resource new state.
4. run `terraform state rm xenserver_vdi.` to remove the VDI resource state. Be careful, you only need to remove the VDI resource used in above VM resource. If there're multiple VDI resources, remove them all.
5. run `terraform import xenserver_vdi. ` to import the VDI resource new state. If there're multiple VDI resources, import them all.
- `with_memory` (Boolean) True if snapshot with the VM's memory, default to be `false`. diff --git a/examples/pool-main/main.tf b/examples/pool-main/main.tf index 30a0bdd..828fc30 100644 --- a/examples/pool-main/main.tf +++ b/examples/pool-main/main.tf @@ -16,6 +16,25 @@ provider "xenserver" { password = local.env_vars["XENSERVER_PASSWORD"] } +# get the existing supporter hosts +data "xenserver_host" "supporter" { + is_coordinator = false +} + +# join a new supporter to the pool +resource "xenserver_pool" "pool" { + name_label = "pool" + join_supporters = [ + { + host = local.env_vars["SUPPORTER_HOST"] + username = local.env_vars["SUPPORTER_USERNAME"] + password = local.env_vars["SUPPORTER_PASSWORD"] + } + ] + eject_supporters = [ data.xenserver_host.supporter.data_items[0].uuid ] +} + + # resource "xenserver_sr_nfs" "nfs" { # name_label = "NFS shared storage" # name_description = "A test NFS storage repository" @@ -43,25 +62,8 @@ provider "xenserver" { # } # } -# resource "xenserver_pool" "pool" { +# resource "xenserver_pool" "pool_management" { # name_label = "pool" -# # default_sr = xenserver_sr_nfs.nfs.uuid -# # management_network = data.xenserver_pif.pif.data_items[0].network -# join_supporters = [ -# { -# host = local.env_vars["SUPPORTER_HOST"] -# username = local.env_vars["SUPPORTER_USERNAME"] -# password = local.env_vars["SUPPORTER_PASSWORD"] -# } -# ] -# } - -# comment out the following block for the second run -data "xenserver_host" "supporter" { - is_coordinator = false -} - -resource "xenserver_pool" "pool" { - name_label = "pool" - eject_supporters = [ data.xenserver_host.supporter.data_items[0].uuid ] -} \ No newline at end of file +# default_sr = data.xenserver_sr_nfs.nfs.data_items[0].uuid +# management_network = data.xenserver_pif.pif.data_items[0].uuid +# } \ No newline at end of file diff --git a/xenserver/snapshot_resource.go b/xenserver/snapshot_resource.go index b2d503e..428592c 100644 --- a/xenserver/snapshot_resource.go +++ b/xenserver/snapshot_resource.go @@ -59,7 +59,7 @@ func (r *snapshotResource) Schema(_ context.Context, _ resource.SchemaRequest, r }, "revert": schema.BoolAttribute{ MarkdownDescription: "Set to `true` if you want to revert this snapshot to VM, default to be `false`." + - "\n\n-> **Note:** When `revert` is true, the snapshot resource will be updated with new configuration first and then revert to VM." + + "\n\n-> **Note:** `revert` only works after the snapshot resource created. When `revert` is true, the snapshot resource attributes will be updated first, for example `name_label`. And then revert to VM." + "\n\n~> **Warning:** After revert, the VM `hard_drive` will be updated. If snapshot revert to the VM resource defined in 'main.tf', it'll cause issue when continue execute terraform commands. There's a suggest solution to resolve this issue, follow the steps:
" + "1. run `terraform state show xenserver_snapshot.`, get the revert VM's UUID 'vm_uuid' and revert VDIs' UUID 'vdi_uuid'.
" + "2. run `terraform state rm xenserver_vm.` to remove the VM resource state.
" +