Terraform Provider Hyper-V

a terraform provider to work with hyper-V

!!! UNDER CONSTRUCTION !!!!!!!!

Prerequisites

To build:

GNU make
Golang >= v1.13
Terraform plugin SDK ~= v1.0.0

To use:

Terraform >= v0.12.9

Building The Provider

Clone the git-repository on your machine
```
mkdir -p $my_repositories
cd $my_repositories
git clone git@github.com:stefaanc/terraform-provider-hyperv
```
$my_repositories must point to the directory where you want to clone the repository
Build the provider
```
cd $my_repositories/terraform-provider-hosts
make release
```
This will build the provider and put it in
- %AppData%\terraform.d\plugins on Windows
- $HOME\.terraform.d\plugins on Linux

💡
The makefile provides more commands: tidy, test, log, report, testacc, build, ...

Installing The Provider

Download the provider to your machine
- go to the releases tab on github
- download the file that is appropriate for your machine
Move the provider from your Downloads folder to
- %AppData%\terraform.d\plugins on Windows
- $HOME\.terraform.d\plugins on Linux

💡
Alternatively, you can try our latest release-in-progress under the releases folder. No guarantee though this will be a fully working provider.

Using The Provider

💡
You can find the some of following examples (and more) under the examples folder

provider "hyperv"

Configures a provider for a Hyper-V server.

provider "hyperv" {}

provider "hyperv" {
    type = "local"
}

provider "hyperv" {
    type     = "ssh"
    host     = "localhost"
    port     = 22
    user     = "me"
    password = "my-password"
    insecure = true
}

Arguments		Description
`type`	Optional	The type of connection to the hyperv-server: `"local"` or `"ssh"`. - defaults to `"local"`
----------
`host`	Optional	The hyperv-server. - ignored when `type = "local"` - defaults to `"localhost"`
`port`	Optional	The hyperv-server's port for ssh. - ignored when `type = "local"` - defaults to `22`
`user`	Optional	The user name for communication with the hyperv-server. - ignored when `type = "local"` - required when `type = "ssh"`
`password`	Optional	The user password for communication with the hyperv-server. - ignored when `type = "local"` - required when `type = "ssh"`
`insecure`	Optional	Allow insecure communication - disables checking of the server certificate. - ignored when `type = "local"` - defaults to `false` When `insecure = false`, the hyperv-server's certificate is checked against the user's known hosts, as specified by the file `~/.ssh/known_hosts`.

💡
The Hyper-V API needs elevated credentials ("Run as Administrator") for all methods. When using type = "local", you need to run terraform from an elevated shell. When using type = "ssh", terraform will always use the most elevated credentials available to the configured user.

Data-sources

data "hyperv_vswitch"

Reads a Hyper-V virtual switch.

data "hyperv_vswitch" "default" {
    name = "Default Switch"
}

Arguments		Description
`name`	Required	The name of the virtual switch.
----------
`x_lifecycle`	Optional	see x_lifecycle for data-sources

Exports		Description
`switch_type`	Computed	The type of virtual switch: `"private"`, `"internal"` or `"external"`.
`notes`	Computed	Notes added to the virtual switch.
`allow_management_os`	Computed	The hyperv-server is allowed to participate into the communication on the virtual switch.
`net_adapter_name`	Computed	The name of the network adapter used for an "external" virtual switch.
`net_adapter_interface_description`	Computed	The description for the network adapter interface used for an "external" virtual switch.

extended lifecycle customizations for data-sources

The x_lifecycle block defines extensions to the terraform lifecycle customizations meta-data for data-sources (although at moment of writing this text, there are no such lifecycle customizations defined for data-sources). As opposed to the terraform meta-data, that can be added to all of the configured data-sources, the x_lifecycle block can only be added to the data-sources that implement this block.

data "hyperv_vswitch" "default" {
    name = "Default Switch"

    x_lifecycle {
        ignore_error_if_not_exists = true
    }
}

Arguments		Description
`x_lifecycle.ignore_error_if_not_exists`	Optional	Ignores the "cannot find" or "doesn't exist" errors from the API. This can be used to test if a data-source exists. For example, the "Default Switch" doesn't exist in older versions of Hyper-V, and does exist by default in newer versions of Hyper-V.

