docs: explain resource metadata (#3447)

docs/manifest.json

@@ -61,7 +61,14 @@
         {
           "title": "Provider Authentication",
           "description": "Learn how to authenticate the provisioner",
-          "path": "./templates/authentication.md"
+          "path": "./templates/authentication.md",
+          "icon_path": "./images/icons/key.svg"
+        },
+        {
+          "title": "Resource Metadata",
+          "description": "Learn how to expose resource data to users",
+          "path": "./templates/resource-metadata.md",
+          "icon_path": "./images/icons/table-rows.svg"
         }
       ]
     },

docs/templates/resource-metadata.md

@@ -0,0 +1,60 @@
+# Resource Metadata
+
+Expose key workspace information to your users via [`coder_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata) resources in your template code.
+
+![ui](../images/metadata-ui.png)
+
+<blockquote class="info">
+Coder automatically generates the <code>type</code> metadata.
+</blockquote>
+
+You can use `coder_metadata` to show
+
+- Compute resources
+- IP addresses
+- [Secrets](../secrets.md#displaying-secrets)
+- Important file paths
+
+and any other Terraform resource attribute.
+
+## Example
+
+Expose the disk size, deployment name, and persistent
+directory in a Kubernetes template with:
+
+```hcl
+resource "kubernetes_persistent_volume_claim" "root" {
+    ...
+}
+
+resource "kubernetes_deployment" "coder" {
+  # My deployment is ephemeral
+  count = data.coder_workspace.me.start_count
+  ...
+}
+
+resource "coder_metadata" "pvc" {
+  resource_id = kubernetes_persistent_volume_claim.root.id
+  item {
+    key = "size"
+    value = kubernetes_persistent_volume_claim.root.spec[0].resources[0].requests.storage
+  }
+  item {
+    key = "dir"
+    value = "/home/coder"
+  }
+}
+
+resource "coder_metadata" "deployment" {
+  count = data.coder_workspace.me.start_count
+  resource_id = kubernetes_deployment.coder[0].id
+  item {
+    key = "name"
+    value = kubernetes_deployment.coder[0].metadata[0].name
+  }
+}
+```
+
+## Up next
+
+- Learn about [secrets](../secrets.md)