Improve documentation and add HCL examples

.changes/v1.0.0/35-features.md

@@ -1,3 +1,3 @@
-- **New Resource:** `vcfa_supervisor_namespace` to manage Supervisor Namespaces [GH-35, GH-58, GH-59, GH-80]
+- **New Resource:** `vcfa_supervisor_namespace` to manage Supervisor Namespaces [GH-35, GH-58, GH-59, GH-80, GH-81]
 - **New Data Source:** `vcfa_supervisor_namespace` to read Supervisor Namespaces [GH-35, GH-58, GH-59]
 - **New Data Source:** `vcfa_kubeconfig` to get Kubeconfig [GH-35, GH-59]

.changes/v1.0.0/81-notes.md

@@ -0,0 +1 @@
+* Add examples of how to use the VMware Cloud Foundation Automation Terraform Provider, that can be found [here](examples) [GH-81]

.gitignore

@@ -19,14 +19,12 @@ modules-dev/
 .vscode/
 *.iml
 *.test
-*.iml
 
 # Ignore test coverage files
 *.cover
 
 vcfa_test_config*.json
 vcfa/vcfa_test_config*.json
-vcfa_test_config*.json
 vcfa/go-vcloud-director.log
 vcfa/test-artifacts
 website/vendor

CODING_GUIDELINES.md

@@ -24,7 +24,7 @@ used when a default hashing function (which calculates hash based on all fields)
 
 ## Testing
 
-Every feature in the provider must include testing. See [TESTING.md](./TESTING.md) for more info.
+Every feature in the provider must include testing. Read [TESTING.md](TESTING.md) for more info.
 
 ## Handling Terraform Read of disappeared (removed by other means than Terraform) entities
 

README.md

@@ -1,8 +1,15 @@
 # Terraform VMware Cloud Foundation Automation Provider
 
