Skip to content

Docs: document every driver option and split contributor docs - #246

Merged
tas50 merged 1 commit into
mainfrom
docs-readme-overhaul
Aug 22, 2026
Merged

Docs: document every driver option and split contributor docs#246
tas50 merged 1 commit into
mainfrom
docs-readme-overhaul

Conversation

@tas50

@tas50 tas50 commented Aug 22, 2026

Copy link
Copy Markdown
Member

What

Adds a complete configuration reference, a quick start, and a CONTRIBUTING.md.

Why

The clouds.yaml / OS_* documentation added recently is genuinely good — but it covers credentials only. The Usage section immediately below it said:

See https://kitchen.ci/docs/drivers/openstack/ for documentation.

So the other 24 default_config keys — image, flavor, networking, floating IPs, timeouts — plus 8 options read directly from config were documented nowhere in the repo.

README

  • A quick start that leans on source openrc.sh, since that's the path most OpenStack users already have working
  • A short Credentials section framing the three sources and their precedence, pointing into the existing clouds.yaml docs rather than duplicating them
  • Full configuration reference grouped by concern: image/flavor, instance, networking, waiting/timeouts, API/endpoints
  • A Block device mapping section, showing the hash shape
  • Examples: floating IPs, multiple networks, cloud-init, slow images, per-platform images
  • Cinc Workstation as the install route, cinc kitchen commands, and a "Using with Chef" section

Every option is now documented. That includes cloud_config, disable_ssl_validation, flavor_id, flavor_ref, image_id, image_ref, server_wait and user_data, which are read from config but never declared through default_config.

Mutually exclusive options

Three pairs raise ActionFailed if you set both halves, which wasn't written down anywhere:

  • image_ref + image_id
  • flavor_ref + flavor_id
  • cloud_config + user_data

The tables now say so at the point you'd reach for them.

CONTRIBUTING.md

New file, absorbing the README's Development section. It notes that kitchen diagnose is the way to see the settings actually in effect — the driver merges clouds.yaml into its config during finalize_config!, so diagnose reflects the combined result of clouds.yaml, OS_*, and kitchen.yml. That's the fastest way to characterise a credential-precedence bug.

The maintenance note (OSU Open Source Lab) is carried across.

Docs only — no code changes.

The Usage section pointed at kitchen.ci and documented no driver options.
The clouds.yaml and OS_* documentation added recently was good, but it
covered only credentials, so the other 24 default_config keys and the
options read directly from config appeared nowhere in the repo.

Adds a full configuration reference grouped by concern: image and flavor,
instance, networking, waiting and timeouts, API and endpoints. Every
default_config key is documented with its real default, along with
cloud_config, disable_ssl_validation, flavor_id, flavor_ref, image_id,
image_ref, server_wait and user_data, which are read from config but never
declared through the DSL.

Calls out the two mutually exclusive pairs explicitly. Setting both
image_ref and image_id, or both flavor_ref and flavor_id, raises
ActionFailed, as does combining cloud_config with user_data.

Adds a quick start, a block device mapping section, and examples for
floating IPs, multiple networks, cloud-init, slow images, and per-platform
images. Leads with Cinc Workstation and adds a "Using with Chef" section.

Move the Development section into a new CONTRIBUTING.md, noting that
kitchen diagnose is the way to see the settings actually in effect, since
the driver merges clouds.yaml into its config in finalize_config!.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Tim Smith <tsmith84@proton.me>
@tas50
tas50 force-pushed the docs-readme-overhaul branch from 4516528 to d83fa41 Compare August 22, 2026 20:47
@tas50
tas50 merged commit ee556da into main Aug 22, 2026
3 checks passed
@tas50
tas50 deleted the docs-readme-overhaul branch August 22, 2026 20:48
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