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

1. 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

2. 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

1. Download the provider to your machine

   • go to the releases tab on github
   • download the file that is appropriate for your machine

2. 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
}

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"
}

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
    }
}

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"
}

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
    }
}

For Further Investigation

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