docs: add install, build, and test docs

Adds seperate documenation for the installation, buiild, and testing of the provider to be linked to an updated `README.md`. Signed-off-by: Ryan Johnson <[email protected]>
vmware · Oct 15, 2024 · d03a2be · d03a2be
1 parent 899e078
commit d03a2be
Show file tree

Hide file tree

Showing 4 changed files with 386 additions and 0 deletions.
diff --git a/docs/build.md b/docs/build.md
@@ -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.png" alt="VMware Cloud on AWS" width="150">
+
+# 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 [email protected]: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
diff --git a/docs/install.md b/docs/install.md
@@ -0,0 +1,272 @@
+<!--
+© 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.png" alt="VMware Cloud on AWS" width="150">
+
+# 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
@@ -0,0 +1,63 @@
+<!--
+© 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.png" alt="VMware Cloud on AWS" width="150">
+
+# 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"
+```