docs: DOC-1208 updated the documentation for the pack data resources (#464)

karl-cardenas-coding · web-flow · commit dc2ec987564e · 2024-06-07T22:53:25.000+05:30
* docs:  DOC-1208 updated the documentation for the pack data resources

* chore: fixed resource name in example

* docs: added types definition
diff --git a/docs/data-sources/pack.md b/docs/data-sources/pack.md
@@ -1,30 +1,52 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "spectrocloud_pack Data Source - terraform-provider-spectrocloud"
 subcategory: ""
 description: |-
-  
+  This data resource provides the ability to search for a pack in the Palette registries. It supports more advanced search criteria than the pack_simple data source.
 ---
 
 # spectrocloud_pack (Data Source)
 
+  This data resource provides the ability to search for a pack in the Palette registries. It supports more advanced search criteria than the pack_simple data source.
 
 
+
+~> Starting with version 0.21.0 the attribute `registry_uid` is required.
+
 ## Example Usage
 
-```terraform
-data "spectrocloud_pack" "cni-calico" {
-  name    = "cni-calico"
-  version = "3.16.0"
 
-  # (alternatively)
-  # id =  "5fd0ca727c411c71b55a359c"
-  # name = "cni-calico-azure"
-  # cloud = ["azure"]
+An example of how to use this data source to retrieve a specific pack from the community registry.
+
+```hcl
+data "spectrocloud_registry" "community_registry" {
+  name = "Palette Community Registry"
+}
+
+
+data "spectrocloud_pack" "hellouniverse" {
+  name         = "hello-universe"
+  version      = "1.1.2"
+  registry_uid = data.spectrocloud_registry.community_registry.id
 }
+```
+
+
+In this example, a filter is applied to retrieve a Calico CNI pack from the Palette OCI registry that is compatible with Edge clusters and has a version greater than 3.26.9.
+
+-> The filter attribute is a string that can contain multiple filters separated by the `AND`, `OR` operator. You can filter for a pack by using the attributes retured in the `spec` object of the payload provided by the `v1/packs/search` endpoint.
+Refer to the Palette Pack Search API endpoint [documentation](https://docs.spectrocloud.com/api/v1/v-1-packs-search/) for more information on the available filters.
+
+
+
+```hcl
+data "spectrocloud_registry" "palette_registry_oci" {
+  name = "Palette Registry"
+}
+
 
-output "same" {
-  value = data.spectrocloud_pack.cni-calico
+data "spectrocloud_pack" "cni" {
+  filters = "spec.cloudTypes=edge-nativeANDspec.layer=cniANDspec.displayName=CalicoANDspec.version>3.26.9ANDspec.registryUid=${data.spectrocloud_registry.palette_registry_oci.id}"
 }
 ```
 
@@ -33,14 +55,14 @@ output "same" {
 
 ### Optional
 
-- `cloud` (Set of String)
-- `filters` (String)
-- `name` (String)
-- `registry_uid` (String)
-- `type` (String)
-- `version` (String)
+- `cloud` (Set of String) Filter results by cloud type. If not provided, all cloud types are returned.
+- `filters` (String) Filters to apply when searching for a pack. This is a string of the form 'key1=value1' with 'AND', 'OR` operators. Refer to the Palette API [pack search API endpoint documentation](https://docs.spectrocloud.com/api/v1/v-1-packs-search/) for filter examples..
+- `id` (String) The UID of the pack returned.
+- `name` (String) The name of the pack to search for.
+- `registry_uid` (String) The UID of the registry to search for the pack in. This is a required parameter starting from version 0.21.0.
+- `type` (String) The type of pack to search for. Supported values are `helm`, `manifest`, `container`, `operator-instance`.
+- `version` (String) The version of the pack to search for.
 
 ### Read-Only
 
-- `id` (String) The ID of this resource.
-- `values` (String)
+- `values` (String) The YAML values of the pack returned as string.
diff --git a/docs/data-sources/pack_simple.md b/docs/data-sources/pack_simple.md
@@ -2,15 +2,17 @@
 page_title: "spectrocloud_pack_simple Data Source - terraform-provider-spectrocloud"
 subcategory: ""
 description: |-
-  
+  This data resource provides a simpler user experience for searching for a pack in Palette registries.
 ---
 
 # spectrocloud_pack_simple (Data Source)
 
-  
+  This data resource provides a simpler user experience for searching for a pack in Palette registries.
 
 ## Example Usage
 
+~> Starting with version 0.21.0 the attribute `registry_uid` is required.
+
 ```hcl
 data "spectrocloud_registry" "registry" {
   name = "Public Repo"
@@ -36,7 +38,7 @@ data "spectrocloud_pack_simple" "pack" {
 ### Optional
 
 - `context` (String) Indicates in which context registry should be searched for the pack values. Allowed values are `system`, `project` or `tenant`. Defaults to `project`.If  the `project` context is specified, the project name will sourced from the provider configuration parameter [`project_name`](https://registry.terraform.io/providers/spectrocloud/spectrocloud/latest/docs#schema).
-- `registry_uid` (String) The unique identifier of the registry the pack belongs to.
+- `registry_uid` (String) The unique identifier of the registry the pack belongs to. This is a required parameter starting from version 0.21.0
 - `version` (String) The version of the pack.
 
 ### Read-Only
diff --git a/spectrocloud/data_source_pack.go b/spectrocloud/data_source_pack.go
@@ -14,50 +14,59 @@ import (
 func dataSourcePack() *schema.Resource {
 	return &schema.Resource{
 		ReadContext: dataSourcePackRead,
+		Description: "This data resource provides the ability to search for a pack in the Palette registries. It supports more advanced search criteria than the `pack_simple` data source.",
 
 		Schema: map[string]*schema.Schema{
 			"filters": {
 				Type:          schema.TypeString,
 				Optional:      true,
+				Description:  "Filters to apply when searching for a pack. This is a string of the form 'key1=value1' with 'AND', 'OR` operators. Refer to the Palette API [pack search API endpoint documentation](https://docs.spectrocloud.com/api/v1/v-1-packs-search/) for filter examples..",
 				ConflictsWith: []string{"id", "cloud", "name", "version", "registry_uid"},
 			},
 			"id": {
 				Type:          schema.TypeString,
 				Computed:      true,
 				Optional:      true,
+				Description:  "The UID of the pack returned.",
 				ConflictsWith: []string{"filters", "cloud", "name", "version", "registry_uid"},
 			},
 			"name": {
 				Type:     schema.TypeString,
+				Description: "The name of the pack to search for.",
 				Computed: true,
 				Optional: true,
 			},
 			"cloud": {
 				Type:     schema.TypeSet,
 				Optional: true,
 				Computed: true,
+				Description: "Filter results by cloud type. If not provided, all cloud types are returned.",
 				Set:      schema.HashString,
 				Elem: &schema.Schema{
 					Type: schema.TypeString,
 				},
 			},
 			"version": {
 				Type:     schema.TypeString,
+				Description: "The version of the pack to search for.",
 				Computed: true,
 				Optional: true,
 			},
 			"registry_uid": {
 				Type:     schema.TypeString,
+				Description: "The UID of the registry to search for the pack in. This is a required parameter starting from version 0.21.0.",
 				Computed: true,
 				Optional: true,
 			},
 			"type": {
 				Type:     schema.TypeString,
+				Description: "The type of pack to search for. Supported values are `helm`, `manifest`, `container`, `operator-instance`.",
 				Computed: true,
 				Optional: true,
 			},
 			"values": {
 				Type:     schema.TypeString,
+				Description: "The YAML values of the pack returned as string.",
 				Computed: true,
 			},
 		},
diff --git a/spectrocloud/data_source_pack_simple.go b/spectrocloud/data_source_pack_simple.go
@@ -16,6 +16,7 @@ import (
 func dataSourcePackSimple() *schema.Resource {
 	return &schema.Resource{
 		ReadContext: dataSourcePackReadSimple,
+		Description: "This data resource provides a simpler user experience for searching for a pack in Palette registries.",
 
 		Schema: map[string]*schema.Schema{
 			"name": {
@@ -39,7 +40,7 @@ func dataSourcePackSimple() *schema.Resource {
 			"registry_uid": {
 				Type:        schema.TypeString,
 				Optional:    true,
-				Description: "The unique identifier of the registry the pack belongs to.",
+				Description: "The unique identifier of the registry the pack belongs to. This is a required parameter starting from version 0.21.0",
 			},
 			"type": {
 				Type:         schema.TypeString,
diff --git a/templates/data-sources/pack.md.tmpl b/templates/data-sources/pack.md.tmpl
@@ -0,0 +1,53 @@
+---
+page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}"
+subcategory: ""
+description: |-
+{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
+---
+
+# {{.Name}} ({{.Type}})
+
+{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
+
+
+
+~> Starting with version 0.21.0 the attribute `registry_uid` is required.
+
+## Example Usage
+
+
+An example of how to use this data source to retrieve a specific pack from the community registry.
+
+```hcl
+data "spectrocloud_registry" "community_registry" {
+  name = "Palette Community Registry"
+}
+
+
+data "spectrocloud_pack" "hellouniverse" {
+  name         = "hello-universe"
+  version      = "1.1.2"
+  registry_uid = data.spectrocloud_registry.community_registry.id
+}
+```
+
+
+In this example, a filter is applied to retrieve a Calico CNI pack from the Palette OCI registry that is compatible with Edge clusters and has a version greater than 3.26.9.
+
+-> The filter attribute is a string that can contain multiple filters separated by the `AND`, `OR` operator. You can filter for a pack by using the attributes retured in the `spec` object of the payload provided by the `v1/packs/search` endpoint.
+Refer to the Palette Pack Search API endpoint [documentation](https://docs.spectrocloud.com/api/v1/v-1-packs-search/) for more information on the available filters.
+
+
+
+```hcl
+data "spectrocloud_registry" "palette_registry_oci" {
+  name = "Palette Registry"
+}
+
+
+data "spectrocloud_pack" "cni" {
+  filters = "spec.cloudTypes=edge-nativeANDspec.layer=cniANDspec.displayName=CalicoANDspec.version>3.26.9ANDspec.registryUid=${data.spectrocloud_registry.palette_registry_oci.id}"
+}
+```
+
+{{ .SchemaMarkdown | trimspace }}
diff --git a/templates/data-sources/pack_simple.md.tmpl b/templates/data-sources/pack_simple.md.tmpl
@@ -11,6 +11,8 @@ description: |-
 
 ## Example Usage
 
+~> Starting with version 0.21.0 the attribute `registry_uid` is required.
+
 ```hcl
 data "spectrocloud_registry" "registry" {
   name = "Public Repo"
