feat!: introduction of preview mode (#185)

# 📥 Pull Request ## ❓ What are you trying to address This pull request includes several changes to the documentation and configuration to introduce a preview mode for various resources and data sources. The changes ensure that users are aware of the risks associated with using preview features and require explicit opt-in at the provider level configuration.
microsoft · Jan 10, 2025 · 1bc4f49 · 1bc4f49
1 parent 3ca1c37
commit 1bc4f49
Show file tree

Hide file tree

Showing 71 changed files with 602 additions and 100 deletions.
diff --git a/.changes/unreleased/breaking-20250107-233638.yaml b/.changes/unreleased/breaking-20250107-233638.yaml
@@ -0,0 +1,8 @@
+kind: breaking
+body: |
+  Using preview resources or data sources now needs explicit opt-in at the provider level configuration by setting the `preview` attribute to `true`.
+  This is to ensure that users are aware of the risks of using preview resources or data sources in production environments.
+  Usage of any preview feature will result in a warning message in the Terraform output.
+time: 2025-01-07T23:36:38.8482843-08:00
+custom:
+  Issue: "185"
diff --git a/Taskfile.yml b/Taskfile.yml
@@ -21,6 +21,9 @@ vars:
   BUILD_DEV_OUTPUT_DIR: "bin/{{OS}}-{{ARCH}}"
   BUILD_DEV_ARTIFACT: "{{.BUILD_DEV_OUTPUT_DIR}}/{{.PROJECT_NAME}}{{exeExt}}"
 
+env:
+  FABRIC_PREVIEW: true
+
 tasks:
   # ----------------------
   # Development

diff --git a/docs/data-sources/data_pipeline.md b/docs/data-sources/data_pipeline.md
@@ -6,6 +6,7 @@ description: |-
   Get a Fabric Data Pipeline.
   Use this data source to fetch a Data Pipeline https://learn.microsoft.com/fabric/data-factory/data-factory-overview#data-pipelines.
   -> This item does not support Service Principal. Please use a User context authentication.
+  ~> This data-source is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_data_pipeline (Data Source)
@@ -16,6 +17,8 @@ Use this data source to fetch a [Data Pipeline](https://learn.microsoft.com/fabr
 
 -> This item does not support Service Principal. Please use a User context authentication.
 
+~> This data-source is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 ## Example Usage
 
 ```terraform

diff --git a/docs/data-sources/domain.md b/docs/data-sources/domain.md
@@ -6,6 +6,7 @@ description: |-
   Get a Fabric Domain.
   Use this data source to get Domain https://learn.microsoft.com/fabric/governance/domains.
   -> This item does not support Service Principal. Please use a User context authentication.
+  ~> This data-source is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_domain (Data Source)
@@ -16,6 +17,8 @@ Use this data source to get [Domain](https://learn.microsoft.com/fabric/governan
 
 -> This item does not support Service Principal. Please use a User context authentication.
 
+~> This data-source is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 ## Example Usage
 
 ```terraform

diff --git a/docs/data-sources/domain_workspace_assignments.md b/docs/data-sources/domain_workspace_assignments.md
@@ -4,18 +4,21 @@ page_title: "fabric_domain_workspace_assignments Data Source - terraform-provide
 subcategory: ""
 description: |-
   List a Fabric Domain Workspace Assignments.
-  See Domain https://learn.microsoft.com/fabric/governance/domains for more information.
+  Use this data source to list Domain Workspace Assignments https://learn.microsoft.com/fabric/governance/domains.
   -> This item does not support Service Principal. Please use a User context authentication.
+  ~> This data-source is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_domain_workspace_assignments (Data Source)
 
 List a Fabric Domain Workspace Assignments.
 
-See [Domain](https://learn.microsoft.com/fabric/governance/domains) for more information.
+Use this data source to list [Domain Workspace Assignments](https://learn.microsoft.com/fabric/governance/domains).
 
 -> This item does not support Service Principal. Please use a User context authentication.
 
+~> This data-source is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 ## Example Usage
 
 ```terraform

diff --git a/docs/data-sources/ml_experiment.md b/docs/data-sources/ml_experiment.md
@@ -6,6 +6,7 @@ description: |-
   Get a Fabric ML Experiment.
   Use this data source to fetch a ML Experiment https://learn.microsoft.com/fabric/data-science/machine-learning-experiment.
   -> This item does not support Service Principal. Please use a User context authentication.
+  ~> This data-source is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_ml_experiment (Data Source)
@@ -16,6 +17,8 @@ Use this data source to fetch a [ML Experiment](https://learn.microsoft.com/fabr
 
 -> This item does not support Service Principal. Please use a User context authentication.
 
+~> This data-source is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 ## Example Usage
 
 ```terraform

diff --git a/docs/data-sources/ml_model.md b/docs/data-sources/ml_model.md
@@ -6,6 +6,7 @@ description: |-
   Get a Fabric ML Model.
   Use this data source to fetch a ML Model https://learn.microsoft.com/fabric/data-science/machine-learning-model.
   -> This item does not support Service Principal. Please use a User context authentication.
+  ~> This data-source is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_ml_model (Data Source)
@@ -16,6 +17,8 @@ Use this data source to fetch a [ML Model](https://learn.microsoft.com/fabric/da
 
 -> This item does not support Service Principal. Please use a User context authentication.
 
+~> This data-source is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 ## Example Usage
 
 ```terraform

diff --git a/docs/data-sources/warehouse.md b/docs/data-sources/warehouse.md
@@ -6,6 +6,7 @@ description: |-
   Get a Fabric Warehouse.
   Use this data source to fetch a Warehouse https://learn.microsoft.com/fabric/data-warehouse/data-warehousing.
   -> This item does not support Service Principal. Please use a User context authentication.
+  ~> This data-source is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_warehouse (Data Source)
@@ -16,6 +17,8 @@ Use this data source to fetch a [Warehouse](https://learn.microsoft.com/fabric/d
 
 -> This item does not support Service Principal. Please use a User context authentication.
 
+~> This data-source is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 ## Example Usage
 
 ```terraform

diff --git a/docs/index.md b/docs/index.md
@@ -92,6 +92,7 @@ You can find more information on how to do this in the following guides:
 - `oidc_request_url` (String) The URL for the OIDC provider from which to request an ID token. For use when authenticating as a Service Principal using OpenID Connect.
 - `oidc_token` (String, Sensitive) The OIDC token for use when authenticating as a Service Principal using OpenID Connect.
 - `oidc_token_file_path` (String) The path to a file containing an OIDC token for use when authenticating as a Service Principal using OpenID Connect.
+- `preview` (Boolean) Enable preview mode to use preview features.
 - `tenant_id` (String) The ID of the Microsoft Entra ID tenant that Fabric API uses to authenticate with.
 - `timeout` (String) Default timeout for all requests. It can be overridden at any Resource/Data-Source
    A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as `30s` or `2h45m`. Valid time units are "s" (seconds), "m" (minutes), "h" (hours)

diff --git a/docs/resources/data_pipeline.md b/docs/resources/data_pipeline.md
@@ -6,6 +6,7 @@ description: |-
   Manage a Fabric Data Pipeline.
   Use this resource to manage Data Pipeline https://learn.microsoft.com/fabric/data-factory/data-factory-overview#data-pipelines.
   -> This item does not support Service Principal. Please use a User context authentication.
+  ~> This resource is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_data_pipeline (Resource)
@@ -16,6 +17,8 @@ Use this resource to manage [Data Pipeline](https://learn.microsoft.com/fabric/d
 
 -> This item does not support Service Principal. Please use a User context authentication.
 
+~> This resource is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 ## Example Usage
 
 ```terraform

diff --git a/docs/resources/domain.md b/docs/resources/domain.md
@@ -3,19 +3,22 @@
 page_title: "fabric_domain Resource - terraform-provider-fabric"
 subcategory: ""
 description: |-
-  This resource manages a Fabric Domain.
-  See Domains https://learn.microsoft.com/fabric/governance/domains for more information.
+  Manage a Fabric Domain.
+  Use this resource to manage Domain https://learn.microsoft.com/fabric/governance/domains.
   -> This item does not support Service Principal. Please use a User context authentication.
+  ~> This resource is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_domain (Resource)
 
-This resource manages a Fabric Domain.
+Manage a Fabric Domain.
 
-See [Domains](https://learn.microsoft.com/fabric/governance/domains) for more information.
+Use this resource to manage [Domain](https://learn.microsoft.com/fabric/governance/domains).
 
 -> This item does not support Service Principal. Please use a User context authentication.
 
+~> This resource is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 ## Example Usage
 
 ```terraform

diff --git a/docs/resources/domain_role_assignments.md b/docs/resources/domain_role_assignments.md
@@ -4,18 +4,21 @@ page_title: "fabric_domain_role_assignments Resource - terraform-provider-fabric
 subcategory: ""
 description: |-
   Manage a Fabric Domain Role Assignments.
-  See Domain https://learn.microsoft.com/fabric/governance/domains for more information.
+  Use this resource to manage Domain Role Assignments https://learn.microsoft.com/fabric/governance/domains.
   -> This item does not support Service Principal. Please use a User context authentication.
+  ~> This resource is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_domain_role_assignments (Resource)
 
 Manage a Fabric Domain Role Assignments.
 
-See [Domain](https://learn.microsoft.com/fabric/governance/domains) for more information.
+Use this resource to manage [Domain Role Assignments](https://learn.microsoft.com/fabric/governance/domains).
 
 -> This item does not support Service Principal. Please use a User context authentication.
 
+~> This resource is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 ## Example Usage
 
 ```terraform

diff --git a/docs/resources/domain_workspace_assignments.md b/docs/resources/domain_workspace_assignments.md
@@ -4,18 +4,21 @@ page_title: "fabric_domain_workspace_assignments Resource - terraform-provider-f
 subcategory: ""
 description: |-
   Manage a Fabric Domain Workspace Assignments.
-  See Domain https://learn.microsoft.com/fabric/governance/domains for more information.
+  Use this resource to manage Domain Workspace Assignments https://learn.microsoft.com/fabric/governance/domains.
   -> This item does not support Service Principal. Please use a User context authentication.
+  ~> This resource is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_domain_workspace_assignments (Resource)
 
 Manage a Fabric Domain Workspace Assignments.
 
-See [Domain](https://learn.microsoft.com/fabric/governance/domains) for more information.
+Use this resource to manage [Domain Workspace Assignments](https://learn.microsoft.com/fabric/governance/domains).
 
 -> This item does not support Service Principal. Please use a User context authentication.
 
+~> This resource is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 ## Example Usage
 
 ```terraform

diff --git a/docs/resources/ml_experiment.md b/docs/resources/ml_experiment.md
@@ -6,6 +6,7 @@ description: |-
   Manage a Fabric ML Experiment.
   Use this resource to manage ML Experiment https://learn.microsoft.com/fabric/data-science/machine-learning-experiment.
   -> This item does not support Service Principal. Please use a User context authentication.
+  ~> This resource is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_ml_experiment (Resource)
@@ -16,6 +17,8 @@ Use this resource to manage [ML Experiment](https://learn.microsoft.com/fabric/d
 
 -> This item does not support Service Principal. Please use a User context authentication.
 
+~> This resource is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 ## Example Usage
 
 ```terraform

diff --git a/docs/resources/ml_model.md b/docs/resources/ml_model.md
@@ -6,6 +6,7 @@ description: |-
   Manage a Fabric ML Model.
   Use this resource to manage ML Model https://learn.microsoft.com/fabric/data-science/machine-learning-model.
   -> This item does not support Service Principal. Please use a User context authentication.
+  ~> This resource is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_ml_model (Resource)
@@ -16,6 +17,8 @@ Use this resource to manage [ML Model](https://learn.microsoft.com/fabric/data-s
 
 -> This item does not support Service Principal. Please use a User context authentication.
 
+~> This resource is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 <!-- schema generated by tfplugindocs -->
 ## Schema
 

diff --git a/docs/resources/warehouse.md b/docs/resources/warehouse.md
@@ -6,6 +6,7 @@ description: |-
   Manage a Fabric Warehouse.
   Use this resource to manage a Warehouse https://learn.microsoft.com/fabric/data-warehouse/data-warehousing.
   -> This item does not support Service Principal. Please use a User context authentication.
+  ~> This resource is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_warehouse (Resource)
@@ -16,6 +17,8 @@ Use this resource to manage a [Warehouse](https://learn.microsoft.com/fabric/dat
 
 -> This item does not support Service Principal. Please use a User context authentication.
 
+~> This resource is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 ## Example Usage
 
 ```terraform

diff --git a/docs/resources/workspace_git.md b/docs/resources/workspace_git.md
@@ -6,6 +6,7 @@ description: |-
   Manage a Fabric Workspace Git integration.
   See Workspace Git integration https://learn.microsoft.com/fabric/cicd/git-integration/intro-to-git-integration for more information.
   -> This item does not support Service Principal. Please use a User context authentication.
+  ~> This resource is in preview. To access it, you must explicitly enable the preview mode in the provider level configuration.
 ---
 
 # fabric_workspace_git (Resource)
@@ -16,6 +17,8 @@ See [Workspace Git integration](https://learn.microsoft.com/fabric/cicd/git-inte
 
 -> This item does not support Service Principal. Please use a User context authentication.
 
+~> This resource is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration.
+
 ## Example Usage
 
 ```terraform

diff --git a/internal/common/errors.go b/internal/common/errors.go
@@ -37,11 +37,15 @@ const (
 	ErrorBase64GzipEncodeHeader       string = "Base64 Gzip encode operation"
 	ErrorJSONNormalizeHeader          string = "JSON normalize operation"
 	ErrorFileReadHeader               string = "File read operation"
-	ErrorTmplParseHeader              string = "template parse operation"
+	ErrorTmplParseHeader              string = "Template parse operation"
+	ErrorPreviewModeHeader            string = "Preview mode not enabled"
+	ErrorPreviewModeDetails           string = "'%s' is not available without explicitly opt-in to the preview mode on the provider level configuration."
 )
 
 // Warnings.
 const (
 	WarningItemDefinitionUpdateHeader  = "Fabric Item definition update"
 	WarningItemDefinitionUpdateDetails = "%s definition update operation will overwrite the existing definition on the Fabric side."
+	WarningPreviewModeHeader           = "'%s' preview mode"
+	WarningPreviewModeDetails          = "The behavior of '%s' may change in future releases without notice."
 )
diff --git a/internal/pkg/fabricitem/base.go b/internal/pkg/fabricitem/base.go
@@ -3,4 +3,8 @@
 
 package fabricitem
 
-const DefinitionFormatNotApplicable = "NotApplicable"
+const (
+	DefinitionFormatNotApplicable = "NotApplicable"
+	PreviewDataSource             = "\n\n~> This data-source is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration."
+	PreviewResource               = "\n\n~> This resource is in **preview**. To access it, you must explicitly enable the `preview` mode in the provider level configuration."
+)
diff --git a/internal/pkg/fabricitem/data_item.go b/internal/pkg/fabricitem/data_item.go
@@ -34,6 +34,7 @@ type DataSourceFabricItem struct {
 	TFName              string
 	MarkdownDescription string
 	IsDisplayNameUnique bool
+	IsPreview           bool
 }
 
 func NewDataSourceFabricItem(config DataSourceFabricItem) datasource.DataSource {
@@ -82,6 +83,15 @@ func (d *DataSourceFabricItem) Configure(_ context.Context, req datasource.Confi
 
 	d.pConfigData = pConfigData
 	d.client = fabcore.NewClientFactoryWithClient(*pConfigData.FabricClient).NewItemsClient()
+
+	diags := IsPreviewMode(d.Name, d.IsPreview, d.pConfigData.Preview)
+	if diags != nil {
+		resp.Diagnostics.Append(diags...)
+
+		if diags.HasError() {
+			return
+		}
+	}
 }
 
 func (d *DataSourceFabricItem) Read(ctx context.Context, req datasource.ReadRequest, resp *datasource.ReadResponse) {

diff --git a/internal/pkg/fabricitem/data_item_definition.go b/internal/pkg/fabricitem/data_item_definition.go
@@ -38,6 +38,7 @@ type DataSourceFabricItemDefinition struct {
 	FormatTypeDefault   string
 	FormatTypes         []string
 	DefinitionPathKeys  []string
+	IsPreview           bool
 }
 
 func NewDataSourceFabricItemDefinition(config DataSourceFabricItemDefinition) datasource.DataSource {
@@ -86,6 +87,15 @@ func (d *DataSourceFabricItemDefinition) Configure(_ context.Context, req dataso
 
 	d.pConfigData = pConfigData
 	d.client = fabcore.NewClientFactoryWithClient(*pConfigData.FabricClient).NewItemsClient()
+
+	diags := IsPreviewMode(d.Name, d.IsPreview, d.pConfigData.Preview)
+	if diags != nil {
+		resp.Diagnostics.Append(diags...)
+
+		if diags.HasError() {
+			return
+		}
+	}
 }
 
 func (d *DataSourceFabricItemDefinition) Read(ctx context.Context, req datasource.ReadRequest, resp *datasource.ReadResponse) {

diff --git a/internal/pkg/fabricitem/data_item_definition_properties.go b/internal/pkg/fabricitem/data_item_definition_properties.go
@@ -83,6 +83,15 @@ func (d *DataSourceFabricItemDefinitionProperties[Ttfprop, Titemprop]) Configure
 
 	d.pConfigData = pConfigData
 	d.client = fabcore.NewClientFactoryWithClient(*pConfigData.FabricClient).NewItemsClient()
+
+	diags := IsPreviewMode(d.Name, d.IsPreview, d.pConfigData.Preview)
+	if diags != nil {
+		resp.Diagnostics.Append(diags...)
+
+		if diags.HasError() {
+			return
+		}
+	}
 }
 
 func (d *DataSourceFabricItemDefinitionProperties[Ttfprop, Titemprop]) Read(ctx context.Context, req datasource.ReadRequest, resp *datasource.ReadResponse) { //revive:disable-line:confusing-naming