Skip to content

Add os_purpose field. #970

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
Open

Add os_purpose field. #970

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
bb0fc8c
Add os_purpose field.
garloff Jul 24, 2025
4942b0d
Add os_purpose=minimal option.
garloff Jul 24, 2025
37645bd
Version number 1.1 and short version history.
garloff Jul 24, 2025
1a6a5e5
Add note that tuple of unique img includes architecture.
garloff Jul 24, 2025
9e1ecdd
Remove `network` and `appliance` os_purpose for now.
garloff Jul 24, 2025
a2d00ca
Fix linting complaints.
garloff Jul 25, 2025
8cabaa5
Indentation as suggested by @horazont
garloff Jul 31, 2025
a63e8a5
Improve uniqueness wording (from @mbuechse)
garloff Aug 1, 2025
f96686f
Merge branch 'main' into feat/add-os-purpose
garloff Aug 1, 2025
c7479a7
fix typos
depressiveRobot Aug 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 49 additions & 3 deletions Standards/scs-0102-v1-image-metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@ status: Stable
track: IaaS
replaces: Image-Metadata-Spec.md
description: |
The SCS-0102 Image Metadata Standard outlines how to categorize and manage metadata for cloud-based operating
This is version 1.1 of the SCS-0102 Image Metadata Standard.
It outlines how to categorize and manage metadata for cloud-based operating
system images to ensure usability and clarity. The standard encompasses naming conventions, technical requirements,
image handling protocols including updating and origin, and licensing/support details. These guidelines ensure
that users can understand, access, and utilize OS images effectively, with clear information on features, updates,
Expand Down Expand Up @@ -65,14 +66,50 @@ The following property is recommended:

- `hypervisor_type`

The values for `architecture` and `os_distro` and `hypervisor_type` (the latter only if specified) values
must follow the [OpenStack specifications](https://docs.openstack.org/glance/2025.1/admin/useful-image-properties.html).
The `os_version` string should be numeric if the distribution uses numbers, the pair `os_distro` `os_version` should
for example be `ubuntu` `24.04` for Ubuntu Noble Numbat 24.04[.x] LTS.

To allow the distinction between general purpose images (which should come from upstream with at most some
targeted adjustments as required by the cloud such as e.g. drivers) and images that are purpose-built, we
recommend an additional field:

- `os_purpose`

The following values are allowed

| `os_purpose` value | Intention |
|--------------------|-----------------------------------------------------------|
| `generic` | A general purpose image, (mostly) vanilla from upstream |
| `minimal` | A much more barebones general purpose image |
| `capinode` | Node image built for cluster-API |
| `gpu` | Image with GPU drivers e.g. for HPC or AI |
| `custom` | None of the above |

Note that no other values are currently allowed and `custom` should be used in case
of doubt. Talk to the SCS standardization bodies if you'd like to see this list extended which is
likely the case if you fall back to `custom`.

The usage of standardized `os_distro`, `os_version`, `architecture`, and `os_purpose` help cloud users to create
automation that works across clouds without requiring image names to be standardized.

_Uniqueness requirement_: whenever there are two images that have `os_hidden=False`, `visibility=public`,
and that coincide in all three fields `os_distro`, `os_version`, and `architecture`, then only one of them may
have `os_purpose=generic`. In other words, users who search visible public images for a generic OS
of a certain distro, version, and architecture will not get more than one result.
The link to the OpenStack specs and the recommended `os_purpose` was added to version 1.1 of
this standard; a new version 2 of the standard that requires `os_purpose` will be created later.
Comment on lines +101 to +102
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would not repeat the version history here, but I would warn people that we intend to turn the recommendation into a requirement soon.

Suggested change
The link to the OpenStack specs and the recommended `os_purpose` was added to version 1.1 of
this standard; a new version 2 of the standard that requires `os_purpose` will be created later.
Note: Expect this field to become mandatory in v2 of this standard sooner rather than later.

Copy link
Member Author

@garloff garloff Aug 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In your suggested wording, the words "this field" lack context.
My understanding of creating a minor revision was that we make the changes within the minor revision visible to non git-pros, thus my mini-changelog. Idea being that a reader can understand why her cloud suddenly gets a warning from the compliance checks without reading git history on the standard or the tool nor even being aware that we do minor revisions if they are non-breaking ...
My vote is for keeping a mini-changelog, but I have no strong opinion here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The context is that this whole part is indented below the bullet point for precisely the field in question, no?


The following further properties are recommended (if the features are supported):

- `hw_rng_model`
- `os_secure_boot`, `hw_firmware_type`
- `hw_watchdog_action`, `hw_mem_encryption`, `hw_pmu`, `hw_video_ram`, `hw_vif_multiqueue_enabled`

The `trait:XXX=required` property can be used to indicate that certain virtual hardware
features `XXX` are required.
features `XXX` are required which may be advertised in matching
[flavor extra specs](https://docs.openstack.org/nova/latest/user/flavors.html#extra-specs).

## Image handling

Expand Down Expand Up @@ -244,4 +281,13 @@ A boolean property that is not present is considered to be `false`.

The script `image-md-check.py` retrieves the
image list from a configured cloud and checks each image for the
completeness and consistency of mandatory properties.
completeness and consistency of mandatory properties. See the
[Corresponding Implementation and Testing Notes](https://docs.scs.community/standards/scs-0102-w1-image-metadata-implementation-testing)

### Version history

- Version 1.0 has existed without notable changes since June 2021.
- Version 1.1 was created in preparation for a new major version 2.0 and has the following additional recommendations:
- Reference OpenStack image spec for standard values of `os_distro`, `architecture` and `hypervisor_type`.
- Recommendation on `os_version` to be a version number (if such a value exists).
- Recommended field `os_purpose`.