terraform-provider-tanzu-mission-control

README

Terraform VMware Tanzu Mission Control Provider

This is the repository for the Terraform Tanzu Mission Control Provider and can be used with VMware Tanzu Mission Control.

For general information about Terraform, visit the official website and the GitHub project page.

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

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.

The syntax is as follows:

terraform {
  required_providers {
    tanzu-mission-control = {
      source = "vmware/tanzu-mission-control"
      version = "1.0.0"
    }
  }
}

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 on provider version control.

Manual Installation

Cloning the Project

First, you will want to clone the repository to github.com/vmware/terraform-provider-tanzu-mission-control:

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

Building and Installing the Provider

Recommended golang version is go1.14 onwards. After the clone has been completed, you can enter the provider directory and build the provider.

cd github.com/vmware/terraform-provider-tanzu-mission-control
make

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. Please note that terraform init should not be used with dev overrides.

Developing the Provider

NOTE: Before you start work on a feature, please make sure to check the issue tracker and existing pull requests to ensure that work is not being duplicated. For further clarification, you can also ask in a new issue.

If you wish to work on the provider, you'll first need Go installed on your machine (version 1.14+ is recommended). You'll also need to correctly setup a GOPATH, as well as adding $GOPATH/bin to your $PATH.

See Manual Installation for details on building the provider.

Testing the Provider

Flattening and Helper Tests

Run the command:

$ 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:

$ export TMC_ENDPOINT = my-org.tmc.cloud.vmware.com
$ export VMW_CLOUD_ENDPOINT = console.cloud.vmware.com

Environment variables specific to particular resources:

• 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.

Running the Test:

Run the command:

$ make acc-test

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.

Running acceptance test without explicitly settingBUILD_TAGSruns all the acceptance test by default. To specifically run acceptances test of a resouces, setBUILD_TAGSvalue to correponding resource name.

For instance to run acceptance test for cluster-group and namespace resource

$ export BUILD_TAGS = "clustergroup namespace"
$ make acc-test

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.

terraform {
  required_providers {
    tanzu-mission-control = {
      source = "vmware/dev/tanzu-mission-control"
    }
  }
}

provider "tanzu-mission-control" {
  # Configuration options
}

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.

Set the environmental variable TMC_MODE to DEV to capture more granular logs.

Connect the VSCode debugger

1. Create ./.vscode/launch.json

   {
         "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:
   

   # 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.

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.

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.