From 76e05af87c649d5eded0af07d14ec5d4145d496d Mon Sep 17 00:00:00 2001 From: Nilesh Date: Tue, 18 Jun 2024 14:29:02 +0530 Subject: [PATCH] Documentation improvements --- .gitignore | 5 +- .vscode/launch.json | 1 - README.md | 59 ++++++++++++------- docs/data-sources/clusters.md | 50 ++++++++-------- docs/data-sources/hosts.md | 2 +- docs/data-sources/kubeconfig.md | 28 ++++----- docs/data-sources/nodes.md | 4 +- .../guides}/attach-detach-nodes.md | 0 .../guides}/create-cluster-with-settings.md | 0 .../guides}/import-existing-cluster.md | 0 {guides => docs/guides}/manage-addons.md | 0 {guides => docs/guides}/upgrading-clusters.md | 0 docs/index.md | 12 ++-- examples/clusters/name.example.tf | 12 ++-- examples/clusters/tags.example.tf | 22 +++---- examples/clusters/tenant.example.tf | 12 ++-- .../data-sources/pf9_clusters/data-source.tf | 4 +- .../data-sources/pf9_hosts/data-source.tf | 2 +- .../pf9_kubeconfig/data-source.tf | 12 ++-- .../pf9_kubeconfig/with-helm-provider.tf | 16 ++--- .../data-sources/pf9_nodes/data-source.tf | 4 +- examples/provider/provider.tf | 6 +- .../resources/pf9_cluster/example_nodes.tf | 6 +- 23 files changed, 139 insertions(+), 118 deletions(-) rename {guides => docs/guides}/attach-detach-nodes.md (100%) rename {guides => docs/guides}/create-cluster-with-settings.md (100%) rename {guides => docs/guides}/import-existing-cluster.md (100%) rename {guides => docs/guides}/manage-addons.md (100%) rename {guides => docs/guides}/upgrading-clusters.md (100%) diff --git a/.gitignore b/.gitignore index 8570d77..c2ea0fe 100644 --- a/.gitignore +++ b/.gitignore @@ -35,4 +35,7 @@ TODO.md pf9-sdk-go pf9-sdk-go/ pf9-sdk-go/* -pf9-sdk-go/** \ No newline at end of file +pf9-sdk-go/** + +# Prevents accidental commiting secrets +*.tfvars diff --git a/.vscode/launch.json b/.vscode/launch.json index 47707eb..3a6d4b1 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -8,7 +8,6 @@ "mode": "debug", "program": "${workspaceFolder}", "env": { - "DU_PASSWORD": "", "TF_LOG": "DEBUG", }, "args": [ diff --git a/README.md b/README.md index b0aa446..bd5d4f9 100644 --- a/README.md +++ b/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" = "" + # Replace the path with the location where the provider binary is installed on your system. + "platform9/pf9" = "/home//go/bin" } direct {} } ``` -Replace `` 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 `` to the path of the binary generated by running `go install .` in the root directory of the provider. For example, `/home//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//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//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 diff --git a/docs/data-sources/clusters.md b/docs/data-sources/clusters.md index 3024440..9c79e2b 100644 --- a/docs/data-sources/clusters.md +++ b/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 diff --git a/docs/data-sources/hosts.md b/docs/data-sources/hosts.md index f626f35..9a54d3d 100644 --- a/docs/data-sources/hosts.md +++ b/docs/data-sources/hosts.md @@ -21,7 +21,7 @@ data "pf9_hosts" "connected" { values = ["true"] }, { - name = "os_info" + name = "os_info" regexes = ["Ubuntu.*"] } ] diff --git a/docs/data-sources/kubeconfig.md b/docs/data-sources/kubeconfig.md index 90437bc..d1a4ea1 100644 --- a/docs/data-sources/kubeconfig.md +++ b/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 ) diff --git a/docs/data-sources/nodes.md b/docs/data-sources/nodes.md index a7980ac..dac6e4d 100644 --- a/docs/data-sources/nodes.md +++ b/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"] } } ``` diff --git a/guides/attach-detach-nodes.md b/docs/guides/attach-detach-nodes.md similarity index 100% rename from guides/attach-detach-nodes.md rename to docs/guides/attach-detach-nodes.md diff --git a/guides/create-cluster-with-settings.md b/docs/guides/create-cluster-with-settings.md similarity index 100% rename from guides/create-cluster-with-settings.md rename to docs/guides/create-cluster-with-settings.md diff --git a/guides/import-existing-cluster.md b/docs/guides/import-existing-cluster.md similarity index 100% rename from guides/import-existing-cluster.md rename to docs/guides/import-existing-cluster.md diff --git a/guides/manage-addons.md b/docs/guides/manage-addons.md similarity index 100% rename from guides/manage-addons.md rename to docs/guides/manage-addons.md diff --git a/guides/upgrading-clusters.md b/docs/guides/upgrading-clusters.md similarity index 100% rename from guides/upgrading-clusters.md rename to docs/guides/upgrading-clusters.md diff --git a/docs/index.md b/docs/index.md index 27219c9..7c4f5f1 100644 --- a/docs/index.md +++ b/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 = [ "" ] + name = "example-cluster" + master_nodes = [""] # 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] } ``` diff --git a/examples/clusters/name.example.tf b/examples/clusters/name.example.tf index 7c8fbbf..be9f007 100644 --- a/examples/clusters/name.example.tf +++ b/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 diff --git a/examples/clusters/tags.example.tf b/examples/clusters/tags.example.tf index 1fdd70b..ddf0168 100644 --- a/examples/clusters/tags.example.tf +++ b/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 diff --git a/examples/clusters/tenant.example.tf b/examples/clusters/tenant.example.tf index d8fc2ee..e39347a 100644 --- a/examples/clusters/tenant.example.tf +++ b/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 diff --git a/examples/data-sources/pf9_clusters/data-source.tf b/examples/data-sources/pf9_clusters/data-source.tf index dced9c0..f614613 100644 --- a/examples/data-sources/pf9_clusters/data-source.tf +++ b/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"] }] } diff --git a/examples/data-sources/pf9_hosts/data-source.tf b/examples/data-sources/pf9_hosts/data-source.tf index 047354e..79fc815 100644 --- a/examples/data-sources/pf9_hosts/data-source.tf +++ b/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.*"] } ] diff --git a/examples/data-sources/pf9_kubeconfig/data-source.tf b/examples/data-sources/pf9_kubeconfig/data-source.tf index 015b7dc..1368e2e 100644 --- a/examples/data-sources/pf9_kubeconfig/data-source.tf +++ b/examples/data-sources/pf9_kubeconfig/data-source.tf @@ -1,17 +1,17 @@ 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" } \ No newline at end of file diff --git a/examples/data-sources/pf9_kubeconfig/with-helm-provider.tf b/examples/data-sources/pf9_kubeconfig/with-helm-provider.tf index 7d944a1..7c98d12 100644 --- a/examples/data-sources/pf9_kubeconfig/with-helm-provider.tf +++ b/examples/data-sources/pf9_kubeconfig/with-helm-provider.tf @@ -1,10 +1,10 @@ terraform { required_providers { pf9 = { - source = "platform9/pf9" + source = "platform9/pf9" } kubernetes = { - source = "hashicorp/kubernetes" + source = "hashicorp/kubernetes" version = ">= 2.7.0" } helm = { @@ -17,25 +17,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 ) diff --git a/examples/data-sources/pf9_nodes/data-source.tf b/examples/data-sources/pf9_nodes/data-source.tf index 43d3a4f..f608df5 100644 --- a/examples/data-sources/pf9_nodes/data-source.tf +++ b/examples/data-sources/pf9_nodes/data-source.tf @@ -15,7 +15,7 @@ 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"] } } \ No newline at end of file diff --git a/examples/provider/provider.tf b/examples/provider/provider.tf index 86b275f..5efaa6e 100644 --- a/examples/provider/provider.tf +++ b/examples/provider/provider.tf @@ -1,7 +1,7 @@ terraform { required_providers { pf9 = { - source = "platform9/pf9" + source = "platform9/pf9" } } } @@ -21,7 +21,7 @@ provider "pf9" { # Create a cluster resource "pf9_cluster" "example" { - name = "example-cluster" - master_nodes = [ "" ] + name = "example-cluster" + master_nodes = [""] # other attributes... } \ No newline at end of file diff --git a/examples/resources/pf9_cluster/example_nodes.tf b/examples/resources/pf9_cluster/example_nodes.tf index 2c37a49..b1a62d7 100644 --- a/examples/resources/pf9_cluster/example_nodes.tf +++ b/examples/resources/pf9_cluster/example_nodes.tf @@ -1,11 +1,11 @@ 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 @@ -57,5 +57,5 @@ 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] }