[Doc] Explain that special characters in URLs should be percent-encoded (#5178)

Resolves #4887

## Changes
<!-- Summary of your changes that are easy to understand -->

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

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

Author: alexott

NEXT_CHANGELOG.md

@@ -12,6 +12,7 @@
 
 ### Documentation
 
+* Explain that special characters in URLs should be percent-encoded ([#5178](https://github.com/databricks/terraform-provider-databricks/pull/5178)).
 * Improve documentation about `preloaded_docker_images.basic_auth` in `databricks_cluster` and `databricks_instance_pool` ([#5154](https://github.com/databricks/terraform-provider-databricks/pull/5154)).
 
 ### Exporter

docs/resources/catalog.md

@@ -26,7 +26,7 @@ resource "databricks_catalog" "sandbox" {
 The following arguments are required:
 
 * `name` - Name of Catalog relative to parent metastore.
-* `storage_root` - (Optional if `storage_root` is specified for the metastore) Managed location of the catalog. Location in cloud storage where data for managed tables will be stored. If not specified, the location will default to the metastore root location. Change forces creation of a new resource.
+* `storage_root` - (Optional if `storage_root` is specified for the metastore) Managed location of the catalog. Location in cloud storage where data for managed tables will be stored.  If the URL contains special characters, such as space, `&`, etc., they should be percent-encoded (space -> `%20`, etc.). If not specified, the location will default to the metastore root location. Change forces creation of a new resource.
 * `provider_name` - (Optional) For Delta Sharing Catalogs: the name of the delta sharing provider. Change forces creation of a new resource.
 * `share_name` - (Optional) For Delta Sharing Catalogs: the name of the share under the share provider. Change forces creation of a new resource.
 * `connection_name` - (Optional) For Foreign Catalogs: the name of the connection to an external data source. Changes forces creation of a new resource.

docs/resources/external_location.md

@@ -127,7 +127,7 @@ encryption_details {
 The following arguments are required:
 
 - `name` - Name of External Location, which must be unique within the [databricks_metastore](metastore.md). Change forces creation of a new resource.
-- `url` - Path URL in cloud storage, of the form: `s3://[bucket-host]/[bucket-dir]` (AWS), `abfss://[user]@[host]/[path]` (Azure), `gs://[bucket-host]/[bucket-dir]` (GCP).
+- `url` - Path URL in cloud storage, of the form: `s3://[bucket-host]/[bucket-dir]` (AWS), `abfss://[user]@[host]/[path]` (Azure), `gs://[bucket-host]/[bucket-dir]` (GCP).   If the URL contains special characters, such as space, `&`, etc., they should be percent-encoded (space -> `%20`, etc.).
 - `credential_name` - Name of the [databricks_storage_credential](storage_credential.md) to use with this external location.
 - `owner` - (Optional) Username/groupname/sp application_id of the external location owner.
 - `comment` - (Optional) User-supplied free-form text.

docs/resources/metastore.md

@@ -71,7 +71,7 @@ resource "databricks_metastore_assignment" "this" {
 The following arguments are required:
 
 * `name` - Name of metastore.
-* `storage_root` - (Optional) Path on cloud storage account, where managed `databricks_table` are stored. Change forces creation of a new resource. If no `storage_root` is defined for the metastore, each catalog must have a `storage_root` defined.
+* `storage_root` - (Optional) Path on cloud storage account, where managed `databricks_table` are stored.  If the URL contains special characters, such as space, `&`, etc., they should be percent-encoded (space -> `%20`, etc.). Change forces creation of a new resource. If no `storage_root` is defined for the metastore, each catalog must have a `storage_root` defined.
 * `region` - (Mandatory for account-level) The region of the metastore
 * `owner` - (Optional) Username/groupname/sp application_id of the metastore owner.
 * `delta_sharing_scope` - (Optional) Required along with `delta_sharing_recipient_token_lifetime_in_seconds`. Used to enable delta sharing on the metastore. Valid values: INTERNAL, INTERNAL_AND_EXTERNAL.  INTERNAL only allows sharing within the same account, and INTERNAL_AND_EXTERNAL allows cross account sharing and token based sharing.

docs/resources/registered_model.md

@@ -26,7 +26,7 @@ The following arguments are supported:
 * `schema_name` - (Required) The name of the schema where the registered model resides. *Change of this parameter forces recreation of the resource.*
 * `owner` - (Optional) Name of the registered model owner.
 * `comment` - (Optional) The comment attached to the registered model.
-* `storage_location` - (Optional) The storage location under which model version data files are stored. *Change of this parameter forces recreation of the resource.*
+* `storage_location` - (Optional) The storage location under which model version data files are stored.  If the URL contains special characters, such as space, `&`, etc., they should be percent-encoded (space -> `%20`, etc.). *Change of this parameter forces recreation of the resource.*
 
 ## Attribute Reference
 

docs/resources/schema.md

@@ -36,7 +36,7 @@ The following arguments are required:
 
 * `name` - Name of Schema relative to parent catalog. Change forces creation of a new resource.
 * `catalog_name` - Name of parent catalog. Change forces creation of a new resource.
-* `storage_root` - (Optional) Managed location of the schema. Location in cloud storage where data for managed tables will be stored. If not specified, the location will default to the catalog root location. Change forces creation of a new resource.
+* `storage_root` - (Optional) Managed location of the schema. Location in cloud storage where data for managed tables will be stored.  If the URL contains special characters, such as space, `&`, etc., they should be percent-encoded (space -> `%20`, etc.). If not specified, the location will default to the catalog root location. Change forces creation of a new resource.
 * `owner` - (Optional) Username/groupname/sp application_id of the schema owner.
 * `comment` - (Optional) User-supplied free-form text.
 * `properties` - (Optional) Extensible Schema properties.

docs/resources/sql_table.md

@@ -175,7 +175,7 @@ The following arguments are supported:
 * `catalog_name` - Name of parent catalog. Change forces the creation of a new resource.
 * `schema_name` - Name of parent Schema relative to parent Catalog. Change forces the creation of a new resource.
 * `table_type` - Distinguishes a view vs. managed/external Table. `MANAGED`, `EXTERNAL` or `VIEW`. Change forces the creation of a new resource.
-* `storage_location` - (Optional) URL of storage location for Table data (required for EXTERNAL Tables). Not supported for `VIEW` or `MANAGED` table_type.
+* `storage_location` - (Optional) URL of storage location for Table data (required for EXTERNAL Tables).  If the URL contains special characters, such as space, `&`, etc., they should be percent-encoded (space -> `%20`, etc.).  Not supported for `VIEW` or `MANAGED` table_type.
 * `data_source_format` - (Optional) External tables are supported in multiple data source formats. The string constants identifying these formats are `DELTA`, `CSV`, `JSON`, `AVRO`, `PARQUET`, `ORC`, and `TEXT`. Change forces the creation of a new resource. Not supported for `MANAGED` tables or `VIEW`.
 * `view_definition` - (Optional) SQL text defining the view (for `table_type == "VIEW"`). Not supported for `MANAGED` or `EXTERNAL` table_type.
 * `cluster_id` - (Optional) All table CRUD operations must be executed on a running cluster or SQL warehouse. If a cluster_id is specified, it will be used to execute SQL commands to manage this table. If empty, a cluster will be created automatically with the name `terraform-sql-table`. Conflicts with `warehouse_id`.

docs/resources/volume.md

@@ -83,7 +83,7 @@ The following arguments are supported:
 * `schema_name` - Name of parent Schema relative to parent Catalog. Change forces creation of a new resource.
 * `volume_type` - Volume type. `EXTERNAL` or `MANAGED`. Change forces creation of a new resource.
 * `owner` - (Optional) Name of the volume owner.
-* `storage_location` - (Optional) Path inside an External Location. Only used for `EXTERNAL` Volumes. Change forces creation of a new resource.
+* `storage_location` - (Optional) URL for the volume (should be inside of an existing [External Location](external_location.md)). Only used for `EXTERNAL` Volumes.  If the URL contains special characters, such as space, `&`, etc., they should be percent-encoded (space -> `%20`, etc.). Change forces creation of a new resource.
 * `comment` - (Optional) Free-form text.
 
 ## Attribute Reference