[Fix] handle auto-enabled errors withdatabricks_system_schema (#4547)

## Changes
- Handle new error message `billing system schema can only be enabled by
Databricks`. Resolves #4539
- Update documentation with warnings about auto-enabled system schemas.
- Enable system schema integration test on GCP

## Tests
<!-- 
How is this tested? Please see the checklist below and also describe any
other relevant tests
-->

- [x] `make test` run locally
- [x] relevant change in `docs/` folder
- [x] covered with integration tests in `internal/acceptance`
- [x] using Go SDK
- [x] using TF Plugin Framework

---------

Co-authored-by: Alex Ott <[email protected]>

Author: nkvuong

NEXT_CHANGELOG.md

@@ -6,7 +6,8 @@
 
 ### Bug Fixes
 
- - Skip Read after Create in `databricks_secret_acl` to avoid errors([#4548](https://github.com/databricks/terraform-provider-databricks/pull/4548)).
+ * Handle auto-enabled errors with `databricks_system_schema` [#4547](https://github.com/databricks/terraform-provider-databricks/pull/4547)
+ * Skip Read after Create in `databricks_secret_acl` to avoid errors([#4548](https://github.com/databricks/terraform-provider-databricks/pull/4548)).
 
 ### Documentation
 

catalog/resource_system_schema.go

@@ -21,6 +21,10 @@ func ResourceSystemSchema() common.Resource {
 			Type:     schema.TypeString,
 			Computed: true,
 		}
+		m["auto_enabled"] = &schema.Schema{
+			Type:     schema.TypeBool,
+			Computed: true,
+		}
 		m["state"].Computed = true
 		return m
 	})
@@ -49,12 +53,20 @@ func ResourceSystemSchema() common.Resource {
 			MetastoreId: metastoreSummary.MetastoreId,
 			SchemaName:  new,
 		})
-		//ignore "schema <schema-name> already exists" error
-		if err != nil && !strings.Contains(err.Error(), "already exists") {
-			return err
+		if err != nil {
+			//ignore "<schema-name> system schema can only be enabled by Databricks" error, also mark it to make delete no-op
+			d.Set("auto_enabled", strings.Contains(err.Error(), "can only be enabled by Databricks"))
+			//ignore "schema <schema-name> already exists" error
+			if !strings.Contains(err.Error(), "already exists") && !strings.Contains(err.Error(), "can only be enabled by Databricks") {
+				return err
+			}
 		}
 		//disable old schemas if needed
 		if old != "" {
+			if d.Get("auto_enabled").(bool) {
+				log.Printf("[WARN] %s is auto enabled, ignoring it", old)
+				return nil
+			}
 			err = w.SystemSchemas.Disable(ctx, catalog.DisableRequest{
 				MetastoreId: metastoreSummary.MetastoreId,
 				SchemaName:  old,
@@ -116,6 +128,10 @@ func ResourceSystemSchema() common.Resource {
 			if err != nil {
 				return err
 			}
+			if d.Get("auto_enabled").(bool) {
+				log.Printf("[WARN] %s is auto enabled, ignoring it", schemaName)
+				return nil
+			}
 			w, err := c.WorkspaceClient()
 			if err != nil {
 				return err

catalog/resource_system_schema_test.go

@@ -1,13 +1,16 @@
 package catalog
 
 import (
+	"errors"
 	"net/http"
 	"testing"
 
+	"github.com/databricks/databricks-sdk-go/experimental/mocks"
 	"github.com/databricks/databricks-sdk-go/service/catalog"
 	"github.com/databricks/terraform-provider-databricks/common"
 	"github.com/databricks/terraform-provider-databricks/qa"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/mock"
 )
 
 func TestSystemSchemaCreate(t *testing.T) {
@@ -87,6 +90,40 @@ func TestSystemSchemaCreate_Error(t *testing.T) {
 	assert.Equal(t, "", d.Id(), "Id should be empty for error creates")
 }
 
+func TestSystemSchemaCreateAlreadyEnabled(t *testing.T) {
+	qa.ResourceFixture{
+		MockWorkspaceClientFunc: func(w *mocks.MockWorkspaceClient) {
+			w.GetMockMetastoresAPI().EXPECT().Summary(mock.Anything).Return(&catalog.GetMetastoreSummaryResponse{
+				MetastoreId: "abc",
+			}, nil)
+			e := w.GetMockSystemSchemasAPI().EXPECT()
+			e.Enable(mock.Anything, catalog.EnableRequest{
+				MetastoreId: "abc",
+				SchemaName:  "billing",
+			}).Return(errors.New("billing system schema can only be enabled by Databricks"))
+			e.ListByMetastoreId(mock.Anything, "abc").Return(&catalog.ListSystemSchemasResponse{
+				Schemas: []catalog.SystemSchemaInfo{
+					{
+						Schema: "access",
+						State:  catalog.SystemSchemaInfoStateEnableCompleted,
+					},
+					{
+						Schema: "billing",
+						State:  catalog.SystemSchemaInfoStateEnableCompleted,
+					},
+				},
+			}, nil)
+		},
+		Resource: ResourceSystemSchema(),
+		HCL:      `schema = "billing"`,
+		Create:   true,
+	}.ApplyAndExpectData(t, map[string]any{
+		"schema":    "billing",
+		"id":        "abc|billing",
+		"full_name": "system.billing",
+	})
+}
+
 func TestSystemSchemaUpdate(t *testing.T) {
 	d, err := qa.ResourceFixture{
 		Fixtures: []qa.HTTPFixture{

catalog/system_schema_test.go

@@ -1,20 +1,19 @@
 package catalog_test
 
 import (
-	"os"
 	"testing"
 
 	"github.com/databricks/terraform-provider-databricks/internal/acceptance"
 )
 
 func TestUcAccResourceSystemSchema(t *testing.T) {
-	if os.Getenv("GOOGLE_CREDENTIALS") != "" {
-		t.Skipf("databricks_system_schema resource not available on GCP")
-	}
 	acceptance.UnityWorkspaceLevel(t, acceptance.Step{
 		Template: `
-		resource "databricks_system_schema" "this" {
+		resource "databricks_system_schema" "access" {
 			schema = "access"
+		}
+		resource "databricks_system_schema" "billing" {
+			schema = "billing"
 		}`,
 	})
 }

docs/resources/system_schema.md

@@ -7,6 +7,8 @@ subcategory: "Unity Catalog"
 
 -> This resource can only be used with a workspace-level provider!
 
+-> Certain system schemas (such as `billing`) may be auto-enabled once GA and should not be manually declared in Terraform configurations.
+
 Manages system tables enablement. System tables are a Databricks-hosted analytical store of your account’s operational data. System tables can be used for historical observability across your account. System tables must be enabled by an account admin.
 
 ## Example Usage