-The official Terraform provider for VMware Cloud Foundation Automation 9+ by Broadcom
+[![Latest Release](https://img.shields.io/github/v/tag/vmware/terraform-provider-vcfa?label=latest%20release&style=for-the-badge)](https://github.com/vmware/terraform-provider-vcfa/releases/latest) [![License](https://img.shields.io/github/license/vmware/terraform-provider-vcfa.svg?style=for-the-badge)](LICENSE)
 
-- This project is using [go-vcloud-director](https://github.com/vmware/go-vcloud-director) Go SDK for making API calls
+The Terraform Provider for VMware Cloud Foundation Automation is a plugin for Terraform that allows you to interact with
+VMware Cloud Foundation Automation 9+ by Broadcom.
+
+Learn more:
+
+- Read the provider [documentation][provider-documentation]
+- Have a look at the [configuration examples][examples]
+- This project is using [go-vcloud-director][go-vcd-sdk] Go SDK for making API calls
 
 ## Part of Terraform
 
@@ -15,12 +22,12 @@ The official Terraform provider for VMware Cloud Foundation Automation 9+ by Bro
 ## Requirements
 
 - [Terraform](https://www.terraform.io/downloads.html)
-- [Go](https://golang.org/doc/install) 1.22 (to build the provider plugin)
+- [Go](https://golang.org/doc/install) 1.23 (to build the provider plugin)
 
 ## Building the Provider
 
 **Note:** You *only* need to build the provider plugin if you want to *develop* it. Refer to
-[documentation](https://registry.terraform.io/providers/vmware/vcfa/latest/docs) for using it. Terraform will
+[documentation][provider-documentation] for using it. Terraform will
 automatically download officially released binaries of this provider plugin on the first run of `terraform init`
 command.
 
@@ -51,31 +58,31 @@ with a name that includes the version (as taken from the `./VERSION` file).
 
 For example, on **macOS**:
 
-```shell
+```console
 $HOME/.terraform.d/
 ├── checkpoint_cache
 ├── checkpoint_signature
 └── plugins
     └── registry.terraform.io
         └── vmware
             └── vcfa
-                └── 0.1.0
+                └── 1.0.0
                     └── darwin_amd64
-                        └── terraform-provider-vcfa_v0.1.0
+                        └── terraform-provider-vcfa_v1.0.0
 ```
 
 On **Linux**:
 
-```shell
+```console
 ├── checkpoint_cache
 ├── checkpoint_signature
 └── plugins
     └── registry.terraform.io
         └── vmware
             └── vcfa
-                └── 0.1.0
+                └── 1.0.0
                     └── linux_amd64
-                        └── terraform-provider-vcfa_v0.1.0
+                        └── terraform-provider-vcfa_v1.0.0
 ```
 
 Once you have installed the plugin as mentioned above, you can simply create a new `config.tf` as defined in [the manual](https://www.terraform.io/docs/providers/vcfa/index.html) and run
@@ -114,9 +121,24 @@ You can also replace pointer to a branch with relative directory:
 replace github.com/vmware/go-vcloud-director/v3 v3.1.0-alpha.2 => ../go-vcloud-director
 ```
 
-See [CODING_GUIDELINES.md](./CODING_GUIDELINES.md) for more advice on how to write code for this project.
+See [CODING_GUIDELINES.md][coding-guidelines] for more advice on how to write code for this project.
 
 ## Troubleshooting the Provider
 
-Read [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) to learn how to configure and understand logs, and how to
+Read [TROUBLESHOOTING.md][troubleshooting] to learn how to configure and understand logs, and how to
 diagnose common errors.
+
+## License
+
+© Broadcom. All Rights Reserved.
+The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.
+
+The Terraform Provider for VMware Cloud Foundation Automation is available under the
+[Mozilla Public License, version 2.0][provider-license] license.
+
+[coding-guidelines]: CODING_GUIDELINES.md
+[examples]: examples
+[go-vcd-sdk]: https://github.com/vmware/go-vcloud-director
+[provider-documentation]: https://registry.terraform.io/providers/vmware/vcfa/latest/docs
+[provider-license]: LICENSE
+[troubleshooting]: TROUBLESHOOTING.md

TESTING.md

@@ -1,4 +1,4 @@
-# Testing terraform-provider-vcfa
+# Testing the Terraform Provider for VMware Cloud Foundation Automation
 
 ## Table of contents
 

TROUBLESHOOTING.md

@@ -67,7 +67,7 @@ Terraform provider plugins follow [semantic versioning][semver] pattern and
 terraform {
   required_providers {
     vcfa = {
-      source = "vmware/vcfa"
+      source  = "vmware/vcfa"
       version = "~> 1.0.0" # pins major and minor versions, but will accept new patch versions (e.g. 1.0.1)
     }
   }

examples/README.md

@@ -0,0 +1,6 @@
+# Example configuration files for the Terraform Provider for VMware Cloud Foundation Automation
+
+In this folder you can find configuration files (`.tf`) for several use cases in VMware Cloud Foundation Automation:
+
+- [Greenfield deployment](greenfield): The Terraform files describe the configuration to apply to a completely fresh installation
+  of VMware Cloud Foundation Automation

examples/greenfield/README.md

@@ -0,0 +1,9 @@
+# Greenfield configuration for VMware Cloud Foundation Automation
+
+In this folder you can find configuration files (`.tf`) to apply to a completely fresh installation of VMware Cloud Foundation Automation.
+
+It is divided into two parts, corresponding to two main roles:
+
+- [`provider`](provider): Is the part that the VMware Cloud Foundation Automation administrator will apply to create the
+  required Organizations (tenants) and configure the underlying infrastructure (vCenter, NSX, Provider Gateways, roles...)
+- [`tenant`](tenant): Is the part that a tenant user will apply to configure the layout of the Organization, like Content Libraries

examples/greenfield/provider/01-provider.tf

@@ -0,0 +1,27 @@
+# Configure the VMware Cloud Foundation Automation Terraform Provider
+
+terraform {
+  required_providers {
+    vcfa = {
+      source  = "vmware/vcfa"
+      version = "~> 1.0.0"
+    }
+  }
+}
+
+provider "vcfa" {
+  user                 = var.username
+  password             = var.password
+  url                  = var.url
+  org                  = "System" # Login in the Provider (System) org
+  allow_unverified_ssl = "true"
+  logging              = true # Generates the log file for troubleshooting
+}
+
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/data-sources/org
+data "vcfa_org" "system" {
+  name = "System"
+}
+
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/data-sources/kubeconfig
+data "vcfa_kubeconfig" "example" {}

examples/greenfield/provider/01-provider_variables.tf

@@ -0,0 +1,15 @@
+variable "url" {
+  type        = string
+  description = "VMware Cloud Foundation Automation URL, e.g. https://HOST"
+}
+
+variable "username" {
+  type        = string
+  description = "Username for authenticating"
+}
+
+variable "password" {
+  type        = string
+  sensitive   = true
+  description = "Password for a given 'username'"
+}

examples/greenfield/provider/02-sddc.tf

@@ -0,0 +1,25 @@
+# Configure underlying vCenter and NSX
+
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/resources/nsx_manager
+resource "vcfa_nsx_manager" "example" {
+  name                   = "tf-example-nsx-manager"
+  description            = "Created by Terraform VCFA Provider"
+  username               = var.nsx_manager_username
+  password               = var.nsx_manager_password
+  url                    = var.nsx_manager_url
+  auto_trust_certificate = true
+}
+
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/resources/vcenter
+resource "vcfa_vcenter" "example" {
+  nsx_manager_id             = vcfa_nsx_manager.example.id
+  name                       = "tf-example-vcenter"
+  description                = "Created by Terraform VCFA Provider"
+  url                        = var.vcenter_url
+  auto_trust_certificate     = true
+  refresh_vcenter_on_create  = true
+  refresh_policies_on_create = true
+  username                   = var.vcenter_username
+  password                   = var.vcenter_password
+  is_enabled                 = true
+}

examples/greenfield/provider/02-sddc_variables.tf

@@ -0,0 +1,31 @@
+variable "vcenter_url" {
+  type        = string
+  description = "URL of vCenter, e.g. https://HOST"
+}
+
+variable "vcenter_username" {
+  type        = string
+  description = "Username for authenticating to vCenter"
+}
+
+variable "vcenter_password" {
+  type        = string
+  sensitive   = true
+  description = "Password for a given 'vcenter_username'"
+}
+
+variable "nsx_manager_url" {
+  type        = string
+  description = "URL of NSX manager, e.g. https://HOST"
+}
+
+variable "nsx_manager_username" {
+  type        = string
+  description = "Username for authenticating to NSX Manager"
+}
+
+variable "nsx_manager_password" {
+  type        = string
+  sensitive   = true
+  description = "Password for a given 'nsx_manager_username'"
+}

examples/greenfield/provider/03-organizations.tf

@@ -0,0 +1,40 @@
+# Create some Organizations (tenants)
+
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/resources/org
+resource "vcfa_org" "example" {
+  name         = "tf-example-org"
+  display_name = "tf-example-org"
+  description  = "Created by Terraform VCFA Provider"
+  is_enabled   = true
+}
+
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/resources/org_settings
+resource "vcfa_org_settings" "example" {
+  org_id                           = vcfa_org.example.id
+  can_create_subscribed_libraries  = true
+  quarantine_content_library_items = false
+}
+
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/data-sources/role
+data "vcfa_role" "org-admin" {
+  org_id = vcfa_org.example.id
+  name   = "Organization Administrator"
+}
+
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/resources/org_local_user
+resource "vcfa_org_local_user" "example" {
+  org_id   = vcfa_org.example.id
+  role_ids = [data.vcfa_role.org-admin.id]
+  username = "tf-example-local-user"
+  password = "long-change-ME1"
+}
+
+# A classic VRA-style organization. See "is_classic_tenant" argument at:
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/resources/org
+resource "vcfa_org" "example-classic" {
+  name              = "tf-example-org-classic"
+  display_name      = "tf-example-org-classic"
+  description       = "Created by Terraform VCFA Provider"
+  is_classic_tenant = true
+  is_enabled        = true
+}

examples/greenfield/provider/04-access_control.tf

@@ -0,0 +1,46 @@
+# Create some Rights Bundles and Roles
+
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/resources/rights_bundle
+resource "vcfa_rights_bundle" "example" {
+  name        = "tf-example-rights-bundle"
+  description = "Created by Terraform VCFA Provider"
+  rights = [
+    "Content Library: View",
+    "Content Library Item: View",
+    "Group / User: View",
+    "IP Blocks: View",
+  ]
+  publish_to_all_orgs = false
+  org_ids = [
+    vcfa_org.example.id
+  ]
+}
+
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/resources/role
+resource "vcfa_role" "example-role" {
+  org_id      = vcfa_org.example.id
+  name        = "tf-example-role"
+  description = "Created by Terraform VCFA Provider"
+  rights = [
+    "Content Library: View",
+    "Content Library Item: View",
+    "Group / User: View",
+    "IP Blocks: View",
+  ]
+}
+
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/resources/global_role
+resource "vcfa_global_role" "new-global-role" {
+  name        = "tf-example-global-role"
+  description = "Created by Terraform VCFA Provider"
+  rights = [
+    "Content Library: View",
+    "Content Library Item: View",
+    "Group / User: View",
+    "IP Blocks: View",
+  ]
+  publish_to_all_orgs = false
+  org_ids = [
+    vcfa_org.example.id
+  ]
+}

examples/greenfield/provider/05-regions.tf

@@ -0,0 +1,22 @@
+# Create a Region
+
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/data-sources/supervisor
+data "vcfa_supervisor" "example" {
+  name       = var.supervisor_name
+  vcenter_id = vcfa_vcenter.example.id
+}
+
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/data-sources/supervisor_zone
+data "vcfa_supervisor_zone" "example" {
+  supervisor_id = data.vcfa_supervisor.example.id
+  name          = var.supervisor_zone_name
+}
+
+# https://registry.terraform.io/providers/vmware/vcfa/latest/docs/resources/region
+resource "vcfa_region" "example" {
+  name                 = "tf-example-region"
+  description          = "Created by Terraform VCFA Provider"
+  nsx_manager_id       = vcfa_nsx_manager.example.id
+  supervisor_ids       = [data.vcfa_supervisor.example.id]
+  storage_policy_names = var.vcenter_storage_policy_names[*]
+}

examples/greenfield/provider/05-regions_variables.tf

@@ -0,0 +1,14 @@
+variable "supervisor_name" {
+  type        = string
+  description = "Name of Supervisor in vCenter"
+}
+
+variable "supervisor_zone_name" {
+  type        = string
+  description = "Name of Supervisor Zone in vCenter"
+}
+
+variable "vcenter_storage_policy_names" {
+  type        = set(string)
+  description = "vCenter storage profiles"
+}