Added docs for singleton best practices and exclude_delete

docs/content/best-practices/common-resource-patterns.md

@@ -0,0 +1,17 @@
+---
+title: "Common resource patterns"
+weight: 40
+---
+
+# Common resource patterns
+
+## Singletons
+
+Singletons are resources – often config or settings objects – that can only exist once. In some cases, it may be possible to create and delete the resource (but only one can exist at a time); in other cases the resource _always_ exists and can only be read and updated.
+
+Implementing resources like this may require some or all of the following:
+
+1. If there _isn't_ a create endpoint, set the [create_url]({{< ref "/develop/resource-reference/#create_url" >}}) to point to the update endpoint.
+1. If there _is_ a create endpoint, add [pre-create custom code]({{< ref "/develop/custom-code/#pre_post_injection" >}}) that implements "acquire-on-create" logic. The custom code should check whether the resource already exists with a read request, and if it does, run the update logic and return early. For example, see [mmv1/templates/terraform/pre_create/firebasehosting_site.go.tmpl](https://github.com/GoogleCloudPlatform/magic-modules/blob/dc4d9755cb9288177e0996c1c3b3fa9738ebdf89/mmv1/templates/terraform/pre_create/firebasehosting_site.go.tmpl).
+   * Note: The main disadvantage of "acquire-on-create" logic is that users will not be presented with a diff between the resource's old and new states – because from the terraform perspective, the resource is only being created. Please upvote https://github.com/hashicorp/terraform/issues/19017 to request better support for this workflow.
+1. If there is no delete endpoint, set [`exclude_delete: true`]({{< ref "/develop/resource-reference/#create_url" >}}) at the top level of the resource.

docs/content/best-practices/deletion-behaviors.md

@@ -33,3 +33,7 @@ Some resources need to let users control the actions taken add deletion time. Fo
 One common example is `ABANDON`, which is useful if the resource is safe to delete from Terraform but could cause problems if deleted from the API - for example, `google_bigtable_gc_policy` deletion can fail in replicated instances. `ABANDON` indicates that attempts to delete the resource should remove it from state without actually deleting it.
 
 See [Client-side fields]({{< ref "/develop/client-side-fields" >}}) for information about adding `deletion_policy` fields.
+
+## Exclude deletion {#exclude_delete}
+
+Some resources do not support deletion in the API and can only be removed from state. For these resources, the best practice is to set [`exclude_delete: true`]({{< ref "/develop/resource-reference#exclude_delete" >}}) on the resource.

docs/content/develop/resource-reference.md

@@ -205,6 +205,14 @@ Example:
 delete_verb: 'POST'
 ```
 
+### `exclude_delete`
+If true, deleting the resource will only remove it from the Terraform state and will not call an API. If false, deleting the resource will run the standard deletion behavior and/or any [custom code]({{< ref "/develop/custom-code" >}}) related to deletion.
+This should be used if the resource can never be deleted in the API, and there is no other reasonable action to take on deletion. See [Deletion behaviors]({{< ref "/best-practices/deletion-behaviors" >}}) for more information.
+
+```yaml
+exclude_delete: true
+```
+
 ### `autogen_async`
 
 If true, code for handling long-running operations is generated along with