-
Notifications
You must be signed in to change notification settings - Fork 85
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add install, build, and test docs (#1431)
- Loading branch information
1 parent
53ed66f
commit 94b907d
Showing
5 changed files
with
465 additions
and
148 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,187 +1,104 @@ | ||
| # Terraform NSX-T Provider | ||
| <!-- | ||
| © Broadcom. All Rights Reserved. | ||
| The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries. | ||
| SPDX-License-Identifier: MPL-2.0 | ||
| --> | ||
|
|
||
| This is the repository for the Terraform NSX Provider, which one can use with | ||
| Terraform to work with [VMware NSX-T][vmware-nsxt]. | ||
| <!-- markdownlint-disable first-line-h1 no-inline-html --> | ||
|
|
||
| [vmware-nsxt]: https://www.vmware.com/products/nsx.html | ||
| <img src="docs/images/icon-color.svg" alt="VMware NSX" width="150"> | ||
|
|
||
| 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 | ||
| [](https://github.com/vmware/terraform-provider-nsxt/releases/latest) [](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 Broadcom supported as well as community supported. For bugs and feature requests please open a Github Issue and label it appropriately or contact Broadcom 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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| <!-- | ||
| © Broadcom. All Rights Reserved. | ||
| The term “Broadcom” refers to Broadcom Inc. and/or its subsidiaries. | ||
| SPDX-License-Identifier: MPL-2.0 | ||
| --> | ||
|
|
||
| <!-- markdownlint-disable first-line-h1 no-inline-html --> | ||
|
|
||
| <img src="images/icon-color.svg" alt="VMware NSX" width="150"> | ||
|
|
||
| # 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 [email protected]: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 |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.