Merge pull request #51 from platform9/pushkar/pcd-9784-docs

docs: import-ID lookups and a Community Edition example (PCD-9784)

Author: PF9-pushkar

CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Documentation
+
+- **Every import now says where its ID comes from** (PCD-9784). Each resource's Import section
+  names the `pcdctl` command (or resource-manager call) that prints the ID it needs, and a new
+  [Importing guide](docs/guides/importing.md) covers CLI setup, `terraform import` versus
+  `import` blocks with generated configuration, a per-resource lookup table, the resmgr host
+  UUID, and a worked blueprint import.
+- **A runnable Community Edition example** at `examples/complete/community-edition/`, rendered
+  by the new [Community Edition guide](docs/guides/community-edition.md): from one prepared
+  host to a running instance with an NFS-backed volume attached, in one apply. Validated end to
+  end on a Community Edition 2026.4 lab.
+- `pcd_blockstorage_volume_type` and `pcd_cluster_blueprint` explain how `volume_backend_name`,
+  `storage_backends_json`, `image_library_storage`, and `pcd_host_cluster_role.backends` fit
+  together; the README's PCD-native table adds `pcd_cluster` and `pcd_host_cluster_role`.
+- **Corrected `pcd_host_cluster_role.backends`:** it lists the *second-level* keys of
+  `storage_backends_json` (the driver configuration names), not the top-level backend names as
+  the description said. The top-level key is what becomes `volume_backend_name` on the host.
+  Naming a top-level key in `backends` yields an empty backend set, `cinder-volume` cannot
+  start, and the host is stuck converging while resmgr refuses every role change (409). The
+  mistake was invisible while every example used the same name at both levels.
+
 ## [0.1.10] - 2026-09-03
 
 ### Changed

README.md

@@ -18,10 +18,19 @@ can do.
 
 | Resource | What it manages |
 |---|---|
-| `pcd_cluster_blueprint` | The region's **cluster blueprint** — the shared config every virtualized cluster inherits: networking type (OVN/OVS), virtual-network segmentation range, image-library and VM storage, Cinder backends, VM HA, and auto-rebalancing. PCD keeps one per region, so the usual flow is `terraform import` then manage in place. Also available read-only as the `pcd_cluster_blueprint` data source. |
+| `pcd_cluster_blueprint` | The region's **cluster blueprint** — the shared config every virtualized cluster inherits: virtual-network segmentation range, DNS domain, image-library and VM storage, and the Cinder storage backends. PCD keeps one per region, so the usual flow is `terraform import` then manage in place. Also available read-only as the `pcd_cluster_blueprint` data source. |
+| `pcd_cluster` | A **cluster** (host cluster) — the unit hypervisors join, carrying VM high availability, auto-rebalancing, GPU, and CPU-model settings. |
 | `pcd_host_config` | A **host configuration** — the mapping of each traffic type (management, VM console, tunneling, image library, live migration) to a network interface, plus physical-network labels. |
-| `pcd_host_role` | Assigns a **PCD role** (e.g. `pf9-ostackhost-neutron`) to an onboarded host. |
 | `pcd_host_config_assignment` | Attaches a host configuration to a host. |
+| `pcd_host_cluster_role` | Onboards a host by assigning it a **cluster role** (`hypervisor`, `image-library`, `persistent-storage`, `dns`); PCD computes the granular role settings from the blueprint and host configuration. |
+| `pcd_host_role` | Assigns one granular **PCD role** (e.g. `pf9-ostackhost-neutron`) directly; the low-level API under `pcd_host_cluster_role`. |
+
+Two guides on the registry tie these together: the
+[Community Edition guide](https://registry.terraform.io/providers/platform9/pcd/latest/docs/guides/community-edition)
+builds a region from an empty host to a running VM (the source is
+[`examples/complete/community-edition/`](examples/complete/community-edition/)), and the
+[Importing guide](https://registry.terraform.io/providers/platform9/pcd/latest/docs/guides/importing)
+says where every import ID comes from.
 
 Everything else mirrors `terraform-provider-openstack` closely (attribute names, import IDs,
 `OS_*` env), so migrating an existing OpenStack configuration is largely mechanical.

docs/data-sources/cluster_blueprint.md

@@ -30,10 +30,10 @@ data "pcd_cluster_blueprint" "example" {
 - `dns_domain_name` (String) The internal DNS domain name for VMs.
 - `enable_distributed_routing` (Boolean) Whether distributed routing is enabled for the region. PCD-set; not user-configurable.
 - `image_library_shared_storage` (Boolean) Whether the image library uses shared storage.
-- `image_library_storage` (String) The image library storage location.
+- `image_library_storage` (String) The name of the volume type the image library stores images on.
 - `instance_shared_storage` (Boolean) Whether `vm_storage` is mounted as shared storage (e.g. NFS) across all hosts.
 - `networking_type` (String) The networking type PCD selected for the region (`ovn`). PCD-set; not user-configurable.
-- `storage_backends_json` (String, Sensitive) The Cinder storage backends as a JSON string (contains credentials).
+- `storage_backends_json` (String, Sensitive) The Cinder storage backends as a JSON string (contains credentials), shaped `{"<backend>": {"<config>": {"driver": ..., "config": {...}}}}`; the `pcd_cluster_blueprint` resource documents the shape.
 - `virtual_networking` (Attributes) Virtual (tenant) networking settings. (see [below for nested schema](#nestedatt--virtual_networking))
 - `vm_storage` (String) The path on each hypervisor where instance (ephemeral) storage lives.
 - `vnc_floating_ip` (String) The floating IP through which VM VNC consoles are reached, if any.