From 32210db0abcfbc0f3a202982875f53e1ccd536ed Mon Sep 17 00:00:00 2001
From: Alisdair McDiarmid <alisdair@users.noreply.github.com>
Date: Wed, 30 Jun 2021 15:00:43 -0400
Subject: [PATCH] documentation: Add drift to machine readable UI

---
 .../internals/machine-readable-ui.html.md     | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/website/docs/internals/machine-readable-ui.html.md b/website/docs/internals/machine-readable-ui.html.md
index 9f234fb24..742e4e9dc 100644
--- a/website/docs/internals/machine-readable-ui.html.md
+++ b/website/docs/internals/machine-readable-ui.html.md
@@ -54,6 +54,7 @@ The following message types are supported:
 
 ### Operation Results
 
+- `resource_drift`: describes a detected change to a single resource made outside of Terraform
 - `planned_change`: describes a planned change to a single resource
 - `change_summary`: summary of all planned or applied changes
 - `outputs`: list of all root module outputs
@@ -85,6 +86,39 @@ A machine-readable UI command output will always begin with a `version` message.
 }
 ```
 
+## Resource Drift
+
+If drift is detected during planning, Terraform will emit a `resource_drift` message for each resource which has changed outside of Terraform. This message has an embedded `change` object with the following keys:
+
+- `resource`: object describing the address of the resource to be changed; see [resource object](#resource-object) below for details
+- `action`: the action planned to be taken for the resource. Values: `update`, `delete`.
+
+This message does not include details about the exact changes which caused the change to be planned. That information is available in [the JSON plan output](./json-format.html).
+
+### Example
+
+```json
+{
+  "@level": "info",
+  "@message": "random_pet.animal: Drift detected (update)",
+  "@module": "terraform.ui",
+  "@timestamp": "2021-05-25T13:32:41.705503-04:00",
+  "change": {
+    "resource": {
+      "addr": "random_pet.animal",
+      "module": "",
+      "resource": "random_pet.animal",
+      "implied_provider": "random",
+      "resource_type": "random_pet",
+      "resource_name": "animal",
+      "resource_key": null
+    },
+    "action": "update"
+  },
+  "type": "resource_drift"
+}
+```
+
 ## Planned Change
 
 At the end of a plan or before an apply, Terraform will emit a `planned_change` message for each resource which has changes to apply. This message has an embedded `change` object with the following keys: