Merge pull request #34 from platform9/private/thenilesh/documentation…

…-improvements

Documentation improvements

.gitignore

@@ -35,4 +35,7 @@ TODO.md
 pf9-sdk-go
 pf9-sdk-go/
 pf9-sdk-go/*
-pf9-sdk-go/**
+pf9-sdk-go/**
+
+# Prevents accidental commiting secrets
+*.tfvars

.vscode/launch.json

@@ -8,7 +8,6 @@
             "mode": "debug",
             "program": "${workspaceFolder}",
             "env": {
-                "DU_PASSWORD": "",
                 "TF_LOG": "DEBUG",
             },
             "args": [

README.md

@@ -9,41 +9,60 @@ Refer to the [documentation](https://registry.terraform.io/providers/platform9/p
 ## Development Setup
 
 To set up your development environment, follow these steps:
-
-1. Create a new file called `.terraformrc` in your home directory if it does not already exist.
-
-2. Add the following `dev_overrides` block to your `.terraformrc` file
-
+1. Create a new file called `.terraformrc` in your home directory if it doesn't already exist.
+2. Add the following `dev_overrides` block to your `.terraformrc` file:
 ```terraform
 provider_installation {
   dev_overrides {
-    "platform9/pf9" = "<absolute-path-to-the-binary>"
+    # Replace the path with the location where the provider binary is installed on your system.
+    "platform9/pf9" = "/home/<your-username>/go/bin"
   }
   direct {}
 }
 ```
-Replace `<absolute-path-to-the-binary>` with the absolute path to the binary of the provider. This will instruct Terraform to use the development version of the provider instead of the one from the registry.
-
-3. Note that you dont need to run `terraform init` after adding the `dev_overrides` block to the `.terraformrc` file. Terraform will automatically use the development version of the provider when you run `terraform apply` or `terraform plan`.
-
-4. If you have a Golang development environment set up, it is recommended to set `<absolute-path-to-the-binary>` to the path of the binary generated by running `go install .` in the root directory of the provider. For example, `/home/<username>/go/bin/terraform-provider-pf9`.
+3. You don't need to run `terraform init` after adding the `dev_overrides` block to the `.terraformrc` file. Terraform automatically uses the development version of the provider when you run `terraform apply` or `terraform plan`.
 
 ## Building the Provider
 
 ### Requirements
 
 - [Terraform](https://www.terraform.io/downloads.html)
-- [Golang](https://golang.org/doc/install) to build the provider plugin
-- [VSCode](https://code.visualstudio.com/download) (optional, but recommended)
-- [Make](https://www.gnu.org/software/make/) For running the Makefile
-- [GoReleaser](https://goreleaser.com/install/) For creating releases
+- [Go](https://golang.org/doc/install) to build the provider plugin
+- [Visual Studio Code](https://code.visualstudio.com/download) (optional, but recommended)
+- [Make](https://www.gnu.org/software/make/) for running the Makefile
+- [GoReleaser](https://goreleaser.com/install/) for creating releases
+
+### Development Workflow
+
+```shell
+# Build the provider and install its binary in GOBIN path, /home/<your-username>/go/bin
+make install
+
+# Add new resource/data source in the `provider_code_spec.json`. Refer existing resource/data-source.
+code provider_code_spec.json
+
+# Use the following command to generate corresponding go types
+make generate-code
+
+# Scaffold code for a new resource or data source
+NAME=newresource make scaffold-rs
+
+# Modify the scaffolded code to implement the resource or data source
+code internal/provider/newresource_resource.go
+
+# Add documentation for the new resource or data source, use templates for attributes and examples. Refer existing templates.
+code templates/resources/newresource.md.tmpl
+
+# Generate the documentation for terraform registry
+make generate
+```
 
-### Setting up Local Development Environment
+### Debugging with Visual Studio Code
 
-1. Clone the repository to your local machine.
-2. Open the project in VSCode
-3. Use Makefile to build the provider plugin by running `make install` in the root directory of the provider. This will build the provider and install it in the default location, `/home/<username>/go/bin`.
-4. Feel free to explore [`Makefile`](./Makefile) for other useful commands.
+1. Set breakpoints and start the debugging session in Visual Studio Code using `launch.json` already included in the repo.
+2. Copy the value of the `TF_REATTACH_PROVIDERS` from the *DEBUG CONSOLE* tab in Visual Studio Code.
+3. Open a terminal and set the `TF_REATTACH_PROVIDERS` environment variable to the copied value.
+4. In the terminal, run `terraform apply` or `terraform plan` to trigger the provider execution and hit the breakpoints.
 
 ## Contributing
 

docs/data-sources/clusters.md

@@ -15,8 +15,8 @@ This data source provides filter functionality on clusters.
 ```terraform
 data "pf9_clusters" "example" {
   filters = [{
-    name = "name"
-    values = [ "mycluster01" ]
+    name   = "name"
+    values = ["mycluster01"]
   }]
 }
 
@@ -31,20 +31,20 @@ The following example shows how to filter clusters by tags. It is possible to co
 
 ```terraform
 data "pf9_clusters" "example" {
-    filters = [
-        {
-            name = "tags:env"
-            values = [ "production", "staging" ]
-        },
-        {
-            name = "tags:app"
-            values = [ "nginx" ]
-        }
-    ]
+  filters = [
+    {
+      name   = "tags:env"
+      values = ["production", "staging"]
+    },
+    {
+      name   = "tags:app"
+      values = ["nginx"]
+    }
+  ]
 }
 
 data "pf9_cluster" "example" {
-    id = data.pf9_clusters.example.cluster_ids[0]
+  id = data.pf9_clusters.example.cluster_ids[0]
 }
 
 # finds name of the cluster that has the
@@ -59,12 +59,12 @@ output "example" {
 
 ```terraform
 data "pf9_clusters" "example" {
-    filters = [
-        {
-            name = "tenant"
-            values = [ "service" ]
-        }
-    ]
+  filters = [
+    {
+      name   = "tenant"
+      values = ["service"]
+    }
+  ]
 }
 
 # finds IDs of the clusters from the tenant service
@@ -77,12 +77,12 @@ output "example" {
 
 ```terraform
 data "pf9_clusters" "example" {
-    filters = [
-        {
-            name = "name"
-            regexes = [ "mycluster[0-9]+" ]
-        }
-    ]
+  filters = [
+    {
+      name    = "name"
+      regexes = ["mycluster[0-9]+"]
+    }
+  ]
 }
 
 # finds IDs of the clusters that have the

docs/data-sources/hosts.md

@@ -21,7 +21,7 @@ data "pf9_hosts" "connected" {
       values = ["true"]
     },
     {
-      name   = "os_info"
+      name    = "os_info"
       regexes = ["Ubuntu.*"]
     }
   ]

docs/data-sources/kubeconfig.md

@@ -15,20 +15,20 @@ The `kubeconfig` data source enables you to generate a kubeconfig file for a clu
 ```terraform
 data "pf9_clusters" "example" {
   filters = [{
-    name = "name"
-    values = [ "mycluster01" ]
+    name   = "name"
+    values = ["mycluster01"]
   }]
 }
 
 data "pf9_kubeconfig" "example" {
-  id = data.pf9_clusters.example.cluster_ids[0]
+  id                    = data.pf9_clusters.example.cluster_ids[0]
   authentication_method = "token"
 }
 
 resource "local_file" "kubeconfig" {
-  count      = 1
-  content    = data.pf9_kubeconfig.example.raw
-  filename   = "${path.root}/kubeconfig"
+  count    = 1
+  content  = data.pf9_kubeconfig.example.raw
+  filename = "${path.root}/kubeconfig"
 }
 ```
 
@@ -38,10 +38,10 @@ resource "local_file" "kubeconfig" {
 terraform {
   required_providers {
     pf9 = {
-      source  = "platform9/pf9"
+      source = "platform9/pf9"
     }
     kubernetes = {
-      source = "hashicorp/kubernetes"
+      source  = "hashicorp/kubernetes"
       version = ">= 2.7.0"
     }
     helm = {
@@ -54,25 +54,25 @@ terraform {
 provider "pf9" {}
 
 variable "cluster_name" {
-  type = string
+  type    = string
   default = "mycluster"
 }
 
 data "pf9_clusters" "example" {
-  filters = [ {
+  filters = [{
     name   = "name"
     values = [var.cluster_name]
-  } ]
+  }]
 }
 
 data "pf9_kubeconfig" "example" {
-  id = data.pf9_clusters.example.cluster_ids[0]
+  id                    = data.pf9_clusters.example.cluster_ids[0]
   authentication_method = "token"
 }
 
 provider "kubernetes" {
-  host             = data.pf9_kubeconfig.kubeconfigs[0].endpoint
-  token            = data.pf9_kubeconfig.kubeconfigs[0].token
+  host  = data.pf9_kubeconfig.kubeconfigs[0].endpoint
+  token = data.pf9_kubeconfig.kubeconfigs[0].token
   cluster_ca_certificate = base64decode(
     data.pf9_kubeconfig.kubeconfigs[0].cluster_ca_certificate
   )

docs/data-sources/nodes.md

@@ -30,8 +30,8 @@ output "foobar" {
 # Filter nodes attached to the cluster named "mycluster"
 data "pf9_nodes" "example" {
   filter = {
-    name = "cluster_name"
-    values = [ "mycluster" ]
+    name   = "cluster_name"
+    values = ["mycluster"]
   }
 }
 ```

docs/index.md

@@ -25,7 +25,7 @@ Before you begin, ensure you have the following:
 terraform {
   required_providers {
     pf9 = {
-      source  = "platform9/pf9"
+      source = "platform9/pf9"
     }
   }
 }
@@ -45,8 +45,8 @@ provider "pf9" {
 
 # Create a cluster
 resource "pf9_cluster" "example" {
-  name = "example-cluster"
-  master_nodes = [ "<node-id>" ]
+  name         = "example-cluster"
+  master_nodes = ["<node-id>"]
   # other attributes...
 }
 ```
@@ -90,12 +90,12 @@ It is also possible to provide the node IDs using `nodes` data source.
 ```terraform
 variable "master_ip" {
   description = "The primary IP address of the master node"
-  type = string
+  type        = string
 }
 
 variable "worker1_hostname" {
   description = "The hostname of the worker node"
-  type = string
+  type        = string
 }
 
 # find node with hostname worker1
@@ -147,7 +147,7 @@ resource "pf9_cluster" "example" {
   tags = {
     "key1" = "value1"
   }
-  depends_on = [ data.pf9_host.master, data.pf9_nodes.workers ]
+  depends_on = [data.pf9_host.master, data.pf9_nodes.workers]
 }
 ```
 

examples/clusters/name.example.tf

@@ -1,10 +1,10 @@
 data "pf9_clusters" "example" {
-    filters = [
-        {
-            name = "name"
-            regexes = [ "mycluster[0-9]+" ]
-        }
-    ]
+  filters = [
+    {
+      name    = "name"
+      regexes = ["mycluster[0-9]+"]
+    }
+  ]
 }
 
 # finds IDs of the clusters that have the

examples/clusters/tags.example.tf

@@ -1,18 +1,18 @@
 data "pf9_clusters" "example" {
-    filters = [
-        {
-            name = "tags:env"
-            values = [ "production", "staging" ]
-        },
-        {
-            name = "tags:app"
-            values = [ "nginx" ]
-        }
-    ]
+  filters = [
+    {
+      name   = "tags:env"
+      values = ["production", "staging"]
+    },
+    {
+      name   = "tags:app"
+      values = ["nginx"]
+    }
+  ]
 }
 
 data "pf9_cluster" "example" {
-    id = data.pf9_clusters.example.cluster_ids[0]
+  id = data.pf9_clusters.example.cluster_ids[0]
 }
 
 # finds name of the cluster that has the

examples/clusters/tenant.example.tf

@@ -1,10 +1,10 @@
 data "pf9_clusters" "example" {
-    filters = [
-        {
-            name = "tenant"
-            values = [ "service" ]
-        }
-    ]
+  filters = [
+    {
+      name   = "tenant"
+      values = ["service"]
+    }
+  ]
 }
 
 # finds IDs of the clusters from the tenant service

examples/data-sources/pf9_clusters/data-source.tf

@@ -1,7 +1,7 @@
 data "pf9_clusters" "example" {
   filters = [{
-    name = "name"
-    values = [ "mycluster01" ]
+    name   = "name"
+    values = ["mycluster01"]
   }]
 }
 

examples/data-sources/pf9_hosts/data-source.tf

@@ -6,7 +6,7 @@ data "pf9_hosts" "connected" {
       values = ["true"]
     },
     {
-      name   = "os_info"
+      name    = "os_info"
       regexes = ["Ubuntu.*"]
     }
   ]