Exports		Description
`x_lifecycle.exists`	Computed	Set to `true` if the data-source exists.

Resources

resource "hyperv_vswitch"

resource "hyperv_vswitch" "private" {
    provider = hyperv.local

    name                = "Private Switch"
    switch_type         = "private"
    notes               = "private notes"
}

resource "hyperv_vswitch" "internal" {
    provider = hyperv.local

    name                = "Internal Switch"
    switch_type         = "internal"
    notes               = "internal notes"
}

resource "hyperv_vswitch" "external" {
    provider = hyperv.local

    name                = "External Switch"
    switch_type         = "external"
    notes               = "external notes"

    allow_management_os = true
    net_adapter_interface_description = "Intel(R) 82579LM Gigabit Network Connection"
}

Arguments		Description
`name`	Required	The name of the virtual switch.
`switch_type`	Required	The type of virtual switch: `"private"`, `"internal"` or `"external"`.
`notes`	Optional	Notes added to the virtual switch.
----------
`allow_management_os`	Optional	The hyperv-server is allowed to participate into the communication on the virtual switch. - must not be configured or set to `false` when `switch_type = "private"`. - must not be configured or set to `true` when `switch_type = "internal"` - defaults to `false` when `switch_type = "external"`
`net_adapter_name`	Optional	Use the existing network adapter with this name. - must not be configured when `switch_type = "private"` or `switch_type = "internal"` - must not be configured when `switch_type = "external"` and `net_adapter_interface_description` is configured - required when `switch_type = "external"` and `net_adapter_interface_description` is not configured
`net_adapter_interface_description`	Optional	Disable existing network adapter and create new network adapter for this interface. - must not be configured when `switch_type = "private"` or `switch_type = "internal"` - must not be configured when `switch_type = "external"` and `net_adapter_name` is configured - required when `switch_type = "external"` and `net_adapter_name` is not configured
----------
`x_lifecycle`	Optional	see x_lifecycle for resources

Exports		Description
`allow_management_os`	Computed	The hyperv-server is allowed to participate into the communication on the virtual switch.
`net_adapter_name`	Computed	The name of the network adapter used for an "external" virtual switch.
`net_adapter_interface_description`	Computed	The description for the network adapter interface used for an "external" virtual switch.

Importing a hyperv_vswitch using terraform import

You can import a virtual switch using the switch's name as an import ID.

Assuming a configuration
```
provider "hyperv" {}

resource "hyperv_vswitch" "default" {
    name        = "Default Switch"
    switch_type = "internal"
    notes       = "internal notes"
}
```
When terraform tries to create this then this will fail when the virtual switch already exists. You can delete the switch from the infrastructure, and then re-create it using terraform. However, this may be a bit more involved when you need to automate this. Alternatively you can import it.
Run the terraform import command using the name of the switch as import ID.
```
terraform import "hyperv_vswitch.default" "Default Switch"
```
The resource will be imported into the terraform state, and the usual lifecycle will be applied next time terraform apply is run.

extended lifecycle customizations for resources

The x_lifecycle block defines extensions to the terraform lifecycle customizations meta-data for resources. As opposed to the terraform meta-data, that can be added to all of the configured resources, the x_lifecycle block can only be added to the resources that implement this block.

resource "hyperv_vswitch" "default" {
    name        = "Default Switch"
    switch_type = "internal"

    x_lifecycle {
        import_if_exists = true
    }
}

Arguments		Description
`x_lifecycle.import_if_exists`	Optional	Imports the resource when it does exist, avoiding the "already exists" errors from the API. This can be used in cases where existence of a resource is unknown and would require "obscure" configuration to test and decide if the resource needs creating. For example, the "Default Switch" doesn't exist in older versions of Hyper-V, and does exist by default in newer versions of Hyper-V.
`x_lifecycle.destroy_if_imported`	Optional	Destroys the imported resource when using `terraform destroy`. By default, a resource that is imported using `import_if_exists = "true"` is not destroyed when using `terraform destroy`.

Exports		Description
`x_lifecycle.imported`	Computed	Set to `true` when the resource is imported using `import_if_exists = "true"`.

For Further Investigation

add more/all arguments in-line with the PowerShell Hyper-V API
add acceptance tests
add API tests
terraform-style documentation

stefaanc / terraform-provider-hyperv