diff --git a/docs/build.md b/docs/build.md new file mode 100644 index 0000000..423d07f --- /dev/null +++ b/docs/build.md @@ -0,0 +1,51 @@ + + + + +VMware Cloud on AWS + +# Building the Terraform Provider for VMware Cloud on AWS + +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-vmc` + + ```sh + mkdir -p $GOPATH/src/github.com/vmware + cd $GOPATH/src/github.com/vmware + git clone git@github.com:vmware/terraform-provider-vmc.git + ``` + +2. Enter the provider directory to build the provider. + + ```sh + cd $GOPATH/src/github.com/vmware/terraform-provider-vmc + go get + go build -o terraform-provider-vmc + ``` + +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-vmc#requirements diff --git a/docs/images/icon-color.png b/docs/images/icon-color.png new file mode 100644 index 0000000..e45e276 Binary files /dev/null and b/docs/images/icon-color.png differ diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..3da5d4d --- /dev/null +++ b/docs/install.md @@ -0,0 +1,272 @@ + + + + +VMware Cloud on AWS + +# Installing the Terraform Provider for VMware Cloud on AWS + +## Automated Installation (Recommended) + +The Terraform Provider for VMware Cloud on AWS 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 { + vmc = { + source = "vmware/vmc" + } + } + required_version = ">= x.y.z" +} +``` + +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 { + vmc = { + source = "vmware/vmc" + version = ">= x.y.z" + } + } + required_version = ">= x.y.z" +} +``` + +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/vmc versions matching ">= x.y.z" ... +- Installing vmware/vmc x.y.z ... +- Installed vmware/vmc 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-vmc/releases/download/v${RELEASE}/terraform-provider-vmc_${RELEASE}_linux_amd64.zip + ``` + +2. Extract the plugin. + + ```console + unzip terraform-provider-vmc_${RELEASE}_linux_amd64.zip -d terraform-provider-vmc_${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/vmc/${RELEASE}/linux_amd64 + ``` + +4. Copy the extracted plugin to a target system and move to the Terraform plugins directory. + + ```console + mv terraform-provider-vmc_${RELEASE}/terraform-provider-vmc_v${RELEASE} ~/.terraform.d/plugins/local/vmware/vmc/${RELEASE}/linux_amd64 + ``` + +5. Verify the presence of the plugin in the Terraform plugins directory. + + ```console + cd ~/.terraform.d/plugins/local/vmware/vmc/${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-vmc/releases/download/v${RELEASE}/terraform-provider-vmc_${RELEASE}_darwin_amd64.zip + ``` + +3. Extract the plugin. + + ```console + unzip terraform-provider-vmc_${RELEASE}_darwin_amd64.zip -d terraform-provider-vmc_${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/vmc/${RELEASE}/darwin_amd64 + ``` + +5. Copy the extracted plugin to a target system and move to the Terraform plugins directory. + + ```console + mv terraform-provider-vmc_${RELEASE}/terraform-provider-vmc_v${RELEASE} ~/.terraform.d/plugins/local/vmware/vmc/${RELEASE}/darwin_amd64 + ``` + +6. Verify the presence of the plugin in the Terraform plugins directory. + + ```console + cd ~/.terraform.d/plugins/local/vmware/vmc/${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-vmc/releases/download/v${RELEASE}/terraform-provider-vmc_${RELEASE}_windows_amd64.zip" -OutFile "terraform-provider-vmc_${RELEASE}_windows_amd64.zip" + ``` + +2. Extract the plugin. + + ```powershell + Expand-Archive terraform-provider-vmc_${RELEASE}_windows_amd64.zip + + cd terraform-provider-vmc_${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\vmc\${RELEASE}\ -Name "windows_amd64" -ItemType "directory" + + Move-Item terraform-provider-vmc_v${RELEASE}.exe $ENV:APPDATA\terraform.d\plugins\local\vmware\vmc\${RELEASE}\windows_amd64\terraform-provider-vmc_v${RELEASE}.exe + ``` + +4. Verify the presence of the plugin in the Terraform plugins directory. + + ```powershell + cd $ENV:APPDATA\terraform.d\plugins\local\vmware\vmc\${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 { + vmc = { + source = "local/vmware/vmc" + 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 Cloud on AWS. + +**Example**: Initialize and Use a Manually Installed Provider + +```console +$ terraform init + +Initializing the backend... + +Initializing provider plugins... +- Finding local/vmware/vmc versions matching ">= x.y.x" ... +- Installing local/vmware/vmc x.y.x ... +- Installed local/vmware/vmc 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/vmc 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/vmc x.y.z +``` + +[releases]: https://github.com/vmware/terraform-provider-vmc/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 0000000..5fdd7e3 --- /dev/null +++ b/docs/test.md @@ -0,0 +1,63 @@ + + + + +VMware Cloud on AWS + +# Testing the Terraform Provider for VMware Cloud on AWS + +Testing the Terraform Provider for VMware Cloud on AWS requires having an VMware +Cloud on AWS organization to test against. Generally, the acceptance tests +create real resources, and often cost money to run. + +## Configuring Environment Variables + +Set required environment variables based based on your infrastructure settings. + +```sh +$ # clientId and client secret of the test OAuth2.0 app attached to the test organization with at least +$ # "Organization Member" role and service role on "VMware Cloud on AWS" service that is allowed to deploy SDDCs. +$ # Note: it is recommended to use OAuth2.0 app with the least possible roles (the above mentioned) for testing +$ # purposes. +$ export CLIENT_ID=xxx +$ export CLIENT_SECRET=xxx +$ # Id of a VMC Org in which test SDDC are (to be) placed +$ export ORG_ID=xxxx +$ # Id of an existing SDDC used for SDDC data source (import) test +$ export TEST_SDDC_ID=xxx +$ # Name of above SDDC +$ export TEST_SDDC_NAME=xxx +$ # NSX URL of a non-ZEROCLOUD SDDC, used for real IP testing +$ export NSXT_REVERSE_PROXY_URL=xxx +$ # Account number of a connected to the above Org AWS account, required for test SDDC deployment +$ export AWS_ACCOUNT_NUMBER=xxx +``` + +## Running the Acceptance Tests + +Acceptance tests create real resources, and often cost money to run. + +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=TestAccResourceVmcSddc_basic" +``` + +Additionally, A limited set of acceptance tests can be ran with the ZEROCLOUD +cloud provider, which is much faster and cheaper, while providing decent API +coverage:. For example: + +```sh +$ make testacc TESTARGS="-run=TestAccResourceVmcSddcZerocloud" +```