Merge pull request #41 from ScaleComputing/docs

extend documentation

Author: justinc1

README.md

@@ -1,4 +1,7 @@
 # Terraform Provider HyperCore
+
+This is Terraform Provider for [Scale Computing](https://www.scalecomputing.com/) [HyperCore](https://www.scalecomputing.com/sc-hypercore) product.
+
 ## Requirements
 
 - [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.0

docs/index.md

@@ -3,12 +3,12 @@
 page_title: "hypercore Provider"
 subcategory: ""
 description: |-
-  
+  Terraform Provider for Scale Computing https://www.scalecomputing.com/ HyperCore https://www.scalecomputing.com/sc-hypercore product.
 ---
 
 # hypercore Provider
 
-
+Terraform Provider for [Scale Computing](https://www.scalecomputing.com/) [HyperCore](https://www.scalecomputing.com/sc-hypercore) product.
 
 ## Example Usage
 

docs/resources/disk.md

@@ -3,12 +3,12 @@
 page_title: "hypercore_disk Resource - hypercore"
 subcategory: ""
 description: |-
-  Hypercore disk resource to manage VM disks. To use this resource, it's recommended to set the environment variable TF_CLI_ARGS_apply="-parallelism=1" or pass the -parallelism parameter to the terraform apply.
+  Hypercore disk resource to manage VM disks. To use this resource, it's recommended to set the environment variable TF_CLI_ARGS_apply="-parallelism=1" or pass the -parallelism parameter to the terraform apply. Removing disk from a running VM is (often) not possible. In this case it is required to shutdown the VM before disk removal.
 ---
 
 # hypercore_disk (Resource)
 
-Hypercore disk resource to manage VM disks. <br><br>To use this resource, it's recommended to set the environment variable `TF_CLI_ARGS_apply="-parallelism=1"` or pass the `-parallelism` parameter to the `terraform apply`.
+Hypercore disk resource to manage VM disks. <br><br>To use this resource, it's recommended to set the environment variable `TF_CLI_ARGS_apply="-parallelism=1"` or pass the `-parallelism` parameter to the `terraform apply`.<br><br> Removing disk from a running VM is (often) not possible. In this case it is required to shutdown the VM before disk removal.
 
 ## Example Usage
 

docs/resources/vm.md

@@ -4,12 +4,28 @@ page_title: "hypercore_vm Resource - hypercore"
 subcategory: ""
 description: |-
   HypercoreVM resource to create a VM from a template VM
+  A running VM might need to shutdown to apply required changes.
+  In this case first a nice ACPI shutdown is tried.
+  If the VM does not stop, a force shutdown is tried.
+  In both cases the provider waits up to HC_VM_SHUTDOWN_TIMEOUT seconds for the VM to shutdown.
+  HC_VM_SHUTDOWN_TIMEOUT dafault value is 300 seconds.
+  HC_VM_SHUTDOWN_TIMEOUT can be changed via environ.
+  The provider will currently try to shutdown VM only before VM delete.
 ---
 
 # hypercore_vm (Resource)
 
 HypercoreVM resource to create a VM from a template VM
 
+A running VM might need to shutdown to apply required changes.
+In this case first a nice ACPI shutdown is tried.
+If the VM does not stop, a force shutdown is tried.
+In both cases the provider waits up to HC_VM_SHUTDOWN_TIMEOUT seconds for the VM to shutdown.
+HC_VM_SHUTDOWN_TIMEOUT dafault value is 300 seconds.
+HC_VM_SHUTDOWN_TIMEOUT can be changed via environ.
+
+The provider will currently try to shutdown VM only before VM delete.
+
 ## Example Usage
 
 ```terraform
@@ -19,6 +35,15 @@ locals {
   vm_name           = "my-vm"
 }
 
+resource "hypercore_vm" "empty-vm" {
+  group       = "my-group"
+  name        = "empty-vm"
+  description = "some description"
+
+  vcpu   = 4
+  memory = 4096 # MiB
+}
+
 data "hypercore_vms" "clone_source_vm" {
   name = "source_vm"
 }

examples/resources/hypercore_vm/resource.tf

@@ -4,6 +4,15 @@ locals {
   vm_name           = "my-vm"
 }
 
+resource "hypercore_vm" "empty-vm" {
+  group       = "my-group"
+  name        = "empty-vm"
+  description = "some description"
+
+  vcpu   = 4
+  memory = 4096 # MiB
+}
+
 data "hypercore_vms" "clone_source_vm" {
   name = "source_vm"
 }

internal/provider/hypercore_disk_resource.go

@@ -51,7 +51,9 @@ func (r *HypercoreDiskResource) Schema(ctx context.Context, req resource.SchemaR
 		// This description is used by the documentation generator and the language server.
 		MarkdownDescription: "" +
 			"Hypercore disk resource to manage VM disks. <br><br>" +
-			"To use this resource, it's recommended to set the environment variable `TF_CLI_ARGS_apply=\"-parallelism=1\"` or pass the `-parallelism` parameter to the `terraform apply`.",
+			"To use this resource, it's recommended to set the environment variable `TF_CLI_ARGS_apply=\"-parallelism=1\"` or pass the `-parallelism` parameter to the `terraform apply`." +
+			"<br><br> Removing disk from a running VM is (often) not possible. In this case it is required to shutdown the VM before disk removal." +
+			"",
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
 				Computed:            true,

internal/provider/hypercore_vm_resource.go

@@ -78,7 +78,16 @@ func (r *HypercoreVMResource) Metadata(ctx context.Context, req resource.Metadat
 func (r *HypercoreVMResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
 		// This description is used by the documentation generator and the language server.
-		MarkdownDescription: "HypercoreVM resource to create a VM from a template VM",
+		MarkdownDescription: `HypercoreVM resource to create a VM from a template VM
+
+A running VM might need to shutdown to apply required changes.
+In this case first a nice ACPI shutdown is tried.
+If the VM does not stop, a force shutdown is tried.
+In both cases the provider waits up to HC_VM_SHUTDOWN_TIMEOUT seconds for the VM to shutdown.
+HC_VM_SHUTDOWN_TIMEOUT dafault value is 300 seconds.
+HC_VM_SHUTDOWN_TIMEOUT can be changed via environ.
+
+The provider will currently try to shutdown VM only before VM delete.`,
 
 		Attributes: map[string]schema.Attribute{
 			"group": schema.StringAttribute{

internal/provider/provider.go

@@ -46,6 +46,7 @@ func (p *HypercoreProvider) Metadata(ctx context.Context, req provider.MetadataR
 
 func (p *HypercoreProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		MarkdownDescription: "Terraform Provider for [Scale Computing](https://www.scalecomputing.com/) [HyperCore](https://www.scalecomputing.com/sc-hypercore) product.",
 		Attributes: map[string]schema.Attribute{
 			"host": schema.StringAttribute{
 				MarkdownDescription: "Hypercore Computing host URI; can also be set with `HC_HOST` environment variable.",

internal/provider/tests/acceptance/setup/env.txt

@@ -1,3 +1,5 @@
+HC_VM_SHUTDOWN_TIMEOUT=30
+
 SOURCE_VM_UUID="97904009-1878-4881-b6df-83c85ab7dc1a"
 EXISTING_VDISK_UUID="33c78baf-c3c6-4600-8432-9c7a2a3008ab"
 SOURCE_VM_NAME="integration-test-vm"