-
Notifications
You must be signed in to change notification settings - Fork 32
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 (#456)
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 <ryan.johnson@broadcom.com>
- Loading branch information
1 parent
2d94ca6
commit 10a1ac4
Showing
5 changed files
with
527 additions
and
195 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,230 +1,95 @@ | ||
| # Terraform VMware Tanzu Mission Control 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 Tanzu Mission Control Provider and can be used with | ||
| [VMware Tanzu Mission Control][vmware-tanzu-mission-control]. | ||
| <!-- markdownlint-disable first-line-h1 no-inline-html --> | ||
|
|
||
| For general information about Terraform, visit the [official website][hashicorp-terraform] and the [GitHub project page.][terraform-github] | ||
| <img src="docs/images/icon-color.svg" alt="VMware Tanzu Mission Control" width="150"> | ||
|
|
||
| [vmware-tanzu-mission-control]: https://tanzu.vmware.com/mission-control | ||
| [hashicorp-terraform]: https://www.terraform.io | ||
| [terraform-github]: https://github.com/hashicorp/terraform | ||
|
|
||
| # Using the Provider | ||
|
|
||
| The latest version of this provider requires Terraform v0.12 or higher to run. | ||
|
|
||
| Note that you need to run `terraform init` to fetch the provider before | ||
| deploying. | ||
|
|
||
| ### Controlling the provider version | ||
| # Terraform Provider for VMware Tanzu Mission Control | ||
|
|
||
| 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. | ||
| [](https://github.com/vmware/terraform-provider-tanzu-mission-control/releases/latest) [](LICENSE) | ||
|
|
||
| The syntax is as follows: | ||
| The Terraform Provider for [VMware Tanzu Mission Control][product-documentation] is a plugin for | ||
| Terraform that allows you to interact with VMware Tanzu Mission Control. | ||
|
|
||
| ```hcl | ||
| terraform { | ||
| required_providers { | ||
| tanzu-mission-control = { | ||
| source = "vmware/tanzu-mission-control" | ||
| version = "1.0.0" | ||
| } | ||
| } | ||
| } | ||
| Learn more: | ||
|
|
||
| provider "tanzu-mission-control" { | ||
| # Configuration options | ||
| } | ||
| ``` | ||
|
|
||
| Version locking uses a pessimistic operator, so this version lock would mean anything within the 1.x namespace, including or after 1.0.0. | ||
| [Read more][provider-vc] on provider version control. | ||
| * Read the provider [documentation][provider-documentation]. | ||
|
|
||
| [provider-vc]: https://docs.vmware.com/en/VMware-Tanzu-Mission-Control/index.html | ||
| * Join the community [discussions][provider-discussions]. | ||
|
|
||
| # Manual Installation | ||
| ## Requirements | ||
|
|
||
| ## Cloning the Project | ||
| * [Terraform 0.12+][terraform-install] | ||
|
|
||
| First, you will want to clone the repository to | ||
| `github.com/vmware/terraform-provider-tanzu-mission-control`: | ||
| 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/terraform-provider-tanzu-mission-control | ||
| cd $GOPATH/src/github.com/vmware/terraform-provider-tanzu-mission-control | ||
| git clone git@github.com:vmware/terraform-provider-tanzu-mission-control.git | ||
| ``` | ||
| * [Go 1.19][golang-install] | ||
|
|
||
| ## Building and Installing the Provider | ||
| Required, if [building][provider-build] and [testing][provider-test]. | ||
|
|
||
| Recommended golang version is go1.14 onwards. | ||
| After the clone has been completed, you can enter the provider directory and build the provider. | ||
|
|
||
| ```sh | ||
| cd github.com/vmware/terraform-provider-tanzu-mission-control | ||
| make | ||
| ``` | ||
| ## Using the Provider | ||
|
|
||
| After the build is complete, copy the provider executable `terraform-provider-tanzu` 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. | ||
| The Terraform Provider for VMware Tanzu Mission Control is a Partner tier provider. | ||
|
|
||
| [dev-overrides]: https://www.terraform.io/docs/cli/config/config-file.html#development-overrides-for-provider-developers | ||
| 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. | ||
|
|
||
| # Developing the Provider | ||
| 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. | ||
|
|
||
| **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. | ||
| Unless you are contributing to the provider or require a pre-release bugfix or feature, use a | ||
| released version of the provider. | ||
|
|
||
| [gh-issues]: https://github.com/vmware/terraform-provider-tanzu-mission-control/issues | ||
| [gh-prs]: https://github.com/vmware/terraform-provider-tanzu-mission-control/pulls | ||
| See [Installing the Terraform Provider for VMware Tanzu Mission Control][provider-install] for | ||
| additional instructions on automated and manual installation methods and how to control the provider | ||
| version. | ||
|
|
||
| If you wish to work on the provider, you'll first need [Go][go-website] | ||
| installed on your machine (version 1.14+ is recommended). You'll also need to | ||
| correctly setup a [GOPATH][gopath], as well as adding `$GOPATH/bin` to your | ||
| `$PATH`. | ||
| For either installation method, documentation about the provider configuration, resources, and data | ||
| sources can be found on the Terraform Registry. | ||
|
|
||
| [go-website]: https://golang.org/ | ||
| [gopath]: http://golang.org/doc/code.html#GOPATH | ||
| ## Upgrading the Provider | ||
|
|
||
| See [Manual Installation](#manual-installation) for details on building the | ||
| provider. | ||
|
|
||
| # Testing the Provider | ||
|
|
||
| ## Flattening and Helper Tests | ||
| Run the command: | ||
| ```sh | ||
| $ make test | ||
| ``` | ||
|
|
||
| ## Acceptance Tests | ||
| **NOTE:** This block is applicable only for Tanzu Mission Control SaaS offering. | ||
| ### Configuring Environment Variables: | ||
| Set the environment variables in your IDE configurations or Terminal. | ||
| Environment variables that are required to be set universally are `TMC_ENDPOINT`, `VMW_CLOUD_ENDPOINT` and `VMW_CLOUD_API_TOKEN`. | ||
|
|
||
| Example: | ||
| The provider does not upgrade automatically. After each new release, you can run the following command to upgrade the provider: | ||
|
|
||
| ```shell | ||
| $ export TMC_ENDPOINT = my-org.tmc.cloud.vmware.com | ||
| $ export VMW_CLOUD_ENDPOINT = console.tanzu.broadcom.com | ||
| terraform init -upgrade | ||
| ``` | ||
|
|
||
| Environment variables specific to particular resources: | ||
| ## Contributing | ||
|
|
||
| - **Attach Cluster with Kubeconfig and Namespace Resource** - `KUBECONFIG` | ||
| - **Tanzu Kubernetes Grid Service for vSphere workload cluster** - `MANAGEMENT_CLUSTER`, `PROVISIONER_NAME`, `VERSION` and `STORAGE_CLASS`. | ||
| - **Tanzu Kubernetes Grid workload cluster** - `MANAGEMENT_CLUSTER` and `CONTROL_PLANE_ENDPOINT`. | ||
| The Terraform Provider for VMware Tanzu Mission Control is the work of many contributors and the project team appreciates your help! | ||
|
|
||
| ### Running the Test: | ||
| Run the command: | ||
| ```sh | ||
| $ make acc-test | ||
| ``` | ||
| If you discover a bug or would like to suggest an enhancement, submit [an issue][provider-issues]. | ||
|
|
||
| To run the acceptance test specific to a resource make use of the build-tags. | ||
| Build tag name is equivalent to the corresponding resource name. | ||
| 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. | ||
|
|
||
| ` | ||
| Running acceptance test without explicitly setting `BUILD_TAGS` runs all the acceptance test by default. | ||
| To specifically run acceptances test of a resouces, set `BUILD_TAGS` value to correponding resource name. | ||
| ` | ||
| ## Support | ||
|
|
||
| For instance to run acceptance test for cluster-group and namespace resource | ||
| ```sh | ||
| $ export BUILD_TAGS = "clustergroup namespace" | ||
| $ make acc-test | ||
| ``` | ||
| The Terraform Provider for VMware Tanzu Mission Control is supported by Broadcom and the provider community. For bugs and enhancement requests please open a GitHub [issue][provider-issues] or contact Broadcom support. | ||
|
|
||
| ### Test provider changes locally | ||
| Please make use of a unique path as provided in the `Makefile` while building the provider with changes | ||
| and kindly use the same path in the source while using the provider to test the local changes. | ||
| ## License | ||
|
|
||
| ```shell | ||
| terraform { | ||
| required_providers { | ||
| tanzu-mission-control = { | ||
| source = "vmware/dev/tanzu-mission-control" | ||
| } | ||
| } | ||
| } | ||
|
|
||
| provider "tanzu-mission-control" { | ||
| # Configuration options | ||
| } | ||
| ``` | ||
| © Broadcom. All Rights Reserved. | ||
| The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries. | ||
|
|
||
| [here]: https://www.terraform.io/internals/debugging | ||
| ## Debugging Provider | ||
| Please set the environmental variable `TF_LOG` to one of the log levels `TRACE`, `DEBUG`, `INFO`, `WARN` or `ERROR` to capture the logs. More details in the link [here]. | ||
| The Terraform Provider for VMware Tanzu Mission Control is available under the [Mozilla Public License, version 2.0][provider-license] license. | ||
|
|
||
| Set the environmental variable `TMC_MODE` to `DEV` to capture more granular logs. | ||
|
|
||
| ## Connect the VSCode debugger | ||
| 1. Create `./.vscode/launch.json` | ||
| ```json5 | ||
| { | ||
| "version": "0.2.0", | ||
| "configurations": [ | ||
| { | ||
| "name": "Debug Terraform Provider", | ||
| "type": "go", | ||
| "request": "launch", | ||
| "mode": "debug", | ||
| // this assumes your workspace is the root of the repo | ||
| "program": "${workspaceFolder}", | ||
| "env": {}, | ||
| "args": [ | ||
| "-debug", | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
| 2. Click on **"Run and Debug"** option in VSCode, This will open a panel on the left side of the editor. Here, you can see a list of configurations for debugging different languages and tools. Find the one that says **"Debug Terraform Provider"** and click on it. This will launch the debugger and attach it to your provider process. You can now set breakpoints, inspect variables, and step through your code as usual. | ||
| 3. Check the **"DEBUG CONSOLE"** tab, there you will find the value of `TF_REATTACH_PROVIDERS`, which is a special environment variable that tells Terraform how to connect to the provider's plugin process. You need to set this variable in your shell before running any Terraform commands. For example, you can use the export command as shown below: | ||
| <br/> | ||
| ```sh | ||
| # Set TF_REATTACH_PROVIDERS as environment variable. | ||
| export TF_REATTACH_PROVIDERS='{"vmware/dev/tanzu-mission-control":{"Protocol":"grpc","ProtocolVersion":5,"Pid":1338,"Test":true,"Addr":{"Network":"unix","String":"/var/folders/r9/h_0mgps9053g3tft7t8xh6rh0000gq/T/plugin2483048401"}}}' | ||
| # Run TF command | ||
| terraform plan | ||
| ``` | ||
| > https://developer.hashicorp.com/terraform/plugin/debugging#visual-studio-code | ||
| ## Provider Documentation | ||
| Tanzu Mission Control Terraform provider documentation is autogenerated using [tfplugindocs][tfplugindocs-link]. | ||
| Use the tfplugindocs tool to generate documentation for your provider in the format required by the Terraform Registry. | ||
| The plugin will read the descriptions and schema of each resource and data source in your provider and generate the relevant Markdown files for you. | ||
| [tfplugindocs-link]: https://github.com/hashicorp/terraform-plugin-docs | ||
| ## Using Tanzu Mission Control Provider | ||
| Please refer to `examples` folder to perform CRUD operations with Tanzu Mission Control provider for various resources | ||
| # Troubleshooting | ||
| ## Executions of a different version of the provider | ||
| Terraform will always look for the latest version of the provided and will use it even if you have just built a previous version. | ||
| Terraform caches all known builds/versions in the cache folder located in ```~/.terraform.d``` folder. | ||
| Delete ```~/.terraform.d/plugins/vmware``` folder to remove all cached versions of the plugin | ||
| # Support | ||
| The Tanzu Mission Control 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 | ||
| Copyright © 2015-2022 VMware, Inc. All Rights Reserved. | ||
| The Tanzu Mission Control Terraform provider is available under [MPL2.0 license](https://github.com/vmware/terraform-provider-tanzu-mission-control/blob/main/LICENSE). | ||
| [golang-install]: https://golang.org/doc/install | ||
| [product-documentation]: https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-mission-control/1-4/tanzu-mission-control-documentation/index-tmc-all.html | ||
| [provider-contributing]: CONTRIBUTING.md | ||
| [provider-discussions]: https://github.com/vmware/terraform-provider-tanzu-mission-control/discussions | ||
| [provider-documentation]: https://registry.terraform.io/providers/vmware/tanzu-mission-control/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-tanzu-mission-control/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 Tanzu Mission Control" width="150"> | ||
|
|
||
| # Building the Terraform Provider for VMware Tanzu Mission Control | ||
|
|
||
| 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-tanzu-mission-control` | ||
|
|
||
| ```sh | ||
| mkdir -p $GOPATH/src/github.com/vmware | ||
| cd $GOPATH/src/github.com/vmware | ||
| git clone git@github.com:vmware/terraform-provider-tanzu-mission-control.git | ||
| ``` | ||
|
|
||
| 2. Enter the provider directory to build the provider. | ||
|
|
||
| ```sh | ||
| cd $GOPATH/src/github.com/vmware/terraform-provider-tanzu-mission-control | ||
| go get | ||
| go build -o terraform-provider-tanzu-mission-control | ||
| ``` | ||
|
|
||
| 3. Add the following to your `~/.terraformrc`: | ||
|
|
||
| ```hcl | ||
| provider_installation { | ||
| dev_overrides { | ||
| "vmware/tanzu-mission-control" = "/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-tanzu-mission-control#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.