From 0f0b2e817e818c78a5e901737a1eedff9c154bca Mon Sep 17 00:00:00 2001
From: Din Music <din.music@canonical.com>
Date: Wed, 7 Aug 2024 18:06:46 +0000
Subject: [PATCH] docs: Add documentation for trust token

Signed-off-by: Din Music <din.music@canonical.com>
---
 docs/resources/trust_token.md | 57 +++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 docs/resources/trust_token.md

diff --git a/docs/resources/trust_token.md b/docs/resources/trust_token.md
new file mode 100644
index 00000000..d2236a66
--- /dev/null
+++ b/docs/resources/trust_token.md
@@ -0,0 +1,57 @@
+# lxd_trust_token
+
+The `lxd_trust_token` resource allows you to create new tokens in the LXD trust store.
+
+## Example Usage
+
+```hcl
+resource "lxd_trust_token" "token1" {
+  name = "mytoken"
+}
+
+output "token" {
+  value = lxd_trust_token.token1.token
+}
+```
+
+## Argument Reference
+
+* `name` - **Required** - Name of the token.
+
+* `projects` - *Optional* - List of projects to restrict the token to.
+
+* `remote` - *Optional* - The remote in which the resource will be created. If not provided,
+  the provider's default remote will be used.
+
+* `trigger` - *Optional* - When to trigger the token generation. Possible values are `once` and `always` (if missing). Defaults to `always`.
+
+## Attribute Reference
+
+The following attributes are exported:
+
+* `token` - The generated token.
+
+* `expires_at` - Time when trust token expires. If token expiry is configured, the value will be in format `YYYY/MM/DD hh:mm TZ`.
+
+## Trust token expiry
+
+~> **Warning**
+  The provider is unable to differentiate between the expired and consumed token.
+  If token generation is set to `once` and the token expires, it will not be regenerated.
+
+Trust token expiry is defined by the system configuration `core.remote_token_expiry`.
+If the setting is configured, `expires_at` attribute will be populated, otherwise, it will be empty.
+
+For example, to set the token expiry to 20 minutes, run the following command:
+```
+lxc config set core.remote_token_expiry=20M
+```
+
+If trigger is set to `once` the token will not be regenerated on consequite applies.
+Setting trigger to `always` ensures that the token is always present, and will be regenerated if missing.
+
+## Notes
+
+* Token's unique identifier is the operation ID and not the token name. Therefore, multiple tokens can exist with the same name.
+
+* See the LXD [documentation](https://documentation.ubuntu.com/lxd/en/latest/authentication/#authentication-token) for more information on trust tokens.