Framework - Resource Identity Documentation (#361)

* add skeleton of thoughts on doc updates

* Initial update to reflect the addition of resource identity.mdx

* Second update of documentation to address some comments

* Removing extra line

* Update content/terraform-plugin-framework/v1.15.x/docs/plugin/framework/resources/identity.mdx

Co-authored-by: Rose M Koron <[email protected]>

* adjust type pages

* Apply suggestions from code review

Co-authored-by: Rose M Koron <[email protected]>

* remove stack + note callout

* add to nav

* update code examples and change name back

* update identity docs

* more identity updates

* updates + todos

* space

* remove sections

* last updates to identity docs

---------

Co-authored-by: Rain <[email protected]>
Co-authored-by: Rain Kwan <[email protected]>
Co-authored-by: Rose M Koron <[email protected]>

Author: 3 people

content/terraform-plugin-framework/v1.15.x/data/plugin-framework-nav-data.json

@@ -63,6 +63,10 @@
         "title": "Delete",
         "path": "resources/delete"
       },
+      {
+        "title": "Identity",
+        "path": "resources/identity"
+      },
       {
         "title": "Configure Clients",
         "path": "resources/configure"
@@ -91,6 +95,10 @@
         "title": "Upgrade State",
         "path": "resources/state-upgrade"
       },
