Skip to content

kube-cloud/terraform-provider-esxi

BranchesTags
 
 

Repository files navigation

Terraform Provider

Requirements

  • Terraform 0.10.1+
  • Go 1.11+ (to build the provider plugin)
  • ovftool from VMware. NOTE: ovftool installer for windows doesn't put ovftool.exe in your path. You will need to manually set your path.
  • You MUST enable ssh access on your ESXi hypervisor.
  • Google 'How to enable ssh access on esxi'
  • In general, you should know how to use terraform, esxi and some networking...
  • You will most likely need a DHCP server on your primary network if you are deploying VMs with public OVF/OVA/VMX images. (Sources that have unconfigured primary interfaces.)
  • The source OVF/OVA/VMX images must have open-vm-tools or vmware-tools installed to properly import an IPaddress. (you need this to run provisioners)

Building The Provider

In general, you don't normally need to build the provider. A release can be downloaded from github, or can automatically be downloaded with terraform 0.13.

You first must set your GOPATH. If you are unsure, please review the documentation at.

https://github.com/golang/go/wiki/SettingGOPATH

Clone repository to: $GOPATH/src/github.com/terraform-providers/terraform-provider-esxi

mkdir $HOME/go
export GOPATH="$HOME/go"

go get -u -v golang.org/x/crypto/ssh
go get -u -v github.com/hashicorp/terraform
go get -u -v github.com/kube-cloud/terraform-provider-esxi

cd $GOPATH/src/github.com/kube-cloud/terraform-provider-esxi
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -ldflags '-w -extldflags "-static"' -o terraform-provider-esxi_`cat version`

sudo cp terraform-provider-esxi_`cat version` /usr/local/bin

Terraform-provider-esxi plugin

  • This is a Terraform plugin that adds a VMware ESXi provider support. This allows Terraform to control and provision VMs directly on an ESXi hypervisor without a need for vCenter or VShpere. ESXi hypervisor is a free download from VMware!

https://www.vmware.com/go/get-free-esxi

  • If you don't know terraform, I highly recommend you read through the introduction on the hashicorp website.

https://www.terraform.io/intro/getting-started/install.html

  • VMware Configuration Maximums tool.

https://configmax.vmware.com/guest

What's New:

  • v1.8.0 added vswitch and portgroup resources.
  • v1.7.1 added Terraform 0.13 support. This provider is now in the terraform registry.

https://registry.terraform.io/providers/josenk/esxi

Features and Compatibility

  • Source image can be a clone of a VM or local vmx, ovf, ova file. This provider uses ovftool, so there should be a wide compatibility.
  • Supports adding your VM to Resource Pools to partition CPU and memory usage from other VMs on your ESXi host.
  • Terraform will Create, Destroy, Update & Import Resource Pools.
  • Terraform will Create, Destroy, Update & Import Guest VMs.
  • Terraform will Create, Destroy, Update & Import Extra Storage for Guests.
  • Terraform will Create, Destroy, Update & Import vSwitches.
  • Terraform will Create, Destroy, Update & Import Port Groups.

This is a provider! NOT a provisioner.

Vagrant vs Terraform.

If you are using vagrant as a deployment tool (infa as code), you may want to consider a better tool. Terraform. Vagrant is better for development environments, while Terraform is better at managing infrastructure. Please give my terraform plugin a try and give me some feedback. What you're trying to do, what's missing, what works, what doesn't work, etc...

https://www.vagrantup.com/intro/vs/terraform.html https://github.com/kube-cloud/terraform-provider-esxi https://github.com/kube-cloud/vagrant-vmware-esxi

Why this plugin?

Not everyone has vCenter, vSphere, expensive APIs... These cost $$$. ESXi is free!

How to install

  • Install terraform
  • Automatic install
    • Add the required_providers block to your terraform project.
terraform {
  required_version = ">= 0.13"
  required_providers {
    esxi = {
      source = "registry.terraform.io/jetune/esxi"
      #
      # For more information, see the provider source documentation:
      # https://github.com/kube-cloud/terraform-provider-esxi
      # https://registry.terraform.io/providers/josenk/esxi
    }
  }
}

How to use and configure a main.tf file

  1. cd SOMEDIR
  2. vi main.tf # Use the contents of this example main.tf as a template. Specify provider parameters to access your ESXi host. Modify the resources for resource pools and guest vm.
terraform {
  required_version = ">= 0.12"
}

provider "esxi" {
  esxi_hostname      = "esxi"
  esxi_hostport      = "22"
  esxi_hostssl       = "443"
  esxi_username      = "root"
  esxi_password      = "MyPassword"
}

resource "esxi_guest" "vmtest" {
  guest_name         = "vmtest"
  disk_store         = "MyDiskStore"

  #
  #  Specify an existing guest to clone, an ovf source, or neither to build a bare-metal guest vm.
  #
  #clone_from_vm      = "Templates/centos7"
  #ovf_source        = "/local_path/centos-7.vmx"

  network_interfaces {
    virtual_network = "VM Network"
  }
}

