Skip to content

Commit d6f47c4

Browse files
mbuechsembuechse
committed
Add Standards/scs-0102-v2-image-metadata.md
Signed-off-by: Matthias Büchse <[email protected]>
1 parent 3d15c18 commit d6f47c4

File tree

2 files changed

+273
-0
lines changed

2 files changed

+273
-0
lines changed

‎Standards/scs-0102-v2-image-metadata.md‎

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
---
2+
title: SCS Image Metadata
3+
type: Standard
4+
status: Draft
5+
track: IaaS
6+
description: |
7+
This is version 2 of the SCS-0102 Image Metadata Standard.
8+
It outlines how to categorize and manage metadata for cloud-based operating
9+
system images to ensure usability and clarity. The standard encompasses naming conventions, technical requirements,
10+
image handling protocols including updating and origin, and licensing/support details. These guidelines ensure
11+
that users can understand, access, and utilize OS images effectively, with clear information on features, updates,
12+
and licensing provided through well-defined metadata properties.
13+
---
14+
15+
## Motivation
16+
17+
Many clouds offer standard Operating System images for their users' convenience.
18+
To make them really useful, they should contain metadata (properties) to allow
19+
users to understand what they can expect using these images.
20+
21+
The specification is targeting images that are managed by the service provider,
22+
provided for public consumption. The spec or parts of it however might turn out
23+
to be useful whenever someone manages images for somebody else's consumption.
24+
25+
## Overview
26+
27+
We categorize the image properties into a few buckets
28+
29+
- Technical requirements and features
30+
- Image handling aspects
31+
- Licensing/Maintenance/Support aspects
32+
33+
## Technical requirements and features
34+
35+
This is dependent on whether we deal with VM images or container images.
36+
37+
For VM images (OpenStack), we recommend to use the properties as described
38+
in the [OpenStack Image documentation](https://docs.openstack.org/glance/latest//admin/useful-image-properties).
39+
40+
The following properties are considered mandatory:
41+
42+
- `architecture`
43+
- `min_disk` (in GiB), `min_ram` (in MiB)
44+
- `os_version`, `os_distro`, `os_purpose` (see below)
45+
- `hw_disk_bus` (`scsi` recommended, and then setting `hw_scsi_model` is also recommended)
46+
47+
**Note**: Disk sizes tend to be measured in GB = 10^9 and not GiB = 2^30 in the disk industry, but OpenStack uses GiB.
48+
49+
The value given vor `min_ram` MUST be sufficient for the VM to boot and survive (for at least 10 s).
50+
51+
To allow the distinction between general purpose images (which should come from upstream with at most some
52+
targeted adjustments as required by the cloud such as e.g. drivers) and images that are purpose-built, we
53+
require an additional field:
54+
55+
- `os_purpose`
56+
57+
The following values are allowed:
58+
59+
| `os_purpose` value | Intention |
60+
|--------------------|-----------------------------------------------------------|
61+
| `generic` | A general purpose image, (mostly) vanilla from upstream |
62+
| `minimal` | A much more barebones general purpose image |
63+
| `k8snode` | Node image built for k8s with CRI and kubelet |
64+
| `gpu` | Image with GPU drivers e.g. for HPC or AI |
65+
| `network` | Network appliance (firewall, router, loadbalancer, ...) |
66+
| `custom` | None of the above |
67+
68+
Note that no other values are currently allowed, and `custom` should be used in case
69+
of doubt. Talk to the SCS standardization bodies if you'd like to see this list extended which is
70+
likely the case if you fall back to `custom`.
71+
72+
The usage of standardized `os_distro`, `os_version`, `architecture`, and `os_purpose` help cloud users to create
73+
automation that works across clouds without requiring image names to be standardized.
74+
75+
_Uniqueness requirement_: whenever there are two images that have `os_hidden=False`, `visibility=public`,
76+
and that coincide in all three fields `os_distro`, `os_version`, and `architecture`, then only one of them may
77+
have `os_purpose=generic`. In other words, users who search visible public images for a generic OS
78+
of a certain distro, version, and architecture will not get more than one result.
79+
80+
The following property is recommended:
81+
82+
- `hypervisor_type`
83+
84+
The values for `architecture` and `os_distro` and `hypervisor_type` (the latter only if specified) values
85+
must follow the [OpenStack specifications](https://docs.openstack.org/glance/2025.1/admin/useful-image-properties.html).
86+
The `os_version` string should be numeric if the distribution uses numbers, the pair `os_distro` `os_version` should
87+
for example be `ubuntu` `24.04` for Ubuntu Noble Numbat 24.04[.x] LTS.
88+
89+
The following further properties are recommended (if the features are supported):
90+
91+
- `hw_rng_model`
92+
- `os_secure_boot`, `hw_firmware_type`
93+
- `hw_watchdog_action`, `hw_mem_encryption`, `hw_pmu`, `hw_video_ram`, `hw_vif_multiqueue_enabled`
94+
95+
The `trait:XXX=required` property can be used to indicate that certain virtual hardware
96+
features `XXX` are required which may be advertised in matching
97+
[flavor extra specs](https://docs.openstack.org/nova/latest/user/flavors.html#extra-specs).
98+
99+
## Image handling
100+
101+
### Image updating
102+
103+
It is recommended that provider managed images are regularly updated.
104+
This means that users referencing an image _by name_ will always get the latest image for the
105+
operating system indicated by that name (which includes a version number, but not the patch
106+
level).
107+
108+
Technically, the thus updated image is a new image and will thus carry a new UUID.
109+
It is recommended that the old image gets renamed (e.g. build date or patch level attached)
110+
and hidden (`os_hidden=True`), but remains accessible via its (unchanged) UUID for some
111+
time.
112+
113+
The update handling by the provider is described via the properties `replace_frequency`,
114+
`uuid_validity`, `provided_until`, and `hotfix_hours`.
115+
116+
The `replace_frequency`, `provided_until`, and `hotfix_hours` fields reference to the image
117+
as referenced by its name.
118+
119+
| `replace_frequency` | meaning |
120+
| ------------------- | -------------------------------------------------------------------------------- |
121+
| `yearly` | the image will get replaced _at least_ once per year |
122+
| `quarterly` | the image will get replaced _at least_ once per quarter |
123+
| `monthly` | the image will get replaced _at least_ once per month |
124+
| `weekly` | the image will get replaced _at least_ once per week |
125+
| `daily` | the image will get replaced _at least_ once per day |
126+
| `critical_bug` | the image will get replaced for critical issues only |
127+
| `never` | the image referenced by name will never change (until the date `provided_until`) |
128+
129+
Note the _at least_ wording: Providers can replace images more often.
130+
The frequency is starting from the first release; so an image published on 2021-04-14 with an
131+
update frequency of `monthly`, should be replaced no later than 2021-05-14. Due to weekends
132+
etc., up to 3 days later is not considered a violation of this policy. So a valid sequence
133+
from an image with `monthly` update frequency might be 2021-04-14, 2021-05-14, 2021-06-15,
134+
2021-07-14, 2021-07-27 (hotfix), 2021-08-13 ...
135+
136+
Promises to update the registered public images typically depend on upstream image providers
137+
(Linux distributors, OS vendors) keeping their promises to build and provide updated images.
138+
Failures from upstream are not a reason to claim the cloud provider to be in violation of his
139+
promises. However, if the provider observes massive upstream failures (which can e.g. cause
140+
increased security risks), we advise the provider to inform the users.
141+
142+
We recommend updating images at least monthly.
143+
144+
The `hotfix_hours` field indicates how providers deal with critical security issues
145+
that affect the images; it is an optional field that contains a numerical value, indicating
146+
how quickly (in hours) a new image is provided _after the latter of the points in time that
147+
the issue becomes public and a tested fix is available as maintenance update from the upstream
148+
distribution_. A value of 0 indicates a best-effort approach without firm SLAs; the field not
149+
being present indicates no commitment. A value of 48 would indicate that the provider
150+
commits to a new image within 48hrs. A critical issue is defined as a security vulnerability
151+
with a CVSS score of 9.0 or higher that affects software that is included in the image.
152+
153+
The `provided_until` field is supposed to contain a date in `YYYY-MM-DD` format that
154+
indicates until when an image under this name will be provided and (according to the
155+
`replace_frequency`) updated at least. (Providers are free to provide updates for
156+
longer or leave the non-updated image visible for longer.)
157+
If this field is set to `none`, no promises are made, if it is set to `notice`, updates
158+
will be provided until a deprecation notice is published. (The values are the same as
159+
for below `uuid_validity`, except that `forever` and `last-N` don't make any sense.)
160+
161+
The `uuid_validity` field indicates how long the public image will be referencable
162+
by its UUID.
163+
164+
| `uuid_validity` | meaning |
165+
| --------------- | ----------------------------------------------------------------------- |
166+
| `none` | UUID will only be valid as long as the content does not change |
167+
| `last-N` | The last N images for newer replacement will remain accessible via UUID |
168+
| `YYYY-MM-DD` | UUID will be valid until at least the date YYYY-MM-DD |
169+
| `notice` | UUID will remain valid until a deprecation notice will be published |
170+
| `forever` | UUID will remain valid for as long as the cloud operates |
171+
172+
Note that the old images must be hidden from the image catalogue or renamed (or both)
173+
to avoid failing referencing by name. Note that `last-N` may be limited by the `provided_until`
174+
date. We recommend providers that keep old images according to the advertized `uuid_validity`
175+
to hide older images (setting the `os_hidden` property to `True`). If the outdated images must
176+
remain visible, the recommendation is to rename the images by attaching a datestamp in the
177+
format " `YYYYMMDD`" to the name where the date must reflect the `build_date` of the image.
178+
179+
The three properties `uuid_validity`, `provided_until` and `replace_frequency` are mandatory;
180+
the field `hotfix_hours` is optional.
181+
182+
All dates are in UTC.
183+
184+
#### Example
185+
186+
Providing an image with name `OPSYS MAJ.MIN` with
187+
`replace_frequency=monthly`, `provided_until=2022-09-30`, `uuid_validity=2022-12-31`,
188+
`hotfix_hours=0`
189+
means that we will have a new image with this name at least once per month (starting from
190+
the initial release) until the end of September 2022. Old images will be hidden and/or
191+
renamed, but remain accessible via their UUID until at least the end of 2022 (in Universal Time).
192+
The provider makes an effort to replace images upon critical security issues out of order.
193+
194+
### Image Origin
195+
196+
- Mandatory: `image_source` needs to be a URL to point to a place from which the image can be downloaded.
197+
(Note: This may be set to the string "private" to indicate that the image can not be freely
198+
downloaded.)
199+
- Mandatory: `image_description` needs to be a URL (or text) with release notes and other human-readable
200+
data about the image.
201+
202+
- Recommended _tag_: `managed_by_VENDOR`
203+
204+
Note that for most images that come straight from an upstream source, `image_description` should point
205+
to an upstream web page where these images are described. If download links are available as well
206+
on that page, `image_source` can point to the same page, otherwise a more direct link to the image
207+
should be used, e.g. directly linking the `.qcow2` or `.img` file.
208+
If providers have their own image building machinery or do some post-processing on top of
209+
upstream images, they should point to the place where they document and offer these images.
210+
211+
### Image build info
212+
213+
- Mandatory: `image_build_date` needs to be `YYYY-MM-DD` or `YYYY-MM-DD hh:mm[:ss]` (time in UTC,
214+
24hrs clock).
215+
All publicly released and generally recommended patches before this date must be included in the
216+
image build. If the cutoff date is earlier, this cutoff date needs to be set instead, even
217+
if the actual build happens significantly after the cutoff date. If not all patches can be
218+
included for a good reason, then the `patchlevel` field (see below) must be used to describe
219+
the patch status.
220+
- Mandatory: `image_original_user` is the default login user for the operating system which can connect
221+
to the image via the injected SSH key or provided password. (This can be set to `none` if no default
222+
username exists for the operating system.)
223+
- Optional: `patchlevel` can be set to an operating specific patch level that describes the
224+
patch status — typically we would expect the `image_build_date` to be sufficient.
225+
226+
- Recommended: `os_hash_algo` and `os_hash_value`: The sha256 or sha512 hash
227+
for the image file. (This references the image file in the format it is stored in, we
228+
recommend raw over qcow2 for systems that use ceph.) Note that these values are
229+
typically generated automatically upon image registration.
230+
231+
- Recommended _tag_: `os:OPERATINGSYSTEM`
232+
233+
### Licensing / Maintenance subscription / Support
234+
235+
Some images require a license; in many cases the cloud providers include the license cost
236+
by a per-use (e.g. hourly) fee. However, it is also possible sometimes that customers
237+
use their own license agreements with the OS vendor with a bring-your-own-license (BYOL)
238+
program. These properties may be attached to the image. Note that free Linux images
239+
might not use any of these properties, except maybe `maintained_until`. Note that
240+
Windows images would typically require `license_included`, `subscription_included`.
241+
A boolean property that is not present is considered to be `false`.
242+
243+
- Optional: `license_included` (boolean) indicates whether the flavor fee
244+
includes the licenses required to use this image. This field is mandatory for
245+
images that contain software that requires commercial licenses.
246+
- Optional: `license_required` (boolean) indicates whether a customer must bring
247+
its own license to be license compliant. This can not be true at the same time as the
248+
previous setting. This field is mandatory IF customers need to bring their own
249+
license to use the image.
250+
- Optional: `subscription_included` (boolean) indicates that the image contains already
251+
a maintenance subscription which typically gives access to bug fixes, security
252+
fixes and (minor) function updates. If a subscription is included, the CSP should
253+
have prepared the image to also receive the provided maintenance updates from the
254+
vendor (optionally via a mirror).
255+
- Optional: `subscription_required` (boolean) indicates that the customer requires
256+
a maintenance subscription from the OS vendor in order to receive fixes
257+
(which is often also a prerequisite to be eligible for support).
258+
- Optional: `maintained_until: YYYY-MM-DD` promises maintenance from the OS vendor
259+
until at least this date (in UTC).
260+
- Optional: `l1_support_contact` contains a URI that provides customer support
261+
contact for issues with this image. Note that this field must only be set if the
262+
service provider does provide support for this image included in the image/flavor
263+
pricing (but it might be provided by a contracted 3rd party, e.g. the OS vendor).
264+
265+
### Version history
266+
267+
- Version 1.0 has existed without notable changes since June 2021.
268+
- Version 1.1 was created in preparation for a new major version 2.0 and has the following additional recommendations:
269+
- Reference OpenStack image spec for standard values of `os_distro`, `architecture` and `hypervisor_type`.
270+
- Recommendation on `os_version` to be a version number (if such a value exists).
271+
- Recommended field `os_purpose`.
272+
- Version 2.0 (this one) makes the field `os_purpose` mandatory.

‎Standards/scs-0102-w1-image-metadata-implementation-testing.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ type: Supplement
44
track: IaaS
55
supplements:
66
- scs-0102-v1-image-metadata.md
7+
- scs-0102-v2-image-metadata.md
78
---
89

910

0 commit comments

Comments
 (0)