Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] vSphere provider update docs #6661

Closed
wants to merge 3 commits into from
+129 −91
Closed

[WIP] vSphere provider update docs #6661

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8c22d51
providing link to vsphere dev docs
chrislovecnm May 13, 2016
75b3f4a
moving test info to dev docs
chrislovecnm May 13, 2016
e48c728
different updates to docs and created new section for user setup
chrislovecnm May 13, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .github/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -510,6 +510,12 @@ When executing the test, the following steps are taken for each `TestStep`:
`azurerm_resource_group` is tested independently in its own acceptance
tests.

### vSphere Provider Developer Documentation

This [document][vsphere] provides information specific to contributing and testing
the vSphere provider.

[website]: https://github.com/hashicorp/terraform/tree/master/website
[acctests]: https://github.com/hashicorp/terraform#acceptance-tests
[ml]: https://groups.google.com/group/terraform-tool
[vsphere]: https://github.com/hashicorp/terraform/blob/master/builtin/providers/vsphere/README.md
65 changes: 60 additions & 5 deletions builtin/providers/vsphere/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,15 @@ Thank-you [@tkak](https://github.com/tkak) and [Rakuten, Inc.](https://github.co

Both [README.md](../../../README.md) and [BUILDING.md](../../../BUILDING.md) should be read first!

## Base API Dependency ~ [govmomi](https://github.com/vmware/govmomi)
## 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
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
Expand All @@ -30,13 +30,13 @@ Click on "+" icon (Create role action), give it appropraite name and select foll
- Remove file
- Update virtual machine files
- Update virtual machine metadata

* Folder (all)
- Create folder
- Delete folder
- Move folder
- Rename folder

* Network
- Assign network

Expand All @@ -54,4 +54,59 @@ Click on "+" icon (Create role action), give it appropraite name and select foll
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.


# Acceptance Tests

The VMware vSphere provider's acceptance tests require the above provider
configuration fields to be set using the documented environment variables.

## Environment Variables
Copy link
Contributor

@thetuxkeeper thetuxkeeper May 13, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VSPHERE_USER and VSPHERE_PASSWORD are missing
Sorry, missed the reference to "the above provider configuration fields".

Copy link
Contributor

@thetuxkeeper thetuxkeeper May 13, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But perhaps this could be more clear instead "above". A link or something like "[...] require the provider configuration fields mentioned in the user documentation to be set [...]"
Perhaps a little shorter, but something in that direction since there is quite much "above" (privileges, govmomi).


In addition, the following environment variables are used in tests, and must be
set to valid values for your VMware vSphere environment:

* VSPHERE\_IPV4\_GATEWAY
* VSPHERE\_IPV4\_ADDRESS
* VSPHERE\_IPV6\_GATEWAY
* VSPHERE\_IPV6\_ADDRESS
* VSPHERE\_NETWORK\_LABEL
* VSPHERE\_NETWORK\_LABEL\_DHCP
* VSPHERE\_TEMPLATE

The following environment variables depend on your vSphere environment:

* VSPHERE\_DATACENTER
* VSPHERE\_CLUSTER
* VSPHERE\_RESOURCE\_POOL
* VSPHERE\_DATASTORE

The following additional environment variables are needed for running the
"Mount ISO as CDROM media" acceptance tests.

* VSPHERE\_CDROM\_DATASTORE
* VSPHERE\_CDROM\_PATH

The following environment variable is needed from running the "Create With Existing VMDK"
acceptance tests

* VSPHERE\_VMDK\_PATH

Refer to the TF documentation in regards to logging but at the current time

* TF\_LOG=DEBUG

As always refer to the acceptance test source code for the latest variables.

## Running tests

Once all these variables are in place, the tests can be run like this:

```
make testacc TEST=./builtin/providers/vsphere
```

In order to run a single test `TESTARGS` Envrionment variable can be set:

```
export TESTARGS="-run TestAccVSphereVirtualMachine_ipv4Andipv6"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I use make testacc TEST=./builtin/providers/vsphere TESTARGS='-run=TestAccVSphereVirtualMachine_ipv4Andipv6'. I think it is more flexible, since you can keep a few versions in shell history

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 for having this as a make variable rather than an environment variable.

```
102 changes: 16 additions & 86 deletions website/source/docs/providers/vsphere/index.html.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,10 @@ The provider needs to be configured with the proper credentials before it can be

Use the navigation to the left to read about the available resources.

~> **NOTE:** The VMware vSphere Provider currently represents _initial support_
and therefore may undergo significant changes as the community improves it. This
provider at this time only supports IPv4 addresses on virtual machines.
~> **NOTE:** The VMware vSphere Provider currently represents _alpha support_
and therefore may undergo changes as the community improves it. As always we strive
to not introduce breaking changes. This provider is maintained by the community,
and therefore all contributions are welcome!

## Example Usage

Expand Down Expand Up @@ -76,54 +77,20 @@ The following arguments are used to configure the VMware vSphere Provider:
value is `false`. Can also be specified with the `VSPHERE_ALLOW_UNVERIFIED_SSL`
environment variable.

## Required Privileges

In order to use Terraform provider as non priviledged user, a Role within
vCenter must be assigned the 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.

## Virtual Machine Customization

### VMware Tools

This module utilizes VMware [tools][vtools] for multiple different vm level operations. Open VM Tools for
Linux is recommended and VMware supported Windows VMware tools is recommended.

### Guest Customizations

Guest Operating Systems can be configured using
[customizations](https://pubs.vmware.com/vsphere-50/index.jsp#com.vmware.vsphere.vm_admin.doc_50/GUID-80F3F5B5-F795-45F1-B0FA-3709978113D5.html),
in order to set things properties such as domain and hostname. This mechanism
[customizations][custom], in order to set things properties such as domain and hostname. This mechanism
is not compatible with all operating systems, however. A list of compatible
operating systems can be found
[here](http://partnerweb.vmware.com/programs/guestOS/guest-os-customization-matrix.pdf)
operating systems can be found [here][matrix].

If customization is attempted on an operating system which is not supported, Terraform will
create the virtual machine, but fail with the following error message:
Expand All @@ -138,43 +105,6 @@ versions. Refer to vCenter documentation for supported configurations. ```
In order to skip the customization step for unsupported operating systems, use
the `skip_customization` argument on the virtual machine resource.

## Acceptance Tests

The VMware vSphere provider's acceptance tests require the above provider
configuration fields to be set using the documented environment variables.

In addition, the following environment variables are used in tests, and must be
set to valid values for your VMware vSphere environment:

* VSPHERE\_IPV4\_GATEWAY
* VSPHERE\_IPV4\_ADDRESS
* VSPHERE\_IPV6\_GATEWAY
* VSPHERE\_IPV6\_ADDRESS
* VSPHERE\_NETWORK\_LABEL
* VSPHERE\_NETWORK\_LABEL\_DHCP
* VSPHERE\_TEMPLATE

The following environment variables depend on your vSphere environment:

* VSPHERE\_DATACENTER
* VSPHERE\_CLUSTER
* VSPHERE\_RESOURCE\_POOL
* VSPHERE\_DATASTORE

The following additional environment variables are needed for running the
"Mount ISO as CDROM media" acceptance tests.

* VSPHERE\_CDROM\_DATASTORE
* VSPHERE\_CDROM\_PATH


These are used to set and verify attributes on the `vsphere_virtual_machine`
resource in tests.

Once all these variables are in place, the tests can be run like this:

```
make testacc TEST=./builtin/providers/vsphere
```


[vtools]:https://kb.vmware.com/selfservice/search.do?cmd=displayKC&docType=kc&docTypeID=DT_KB_1_1&externalId=2004754
[custom]:https://pubs.vmware.com/vsphere-50/index.jsp#com.vmware.vsphere.vm_admin.doc_50/GUID-80F3F5B5-F795-45F1-B0FA-3709978113D5.html
[matrix]:http://partnerweb.vmware.com/programs/guestOS/guest-os-customization-matrix.pdf
47 changes: 47 additions & 0 deletions website/source/docs/providers/vsphere/r/user_security_setup.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
layout: "vsphere"
page_title: "VMware vSphere: vsphere_user_security_setup"
sidebar_current: "docs-vsphere-resource-user-security-setup"
description: |-
Setup up a vSphere user to use the vSphere Terraform provider.
-----------------------------------------------------------------------------------------------------------------------------------------------------

## 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 administrative user, we can define a new Role within a vCenter and assign it appropriate privileges.

In the vCenter UI navigate to the following:

Navigate to Administration -> Access Control -> Roles

Click on "+" icon (Create role action), give it appropriate 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.