Document name and id (#475)

* Update task.md

* Update getting-started.md

* Restyled by prettier-markdown

* Reword `id` note

* Update getting-started.md

* Update task.md

* Restyled by prettier-markdown

* Apply suggestions from code review

Co-authored-by: Casper da Costa-Luis <[email protected]>

* Simplify name deprecation

* Update task.md

* Apply suggestions from code review

Co-authored-by: Casper da Costa-Luis <[email protected]>

* Apply suggestions from code review

Co-authored-by: Casper da Costa-Luis <[email protected]>

Co-authored-by: Restyled.io <[email protected]>
Co-authored-by: Casper da Costa-Luis <[email protected]>

Author: 3 people

docs/guides/getting-started.md

@@ -87,6 +87,8 @@ With spot/preemptible instances (`spot >= 0`), auto-recovery logic and persisten
 
 -> **Note:** A large `workdir` may take a long time to upload.
 
+-> **Note:** The [`id`](https://registry.terraform.io/providers/iterative/iterative/latest/docs/resources/task#id) returned by `terraform apply` (i.e. `[id=tpi-···]`) can be used to locate the created cloud resources through the cloud's web console or command–line tool.
+
 ## Query Status
 
 ```console

docs/resources/task.md

@@ -11,7 +11,6 @@ This resource will:
 
 ```hcl
 resource "iterative_task" "example" {
-  name        = "example"
   cloud       = "aws"
   machine     = "m"       # medium. Or any of: l, xl, m+k80, xl+v100, ...
   image       = "ubuntu"
@@ -43,7 +42,6 @@ resource "iterative_task" "example" {
 
 ### Optional
 
-- `name` - (Optional) Deterministic task name.
 - `region` - (Optional) [Cloud region/zone](#cloud-regions) to run the task on.
 - `machine` - (Optional) See [Machine Types](#machine-types) below.
 - `disk_size` - (Optional) Size of the ephemeral machine storage in GB.
@@ -54,21 +52,23 @@ resource "iterative_task" "example" {
 - `storage.output` - (Optional) Results directory (**relative to `workdir`**) to download (default: no download).
 - `environment` - (Optional) Map of environment variable names and values for the task script. Empty string values are replaced with local environment values. Empty values may also be combined with a [glob](<https://en.wikipedia.org/wiki/Glob_(programming)>) name to import all matching variables.
 - `timeout` - (Optional) Maximum number of seconds to run before termination.
+- `name` - (Optional) Discouraged and may be removed in future. Deterministic task name (e.g. `name="Hello, World!"` always produces `id="tpi-hello-world-5kz6ldls-57wo7rsp"`).
 
 -> **Note:** `output` is relative to `workdir`, so `storage { workdir = "foo", output = "bar" }` means "upload `./foo/`, change working directory to the uploaded folder, run `script`, and download `bar` (i.e. `./foo/bar`)".
 
 ## Attribute Reference
 
 In addition to all arguments above, the following attributes are exported:
 
+- `id` - Task identifier, `tpi-{name}-{random_hash_1}-{random_hash_2}`. Either the full `{id}` or (if too long), the shorter `{random_hash_1}{random_hash_2}` is used as the name for all cloud resources.
 - `ssh_public_key` - Used to access the created machines.
 - `ssh_private_key` - Used to access the created machines.
 - `addresses` - IP addresses of the currently active machines.
 - `status` - Status of the machine orchestrator.
 - `events` - List of events for the machine orchestrator.
 - `logs` - List with task logs; one for each machine.
 
-~> **Warning:** Status and events don't produce a stable output between cloud providers and are intended for human consumption only.
+~> **Warning:** `events` have different formats across cloud providers and cannot be relied on for programmatic consumption/automation.
 
 ## Machine Type