Basic usage

  1. terraform init
  2. terraform plan
  3. terraform apply
  4. terraform show
  5. terraform destroy

Configuration reference

  • provider "esxi"

    • esxi_hostname - Required
    • esxi_hostport - Optional - Default "22".
    • esxi_hostssl - Optional - Default "443".
    • esxi_username - Optional - Default "root".
    • esxi_password - Required

  • resource "esxi_resource_pool"

    • resource_pool_name - Required - The Resource Pool name.
    • cpu_min - Optional
    • cpu_min_expandable - Optional
    • cpu_max - Optional
    • cpu_shares - Optional
    • mem_min - Optional
    • mem_min_expandable - Optional
    • mem_max - Optional
    • mem_shares - Optional

  • resource "esxi_virtual_disk"

    • virtual_disk_disk_store - Required - esxi Disk Store where virtual disk will be created.
    • virtual_disk_dir - Required - A subdirectory to contain the virtual disk. (Can be the same as guest_name)
    • virtual_disk_name - Optional - Virtual Disk Name. (ext must be .vmdk)
    • virtual_disk_size - Optional - Virtual Disk size in GB. Default 1GB.
    • virtual_disk_type - Optional - Virtual Disk type. (thin, zeroedthick or eagerzeroedthick) Default 'thin'.

  • resource "esxi_guest"

    • guest_name - Required - The Guest name.
    • ip_address - Computed - The IP address reported by VMware tools.
    • boot_disk_type - Optional - Guest boot disk type. Default 'thin'. Available thin, zeroedthick, eagerzeroedthick.
    • boot_disk_size - Optional - Specify boot disk size or grow cloned vm to this size.
    • guestos - Optional - Default will be taken from cloned source.
    • clone_from_vm - Source vm to clone. Mutually exclusive with ovf_source option.
    • ovf_source - ovf files or URLs to use as a source. Mutually exclusive with clone_from_vm option.
    • disk_store - Required - esxi Disk Store where guest vm will be created.
    • resource_pool_name - Optional - Any existing or terraform managed resource pool name. - Default "/".
    • memsize - Optional - Memory size in MB. (ie, 1024 == 1GB). See esxi documentation for limits. - Default 512 or default taken from cloned source.
    • numvcpus - Optional - Number of virtual cpus. See esxi documentation for limits. - Default 1 or default taken from cloned source.
    • virthwver - Optional - esxi guest virtual HW version. See esxi documentation for compatible values. - Default 8 or taken from cloned source.
    • network_interfaces - Array of up to 10 network interfaces.
      • virtual_network - Required for each Guest NIC - This is the esxi virtual network name configured on esxi host.
      • mac_address - Optional - If not set, mac_address will be generated by esxi.
      • nic_type - Optional - See esxi documentation for compatibility list. - Default "e1000" or taken from cloned source.
    • virtual_disks - Optional - Array of additional storage to be added to the guest.
      • virtual_disk_id - Required - virtual_disk.id from esxi_virtual_disk resource.
      • slot - Required - SCSI_Ctrl:SCSI_id. Range '0:1' to '3:15'. SCSI_id 7 is not allowed.
    • power - Optional - on, off.
    • guest_startup_timeout - Optional - The amount of guest uptime, in seconds, to wait for an available IP address on this virtual machine. Default 120s.
    • guest_shutdown_timeout - Optional - The amount of time, in seconds, to wait for a graceful shutdown before doing a forced power off. Default 20s.
    • notes - Optional - The Guest notes (annotation).
    • guestinfo - Optional - The Guestinfo root
      • metadata - Optional - A JSON string containing the cloud-init metadata.
      • metadata.encoding - Optional - The encoding type for guestinfo.metadata. (base64 or gzip+base64)
      • userdata - Optional - A YAML document containing the cloud-init user data.
      • userdata.encoding - Optional - The encoding type for guestinfo.userdata. (base64 or gzip+base64)
      • vendordata - Optional - A YAML document containing the cloud-init vendor data.
      • vendordata.encoding - Optional - The encoding type for guestinfo.vendordata (base64 or gzip+base64)
    • ovf_properties - Optional - List of ovf properties to override in ovf/ova sources.
      • key - Required - Key of the property
      • value - Required - Value of the property
    • ovf_properties_timer - Optional - Length of time to wait for ovf_properties to process. Default 90s.

  • resource "esxi_vswitch"

    • name - Required - The vswitch name.
    • ports - Optional - The number of ports available on the vswitch. Default 128.
    • mtu - Optional - The mtu. Default 1500
    • promiscuous_mode - Optional - Enable Promiscuous Mode (true/false) - Default false
    • mac_changes - Optional - Enable MAC Changes (true/false) - Default false.
    • forged_transmits - Optional - Enable Forged Transmits (true/false) - Default false.
    • uplink - Optional - Array of up to 32 uplinks.
      • name - Required - The uplink name. (for example vnic2)

  • resource "esxi_portgroup"

    • name - Required - The portgroup name.
    • vswitch - Required - The vswitch to connect to.
    • vlan - Optional - The vlan id of the portgroup - Default 0.

