From e6ac2ff9c7871f4fb2ea2156996e8f7fda86fa50 Mon Sep 17 00:00:00 2001 From: Ryan Johnson Date: Mon, 14 Oct 2024 10:27:22 -0400 Subject: [PATCH] docs: add install, build, and test docs Adds seperate documenation for the installation, buiild, and testing of the provider linked from the an updated `README.md`. Signed-off-by: Ryan Johnson --- README.md | 213 +++++++++------------------- docs/build.md | 51 +++++++ docs/images/icon-color.svg | 23 ++++ docs/install.md | 275 +++++++++++++++++++++++++++++++++++++ docs/test.md | 53 +++++++ 5 files changed, 467 insertions(+), 148 deletions(-) create mode 100644 docs/build.md create mode 100644 docs/images/icon-color.svg create mode 100644 docs/install.md create mode 100644 docs/test.md diff --git a/README.md b/README.md index faab08ae2..c5540af10 100644 --- a/README.md +++ b/README.md @@ -1,187 +1,104 @@ -# Terraform NSX-T Provider + -This is the repository for the Terraform NSX Provider, which one can use with -Terraform to work with [VMware NSX-T][vmware-nsxt]. + -[vmware-nsxt]: https://www.vmware.com/products/nsx.html +VMware NSX -For general information about Terraform, visit the [official -website][tf-website] and the [GitHub project page][tf-github]. +# Terraform Provider for VMware NSX -[tf-website]: https://terraform.io/ -[tf-github]: https://github.com/hashicorp/terraform +[![Latest Release](https://img.shields.io/github/v/tag/vmware/terraform-provider-nsxt?label=latest%20release&style=for-the-badge)](https://github.com/vmware/terraform-provider-nsxt/releases/latest) [![License](https://img.shields.io/github/license/vmware/terraform-provider-nsxt.svg?style=for-the-badge)](LICENSE) -Documentation on the NSX platform can be found at the [NSX-T Documentation page](https://docs.vmware.com/en/VMware-NSX-T/index.html) +The Terraform Provider for [VMware NSX][product-documentation] is a plugin for Terraform that allows you to interact with VMware NSX. -# Using the Provider +Learn more: -The latest version of this provider requires Terraform v0.12 or higher to run. +* Read the provider [documentation][provider-documentation]. -The VMware supported version of the provider requires NSX version 3.0.0 onwards and Terraform 0.12 onwards. -Version 2.0.0 of the provider offers NSX consumption via policy APIs, which is the recommended way. -Most policy resources are supported with NSX version 3.0.0 onwards, however some resources or attributes require later releases. Please refer to documentation for more details. -The recommended vSphere provider to be used in conjunction with the NSX-T Terraform Provider is 1.3.3 or above. +* Join the community [discussions][provider-discussions]. -Note that you need to run `terraform init` to fetch the provider before -deploying. +## Requirements -## Full Provider Documentation +* [VMware NSX][product-documentation] -The provider is documented in full on the Terraform website and can be found -[here](https://registry.terraform.io/providers/vmware/nsxt/latest). Check the provider documentation for details on entering your connection information and how to get started with writing configuration for vSphere resources. + The following table lists the supported product versions for this provider. -### Controlling the provider version + * VMware NSX 4.2.x + * VMware NSX 4.1.x + * VMware NSX 4.0.x + * VMware NSX-T Data Center 3.2.x + * VMware NSX-T Data Center 3.1.x + * VMware NSX-T Data Center 3.1.x + * VMware NSX-T Data Center 2.5.x [^1] -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. + [^1]: Support for VMware NSX-T Data Center 2.5.x is limited with v3.2.x and later. -The syntax is as follows: + The plugin supports versions in accordance with the [Broadcom Product Lifecycle][product-lifecycle]. -```hcl -provider "nsxt" { - version = "~> 3.2" - ... -} -``` - -Version locking uses a pessimistic operator, so this version lock would mean -anything within the 3.x namespace, including or after 3.0.0. [Read more][provider-vc] on provider version control. - -[provider-vc]: https://www.terraform.io/docs/configuration/providers.html#provider-versions - -# Automated Installation (Recommended) - -Download and initialization of Terraform providers is with the “terraform init” command. This applies to the NSX-T provider as well. Once the provider block for the NSX-T provider is specified in your .tf file, “terraform init” will detect a need for the provider and download it to your environment. -You can list versions of providers installed in your environment by running “terraform version” command: - -```hcl -$ ./terraform version -Terraform v1.2.1 -on linux_amd64 -+ provider registry.terraform.io/vmware/nsxt v3.3 -``` - -# Manual Installation - -**NOTE:** Unless you are [developing](#developing-the-provider) or require a -pre-release bugfix or feature, you will want to use the officially released -version of the provider (see [the section above](#using-the-provider)). - -**NOTE:** Recommended way to compile the provider is using [Go Modules](https://blog.golang.org/using-go-modules). - -**NOTE:** For terraform 0.13, please refer to [provider installation configuration][install-013] in order to use custom provider. - -[install-013]: https://www.terraform.io/docs/commands/cli-config.html#provider-installation - -## Cloning the Project +* [Terraform 0.12+][terraform-install] -First, you will want to clone the repository to -`$GOPATH/src/github.com/vmware/terraform-provider-nsxt`: + For general information about Terraform, visit [HashiCorp Developer][terraform-install] and [the project][terraform-github] on GitHub. -```sh -mkdir -p $GOPATH/src/github.com/vmware -cd $GOPATH/src/github.com/vmware -git clone https://github.com/vmware/terraform-provider-nsxt.git -``` - -## Building and Installing the Provider - -Recommended golang version is go1.18 onwards. -After the clone has been completed, you can enter the provider directory and build the provider. - -```sh -cd $GOPATH/src/github.com/vmware/terraform-provider-nsxt -make -``` - -After the build is complete, copy the provider executable `terraform-provider-nsxt` into location specified in your provider installation configuration. Make sure to delete provider lock files that might exist in your working directory due to prior provider usage. Run `terraform init`. -For developing, consider using [dev overrides configuration][dev-overrides]. Please note that `terraform init` should not be used with dev overrides. - -[dev-overrides]: https://www.terraform.io/docs/cli/config/config-file.html#development-overrides-for-provider-developers +* [Go 1.22][golang-install] -# Developing the Provider + Required, if [building][provider-build] and [testing][provider-test]. -**NOTE:** Before you start work on a feature, please make sure to check the -[issue tracker][gh-issues] and existing [pull requests][gh-prs] to ensure that -work is not being duplicated. For further clarification, you can also ask in a -new issue. +## Using the Provider -[gh-issues]: https://github.com/vmware/terraform-provider-nsxt/issues -[gh-prs]: https://github.com/vmware/terraform-provider-nsxt/pulls +The Terraform Provider for VMware NSX is a Partner tier provider. -If you wish to work on the provider, you'll first need [Go][go-website] -installed on your machine (version 1.19+ is recommended). You'll also need to -correctly setup a [GOPATH][gopath], as well as adding `$GOPATH/bin` to your -`$PATH`. +Partner tier providers are owned and maintained by a partner in the HashiCorp Technology Partner Program. HashiCorp verifies the authenticity of the publisher and the provider is listed on the [Terraform Registry][terraform-registry] with a Partner tier label. -[go-website]: https://golang.org/ -[gopath]: http://golang.org/doc/code.html#GOPATH +To use a released version of the Terraform provider in your environment, run `terraform init` and Terraform will automatically install the provider from the Terraform Registry. -See [Manual Installation](#manual-installation) for details on building the -provider. +Unless you are contributing to the provider or require a pre-release bugfix or feature, use a +released version of the provider. -# Testing the Provider +See [Installing the Terraform Provider for VMware NSX][provider-install] for additional instructions on automated and manual installation methods and how to control the provider version. -**NOTE:** Testing the NSX-T provider is currently a complex operation as it -requires having a NSX-T manager endpoint to test against, which should be -hosting a standard configuration for a NSX-T cluster. To cover Global Manager -test cases, NSX-T Global Manager suite needs to be preconfigured. +For either installation method, documentation about the provider configuration, resources, and data sources can be found on the Terraform Registry. -## Configuring Environment Variables +## Upgrading the Provider -Most of the tests in this provider require a comprehensive list of environment -variables to run. See the individual `*_test.go` files in the [`nsxt/`](nsxt/) -directory for more details, in addition to -[`tests_utils.go`](nsxt/tests_utils.go) for details on some tunables that can be -used to specify the locations of certain pre-created resources that some tests -require. +The provider does not upgrade automatically. After each new release, you can run the following command to upgrade the provider: -Minimum environment variable : -```sh -$ export NSXT_MANAGER_HOST="192.168.110.41" -$ export NSXT_USERNAME="admin" -$ export NSXT_PASSWORD="MyPassword123!" -$ export NSXT_ALLOW_UNVERIFIED_SSL=true +```shell +terraform init -upgrade ``` -## 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=TestAccResourceNsxtPolicyTier0Gateway" -``` +## Contributing -This following example would run all of the acceptance tests matching -`TestAccResourceNsxtPolicyTier0Gateway`. Change this for the specific tests you want -to run. +The Terraform Provider for VMware NSX is the work of many contributors and the project team appreciates your help! -# Interoperability +If you discover a bug or would like to suggest an enhancement, submit [an issue][provider-issues]. -The following versions of NSX are supported: +If you would like to submit a pull request, please read the [contribution guidelines][provider-contributing] to get started. In case of enhancement or feature contribution, we kindly ask you to open an issue to discuss it beforehand. - * NSX-T 4.2.* - * NSX-T 4.1.* - * NSX-T 4.0.* - * NSX-T 3.2.* - * NSX-T 3.1.* - * NSX-T 3.0.* - * NSX-T 2.5.* support is limited with provider version 3.2.x and above - -Some specific resources and attributes may require recent versions of NSX-T. Please refer to documentation for more details. +## Support -# Support +The Terraform Provider for VMware NSX is supported by Broadcom and the provider community. For bugs and feature requests please open a Github Issue and label it appropriately or contact Broadcom support. -The NSX Terraform provider is now VMware supported as well as community supported. For bugs and feature requests please open a Github Issue and label it appropriately or contact VMware support. +## License -# License +© Broadcom. All Rights Reserved. +The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries. -Copyright © 2015-2024 Broadcom, Inc. All Rights Reserved. +The Terraform Provider for VMware NSX is available under the [Mozilla Public License, version 2.0][provider-license] license. -The NSX Terraform provider is available under [MPL2.0 license](https://github.com/vmware/terraform-provider-nsxt/blob/master/LICENSE.txt). +[golang-install]: https://golang.org/doc/install +[product-documentation]: https://docs.vmware.com/en/VMware-NSX/index.html +[product-lifecycle]: https://support.broadcom.com/group/ecx/productlifecycle +[provider-contributing]: CONTRIBUTING.md +[provider-discussions]: https://github.com/vmware/terraform-provider-nsxt/discussions +[provider-documentation]: https://registry.terraform.io/providers/vmware/nsxt/latest/docs +[provider-build]: docs/build.md +[provider-install]: docs/install.md +[provider-test]: docs/test.md +[provider-issues]: https://github.com/vmware/terraform-provider-nsxt/issues/new/choose +[provider-license]: LICENSE +[terraform-github]: https://github.com/hashicorp/terraform +[terraform-install]: https://developer.hashicorp.com/terraform/install +[terraform-registry]: https://registry.terraform.io diff --git a/docs/build.md b/docs/build.md new file mode 100644 index 000000000..81683d253 --- /dev/null +++ b/docs/build.md @@ -0,0 +1,51 @@ + + + + +VMware NSX + +# Building the Terraform Provider for VMware NSX + +The instructions outlined below are specific to macOS and Linux only. + +If you wish to work on the provider, you'll first need [Go][golang-install] installed on your +machine. Check the [requirements][requirements] before proceeding. + +1. Clone the repository to: `$GOPATH/src/github.com/vmware/terraform-provider-nsxt` + + ```sh + mkdir -p $GOPATH/src/github.com/vmware + cd $GOPATH/src/github.com/vmware + git clone git@github.com:vmware/terraform-provider-nsxt.git + ``` + +2. Enter the provider directory to build the provider. + + ```sh + cd $GOPATH/src/github.com/vmware/terraform-provider-nsxt + go get + go build -o terraform-provider-nsxt + ``` + +3. Add the following to your `~/.terraformrc`: + + ```hcl + provider_installation { + dev_overrides { + "vmware/vcf" = "/Users/rainpole/go/bin" + } + + direct {} + } + ``` + + Where `/Users/rainpole/go/bin` is your `GOPATH/bin` path. + +4. Run `go install` to install the development binary. + +[golang-install]: https://golang.org/doc/install +[requirements]: https://github.com/vmware/terraform-provider-nsxt#requirements diff --git a/docs/images/icon-color.svg b/docs/images/icon-color.svg new file mode 100644 index 000000000..4d89f0b59 --- /dev/null +++ b/docs/images/icon-color.svg @@ -0,0 +1,23 @@ + + + + + + + + + + + \ No newline at end of file diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 000000000..fd9bdac4b --- /dev/null +++ b/docs/install.md @@ -0,0 +1,275 @@ + + + + +VMware NSX + +# Installing the Terraform Provider for VMware NSX + +This document assumes the use of Terraform 1.4 or later. + +## Automated Installation (Recommended) + +The Terraform Provider for VMware NSX is a Partner Tier provider. + +Partner providers are owned and maintained by a partner in the HashiCorp Technology Partner Program. HashiCorp verifies the authenticity of the publisher and the provider is listed on the [Terraform Registry][terraform-registry] with a partner tier label. + +### Configure the Terraform Configuration Files + +Providers listed on the Terraform Registry can be automatically downloaded when initializing a working directory with `terraform init`. The Terraform configuration block is used to configure some behaviors of Terraform itself, such as the Terraform version and the required providers and versions. + +**Example**: A Terraform configuration block. + +```hcl +terraform { + required_providers { + nsxt = { + source = "vmware/nsxt" + } + } + required_version = ">= 1.4.0" +} +``` + +You can use `version` locking and operators to require specific versions of the provider. + +**Example**: A Terraform configuration block with the provider versions. + +```hcl +terraform { + required_providers { + nsxt = { + source = "vmware/nsxt" + version = ">= x.y.z" + } + } + required_version = ">= 1.4.0" +} +``` + +To specify a particular provider version when installing released providers, see the Terraform documentation [on provider versioning][terraform-provider-versioning] + +### Verify Terraform Initialization Using the Terraform Registry + +To verify the initialization, navigate to the working directory for your Terraform configuration and run `terraform init`. You should see a message indicating that Terraform has been successfully initialized and has installed the provider from the Terraform Registry. + +**Example**: Initialize and Download the Provider. + +```console +$ terraform init + +Initializing the backend... + +Initializing provider plugins... +- Finding vmware/nsxt versions matching ">= x.y.z" ... +- Installing vmware/nsxt x.y.z ... +- Installed vmware/nsxt x.y.z +... + +Terraform has been successfully initialized! +``` + +## Manual Installation + +The latest release of the provider can be found in the [releases][releases]. You can download the appropriate version of the provider for your operating system using a command line shell or a browser. + +This can be useful in environments that do not allow direct access to the Internet. + +### Linux + +The following examples use Bash on Linux (x64). + +1. On a Linux operating system with Internet access, download the plugin from GitHub using the shell. + + ```console + RELEASE=x.y.z + wget -q https://github.com/vmware/terraform-provider-nsxt/releases/download/v${RELEASE}/terraform-provider-nsxt_${RELEASE}_linux_amd64.zip + ``` + +2. Extract the plugin. + + ```console + unzip terraform-provider-nsxt_${RELEASE}_linux_amd64.zip -d terraform-provider-nsxt_${RELEASE} + ``` + +3. Create a directory for the provider. + + > **Note** + > + > The directory hierarchy that Terraform uses to precisely determine the source of each provider it finds locally. + > + > `$PLUGIN_DIRECTORY/$SOURCEHOSTNAME/$SOURCENAMESPACE/$NAME/$VERSION/$OS_$ARCH/` + + ```console + mkdir -p ~/.terraform.d/plugins/local/vmware/nsxt/${RELEASE}/linux_amd64 + ``` + +4. Copy the extracted plugin to a target system and move to the Terraform plugins directory. + + ```console + mv terraform-provider-nsxt_${RELEASE}/terraform-provider-nsxt_v${RELEASE} ~/.terraform.d/plugins/local/vmware/nsxt/${RELEASE}/linux_amd64 + ``` + +5. Verify the presence of the plugin in the Terraform plugins directory. + + ```console + cd ~/.terraform.d/plugins/local/vmware/nsxt/${RELEASE}/linux_amd64 + ls + ``` + +### macOS + +The following example uses Bash (default) on macOS (Intel). + +1. On a macOS operating system with Internet access, install wget with [Homebrew](https://brew.sh). + + ```console + brew install wget + ``` + +2. Download the plugin from GitHub using the shell. + + ```console + RELEASE=x.y.z + wget -q https://github.com/vmware/terraform-provider-nsxt/releases/download/v${RELEASE}/terraform-provider-nsxt_${RELEASE}_darwin_amd64.zip + ``` + +3. Extract the plugin. + + ```console + unzip terraform-provider-nsxt_${RELEASE}_darwin_amd64.zip -d terraform-provider-nsxt_${RELEASE} + ``` + +4. Create a directory for the provider. + + > **Note** + > + > The directory hierarchy that Terraform uses to precisely determine the source of each provider it finds locally. + > + > `$PLUGIN_DIRECTORY/$SOURCEHOSTNAME/$SOURCENAMESPACE/$NAME/$VERSION/$OS_$ARCH/` + + ```console + mkdir -p ~/.terraform.d/plugins/local/vmware/nsxt/${RELEASE}/darwin_amd64 + ``` + +5. Copy the extracted plugin to a target system and move to the Terraform plugins directory. + + ```console + mv terraform-provider-nsxt_${RELEASE}/terraform-provider-nsxt_v${RELEASE} ~/.terraform.d/plugins/local/vmware/nsxt/${RELEASE}/darwin_amd64 + ``` + +6. Verify the presence of the plugin in the Terraform plugins directory. + + ```console + cd ~/.terraform.d/plugins/local/vmware/nsxt/${RELEASE}/darwin_amd64 + ls + ``` + +### Windows + +The following examples use PowerShell on Windows (x64). + +1. On a Windows operating system with Internet access, download the plugin using the PowerShell. + + ```powershell + $RELEASE="x.y.z" + Invoke-WebRequest -Uri "https://github.com/vmware/terraform-provider-nsxt/releases/download/v${RELEASE}/terraform-provider-nsxt_${RELEASE}_windows_amd64.zip" -OutFile "terraform-provider-nsxt_${RELEASE}_windows_amd64.zip" + ``` + +2. Extract the plugin. + + ```powershell + Expand-Archive terraform-provider-nsxt_${RELEASE}_windows_amd64.zip + + cd terraform-provider-nsxt_${RELEASE}_windows_amd64 + ``` + +3. Copy the extracted plugin to a target system and move to the Terraform plugins directory. + + > **Note** + > + > The directory hierarchy that Terraform uses to precisely determine the source of each provider it finds locally. + > + > `$PLUGIN_DIRECTORY/$SOURCEHOSTNAME/$SOURCENAMESPACE/$NAME/$VERSION/$OS_$ARCH/` + + ```powershell + New-Item $ENV:APPDATA\terraform.d\plugins\local\vmware\nsxt\${RELEASE}\ -Name "windows_amd64" -ItemType "directory" + + Move-Item terraform-provider-nsxt_v${RELEASE}.exe $ENV:APPDATA\terraform.d\plugins\local\vmware\nsxt\${RELEASE}\windows_amd64\terraform-provider-nsxt_v${RELEASE}.exe + ``` + +4. Verify the presence of the plugin in the Terraform plugins directory. + + ```powershell + cd $ENV:APPDATA\terraform.d\plugins\local\vmware\nsxt\${RELEASE}\windows_amd64 + dir + ``` + +### Configure the Terraform Configuration Files + +A working directory can be initialized with providers that are installed locally on a system by using `terraform init`. The Terraform configuration block is used to configure some behaviors of Terraform itself, such as the Terraform version and the required providers source and version. + +**Example**: A Terraform configuration block. + +```hcl +terraform { + required_providers { + nsxt = { + source = "local/vmware/nsxt" + version = ">= x.y.z" + } + } + required_version = ">= 0.13" +} +``` + +### Verify the Terraform Initialization of a Manually Installed Provider + +To verify the initialization, navigate to the working directory for your Terraform configuration and run `terraform init`. You should see a message indicating that Terraform has been successfully initialized and the installed version of the Terraform Provider for VMware NSX. + +**Example**: Initialize and Use a Manually Installed Provider + +```console +$ terraform init + +Initializing the backend... + +Initializing provider plugins... +- Finding local/vmware/nsxt versions matching ">= x.y.x" ... +- Installing local/vmware/nsxt x.y.x ... +- Installed local/vmware/nsxt x.y.x (unauthenticated) +... + +Terraform has been successfully initialized! +``` + +## Get the Provider Version + +To find the provider version, navigate to the working directory of your Terraform configuration and run `terraform version`. You should see a message indicating the provider version. + +**Example**: Terraform Provider Version from the Terraform Registry + +```console +$ terraform version +Terraform x.y.z +on linux_amd64 ++ provider registry.terraform.io/vmware/nsxt x.y.z +``` + +**Example**: Terraform Provider Version for a Manually Installed Provider + +```console +$ terraform version +Terraform x.y.z +on linux_amd64 ++ provider local/vmware/nsxt x.y.z +``` + +[hashicorp]: https://www.hashicorp.com/ +[releases]: https://github.com/vmware/terraform-provider-nsxt/releases +[terraform-provider-versioning]: https://developer.hashicorp.com/terraform/language/providers/configuration#version-provider-versions +[terraform-registry]: https://registry.terraform.io diff --git a/docs/test.md b/docs/test.md new file mode 100644 index 000000000..701794e99 --- /dev/null +++ b/docs/test.md @@ -0,0 +1,53 @@ + + + + +VMware NSX + +# Testing the Terraform Provider for VMware NSX + +Testing the Terraform Provider for VMware NSX is currently a complex operation +as it requires having an NSX Local Manager endpoint to test against, which +should be hosting a standard configuration for a NSX Manager cluster. To cover +NSX Global Manager test cases, NSX Global Manager suite needs to be +pre-configured. + +## Configuring Environment Variables + +Most of the tests for the provider require a comprehensive list of environment +variables to run. Please refer to the individual `*_test.go` files in the +[`nsxt/`](nsxt/) directory for more details. In addition, refer to the +`tests_utils.go` for details on some tunables that can be used to specify the +locations of certain pre-created resources that some tests require. + +Minimum Environment Variable: + +```sh +$ export NSXT_MANAGER_HOST="nsx-01.example.com" +$ export NSXT_USERNAME="admin" +$ export NSXT_PASSWORD="VMw@re123!VMw@re123!" +$ export NSXT_ALLOW_UNVERIFIED_SSL=true +``` + +## Running the Acceptance Tests + +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. For example: + +```sh +make testacc TESTARGS="-run=TestAccResourceNsxtPolicyTier0Gateway" +``` + +This following example would run all of the acceptance tests matching +`TestAccResourceNsxtPolicyTier0Gateway`. Change this for the specific tests you +want to run.