Terraform: match_baton_id with already-synced groups and destroy behavior

developer/terraform.mdx

@@ -20,7 +20,7 @@
 The Terraform provider supports three authentication methods:
 
 1. **Client credentials** -- traditional client ID + secret from a [service principal](/product/admin/service-principals/overview)
 2. **Workload federation** -- secretless OIDC token exchange from [HCP Terraform](/product/admin/service-principals/hcp-terraform), [GitHub Actions](/product/admin/service-principals/github-actions), or other CI/CD platforms
 3. **Static access token** -- pre-exchanged bearer token via `CONDUCTORONE_ACCESS_TOKEN`
 
 For details on setting up service principals and choosing an authentication method, see [service principals](/product/admin/service-principals/overview).
@@ -47,7 +47,9 @@
 
 Now, with the Group ID as a join key, you can perform a single Terraform run that creates a group in C1 and simultaneously merges that group with the corresponding IdP group. This eliminates the need to wait for multiple C1 syncs and dramatically simplifies your group management process.
 
+The same configuration works whether or not C1 has already synced the group. If the group is new, Terraform creates the resource and entitlement in C1, and the next sync merges the IdP group into them. If C1 has already synced the group, Terraform adopts the existing resource and entitlement instead of creating duplicates, and their C1 IDs stay the same.
+
 Here are sample Terraform files demonstrating how to use the `match_baton_id` key to sync a C1 group with Okta:
 
 **okta.tf file:**
 
@@ -127,11 +129,36 @@
 ```
 
 <Warning>
 This example works because Okta's connector uses the native Okta group ID as the match key. Other connectors may not. For a Databricks group, set `match_baton_id` to `account/<account-id>/group/<group-id>`, not the bare Databricks group ID. With the bare ID, the sync creates a second resource for the group instead of merging. See [per-connector ID formats](/developer/recipes-id#per-connector-id-formats).
 </Warning>
 
+#### Keep the IdP group's name
+
+After the group syncs, the connector can update the resource's display name to match the IdP. To stop Terraform from planning a change back to the name in your configuration, ignore that attribute:
+
+```terraform
+resource "conductorone_app_resource" "okta_group_resource" {
+  # ...
+  lifecycle {
+    ignore_changes = [display_name]
+  }
+}
+```
+
+#### What `terraform destroy` does
+
+The IdP and its connector decide whether a synced group exists in C1, so Terraform does not delete it. In provider version 1.8.2 and later:
 
+| State of the resource or entitlement in C1 | Result of `terraform destroy` |
+| --- | --- |
+| Created by Terraform and not yet synced from the IdP | Deleted from C1. |
+| Synced from the IdP (merged after creation, or adopted) | Removed from Terraform state only. It stays in C1 and the connector keeps managing it. Terraform shows a warning. |
+| Already deleted in C1 | Removed from Terraform state. |
 
+If you also delete the group in the IdP, the next sync removes it from C1. If you apply the configuration again later, Terraform adopts the same resource and entitlement.
 
+<Note>
+Earlier provider versions return an error such as `only resources created in ConductorOne can be deleted` when you destroy a synced resource. To stop managing the resource in those versions, run `terraform state rm <resource address>`. Nothing in C1 is changed.
+</Note>