docs: explain resource metadata (#3447)

docs/images/icons/key.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 0 24 24" width="24"><path d="M0 0h24v24H0z" fill="none"/><path d="M12.65 10C11.83 7.67 9.61 6 7 6c-3.31 0-6 2.69-6 6s2.69 6 6 6c2.61 0 4.83-1.67 5.65-4H17v4h4v-4h2v-4H12.65zM7 14c-1.1 0-2-.9-2-2s.9-2 2-2 2 .9 2 2-.9 2-2 2z"/></svg>

docs/images/icons/table-rows.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" enable-background="new 0 0 24 24" height="24" viewBox="0 0 24 24" width="24"><rect fill="none" height="24" width="24"/><path d="M21,8H3V4h18V8z M21,10H3v4h18V10z M21,16H3v4h18V16z"/></svg>

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)