+      {
+        "title": "Upgrade Identity",
+        "path": "resources/identity-upgrade"
+      },
       {
         "title": "Manage Private State",
         "path": "resources/private-state"

content/terraform-plugin-framework/v1.15.x/docs/plugin/framework/handling-data/attributes/bool.mdx

@@ -59,6 +59,15 @@ The acceptable behaviors of these configurability options are:
 - `Optional` and `Computed`: The value may be practitioner configured or the value may be set in provider logic when the practitioner configuration is null.
 - `Computed` only: The value will be set in provider logic and any practitioner configuration causes the framework to automatically raise an error diagnostic for the unexpected configuration value.
 
+#### Resource Identity
+
+If creating a resource identity schema, set either `OptionalForImport` or `RequiredForImport` to `true` to inform Terraform if practitioners must set the attribute when importing with that resource's identity.
+
+The acceptable behaviors of these configurability options are:
+
+- `RequiredForImport` only: A practitioner must configure the attribute to a known value (not `null`), otherwise Terraform automatically raises an error diagnostic for the missing value.
+- `OptionalForImport` only: A practitioner must configure the value to a known value or `null`.
+
 ### Custom Types
 
 You may want to build your own attribute value and type implementations to allow your provider to combine validation, description, and plan customization behaviors into a reusable bundle. This helps avoid duplication or reimplementation and ensures consistency. These implementations use the `CustomType` field in the attribute type.

content/terraform-plugin-framework/v1.15.x/docs/plugin/framework/handling-data/attributes/float32.mdx

@@ -65,6 +65,15 @@ The acceptable behaviors of these configurability options are:
 - `Optional` and `Computed`: The value may be practitioner configured or the value may be set in provider logic when the practitioner configuration is null.
 - `Computed` only: The value will be set in provider logic and any practitioner configuration causes the framework to automatically raise an error diagnostic for the unexpected configuration value.
 
+#### Resource Identity
+
+If creating a resource identity schema, set either `OptionalForImport` or `RequiredForImport` to `true` to inform Terraform if practitioners must set the attribute when importing with that resource's identity.
+
+The acceptable behaviors of these configurability options are:
+
+- `RequiredForImport` only: A practitioner must configure the attribute to a known value (not `null`), otherwise Terraform automatically raises an error diagnostic for the missing value.
+- `OptionalForImport` only: A practitioner must configure the value to a known value or `null`.
+
 ### Custom Types
 
 You may want to build your own attribute value and type implementations to allow your provider to combine validation, description, and plan customization behaviors into a reusable bundle. This helps avoid duplication or reimplementation and ensures consistency. These implementations use the `CustomType` field in the attribute type.

content/terraform-plugin-framework/v1.15.x/docs/plugin/framework/handling-data/attributes/float64.mdx

@@ -65,6 +65,15 @@ The acceptable behaviors of these configurability options are:
 - `Optional` and `Computed`: The value may be practitioner configured or the value may be set in provider logic when the practitioner configuration is null.
 - `Computed` only: The value will be set in provider logic and any practitioner configuration causes the framework to automatically raise an error diagnostic for the unexpected configuration value.
 
+#### Resource Identity
+
+If creating a resource identity schema, set either `OptionalForImport` or `RequiredForImport` to `true` to inform Terraform if practitioners must set the attribute when importing with that resource's identity.
+
+The acceptable behaviors of these configurability options are:
+
+- `RequiredForImport` only: A practitioner must configure the attribute to a known value (not `null`), otherwise Terraform automatically raises an error diagnostic for the missing value.
+- `OptionalForImport` only: A practitioner must configure the value to a known value or `null`.
+
 ### Custom Types
 
 You may want to build your own attribute value and type implementations to allow your provider to combine validation, description, and plan customization behaviors into a reusable bundle. This helps avoid duplication or reimplementation and ensures consistency. These implementations use the `CustomType` field in the attribute type.

content/terraform-plugin-framework/v1.15.x/docs/plugin/framework/handling-data/attributes/int32.mdx

@@ -65,6 +65,15 @@ The acceptable behaviors of these configurability options are:
 - `Optional` and `Computed`: The value may be practitioner configured or the value may be set in provider logic when the practitioner configuration is null.
 - `Computed` only: The value will be set in provider logic and any practitioner configuration causes the framework to automatically raise an error diagnostic for the unexpected configuration value.
 
+#### Resource Identity
+
+If creating a resource identity schema, set either `OptionalForImport` or `RequiredForImport` to `true` to inform Terraform if practitioners must set the attribute when importing with that resource's identity.
+
+The acceptable behaviors of these configurability options are:
+
+- `RequiredForImport` only: A practitioner must configure the attribute to a known value (not `null`), otherwise Terraform automatically raises an error diagnostic for the missing value.
+- `OptionalForImport` only: A practitioner must configure the value to a known value or `null`.
+
 ### Custom Types
 
 You may want to build your own attribute value and type implementations to allow your provider to combine validation, description, and plan customization behaviors into a reusable bundle. This helps avoid duplication or reimplementation and ensures consistency. These implementations use the `CustomType` field in the attribute type.

content/terraform-plugin-framework/v1.15.x/docs/plugin/framework/handling-data/attributes/int64.mdx

@@ -65,6 +65,15 @@ The acceptable behaviors of these configurability options are:
 - `Optional` and `Computed`: The value may be practitioner configured or the value may be set in provider logic when the practitioner configuration is null.
 - `Computed` only: The value will be set in provider logic and any practitioner configuration causes the framework to automatically raise an error diagnostic for the unexpected configuration value.
 
+#### Resource Identity
+
+If creating a resource identity schema, set either `OptionalForImport` or `RequiredForImport` to `true` to inform Terraform if practitioners must set the attribute when importing with that resource's identity.
+
+The acceptable behaviors of these configurability options are:
+
+- `RequiredForImport` only: A practitioner must configure the attribute to a known value (not `null`), otherwise Terraform automatically raises an error diagnostic for the missing value.
+- `OptionalForImport` only: A practitioner must configure the value to a known value or `null`.
+
 ### Custom Types
 
 You may want to build your own attribute value and type implementations to allow your provider to combine validation, description, and plan customization behaviors into a reusable bundle. This helps avoid duplication or reimplementation and ensures consistency. These implementations use the `CustomType` field in the attribute type.

content/terraform-plugin-framework/v1.15.x/docs/plugin/framework/handling-data/attributes/list.mdx

@@ -82,6 +82,15 @@ The acceptable behaviors of these configurability options are:
 - `Optional` and `Computed`: The value may be practitioner configured or the value may be set in provider logic when the practitioner configuration is null.
 - `Computed` only: The value will be set in provider logic and any practitioner configuration causes the framework to automatically raise an error diagnostic for the unexpected configuration value.
 
+#### Resource Identity
+
+If creating a resource identity schema, set either `OptionalForImport` or `RequiredForImport` to `true` to inform Terraform if practitioners must set the attribute when importing with that resource's identity.
+
+The acceptable behaviors of these configurability options are:
+
+- `RequiredForImport` only: A practitioner must configure the attribute to a known value (not `null`), otherwise Terraform automatically raises an error diagnostic for the missing value.
+- `OptionalForImport` only: A practitioner must configure the value to a known value or `null`.
+
 ### Custom Types
 
 You may want to build your own attribute value and type implementations to allow your provider to combine validation, description, and plan customization behaviors into a reusable bundle. This helps avoid duplication or reimplementation and ensures consistency. These implementations use the `CustomType` field in the attribute type.

content/terraform-plugin-framework/v1.15.x/docs/plugin/framework/handling-data/attributes/number.mdx

@@ -65,6 +65,15 @@ The acceptable behaviors of these configurability options are:
 - `Optional` and `Computed`: The value may be practitioner configured or the value may be set in provider logic when the practitioner configuration is null.
 - `Computed` only: The value will be set in provider logic and any practitioner configuration causes the framework to automatically raise an error diagnostic for the unexpected configuration value.
 
+#### Resource Identity
+
+If creating a resource identity schema, set either `OptionalForImport` or `RequiredForImport` to `true` to inform Terraform if practitioners must set the attribute when importing with that resource's identity.
+
+The acceptable behaviors of these configurability options are:
+
+- `RequiredForImport` only: A practitioner must configure the attribute to a known value (not `null`), otherwise Terraform automatically raises an error diagnostic for the missing value.
+- `OptionalForImport` only: A practitioner must configure the value to a known value or `null`.
+
 ### Custom Types
 
 You may want to build your own attribute value and type implementations to allow your provider to combine validation, description, and plan customization behaviors into a reusable bundle. This helps avoid duplication or reimplementation and ensures consistency. These implementations use the `CustomType` field in the attribute type.

content/terraform-plugin-framework/v1.15.x/docs/plugin/framework/handling-data/attributes/string.mdx

@@ -58,6 +58,15 @@ The acceptable behaviors of these configurability options are:
 - `Optional` and `Computed`: The value may be practitioner configured or the value may be set in provider logic when the practitioner configuration is null.
 - `Computed` only: The value will be set in provider logic and any practitioner configuration causes the framework to automatically raise an error diagnostic for the unexpected configuration value.
 
+#### Resource Identity
+
+If creating a resource identity schema, set either `OptionalForImport` or `RequiredForImport` to `true` to inform Terraform if practitioners must set the attribute when importing with that resource's identity.
+
+The acceptable behaviors of these configurability options are:
+
+- `RequiredForImport` only: A practitioner must configure the attribute to a known value (not `null`), otherwise Terraform automatically raises an error diagnostic for the missing value.
+- `OptionalForImport` only: A practitioner must configure the value to a known value or `null`.
+
 ### Custom Types
 
 You may want to build your own attribute value and type implementations to allow your provider to combine validation, description, and plan customization behaviors into a reusable bundle. This helps avoid duplication or reimplementation and ensures consistency. These implementations use the `CustomType` field in the attribute type.

content/terraform-plugin-framework/v1.15.x/docs/plugin/framework/resources/create.mdx

@@ -155,6 +155,10 @@ func (r ThingResource) Create(ctx context.Context, req resource.CreateRequest, r
 }
 ```
 
+## Resource Identity
+
+Managed resources that support identity also need to set the identity data during `Create`, see the ["Identity" page](/terraform/plugin/framework/resources/identity#writing-identity) for more information.
+
 ## Caveats
 
 Note these caveats when implementing the `Create` method: