config - add Chaos Studio Target resource definition (#3671)

* add new properties to resource generation guide

* add contents of files

* review comments

config/resources/chaosstudio.hcl

@@ -0,0 +1,29 @@
+service "ChaosStudio" {
+  terraform_package = "chaosstudio"
+
+  api "2023-11-01" {
+    package "Targets" {
+      definition "chaos_studio_target" {
+        id                  = "/{scope}/providers/Microsoft.Chaos/targets/{targetName}"
+        display_name        = "Chaos Studio Target"
+        website_subcategory = "Chaos Studio"
+        description         = "Manages a Chaos Studio Target"
+        generate_create     = false
+        overrides "name" {
+          updated_name = "target_type"
+          description = "The name of the Chaos Studio Target. This has the format of [publisher]-[targetType] e.g. `Microsoft-StorageAccount`. For supported values please see this Target Type column in [this table](https://learn.microsoft.com/azure/chaos-studio/chaos-studio-fault-providers)."
+        }
+        overrides "scope" {
+          updated_name = "target_resource_id"
+        }
+        test_data {
+          basic_variables {
+            strings = {
+              "target_type" = "Microsoft-AzureKubernetesServiceChaosMesh"
+            }
+          }
+        }
+      }
+    }
+  }
+}

docs/resource-manager-generate-new-resource.md

@@ -39,6 +39,10 @@ service "ContainerService" {
 Manages a Kubernetes Cluster Trusted Access Role Binding
 ~> **Note:** This Resource is in **Preview** to use this you must be opted into the Preview. You can do this by running `az feature register --namespace Microsoft.ContainerService --name TrustedAccessPreview` and then `az provider register -n Microsoft.ContainerService`
 HERE
+        overrides "resource_id" {
+          updated_name = "source_resource_id"
+          description = "A special description here."
+        }
         test_data {
           basic_variables {
             lists = {
@@ -66,10 +70,11 @@ HERE
 The example above consists of the following properties:
 
 * Labels:
-  * `Compute` - (Required) - This is the name of the Service defined in Pandora, it is identical to the directory name containing the Pandora API definitions residing in [ `./api-definitions`](https://github.com/hashicorp/pandora/blob/main/api-definitions)
-  * `2021-11-01` - (Required) - This is the Version of the Service
-  * `VirtualMachines`, `VirtualMachineScaleSets` - (Required) - This is the name of the Resource for which there are Pandora API definitions
-  * `virtual_machine`, `virtual_machine_scale_set` - (Required) - This is the name that the resource should have in the AzureRM provider with the `azurerm` prefix omitted. The prefix will be added automatically during generation
+  * `ContainerService` - (Required) - This is the name of the Service defined in Pandora, it is identical to the directory name containing the Pandora API definitions residing in [ `./api-definitions`](https://github.com/hashicorp/pandora/blob/main/api-definitions)
+  * `2022-09-02-preview`, `2023-03-02-preview` - (Required) - These are the API Versions from which the resources are generated from.
+  * `Fleets`, `TrustedAccess` - (Required) - This is the name of the API Resource(s) within the Service/API Version where the Resource(s) are located.
+  * `kubernetes_fleet_manager`, `kubernetes_cluster_trusted_access_role_binding` - (Required) - This specifies [the Resource Type](https://developer.hashicorp.com/terraform/language/resources/syntax#resource-types) without the provider prefix (e.g. `azurerm_kubernetes_fleet_manager` would be `kubernetes_fleet_manager`). The provider prefix (e.g. `azurerm`) will be added automatically during generation.
+  * `resource_id` - (Required) - When overrides are specified the label defines which API property the overrides should be applied to
 * `id` - (Required) - This is the resource ID that the resource should have. Segments must be camel cased and user specified segments are expressed in curly braces e.g. {resourceName}
 * `display_name` - (Required) - This is the name we use when referring to the resource in the documentation
 * `website_subcategory` - (Required) - This is the documentation category that the resource belongs to
@@ -79,11 +84,16 @@ The example above consists of the following properties:
 
 In addition to the properties above there are also several options that are available to control the generation of a resource.
 
+* `generate_create` - (Optional) - Whether to generate the create method for this resource, defaults to `true`
+* `generate_read` - (Optional) - Whether to generate the read method for this resource, defaults to `true`
+* `generate_update` - (Optional) - Whether to generate the update method for this resource, defaults to `true`
+* `generate_delete` - (Optional) - Whether to generate the delete method for this resource, defaults to `true`
 * `test_data` - (Optional) - One test data block that allows us to customise the test data to be used in the basic and complete tests
 * `basic_variables` - (Optional) - One basic variable block that specifies custom values for test data in the basic resource test
 * `complete_variables` - (Optional) - One complete variable block that specifies custom values for test data in the complete resource test
 * `lists` - (Optional) - This is a map of property name to list, e.g. if there is a list property in a resource that requires a custom value it would be specified in this map
 * `strings` - (Optional) - This is a map of property name to string, e.g. if there is a string property in a resource that requires a custom value it would be specified in this map
+* `overrides` - (Optional) - One or more overrides blocks that will apply property renames and custom documentation descriptions to the property
 
 ### Workflow
 

docs/resource-manager-partial-resource-generation.md

@@ -0,0 +1,63 @@
+## Guide: Partially generating a new (Resource Manager) Resource
+
+There are instances where we might only want to generate parts of a resource, e.g. everything except for the update which can require special logic to do.
+
+This guide walks through an example for the resource `azurerm_chaos_studio_target` where we generate everything but handwrite the create method.
+
+### Prerequisites and Known Limitations
+
+At the moment only the resource's Create/Read/Update/Delete methods can be toggled for generation. It isn't possible to toggle test generation yet.
+
+### Example
+
+```hcl
+service "ChaosStudio" {
+  terraform_package = "chaosstudio"
+
+  api "2023-11-01" {
+    package "Targets" {
+      definition "chaos_studio_target" {
+        id                  = "/{scope}/providers/Microsoft.Chaos/targets/{targetName}"
+        display_name        = "Chaos Studio Target"
+        website_subcategory = "Chaos Studio"
+        description         = "Manages a Chaos Studio Target"
+        generate_create     = false
+        overrides "name" {
+          updated_name = "target_type"
+          description = "The name of the Chaos Studio Target. This has the format of [publisher]-[targetType] e.g. `Microsoft-StorageAccount`. For supported values please see this Target Type column in [this table](https://learn.microsoft.com/azure/chaos-studio/chaos-studio-fault-providers)."
+        }
+        overrides "scope" {
+          updated_name = "target_resource_id"
+        }
+        test_data {
+          basic_variables {
+            strings = {
+              "target_type" = "Microsoft-AzureKubernetesServiceChaosMesh"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The configuration above will generate the resource `azurerm_chaos_studio_target` but without the create method.
+
+In addition to not generating the create method we are also applying overrides to the fields `name` and `scope`, renaming them to `target_type` and `target_resource_id` respectively.
+
+The property `name` also has a custom description applied that gives the user more information on what the field is and what information we expect in it.
+
+### Workflow
+
+For partially generated resources we need to add the pieces in a specific order. For this particular example the order is as follows:
+
+1. Open a PR to add the following files to the `hashicorp/terraform-azurerm-provider` repository under the path `internal/services/chaosstudio`:
+    * `client/client_gen.go` - contains the initialisation of the Chaos Studio client, this file will be overwritten
+    * `chaos_studio_target_resource_create.go` - contains the handwritten create method for the Chaos Studio Target resource. See [this PR](https://github.com/hashicorp/terraform-provider-azurerm/pull/24580) as an example.
+    * `chaos_studio_target_resource_gen.go` - contains the initialised typed resource, but with the bare minimum information so that `chaos_studio_target_resource_create.go` can be added without causing a compile error. This file will be overwritten with the correct information when the automated PR is opened on the repository.
+    * `registration.go` - contains the registration information for the resource
+    * `registration_gen.go` - contains the registration information for generated resources, this file will be overwritten as well
+2. Once the PR from step 1. has been merged we can open a PR on `hashicorp/pandora` adding the resource definition defined in the [Example](#example)
+3. When the PR from step 2. has been merged `hashicorp/pandora` will run `./tools/importer-rest-api-specs`, which imports the API Definitions and builds up the Resource Definition, Tests and Documentation for each Terraform Resource. These are generated and sent as an auto-PR to `hashicorp/pandora` for review.
+4. When the PR from step 3. has been merged `hashicorp/pandora` will generate each of the Terraform Resources into `hashicorp/terraform-provider-azurerm` and send a PR to that repository. Note that as a part of this, any filenames matching `*_gen.go` (such as those added in step 1.) will be overwritten.