Skip to content

Getting Started with the Tanzu Mission Control Terraform Provider

Jump to bottom
Vasundhara Shukla edited this page Dec 23, 2022 · 2 revisions

Step by Step Process to support a new TMC functionality/feature via Terraform:

For TKP Feature Owners:

  • Provide API protos and postman collection for the related feature to the concerned developer/contractor.
  • Give a dive-in session to the developer on the particular TMC resource.
  • Provide the developer with the necessary information related to the schema attributes (required/ optional) and their purpose.
  • Involve in the discussion on finalizing the Terraform schema and cover all corner cases of the implementation. Eg: Tagging force-new to an attribute.
  • Discuss best-case scenarios for user interaction of the client and assist the developer to implement additional feature requests.
  • Post the addition of the working code, manually test the feature through terraform covering all corner cases and suggest any enhancements/ give necessary feedback.

For Terraform Developers:

  • Understand the features that need to be implemented and go through the APIs related. Reference: Tanzu Mission Control API Explorer

  • Generate the models and clients with the help of the swagger-gen tool. Use the public-swagger.yaml and run the commands: swagger generate client -f public-swagger.yaml and swagger generate model -f public-swagger.yaml.

  • Once the generated models are there, filter out the excess code and only incorporate the structs and marshaling and unmarshalling functions. For Reference -

    unnamed

    Here, the required code in the recipe models is the struct-

      type VmwareTanzuManageV1alpha1CommonPolicySpecTypeRecipeName struct{}

    and the marshal and unmarshal Binary functions-

     func (m *VmwareTanzuManageV1alpha1CommonPolicySpecTypeVersionRecipeName) MarshalBinary() ([]byte, error){},
 func (m *VmwareTanzuManageV1alpha1CommonPolicySpecTypeVersionRecipeName) UnmarshalBinary(b []byte) error{}

    All other functions of validate and context validate are not required. Example PR for the above steps: Client and Models implementation of access management

  • The concerned engineer needs to then document the schema with the use-cases and approach(example) and get it formally reviewed with the Resource owners, Terraform team and the PMs.

  • Write the schema based on the generated swagger models with descriptions taken from the comments related to the specific attribute.

  • Alternatively, for the above steps one can also follow: swagger-gen-policy-schema-tool to get the models and a basic terraform schema (with some modifications required related to giving constants, descriptions and force-new). This currently has steps to generate schema for policies, but can be made generic.

  • Perform another round of review with the resource owners and the terraform team in order to check for any missing specifications to the attributes. Some examples for the same:

    1. If the attribute is computed like status in meta-data
    2. If the attribute should be force-new or not, like the full name of a resource
    3. If the attribute is required (cluster name) or optional (nodepool)
    4. Should there be any validation for the particular attribute like scope validation for security and IAM policies.
    5. Is the attribute having any default value, like Default value for Provisioner name is attached

  • Write the construct and flattening functions(optional) for the generated Terraform schema to map with the models.

    Note: Here optional suggests that: it is upto the developer/use case that these functions can be manually written or one can leverage json marshall and unmarshall functionality.

  • Implement the CRUD functions for the feature that is required to be added for the resource.

  • Implement the Read which is the Data source for the particular feature depending on the use case.

  • Write the example terraform scripts and resource templates for the new TMC capability to support users.

    Example PR for work mentioned in the last 4 steps: Resource implementation for IAM Policy (Access Management) (contains unit tests as well)

Testing:

  • Prepare a test terraform script and perform CRUD operations leveraging it and also cover corner cases that make the feature well tested.

    Process: Create a directory inside examples directory of the repo and add a script named test.tf which contains your HCL code that shall be used to test the resources. Test your script on any TMC instance(dev stack) and add it as an env variable or in the script corresponding to endpoint under the provider section.

    Example script-

     terraform {
   required_providers {
     tanzu-mission-control = {
       source = "vmware/dev/tanzu-mission-control"
       version = "1.1.3"
     }
   }
 }
 provider "tanzu-mission-control" {
   endpoint            = "playground.tmc.cloud.vmware.com"  # optionally use TMC_ENDPOINT env var
   vmw_cloud_api_token = "<API-TOKEN>" # optionally use VMW_CLOUD_API_TOKEN env var
   vmw_cloud_endpoint  = "console.cloud.vmware.com"
 }
 resource "tanzu-mission-control_iam_policy" "organization_scoped_iam_policy" {
   scope {
     organization {
       org_id = "dummy-org-id"
     }
   }

   role_bindings {
     role = "organization.view"
     subjects {
       name = "test-1"
       kind = "USER"
     }
     subjects {
       name = "test-2"
       kind = "GROUP"
     }
   }
 }

  • Write the unit tests for the flattening functions and any extra functions that have been written for better coverage.

    Example PR: Flatten Test for Role Bindings

  • Run the make-all command after adding any new feature to ensure there are no linter and import issues.

  • Implement the Acceptance tests for the resource and data-source that has been added. Test them thoroughly with all corner cases.

    Procedure to run Acceptance tests can be found here.

    Example PR: Acceptance test for IAM

Documentation:

Download the latest release of Terraform plugin Docs tool from here.

  • Clone the repository in your system and create a new branch: git checkout -b “documention-<feature-name>”
  • Under templates directory, create a new file of the format- <feature-name>.md.tmpl
  • Add the layout and definitions of the feature as to how you want the Documentation to come out. You can refer to PR- Refining the documentation
  • After the template is ready, run the command ~/Downloads/tfplugindocs_0/tfplugindocs (considering the plugin tool was downloaded in the downloads folder, change the command as per the root directory)
  • On successful execution, you will be able to see a <feature-name>.md file under the docs directory.

Some important links:

Clone this wiki locally