misc doc fixes (#2166)

nkvuong · web-flow · commit deffe04f10f5 · 2023-03-28T10:09:18.000+02:00
* misc doc fixes

* one more fix
diff --git a/docs/data-sources/aws_crossaccount_policy.md b/docs/data-sources/aws_crossaccount_policy.md
@@ -9,7 +9,7 @@ This data source constructs necessary AWS cross-account policy for you, which is
 
 ## Example Usage
 
-For more detailed usage please see [databricks_aws_assume_role_policy](aws_assume_role_policy.md) or [databricks_aws_s3_mount](../resources/aws_s3_mount.md) pages.
+For more detailed usage please see [databricks_aws_assume_role_policy](aws_assume_role_policy.md) or [databricks_aws_s3_mount](../resources/mount.md) pages.
 
 ```hcl
 data "databricks_aws_crossaccount_policy" "this" {}
diff --git a/docs/data-sources/service_principal.md b/docs/data-sources/service_principal.md
@@ -48,11 +48,11 @@ Data source exposes the following attributes:
 
 The following resources are used in the same context:
 
-* [End to end workspace management](../guides/passthrough-cluster-per-user.md) guide.
-* [databricks_current_user](current_user.md) data to retrieve information about [databricks_user](../resources/user.md) or [databricks_service_principal](../resources/service_principal.md), that is calling Databricks REST API.
-* [databricks_group](../resources/group.md) to manage [groups in Databricks Workspace](https://docs.databricks.com/administration-guide/users-groups/groups.html) or [Account Console](https://accounts.cloud.databricks.com/) (for AWS deployments).
-* [databricks_group](group.md) data to retrieve information about [databricks_group](../resources/group.md) members, entitlements and instance profiles.
-* [databricks_group_instance_profile](../resources/group_instance_profile.md) to attach [databricks_instance_profile](../resources/instance_profile.md) (AWS) to [databricks_group](../resources/group.md).
-* [databricks_group_member](../resources/group_member.md) to attach [users](../resources/user.md) and [groups](../resources/group.md) as group members.
-* [databricks_permissions](../resources/permissions.md) to manage [access control](https://docs.databricks.com/security/access-control/index.html) in Databricks workspace.
-* [databricks_service principal](../resources/service_principal.md) to manage [service principals](../resources/service_principal.md)
+- [End to end workspace management](../guides/passthrough-cluster-per-user.md) guide.
+- [databricks_current_user](current_user.md) data to retrieve information about [databricks_user](../resources/user.md) or [databricks_service_principal](../resources/service_principal.md), that is calling Databricks REST API.
+- [databricks_group](../resources/group.md) to manage [groups in Databricks Workspace](https://docs.databricks.com/administration-guide/users-groups/groups.html) or [Account Console](https://accounts.cloud.databricks.com/) (for AWS deployments).
+- [databricks_group](group.md) data to retrieve information about [databricks_group](../resources/group.md) members, entitlements and instance profiles.
+- [databricks_group_instance_profile](../resources/group_instance_profile.md) to attach [databricks_instance_profile](../resources/instance_profile.md) (AWS) to [databricks_group](../resources/group.md).
+- [databricks_group_member](../resources/group_member.md) to attach [users](../resources/user.md) and [groups](../resources/group.md) as group members.
+- [databricks_permissions](../resources/permissions.md) to manage [access control](https://docs.databricks.com/security/access-control/index.html) in Databricks workspace.
+- [databricks_service principal](../resources/service_principal.md) to manage [service principals](../resources/service_principal.md)
diff --git a/docs/guides/aws-private-link-workspace.md b/docs/guides/aws-private-link-workspace.md
@@ -127,6 +127,8 @@ The first step is to create the required AWS objects:
 - A subnet dedicated to your VPC endpoints.
 - A security group dedicated to your VPC endpoints and satisfying required inbound/outbound TCP/HTTPS traffic rules on ports 443 and 6666, respectively.
 
+For workspace with [compliance security profile](https://docs.databricks.com/security/privacy/security-profile.html#prepare-a-workspace-for-the-compliance-security-profile), you need *additionally* allow bidirectional access to port 2443 for FIPS connections. The total set of ports to allow bidirectional access are 443, 2443, and 6666.
+
 ```hcl
 data "aws_vpc" "prod" {
   id = var.vpc_id
@@ -176,36 +178,36 @@ resource "aws_security_group" "dataplane_vpce" {
   description = "Security group shared with relay and workspace endpoints"
   vpc_id      = var.vpc_id
 
-  ingress {
-    description = "Inbound rules"
-    from_port   = 443
-    to_port     = 443
-    protocol    = "tcp"
-    cidr_blocks = concat([var.vpce_subnet_cidr], local.vpc_cidr_blocks)
-  }
-
-  ingress {
-    description = "Inbound rules"
-    from_port   = 6666
-    to_port     = 6666
-    protocol    = "tcp"
-    cidr_blocks = concat([var.vpce_subnet_cidr], local.vpc_cidr_blocks)
-  }
-
-  egress {
-    description = "Outbound rules"
-    from_port   = 443
-    to_port     = 443
-    protocol    = "tcp"
-    cidr_blocks = concat([var.vpce_subnet_cidr], local.vpc_cidr_blocks)
+  dynamic "ingress" {
+    for_each = toset([
+      443,
+      2443, # FIPS port for CSP
+      6666,
+    ])
+
+    content {
+      description = "Inbound rules"
+      from_port   = ingress.value
+      to_port     = ingress.value
+      protocol    = "tcp"
+      cidr_blocks = concat([var.vpce_subnet_cidr], local.vpc_cidr_blocks)
+    }
   }
 
-  egress {
-    description = "Outbound rules"
-    from_port   = 6666
-    to_port     = 6666
-    protocol    = "tcp"
-    cidr_blocks = concat([var.vpce_subnet_cidr], local.vpc_cidr_blocks)
+  dynamic "egress" {
+    for_each = toset([
+      443,
+      2443, # FIPS port for CSP
+      6666,
+    ])
+
+    content {
+      description = "Outbound rules"
+      from_port   = egress.value
+      to_port     = egress.value
+      protocol    = "tcp"
+      cidr_blocks = concat([var.vpce_subnet_cidr], local.vpc_cidr_blocks)
+    }
   }
 
   tags = merge(data.aws_vpc.prod.tags, {
diff --git a/docs/guides/unity-catalog-azure.md b/docs/guides/unity-catalog-azure.md
@@ -168,11 +168,11 @@ resource "databricks_grants" "sandbox" {
   catalog = databricks_catalog.sandbox.name
   grant {
     principal  = "Data Scientists"
-    privileges = ["USAGE", "CREATE"]
+    privileges = ["USE_CATALOG", "CREATE"]
   }
   grant {
     principal  = "Data Engineers"
-    privileges = ["USAGE"]
+    privileges = ["USE_CATALOG"]
   }
 }
 
@@ -189,7 +189,7 @@ resource "databricks_grants" "things" {
   schema = databricks_schema.things.id
   grant {
     principal  = "Data Engineers"
-    privileges = ["USAGE"]
+    privileges = ["USE_SCHEMA"]
   }
 }
 ```
@@ -260,7 +260,7 @@ resource "databricks_grants" "external_creds" {
 
 resource "databricks_external_location" "some" {
   name = "external"
-  url = format("abfss://%s@%s.dfs.core.windows.net/",
+  url = format("abfss://%s@%s.dfs.core.windows.net",
     azurerm_storage_container.ext_storage.name,
   azurerm_storage_account.ext_storage.name)
 
diff --git a/docs/guides/unity-catalog-gcp.md b/docs/guides/unity-catalog-gcp.md
@@ -146,11 +146,11 @@ resource "databricks_grants" "sandbox" {
   catalog = databricks_catalog.sandbox.name
   grant {
     principal  = "Data Scientists"
-    privileges = ["USAGE", "CREATE"]
+    privileges = ["USE_CATALOG", "CREATE"]
   }
   grant {
     principal  = "Data Engineers"
-    privileges = ["USAGE"]
+    privileges = ["USE_CATALOG"]
   }
 }
 
@@ -167,7 +167,7 @@ resource "databricks_grants" "things" {
   schema = databricks_schema.things.id
   grant {
     principal  = "Data Engineers"
-    privileges = ["USAGE"]
+    privileges = ["USE_SCHEMA"]
   }
 }
 ```
diff --git a/docs/guides/unity-catalog.md b/docs/guides/unity-catalog.md
@@ -338,11 +338,11 @@ resource "databricks_grants" "sandbox" {
   catalog  = databricks_catalog.sandbox.name
   grant {
     principal  = "Data Scientists"
-    privileges = ["USAGE", "CREATE"]
+    privileges = ["USE_CATALOG", "CREATE"]
   }
   grant {
     principal  = "Data Engineers"
-    privileges = ["USAGE"]
+    privileges = ["USE_CATALOG"]
   }
 }
 
@@ -361,7 +361,7 @@ resource "databricks_grants" "things" {
   schema   = databricks_schema.things.id
   grant {
     principal  = "Data Engineers"
-    privileges = ["USAGE"]
+    privileges = ["USE_SCHEMA"]
   }
 }
 ```
diff --git a/docs/index.md b/docs/index.md
@@ -7,7 +7,7 @@ description: Terraform provider for the Databricks Lakehouse platform
 
 # Databricks Provider
 
-Use the Databricks Terraform provider to interact with almost all of [Databricks](http://databricks.com/) resources. If you're new to Databricks, please follow guide to create a workspace on [Azure](guides/azure-workspace.md) or [AWS](guides/aws-workspace.md) and then this [workspace management](guides/workspace-management.md) tutorial. Changelog is available [on GitHub](https://github.com/databricks/terraform-provider-databricks/blob/master/CHANGELOG.md).
+Use the Databricks Terraform provider to interact with almost all of [Databricks](http://databricks.com/) resources. If you're new to Databricks, please follow guide to create a workspace on [Azure](guides/azure-workspace.md), [AWS](guides/aws-workspace.md) or [GCP](guides/gcp-workspace.md) and then this [workspace management](guides/workspace-management.md) tutorial. Changelog is available [on GitHub](https://github.com/databricks/terraform-provider-databricks/blob/master/CHANGELOG.md).
 
 ![Resources](https://github.com/databricks/terraform-provider-databricks/raw/master/docs/resources.png)
 
@@ -291,7 +291,13 @@ When a workspace is created using a service principal account, that service prin
 
 ## Special configurations for GCP
 
-The provider works with [Google Cloud CLI authentication](https://cloud.google.com/sdk/docs/authorizing) to facilitate local development workflows. For automated scenarios, a service principal auth is necessary using `google_service_account` parameter with [impersonation](https://cloud.google.com/docs/authentication#service-accounts) and Application Default Credentials. and specification of  and `google_credentials` parameters). Alternatively, you could provide the service account key directly by passing it to `google_credentials` parameter (or `GOOGLE_CREDENTIALS` environment variable)
+The provider works with [Google Cloud CLI authentication](https://cloud.google.com/sdk/docs/authorizing) to facilitate local development workflows. For automated scenarios, a service principal auth is necessary using `google_service_account` parameter with [impersonation](https://cloud.google.com/docs/authentication#service-accounts) and Application Default Credentials. Alternatively, you could provide the service account key directly by passing it to `google_credentials` parameter (or `GOOGLE_CREDENTIALS` environment variable)
+
+## Special configuration for Unity Catalog
+
+Unity Catalog APIs are accessible via **workspace-level APIs**. This design may change in the future.
+
+If you are configuring a new Databricks account for the first time, please create at least one workspace and with an identity (user or service principal) that you intend to use for Unity Catalog rollout. You can then configure the provider using that identity and workspace to provision the required Unity Catalog resources.
 
 ## Miscellaneous configuration parameters
 
diff --git a/docs/resources/external_location.md b/docs/resources/external_location.md
@@ -55,7 +55,7 @@ resource "databricks_storage_credential" "external" {
 
 resource "databricks_external_location" "some" {
   name = "external"
-  url = format("abfss://%s@%s.dfs.core.windows.net/",
+  url = format("abfss://%s@%s.dfs.core.windows.net",
     azurerm_storage_container.ext_storage.name,
   azurerm_storage_account.ext_storage.name)
   credential_name = databricks_storage_credential.external.id
diff --git a/docs/resources/instance_profile.md b/docs/resources/instance_profile.md
@@ -108,8 +108,10 @@ resource "databricks_group_instance_profile" "all" {
   instance_profile_id = databricks_instance_profile.this.id
 }
 ```
+
 ## Usage with Databricks SQL serverless
-When the instance profile ARN and its associated IAM role ARN don't match and the instance profile is intended for use with Databricks SQL serverless, the `iam_role_arn` parameter can be specified
+
+When the instance profile ARN and its associated IAM role ARN don't match and the instance profile is intended for use with Databricks SQL serverless, the `iam_role_arn` parameter can be specified.
 
 ```hcl
 data "aws_iam_policy_document" "sql_serverless_assume_role" {
@@ -166,5 +168,5 @@ In addition to all arguments above, the following attributes are exported:
 The resource instance profile can be imported using the ARN of it
 
 ```bash
-$ terraform import databricks_instance_profile.this <instance-profile-arn>
+terraform import databricks_instance_profile.this <instance-profile-arn>
 ```
diff --git a/docs/resources/mws_workspaces.md b/docs/resources/mws_workspaces.md
@@ -344,7 +344,8 @@ On AWS, the following arguments could be modified after the workspace is running
 
 In addition to all arguments above, the following attributes are exported:
 
-* `id` - Canonical unique identifier for the workspace.
+* `id` - (String) Canonical unique identifier for the workspace, of the format `<account-id>/<workspace-id>`
+* `workspace_id` - (String) workspace id
 * `workspace_status_message` - (String) updates on workspace status
 * `workspace_status` - (String) workspace status
 * `creation_time` - (Integer) time when workspace was created
diff --git a/docs/resources/permissions.md b/docs/resources/permissions.md
@@ -4,11 +4,13 @@ subcategory: "Security"
 
 # databricks_permissions Resource
 
-This resource allows you to generically manage [access control](https://docs.databricks.com/security/access-control/index.html) in Databricks workspace. It would guarantee that only _admins_, _authenticated principal_ and those declared within `access_control` blocks would have specified access. It is not possible to remove management rights from _admins_ group. 
+This resource allows you to generically manage [access control](https://docs.databricks.com/security/access-control/index.html) in Databricks workspace. It would guarantee that only _admins_, _authenticated principal_ and those declared within `access_control` blocks would have specified access. It is not possible to remove management rights from _admins_ group.
 
 -> **Note** Configuring this resource for an object will **OVERWRITE** any existing permissions of the same type unless imported, and changes made outside of Terraform will be reset unless the changes are also reflected in the configuration.
 
--> **Note** It is not possible to lower permissions for `admins` or your own user anywhere from `CAN_MANAGE` level, so Databricks Terraform Provider [removes](https://github.com/databricks/terraform-provider-databricks/blob/master/access/resource_permissions.go#L261-L271) those `access_control` blocks automatically. 
+-> **Note** It is not possible to lower permissions for `admins` or your own user anywhere from `CAN_MANAGE` level, so Databricks Terraform Provider [removes](https://github.com/databricks/terraform-provider-databricks/blob/master/access/resource_permissions.go#L261-L271) those `access_control` blocks automatically.
+
+-> **Note** If multiple permission levels are specified for an identity (e.g. `CAN_RESTART` and `CAN_MANAGE` for a cluster), only the highest level permission is returned and will cause permanent drift.
 
 ## Cluster usage
 
@@ -602,7 +604,6 @@ resource "databricks_permissions" "endpoint_usage" {
 
 [SQL queries](https://docs.databricks.com/sql/user/security/access-control/query-acl.html) have three possible permissions: `CAN_VIEW`, `CAN_RUN` and `CAN_MANAGE`:
 
-
 -> **Note** If you do not define an `access_control` block granting `CAN_MANAGE` explictly for the user calling this provider, Databricks Terraform Provider will add `CAN_MANAGE` permission for the caller. This is a failsafe to prevent situations where the caller is locked out from making changes to the targeted `databricks_sql_query` resource when backend API do not apply permission inheritance correctly.
 
 ```hcl
@@ -674,9 +675,11 @@ General Permissions API does not apply to access control for tables and they hav
 Initially in Unity Catalog all users have no access to data, which has to be later assigned through [databricks_grants](grants.md) resource.
 
 ## Argument Reference
+
 One type argument and at least one access control block argument are required.
 
 ### Type Argument
+
 Exactly one of the following arguments is required:
 
 - `cluster_id` - [cluster](cluster.md) id
@@ -699,6 +702,7 @@ Exactly one of the following arguments is required:
 - `sql_alert_id` - [SQL alert](https://docs.databricks.com/sql/user/security/access-control/alert-acl.html) id
 
 ### Access Control Argument
+
 One or more `access_control` blocks are required to actually set the permission levels:
 
 ```hcl
@@ -710,11 +714,12 @@ access_control {
 
 Arguments for the `access_control` block are:
 
--> **Note** It is not possible to lower permissions for `admins` or your own user anywhere from `CAN_MANAGE` level, so Databricks Terraform Provider [removes](https://github.com/databricks/terraform-provider-databricks/blob/master/access/resource_permissions.go#L261-L271) those `access_control` blocks automatically. 
+-> **Note** It is not possible to lower permissions for `admins` or your own user anywhere from `CAN_MANAGE` level, so Databricks Terraform Provider [removes](https://github.com/databricks/terraform-provider-databricks/blob/master/access/resource_permissions.go#L261-L271) those `access_control` blocks automatically.
 
 - `permission_level` - (Required) permission level according to specific resource. See examples above for the reference.
 
 Exactly one of the below arguments is required:
+
 - `user_name` - (Optional) name of the [user](user.md).
 - `service_principal_name` - (Optional) Application ID of the [service_principal](service_principal.md#application_id).
 - `group_name` - (Optional) name of the [group](group.md). We recommend setting permissions on groups.
@@ -731,11 +736,13 @@ In addition to all arguments above, the following attributes are exported:
 The resource permissions can be imported using the object id
 
 ```bash
-$ terraform import databricks_permissions.this /<object type>/<object id>
+terraform import databricks_permissions.this /<object type>/<object id>
 ```
 
 ### Import Example
+
 Configuration file:
+
 ```hcl
 resource "databricks_mlflow_model" "model" {
   name        = "example_model"
@@ -753,6 +760,7 @@ resource "databricks_permissions" "model_usage" {
 ```
 
 Import command:
+
 ```bash
-$ terraform import databricks_permissions.model_usage /registered-models/<registered_model_id>
+terraform import databricks_permissions.model_usage /registered-models/<registered_model_id>
 ```

Original file line number	Diff line number	Diff line change
`@@ -168,11 +168,11 @@ resource "databricks_grants" "sandbox" {`
`168`	`168`	`catalog = databricks_catalog.sandbox.name`
`169`	`169`	`grant {`
`170`	`170`	`principal = "Data Scientists"`
`171`		`- privileges = ["USAGE", "CREATE"]`
	`171`	`+ privileges = ["USE_CATALOG", "CREATE"]`
`172`	`172`	`}`
`173`	`173`	`grant {`
`174`	`174`	`principal = "Data Engineers"`
`175`		`- privileges = ["USAGE"]`
	`175`	`+ privileges = ["USE_CATALOG"]`
`176`	`176`	`}`
`177`	`177`	`}`
`178`	`178`
`@@ -189,7 +189,7 @@ resource "databricks_grants" "things" {`
`189`	`189`	`schema = databricks_schema.things.id`
`190`	`190`	`grant {`
`191`	`191`	`principal = "Data Engineers"`
`192`		`- privileges = ["USAGE"]`
	`192`	`+ privileges = ["USE_SCHEMA"]`
`193`	`193`	`}`
`194`	`194`	`}`
`195`	`195`	```
`@@ -260,7 +260,7 @@ resource "databricks_grants" "external_creds" {`
`260`	`260`
`261`	`261`	`resource "databricks_external_location" "some" {`
`262`	`262`	`name = "external"`
`263`		`- url = format("abfss://%s@%s.dfs.core.windows.net/",`
	`263`	`+ url = format("abfss://%s@%s.dfs.core.windows.net",`
`264`	`264`	`azurerm_storage_container.ext_storage.name,`
`265`	`265`	`azurerm_storage_account.ext_storage.name)`
`266`	`266`
Original file line number	Diff line number	Diff line change
`@@ -146,11 +146,11 @@ resource "databricks_grants" "sandbox" {`
`146`	`146`	`catalog = databricks_catalog.sandbox.name`
`147`	`147`	`grant {`
`148`	`148`	`principal = "Data Scientists"`
`149`		`- privileges = ["USAGE", "CREATE"]`
	`149`	`+ privileges = ["USE_CATALOG", "CREATE"]`
`150`	`150`	`}`
`151`	`151`	`grant {`
`152`	`152`	`principal = "Data Engineers"`
`153`		`- privileges = ["USAGE"]`
	`153`	`+ privileges = ["USE_CATALOG"]`
`154`	`154`	`}`
`155`	`155`	`}`
`156`	`156`
`@@ -167,7 +167,7 @@ resource "databricks_grants" "things" {`
`167`	`167`	`schema = databricks_schema.things.id`
`168`	`168`	`grant {`
`169`	`169`	`principal = "Data Engineers"`
`170`		`- privileges = ["USAGE"]`
	`170`	`+ privileges = ["USE_SCHEMA"]`
`171`	`171`	`}`
`172`	`172`	`}`
`173`	`173`	```
Original file line number	Diff line number	Diff line change
`@@ -338,11 +338,11 @@ resource "databricks_grants" "sandbox" {`
`338`	`338`	`catalog = databricks_catalog.sandbox.name`
`339`	`339`	`grant {`
`340`	`340`	`principal = "Data Scientists"`
`341`		`- privileges = ["USAGE", "CREATE"]`
	`341`	`+ privileges = ["USE_CATALOG", "CREATE"]`
`342`	`342`	`}`
`343`	`343`	`grant {`
`344`	`344`	`principal = "Data Engineers"`
`345`		`- privileges = ["USAGE"]`
	`345`	`+ privileges = ["USE_CATALOG"]`
`346`	`346`	`}`
`347`	`347`	`}`
`348`	`348`
`@@ -361,7 +361,7 @@ resource "databricks_grants" "things" {`
`361`	`361`	`schema = databricks_schema.things.id`
`362`	`362`	`grant {`
`363`	`363`	`principal = "Data Engineers"`
`364`		`- privileges = ["USAGE"]`
	`364`	`+ privileges = ["USE_SCHEMA"]`
`365`	`365`	`}`
`366`	`366`	`}`
`367`	`367`	```