Using ovf_source & clone_from_vm

  • clone_from_vm clones from sources on the esxi host.
    • The source VM must be powered off.
    • If the source VM is stored in a resource group, you must specify the path, for example.
      • clone_from_vm = "my_resource_group/my_source_vm"
  • ovf_source clones from sources on your local hard disk or a URL.
  • If neither is specified, then a bare-metal VM will be created. There will be no OS on this vm. If the VM is powered on, it will default to a network PXE boot.
  • ovf_source & clone_from_vm are mutually exclusive.

Known issues with vmware_esxi

  • Using a local source vmx files should not have any networks configured. There is very limited network interface mapping abilities in ovf_tools for vmx files. It's best to simply clean out all network information from your vmx file. The plugin will add network configuration to the destination vm guest as required.
  • terraform import cannot import the guest disk type (thick, thin, etc) if the VM is powered on and cannot import the guest ip_address if it's powered off.
  • Only numvcpus are supported. numcores is not supported.
  • Doesn't support CDrom or floppy.
  • Doesn't support Shared bus Interfaces, or Shared disks
  • Using an incorrect password could lockout your account using default esxi pam settings.
  • Don't set guest_startup_timeout or guest_shutdown_timeout to 0 (zero). It's valid, however it will be changed to default values by terraform.

Version History

  • 1.8.1 Fix, multimachine create on Windows.
  • 1.8.0 Add support for vswitch and portgroup resources.
  • 1.7.2 Correctly set numvcpu when using clone_from_vm that doesn't have a numvcpu key set.
  • 1.7.1 Bump release to include support for Terraform 0.13
  • 1.7.0 Add support for esxi_hostssl (Setting the ssl port for ovftool).
  • 1.6.4 Fix default IP dection. Fix Disk Stores containing spaces.
  • 1.6.3 Mask username/password in debug logs. Set default, disk.EnableUUID = true.
  • 1.6.2 Fix Defaults for guest_startup_timeout and guest_shutdown_timeout. Fix IP address detection type2 to always run regardless of guest_startup_timeout value.
  • 1.6.1 Fix some minor refresh bugs, allow http(s) ovf sources.
  • 1.6.0 Add support for ovf_properties for OVF/OVA sources.
  • 1.5.4 Fix bare-metal build when using additional virtual disks.
  • 1.5.3 Fix introduced bug when creating a bare-metal guest.
  • 1.5.2 Handle large userdata using scp. Connectivity test will retry only 3 times to help prevent account lockout.
  • 1.5.1 Windows Fix for special characters in esxi password.
  • 1.5.0 Support for Terraform 0.12, migrated examples to 0.12 format. Support to modify virtual_network & nic_type. Windows fixes.
  • 1.4.3 Fix virtdisk count. Fixes to support Terraform 0.12
  • 1.4.2 Support 10 nics, more README changes
  • 1.4.1 Fix README build instructions, static binaries, update guest types
  • 1.4.0 Add GuestInfo (Cloud-init, Ignition!). Fix, allow esxi passwords with special characters.
  • 1.3.0 Add support to Update storage attachments.
  • 1.2.2 fix guest_update power, boot_disk_type defaults, README, windows support
  • 1.2.1 Fix ssh connection retries.
  • 1.2.0 Add support for notes (annotation)
  • 1.1.1 Fix, unable to provision ova sources. go fmt.
  • 1.1.0 Add Import support.
  • 1.0.2 Switch authentication method to Keyboard Interactive. Read disk_type (thin, thick, etc)
  • 1.0.1 Validate DiskStores and refresh
  • 1.0.0 First Major release
  • 0.1.2 Add ability to manage existing Guest VMs. A lot of code cleanup, various fixes, more validation.
  • 0.1.0 Add virtual_disk resource.
  • 0.0.8 Add virthwver.
  • 0.0.7 build vmx from scratch if no source is specified
  • 0.0.6 Add power resource.
  • 0.0.5 Add network_interfaces resource.
  • 0.0.4 Add more stuff.
  • 0.0.3 Add memory and numvcpus resource. Add support to update some guests params.
  • 0.0.2 Add Resource Pool resource.
  • 0.0.1 Init release

About

Terraform-provider-esxi plugin

Resources

Readme

License

GPL-3.0 license
Activity
Custom properties

Stars

2 stars

Watchers

1 watching

Forks

2 forks
Report repository

Releases 5

v1.9.5 Latest
Dec 31, 2020
+ 4 releases

Packages

No packages published

Languages

  • Go 70.6%
  • HCL 26.6%
  • Smarty 2.7%
  • Makefile 0.1%