FLPATH-4770 - fix getting started examples for multi-resource catalog items

[testetson22]

The Getting Started tutorials still used the old schema, causing users to get HTTP 400 errors when following the documented steps.

The control-plane's catalog item schema was updated (FLPATH-4384) to require spec.resources (an array of named resource definitions) instead of the flat spec.service_type / spec.fields structure. The instance schema now requires user_values[].resource to specify which resource each value applies to.

Changes

• Update small-vm.yaml example to use the multi-resource schema (spec.resources[]) introduced by control-plane PR docs: add missing enhancement pages from enhancements repo #11
• Update my-vm.yaml example to include the required resource field in each user_values entry
• Add explanatory text about the resources and resource fields for users following the tutorials

Dependent PR

• FLPATH-4770 - bump control-plane and add check-website-fixtures workflow cli#31 - bumps control-plane dependency so the CLI can serialize the new schema correctly (dcm-project/cli branch FLPATH-4770-fix-user-journey)

Test plan

• hugo --minify builds without errors
• Local hugo server renders both pages correctly
• YAML examples match what the current control-plane API accepts (spec.resources required, user_values[].resource required)

Summary by Sourcery

Align the Getting Started VM tutorials with the current catalog item and instance schemas.

Bug Fixes:

• Update the Getting Started catalog item and instance examples to use the current multi-resource schemas, preventing HTTP 400 errors when users follow the tutorials.

Enhancements:

• Clarify how catalog resources and per-instance resource references work in the single-resource example.

Documentation:

• Refresh the Getting Started YAML examples and explanatory text for the current control-plane API.

[sourcery-ai]

Hey - I've left some high level feedback:

• Consider briefly explaining why the resource is named main in the example (e.g., a common convention) to help users choose meaningful names for multi-resource catalog items.
• In the catalog item tutorial, you might add a short note or example showing how multiple resources would look (even just a second stub resource) to make the new multi-resource schema clearer for users who will define more complex items.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Consider briefly explaining why the resource is named `main` in the example (e.g., a common convention) to help users choose meaningful names for multi-resource catalog items.
- In the catalog item tutorial, you might add a short note or example showing how multiple resources would look (even just a second stub resource) to make the new multi-resource schema clearer for users who will define more complex items.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[qodo-code-review]

PR Summary by Qodo

Fix Getting Started examples for multi-resource catalog items

🐞 Bug fix 📝 Documentation 🕐 Less than 10 minutes

AI Description

• Migrates Small VM catalog YAML to the required named spec.resources schema.
• Scopes instance user values to main, preventing control-plane HTTP 400 responses.
• Explains resource naming across catalog item and instance tutorials.

Diagram

graph TD
  A["Tutorial user"] --> B["Catalog YAML"] --> C["Named resource"] --> D["Instance YAML"] --> E["Scoped values"] --> F["Control-plane API"]

Loading

High-Level Assessment

Directly aligning both linked tutorials with the required control-plane schema is the optimal approach. A shared generated example was considered unnecessary for two small, context-specific tutorial snippets and would add maintenance complexity.

Files changed (2) +46 / -36

Documentation (2) +46 / -36

create-small-vm-catalog-item.mdMigrate Small VM catalog example to named resources +38/-34

Migrate Small VM catalog example to named resources

• Moves the VM service type and field definitions beneath 'spec.resources[]' and names the resource 'main'. Adds guidance explaining multi-resource catalog items and the role of resource names.

content/docs/getting-started/create-small-vm-catalog-item.md

create-small-vm-instance.mdScope Small VM instance values to the main resource +8/-2

Scope Small VM instance values to the main resource

• Adds 'resource: main' to each 'user_values' entry so the instance matches the current schema. Explains how instance values target catalog resources by name.

content/docs/getting-started/create-small-vm-instance.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can keep summaries lean with Finding overflow, which tucks the rest behind 'View more'

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