Folder: Use UID instead of numerical ID (#1469)

The numerical ID is deprecated since v9. Let's remove it on next major version

Author: julienduchesne

.golangci.toml

@@ -42,13 +42,3 @@ text = "deprecatedComment: the proper format is `Deprecated: <text>`"
 [[issues.exclude-rules]]
 linters = ["gosec"]
 text = "G402: TLS MinVersion too low."
-
-# TODO: Use Folder UID instead where possible
-[[issues.exclude-rules]]
-linters = ["staticcheck"]
-text = "use FolderUID instead"
-
-# TODO: Use Folder UID instead where possible
-[[issues.exclude-rules]]
-linters = ["staticcheck"]
-text = "use UID instead"

docs/data-sources/dashboard.md

@@ -52,7 +52,8 @@ data "grafana_dashboard" "from_uid" {
 ### Read-Only
 
 - `config_json` (String) The complete dashboard model JSON.
-- `folder` (Number) The numerical ID of the folder where the Grafana dashboard is found.
+- `folder` (Number, Deprecated) Deprecated. Use `folder_uid` instead
+- `folder_uid` (String) The UID of the folder where the Grafana dashboard is found.
 - `id` (String) The ID of this resource.
 - `is_starred` (Boolean) Whether or not the Grafana dashboard is starred. Starred Dashboards will show up on your own Home Dashboard by default, and are a convenient way to mark Dashboards that you’re interested in.
 - `slug` (String) URL slug of the dashboard (deprecated).

docs/data-sources/dashboards.md

@@ -54,15 +54,15 @@ data "grafana_dashboards" "tags" {
   tags   = jsondecode(grafana_dashboard.data_source_dashboards1.config_json)["tags"]
 }
 
-data "grafana_dashboards" "folder_ids" {
-  org_id     = grafana_organization.test.id
-  folder_ids = [grafana_dashboard.data_source_dashboards1.folder]
+data "grafana_dashboards" "folder_uids" {
+  org_id      = grafana_organization.test.id
+  folder_uids = [grafana_dashboard.data_source_dashboards1.folder]
 }
 
-data "grafana_dashboards" "folder_ids_tags" {
-  org_id     = grafana_organization.test.id
-  folder_ids = [grafana_dashboard.data_source_dashboards1.folder]
-  tags       = jsondecode(grafana_dashboard.data_source_dashboards1.config_json)["tags"]
+data "grafana_dashboards" "folder_uids_tags" {
+  org_id      = grafana_organization.test.id
+  folder_uids = [grafana_dashboard.data_source_dashboards1.folder]
+  tags        = jsondecode(grafana_dashboard.data_source_dashboards1.config_json)["tags"]
 }
 
 // use depends_on to wait for dashboard resource to be created before searching
@@ -98,7 +98,8 @@ data "grafana_dashboards" "wrong_org" {
 
 ### Optional
 
-- `folder_ids` (List of Number) Numerical IDs of Grafana folders containing dashboards. Specify to filter for dashboards by folder (eg. `[0]` for General folder), or leave blank to get all dashboards in all folders.
+- `folder_ids` (List of Number, Deprecated) Deprecated, use `folder_uids` instead.
+- `folder_uids` (List of String) UIDs of Grafana folders containing dashboards. Specify to filter for dashboards by folder (eg. `["General"]` for General folder), or leave blank to get all dashboards in all folders.
 - `limit` (Number) Maximum number of dashboard search results to return. Defaults to `5000`.
 - `org_id` (String) The Organization ID. If not set, the Org ID defined in the provider block will be used.
 - `tags` (List of String) List of string Grafana dashboard tags to search for, eg. `["prod"]`. Used only as search input, i.e., attribute value will remain unchanged.

docs/data-sources/library_panel.md

@@ -97,7 +97,7 @@ data "grafana_dashboard" "from_library_panel_connection" {
 - `created` (String) Timestamp when the library panel was created.
 - `dashboard_ids` (List of Number) Numerical IDs of Grafana dashboards containing the library panel.
 - `description` (String) Description of the library panel.
-- `folder_id` (String) ID of the folder where the library panel is stored.
+- `folder_id` (String, Deprecated) Deprecated. Use `folder_uid` instead
 - `folder_name` (String) Name of the folder containing the library panel.
 - `folder_uid` (String) Unique ID (UID) of the folder containing the library panel.
 - `id` (String) The ID of this resource.

docs/resources/library_panel.md

@@ -43,7 +43,8 @@ resource "grafana_library_panel" "test" {
 
 ### Optional
 
-- `folder_id` (String) ID of the folder where the library panel is stored.
+- `folder_id` (String, Deprecated) Deprecated. Use `folder_uid` instead
+- `folder_uid` (String) Unique ID (UID) of the folder containing the library panel.
 - `org_id` (String) The Organization ID. If not set, the Org ID defined in the provider block will be used.
 - `uid` (String) The unique identifier (UID) of a library panel uniquely identifies library panels between multiple Grafana installs. It’s automatically generated unless you specify it during library panel creation.The UID provides consistent URLs for accessing library panels and when syncing library panels between multiple Grafana installs.
 
@@ -53,7 +54,6 @@ resource "grafana_library_panel" "test" {
 - `dashboard_ids` (List of Number) Numerical IDs of Grafana dashboards containing the library panel.
 - `description` (String) Description of the library panel.
 - `folder_name` (String) Name of the folder containing the library panel.
-- `folder_uid` (String) Unique ID (UID) of the folder containing the library panel.
 - `id` (String) The ID of this resource.
 - `panel_id` (Number) The numeric ID of the library panel computed by Grafana.
 - `type` (String) Type of the library panel (eg. text).

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

@@ -34,15 +34,15 @@ data "grafana_dashboards" "tags" {
   tags   = jsondecode(grafana_dashboard.data_source_dashboards1.config_json)["tags"]
 }
 
-data "grafana_dashboards" "folder_ids" {
-  org_id     = grafana_organization.test.id
-  folder_ids = [grafana_dashboard.data_source_dashboards1.folder]
+data "grafana_dashboards" "folder_uids" {
+  org_id      = grafana_organization.test.id
+  folder_uids = [grafana_dashboard.data_source_dashboards1.folder]
 }
 
-data "grafana_dashboards" "folder_ids_tags" {
-  org_id     = grafana_organization.test.id
-  folder_ids = [grafana_dashboard.data_source_dashboards1.folder]
-  tags       = jsondecode(grafana_dashboard.data_source_dashboards1.config_json)["tags"]
+data "grafana_dashboards" "folder_uids_tags" {
+  org_id      = grafana_organization.test.id
+  folder_uids = [grafana_dashboard.data_source_dashboards1.folder]
+  tags        = jsondecode(grafana_dashboard.data_source_dashboards1.config_json)["tags"]
 }
 
 // use depends_on to wait for dashboard resource to be created before searching

internal/resources/grafana/common_check_exists_test.go

@@ -144,9 +144,9 @@ var (
 		},
 	)
 	folderCheckExists = newCheckExistsHelper(
-		func(f *models.Folder) string { return strconv.FormatInt(f.ID, 10) },
-		func(client *goapi.GrafanaHTTPAPI, id string) (*models.Folder, error) {
-			resp, err := client.Folders.GetFolderByID(mustParseInt64(id))
+		func(f *models.Folder) string { return f.UID },
+		func(client *goapi.GrafanaHTTPAPI, uid string) (*models.Folder, error) {
+			resp, err := client.Folders.GetFolderByUID(uid)
 			return payloadOrError(resp, err)
 		},
 	)

internal/resources/grafana/data_source_dashboard.go

@@ -53,7 +53,13 @@ func datasourceDashboard() *schema.Resource {
 			"folder": {
 				Type:        schema.TypeInt,
 				Computed:    true,
-				Description: "The numerical ID of the folder where the Grafana dashboard is found.",
+				Description: "Deprecated. Use `folder_uid` instead",
+				Deprecated:  "Use `folder_uid` instead",
+			},
+			"folder_uid": {
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The UID of the folder where the Grafana dashboard is found.",
 			},
 			"is_starred": {
 				Type:        schema.TypeBool,
@@ -120,7 +126,9 @@ func dataSourceDashboardRead(ctx context.Context, d *schema.ResourceData, meta i
 	d.Set("config_json", string(configJSONBytes))
 	d.Set("version", int64(model["version"].(float64)))
 	d.Set("title", model["title"].(string))
+	// nolint:staticcheck
 	d.Set("folder", dashboard.Meta.FolderID)
+	d.Set("folder_uid", dashboard.Meta.FolderUID)
 	d.Set("is_starred", dashboard.Meta.IsStarred)
 	d.Set("slug", dashboard.Meta.Slug)
 	d.Set("url", metaClient.GrafanaSubpath(dashboard.Meta.URL))

internal/resources/grafana/data_source_dashboards.go

@@ -26,8 +26,15 @@ Datasource for retrieving all dashboards. Specify list of folder IDs to search i
 			"folder_ids": {
 				Type:        schema.TypeList,
 				Optional:    true,
-				Description: "Numerical IDs of Grafana folders containing dashboards. Specify to filter for dashboards by folder (eg. `[0]` for General folder), or leave blank to get all dashboards in all folders.",
+				Description: "Deprecated, use `folder_uids` instead.",
 				Elem:        &schema.Schema{Type: schema.TypeInt},
+				Deprecated:  "Use `folder_uids` instead.",
+			},
+			"folder_uids": {
+				Type:        schema.TypeList,
+				Optional:    true,
+				Description: "UIDs of Grafana folders containing dashboards. Specify to filter for dashboards by folder (eg. `[\"General\"]` for General folder), or leave blank to get all dashboards in all folders.",
+				Elem:        &schema.Schema{Type: schema.TypeString},
 			},
 			"limit": {
 				Type:        schema.TypeInt,
@@ -81,6 +88,11 @@ func dataSourceReadDashboards(ctx context.Context, d *schema.ResourceData, meta
 		id.Write([]byte(fmt.Sprintf("%v", params.FolderIds)))
 	}
 
+	if list, ok := d.GetOk("folder_uids"); ok {
+		params.FolderUIDs = common.ListToStringSlice(list.([]interface{}))
+		id.Write([]byte(fmt.Sprintf("%v", params.FolderUIDs)))
+	}
+
 	if list, ok := d.GetOk("tags"); ok {
 		params.Tag = common.ListToStringSlice(list.([]interface{}))
 		id.Write([]byte(fmt.Sprintf("%v", params.Tag)))

internal/resources/grafana/data_source_dashboards_test.go

@@ -7,8 +7,8 @@ import (
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource"
 )
 
-func TestAccDataSourceDashboardsAllAndByFolderID(t *testing.T) {
-	testutils.CheckOSSTestsEnabled(t)
+func TestAccDataSourceDashboardsAllAndByFolderUID(t *testing.T) {
+	testutils.CheckOSSTestsEnabled(t, ">=10.0.0")
 
 	// Do not use parallel tests here because it tests a listing datasource on the default org
 	resource.Test(t, resource.TestCase{
@@ -22,15 +22,15 @@ func TestAccDataSourceDashboardsAllAndByFolderID(t *testing.T) {
 					resource.TestCheckResourceAttr("data.grafana_dashboards.tags", "dashboards.0.title", "data_source_dashboards 1"),
 					resource.TestCheckResourceAttr("data.grafana_dashboards.tags", "dashboards.0.folder_title", "test folder data_source_dashboards"),
 
-					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_ids", "dashboards.#", "1"),
-					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_ids", "dashboards.0.uid", "data-source-dashboards-1"),
-					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_ids", "dashboards.0.title", "data_source_dashboards 1"),
-					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_ids", "dashboards.0.folder_title", "test folder data_source_dashboards"),
+					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_uids", "dashboards.#", "1"),
+					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_uids", "dashboards.0.uid", "data-source-dashboards-1"),
+					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_uids", "dashboards.0.title", "data_source_dashboards 1"),
+					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_uids", "dashboards.0.folder_title", "test folder data_source_dashboards"),
 
-					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_ids_tags", "dashboards.#", "1"),
-					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_ids_tags", "dashboards.0.uid", "data-source-dashboards-1"),
-					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_ids_tags", "dashboards.0.title", "data_source_dashboards 1"),
-					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_ids_tags", "dashboards.0.folder_title", "test folder data_source_dashboards"),
+					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_uids_tags", "dashboards.#", "1"),
+					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_uids_tags", "dashboards.0.uid", "data-source-dashboards-1"),
+					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_uids_tags", "dashboards.0.title", "data_source_dashboards 1"),
+					resource.TestCheckResourceAttr("data.grafana_dashboards.folder_uids_tags", "dashboards.0.folder_title", "test folder data_source_dashboards"),
 
 					resource.TestCheckResourceAttr("data.grafana_dashboards.limit_one", "dashboards.#", "1"),
 					resource.TestCheckResourceAttr("data.grafana_dashboards.limit_one", "dashboards.0.uid", "data-source-dashboards-1"),

internal/resources/grafana/resource_dashboard.go

@@ -135,7 +135,10 @@ func ReadDashboard(ctx context.Context, d *schema.ResourceData, meta interface{}
 	// If the folder was originally set to a numeric ID, we read the folder ID
 	// Othwerwise, we read the folder UID
 	_, folderID := SplitOrgResourceID(d.Get("folder").(string))
+	// nolint:staticcheck
 	if common.IDRegexp.MatchString(folderID) && dashboard.Meta.FolderID > 0 {
+		// TODO: Remove on next major release
+		// nolint:staticcheck
 		d.Set("folder", strconv.FormatInt(dashboard.Meta.FolderID, 10))
 	} else {
 		d.Set("folder", dashboard.Meta.FolderUID)
@@ -205,6 +208,8 @@ func makeDashboard(d *schema.ResourceData) (models.SaveDashboardCommand, error)
 
 	_, folderID := SplitOrgResourceID(d.Get("folder").(string))
 	if folderInt, err := strconv.ParseInt(folderID, 10, 64); err == nil {
+		// TODO: Remove on next major release
+		// nolint:staticcheck
 		dashboard.FolderID = folderInt
 	} else {
 		dashboard.FolderUID = folderID

internal/resources/grafana/resource_dashboard_test.go

@@ -7,7 +7,6 @@ import (
 	"testing"
 
 	"github.com/grafana/grafana-openapi-client-go/models"
-	"github.com/grafana/terraform-provider-grafana/v2/internal/common"
 	"github.com/grafana/terraform-provider-grafana/v2/internal/resources/grafana"
 	"github.com/grafana/terraform-provider-grafana/v2/internal/testutils"
 
@@ -159,48 +158,6 @@ func TestAccDashboard_computed_config(t *testing.T) {
 	})
 }
 
-func TestAccDashboard_folder(t *testing.T) {
-	testutils.CheckOSSTestsEnabled(t)
-
-	uid := acctest.RandString(10)
-
-	var dashboard models.DashboardFullWithMeta
-	var folder models.Folder
-
-	resource.ParallelTest(t, resource.TestCase{
-		ProtoV5ProviderFactories: testutils.ProtoV5ProviderFactories,
-		CheckDestroy: resource.ComposeTestCheckFunc(
-			dashboardCheckExists.destroyed(&dashboard, nil),
-			folderCheckExists.destroyed(&folder, nil),
-		),
-		Steps: []resource.TestStep{
-			{
-				Config: testAccDashboardFolder(uid, "grafana_folder.test_folder1.id"),
-				Check: resource.ComposeTestCheckFunc(
-					dashboardCheckExists.exists("grafana_dashboard.test_folder", &dashboard),
-					folderCheckExists.exists("grafana_folder.test_folder1", &folder),
-					testAccDashboardCheckExistsInFolder(&dashboard, &folder),
-					resource.TestCheckResourceAttr("grafana_dashboard.test_folder", "id", "1:"+uid), // <org id>:<uid>
-					resource.TestCheckResourceAttr("grafana_dashboard.test_folder", "uid", uid),
-					resource.TestMatchResourceAttr("grafana_dashboard.test_folder", "folder", common.IDRegexp),
-				),
-			},
-			// Update folder
-			{
-				Config: testAccDashboardFolder(uid, "grafana_folder.test_folder2.id"),
-				Check: resource.ComposeTestCheckFunc(
-					dashboardCheckExists.exists("grafana_dashboard.test_folder", &dashboard),
-					folderCheckExists.exists("grafana_folder.test_folder2", &folder),
-					testAccDashboardCheckExistsInFolder(&dashboard, &folder),
-					resource.TestCheckResourceAttr("grafana_dashboard.test_folder", "id", "1:"+uid), // <org id>:<uid>
-					resource.TestCheckResourceAttr("grafana_dashboard.test_folder", "uid", uid),
-					resource.TestMatchResourceAttr("grafana_dashboard.test_folder", "folder", common.IDRegexp),
-				),
-			},
-		},
-	})
-}
-
 func TestAccDashboard_folder_uid(t *testing.T) {
 	testutils.CheckOSSTestsEnabled(t, ">=8.0.0") // UID in folders were added in v8
 
@@ -289,8 +246,8 @@ func TestAccDashboard_inOrg(t *testing.T) {
 
 func testAccDashboardCheckExistsInFolder(dashboard *models.DashboardFullWithMeta, folder *models.Folder) resource.TestCheckFunc {
 	return func(s *terraform.State) error {
-		if dashboard.Meta.FolderID != folder.ID && folder.ID != 0 {
-			return fmt.Errorf("dashboard.Folder(%d) does not match folder.ID(%d)", dashboard.Meta.FolderID, folder.ID)
+		if dashboard.Meta.FolderUID != folder.UID && folder.UID != "" {
+			return fmt.Errorf("dashboard.Folder(%s) does not match folder.ID(%s)", dashboard.Meta.FolderUID, folder.UID)
 		}
 		return nil
 	}

internal/resources/grafana/resource_folder.go

@@ -96,8 +96,7 @@ func CreateFolder(ctx context.Context, d *schema.ResourceData, meta interface{})
 	}
 
 	folder := resp.GetPayload()
-	// TODO: Switch to UID
-	d.SetId(MakeOrgResourceID(orgID, folder.ID))
+	d.SetId(MakeOrgResourceID(orgID, folder.UID))
 
 	return ReadFolder(ctx, d, meta)
 }
@@ -131,7 +130,7 @@ func ReadFolder(ctx context.Context, d *schema.ResourceData, meta interface{}) d
 		return err
 	}
 
-	d.SetId(MakeOrgResourceID(orgID, folder.ID))
+	d.SetId(MakeOrgResourceID(orgID, folder.UID))
 	d.Set("org_id", strconv.FormatInt(orgID, 10))
 	d.Set("title", folder.Title)
 	d.Set("uid", folder.UID)
@@ -142,16 +141,11 @@ func ReadFolder(ctx context.Context, d *schema.ResourceData, meta interface{}) d
 }
 
 func DeleteFolder(ctx context.Context, d *schema.ResourceData, meta interface{}) diag.Diagnostics {
-	client, _, idStr := OAPIClientFromExistingOrgResource(meta, d.Id())
-	deleteParams := folders.NewDeleteFolderParams().WithFolderUID(d.Get("uid").(string))
+	client, _, uid := OAPIClientFromExistingOrgResource(meta, d.Id())
+	deleteParams := folders.NewDeleteFolderParams().WithFolderUID(uid)
 	if d.Get("prevent_destroy_if_not_empty").(bool) {
-		// Search for dashboards and fail if any are found
-		folderID, err := strconv.ParseInt(idStr, 10, 64)
-		if err != nil {
-			return diag.Errorf("failed to parse folder ID: %s", err)
-		}
 		searchType := "dash-db"
-		searchParams := search.NewSearchParams().WithFolderIds([]int64{folderID}).WithType(&searchType)
+		searchParams := search.NewSearchParams().WithFolderUIDs([]string{uid}).WithType(&searchType)
 		searchResp, err := client.Search.Search(searchParams)
 		if err != nil {
 			return diag.Errorf("failed to search for dashboards in folder: %s", err)
@@ -161,7 +155,7 @@ func DeleteFolder(ctx context.Context, d *schema.ResourceData, meta interface{})
 			for _, dashboard := range searchResp.GetPayload() {
 				dashboardNames = append(dashboardNames, dashboard.Title)
 			}
-			return diag.Errorf("folder %s is not empty and prevent_destroy_if_not_empty is set. It contains the following dashboards: %v", d.Get("uid").(string), dashboardNames)
+			return diag.Errorf("folder %s is not empty and prevent_destroy_if_not_empty is set. It contains the following dashboards: %v", uid, dashboardNames)
 		}
 	} else {
 		// If we're not preventing destroys, then we can force delete folders that have alert rules