Skip to content

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

Merged
PF9-pushkar merged 8 commits into
mainfrom
pushkar/pcd-9784-docs
Sep 4, 2026
Merged

docs: import-ID lookups and a Community Edition example (PCD-9784)#51
PF9-pushkar merged 8 commits into
mainfrom
pushkar/pcd-9784-docs

Conversation

@PF9-pushkar

@PF9-pushkar PF9-pushkar commented Sep 4, 2026

Copy link
Copy Markdown
Collaborator

Summary

Docs-only change for PCD-9784: every registry page that imports by a PCD-assigned ID now says how to look that ID up, and the registry carries a lab-validated, runnable zero-to-VM configuration for Community Edition. Along the way the lab run exposed two things the docs had wrong.

What changed

  • Importing guide (docs/guides/importing.md): CLI setup (pcdctl RC file, OS_INSECURE on CE), terraform import versus import blocks with -generate-config-out, a per-resource lookup table for every importable resource, the resmgr host UUID and the host-config/blueprint/cluster lookups, and a worked blueprint import.
  • Every import.sh (52 resources) carries the lookup command above the import line, so each registry page's Import section answers "where does this ID come from". The resource template links the guide.
  • Community Edition guide (docs/guides/community-edition.md) rendered from a runnable examples/complete/community-edition/: volume type, blueprint with an NFS backend, host config, cluster, three cluster roles, provider network, CirrOS image, flavor, instance with an attached volume.
  • 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. The mistake was invisible while every example used the same name at both levels.
  • pcd_blockstorage_volume_type and pcd_cluster_blueprint descriptions and examples explain the volume_backend_name / storage_backends_json / image_library_storage linkage and the JSON shape; README's PCD-native table adds pcd_cluster and pcd_host_cluster_role.

Validated on the CE lab (2026.4, provider built from this branch)

  • Import of the live volume type by UUID (by name fails), post-import plan clean; import blocks with generated config for volume type, blueprint, cluster, and host config (storage_backends_json comes out null # sensitive).
  • pcdctl service commands need the sourced RC file plus OS_INSECURE=true on CE; every command cited in the guide was run.
  • The example applied end to end with an NFS backend whose two key levels differ (nfs / nfs-primary): resmgr computed [nfs-primary] with volume_backend_name = nfs, the volume type routed a volume to it, the image uploaded to the image-library host, the instance booted and answered ping, plan clean.
  • Two traps found and documented: listing the top-level key in backends yields an empty backend set and a host stuck converging (resmgr 409s every role change); boolean driver options written as quoted strings never validate on the host and it converges forever.
  • Destroy needs three runs (image backing volume left behind, HostClusterDeleteFailed, HostInAuthState); the guide's Destroy section walks through it. Region left empty.

Pages touched

docs/guides/importing.md, docs/guides/community-edition.md (new); docs/resources/*.md (Import sections); docs/resources/blockstorage_volume_type.md, cluster_blueprint.md, host_cluster_role.md, docs/data-sources/cluster_blueprint.md; README.md; CHANGELOG.md; the sources under templates/, examples/, and the three schema descriptions in internal/.

Release

Docs-only v0.1.11 after merge, so the registry renders the guides before the first-party page links to them.

Records the lab-verified facts (import needs the volume type UUID, pcdctl needs a sourced RC and OS_INSECURE on CE, where the resmgr host UUID comes from, import blocks with generated config), the approved decisions, and the two deliverables: registry guides plus per-resource import lookups, and the first-party docs handoff.
…PCD-9784)

Every resource's Import section now names the pcdctl command (or resmgr call) that prints the ID it needs, and links a new Importing guide that 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. README's PCD-native table gains pcd_cluster and pcd_host_cluster_role.
The volume type, blueprint resource, and blueprint data source descriptions now say what volume_backend_name selects, that image_library_storage names a volume type, and what shape storage_backends_json takes; the two examples pair an NFS backend with its volume type.
examples/complete/community-edition/ builds a region from one prepared host to a running instance with an attached NFS-backed volume; the new guide renders those files with tffile so the published text and the runnable configuration cannot drift.
Applied and destroyed examples/complete/community-edition on a CE 2026.4 lab with an NFS backend whose two key levels differ. pcd_host_cluster_role.backends names the second-level (driver configuration) keys, not the top-level backend names; the top-level key becomes volume_backend_name on the host. Boolean driver options must be JSON booleans: quoted strings never validate and the host converges forever. The provider already uploads images to the image-library host's 9494 endpoint, so the guide states the reachability requirement. The Destroy section records the three-run teardown (image backing volume, HostClusterDeleteFailed, HostInAuthState).
@PF9-pushkar
PF9-pushkar merged commit fe547a3 into main Sep 4, 2026
5 checks passed
@PF9-pushkar
PF9-pushkar deleted the pushkar/pcd-9784-docs branch September 4, 2026 22:53
@PF9-pushkar PF9-pushkar mentioned this pull request Sep 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant