diff --git a/GNUmakefile b/GNUmakefile index c9eacb451..c7d1b15a1 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -1,3 +1,5 @@ +-include $(HOME)/.tf-vsphere-devrc.mk + TEST?=$$(go list ./... |grep -v 'vendor') GOFMT_FILES?=$$(find . -name '*.go' |grep -v vendor) diff --git a/README.md b/README.md index 0237928f1..9ede94c0a 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,156 @@ -Terraform Provider -================== +# Terraform vSphere Provider -- Website: https://www.terraform.io -- [![Gitter chat](https://badges.gitter.im/hashicorp-terraform/Lobby.png)](https://gitter.im/hashicorp-terraform/Lobby) -- Mailing list: [Google Groups](http://groups.google.com/group/terraform-tool) +This is the repository for the Terraform vSphere Provider, which one can use +with Terraform to work with VMware vSphere Products, notably [vCenter Server][1] +and [ESXi][2]. - +[1]: https://www.vmware.com/products/vcenter-server.html +[2]: https://www.vmware.com/products/esxi-and-esx.html -Requirements ------------- +Coverage is currently only limited to a few resources namely surrounding virtual +machines, but in the coming months we are planning release coverage for most +essential vSphere workflows, including working with storage and networking +components such as datastores, and standard and distributed vSwitches. Watch +this space! -- [Terraform](https://www.terraform.io/downloads.html) 0.10.x -- [Go](https://golang.org/doc/install) 1.8 (to build the provider plugin) +For general information about Terraform, visit the [official website][3] and the +[GitHub project page][4]. -Building The Provider ---------------------- +[3]: https://terraform.io/ +[4]: https://github.com/hashicorp/terraform -Clone repository to: `$GOPATH/src/github.com/terraform-providers/terraform-provider-vsphere` +# Using the Provider -```sh -$ mkdir -p $GOPATH/src/github.com/terraform-providers; cd $GOPATH/src/github.com/terraform-providers -$ git clone git@github.com:terraform-providers/terraform-provider-vsphere -``` +The current version of this provider requires Terraform v0.10.0 or higher to +run. -Enter the provider directory and build the provider +Note that you need to run `terraform init` to fetch the provider before +deploying. Read about the provider split and other changes to TF v0.10.0 in the +official release announcement found [here][4]. -```sh -$ cd $GOPATH/src/github.com/terraform-providers/terraform-provider-vsphere -$ make build +[4]: https://www.hashicorp.com/blog/hashicorp-terraform-0-10/ + +## Full Provider Documentation + +The provider is documented in full on the Terraform website and can be found +[here][5]. Check the provider documentation for details on entering your +connection information and how to get started with writing configuration for +vSphere resources. + +[5]: https://www.terraform.io/docs/providers/vsphere/index.html + +### Controlling the provider version + +Note that you can also control the provider version. This requires the use of a +`provider` block in your Terraform configuration if you have not added one +already. + +The syntax is as follows: + +```hcl +provider "vsphere" { + version = "~> 0.1" + ... +} ``` -Using the provider ----------------------- -## Fill in for each provider +Version locking uses a pessimistic operator, so this version lock would mean +anything within the 0.1.x namespace. [Read more][6] on provider version control. + +[6]: https://www.terraform.io/docs/configuration/providers.html#provider-versions + +# Building The Provider + +**NOTE:** Unless you are [developing][7] or require a pre-release bugfix or feature, +you will want to use the officially released version of the provider (see [the +section above][8]). -Developing the Provider ---------------------------- +[7]: #developing-the-provider +[8]: #using-the-provider -If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (version 1.8+ is *required*). You'll also need to correctly setup a [GOPATH](http://golang.org/doc/code.html#GOPATH), as well as adding `$GOPATH/bin` to your `$PATH`. -To compile the provider, run `make build`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory. +## Cloning the Project + +First, you will want to clone the repository to +`$GOPATH/src/github.com/terraform-providers/terraform-provider-vsphere`: ```sh -$ make build -... -$ $GOPATH/bin/terraform-provider-vsphere -... +mkdir -p $GOPATH/src/github.com/terraform-providers +cd $GOPATH/src/github.com/terraform-providers +git clone git@github.com:terraform-providers/terraform-provider-vsphere ``` -In order to test the provider, you can simply run `make test`. +## Running the Build + +After the clone has been completed, you can enter the provider directory and +build the provider. ```sh -$ make test +cd $GOPATH/src/github.com/terraform-providers/terraform-provider-vsphere +make build ``` -In order to run the full suite of Acceptance tests, run `make testacc`. +## Installing the Local Plugin + +After the build is complete, copy the `terraform-provider-vsphere` binary into +the same path as your `terraform` binary, and re-run `terraform init`. + +After this, your project-local `.terraform/plugins/ARCH/lock.json` (where `ARCH` +matches the architecture of your machine) file should contain a SHA256 sum that +matches the local plugin. Run `shasum -a 256` on the binary to verify the values +match. -*Note:* Acceptance tests create real resources, and often cost money to run. +# Developing the Provider + +If you wish to work on the provider, you'll first need [Go][9] installed on your +machine (version 1.8+ is **required**). You'll also need to correctly setup a +[GOPATH][10], as well as adding `$GOPATH/bin` to your `$PATH`. + +[9]: https://golang.org/ +[10]: http://golang.org/doc/code.html#GOPATH + +See [Building the Provider][11] for details on building the provider. + +[11]: #building-the-provider + +# Testing the Provider + +**NOTE:** Testing the vSphere provider is currently a complex operation as it +requires having a vCenter endpoint to test against, which should be hosting a +standard configuration for a vSphere cluster. Some of the tests will work +against ESXi, but YMMV. + +## Configuring Environment Variables + +Most of the tests in this provider require a comprehensive list of environment +variables to run. See the individual `*_test.go` files in the +[`vsphere/`](vsphere/) directory for more details. The next section also +describes how you can manage a configuration file of the test environment +variables. + +### Using the `.tf-vsphere-devrc.mk` file + +The [`tf-vsphere-devrc.mk.example`](tf-vsphere-devrc.mk.example) file contains +an up-to-date list of environment variables required to run the acceptance +tests. Copy this to `$HOME/.tf-vsphere-devrc.mk` and change the permissions to +something more secure (ie: `chmod 600 $HOME/.tf-vsphere-devrc.mk`), and +configure the variables accordingly. + +## Running the Acceptance Tests + +After this is done, you can run the acceptance tests by running: ```sh $ make testacc ``` + +If you want to run against a specific set of tests, run `make testacc` with the +`TESTARGS` parameter containing the run mask as per below: + +```sh +make testacc TESTARGS="-run=TestAccVSphereVirtualMachine" +``` + +This following example would run all of the acceptance tests matching +`TestAccVSphereVirtualMachine`. Change this for the specific tests you want to +run. diff --git a/tf-vsphere-devrc.mk.example b/tf-vsphere-devrc.mk.example new file mode 100644 index 000000000..4d1e25a5e --- /dev/null +++ b/tf-vsphere-devrc.mk.example @@ -0,0 +1,31 @@ +# This file is designed to assist you with configuring your environment for +# testing the vSphere provider, and also serves as a catalog of the environment +# variables that are required to test all of the resources in this provider. +# +# This should be copied to ~/.tf-vsphere-devrc.mk and edited accordingly. +# +# Note that the use of all of this file is not required - enviornment variables +# can still be completely set from the command line or your existing +# environment. In this case, don't use this file as it may cause conflicts. +# +# The essentials. None of the tests will run if you don't have these. +export VSPHERE_SERVER ?= vcenter.internal +export VSPHERE_USER ?= user@vsphere.internal +export VSPHERE_PASSWORD ?= changeme + +# Enable this if you want to skip SSL verification +export VSPHERE_ALLOW_UNVERIFIED_SSL ?= false + +# vsphere_virtaul_machine variables +export VSPHERE_TEMPLATE ?= base-linux +export VSPHERE_NETWORK_LABEL ?= vm-network +export VSPHERE_NETWORK_LABEL_DHCP ?= vm-network +export VSPHERE_IPV4_ADDRESS ?= 10.0.0.100 +export VSPHERE_IPV4_PREFIX ?= 24 +export VSPHERE_IPV4_GATEWAY ?= 10.0.0.1 +export VSPHERE_DATACENTER ?= vm-dc +export VSPHERE_CLUSTER ?= vm-cluster1 +export VSPHERE_RESOURCE_POOL ?= vm-resource-pool +export VSPHERE_DATASTORE ?= datastore1 + +# vi: filetype=make diff --git a/vsphere/README.md b/vsphere/README.md deleted file mode 100644 index 0da819f8d..000000000 --- a/vsphere/README.md +++ /dev/null @@ -1,57 +0,0 @@ -# Terraform vSphere Provider Dev Docs - -This document is in place for developer documentation. User documentation is located [HERE](https://www.terraform.io/docs/providers/vsphere/) on Terraform's website. - -Thank-you [@tkak](https://github.com/tkak) and [Rakuten, Inc.](https://github.com/rakutentech) for their original contribution of the source base used for this provider! - -## Introductory Documentation - -Both [README.md](../../../README.md) and [BUILDING.md](../../../BUILDING.md) should be read first! - -## Base API Dependency ~ [govmomi](https://github.com/vmware/govmomi) - -This provider utilizes [govmomi](https://github.com/vmware/govmomi) Go Library for communicating to VMware vSphere APIs (ESXi and/or vCenter). -Because of the dependency this provider is compatible with VMware systems that are supported by govmomi. Much thanks to the dev team that maintains govmomi, and -even more thanks to their guidance with the development of this provider. We have had many issues answered by the govmomi team! - -#### vSphere CLI ~ [govc](https://github.com/vmware/govmomi/blob/master/govc/README.md) - -One of the great tools that govmomi contains is [govc](https://github.com/vmware/govmomi/blob/master/govc/README.md). It is a command line tool for using the govmomi API. Not only is it a tool to use, but also it's -[source base](https://github.com/vmware/govmomi/blob/master/govc/) is a great resource of examples on how to exercise the API. - -## Required privileges for running Terraform as non-administrative user -Most of the organizations are concerned about administrative privileges. In order to use Terraform provider as non priviledged user, we can define a new Role within a vCenter and assign it appropriate privileges: -Navigate to Administration -> Access Control -> Roles -Click on "+" icon (Create role action), give it appropraite name and select following privileges: - * Datastore - - Allocate space - - Browse datastore - - Low level file operations - - Remove file - - Update virtual machine files - - Update virtual machine metadata - - * Folder (all) - - Create folder - - Delete folder - - Move folder - - Rename folder - - * Network - - Assign network - - * Resource - - Apply recommendation - - Assign virtual machine to resource pool - - * Virtual Machine - - Configuration (all) - for now - - Guest Operations (all) - for now - - Interaction (all) - - Inventory (all) - - Provisioning (all) - -These settings were tested with [vSphere 6.0](https://pubs.vmware.com/vsphere-60/index.jsp?topic=%2Fcom.vmware.vsphere.security.doc%2FGUID-18071E9A-EED1-4968-8D51-E0B4F526FDA3.html) and [vSphere 5.5](https://pubs.vmware.com/vsphere-55/index.jsp?topic=%2Fcom.vmware.vsphere.security.doc%2FGUID-18071E9A-EED1-4968-8D51-E0B4F526FDA3.html). For additional information on roles and permissions, please refer to official VMware documentation. - -This section is a work in progress and additional contributions are more than welcome. -