Skip to content
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

Clarify subiquity docs #5957

Merged
merged 3 commits into from
Feb 6, 2025
Merged

Clarify subiquity docs #5957

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2be0c50
doc: clarify subiquity docs
holmanb Jan 9, 2025
f814843
chore: remove redundant manual schema validation
holmanb Jan 9, 2025
deb2ed9
test: eliminate obsolete cases, add non-error case
holmanb Jan 9, 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
57 changes: 1 addition & 56 deletions cloudinit/config/cc_ubuntu_autoinstall.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,7 @@
from cloudinit import subp, util
from cloudinit.cloud import Cloud
from cloudinit.config import Config
from cloudinit.config.schema import (
MetaSchema,
SchemaProblem,
SchemaValidationError,
)
from cloudinit.config.schema import MetaSchema
from cloudinit.settings import PER_ONCE

LOG = logging.getLogger(__name__)
Expand All @@ -30,13 +26,6 @@

def handle(name: str, cfg: Config, cloud: Cloud, args: list) -> None:

if "autoinstall" not in cfg:
LOG.debug(
"Skipping module named %s, no 'autoinstall' key in configuration",
name,
)
return

util.wait_for_snap_seeded(cloud)
snap_list, _ = subp.subp(["snap", "list"])
installer_present = None
Expand All @@ -50,51 +39,7 @@ def handle(name: str, cfg: Config, cloud: Cloud, args: list) -> None:
", ".join(LIVE_INSTALLER_SNAPS),
)
return
validate_config_schema(cfg)
LOG.debug(
"Valid autoinstall schema. Config will be processed by %s",
installer_present,
)


def validate_config_schema(cfg):
"""Supplemental runtime schema validation for autoinstall yaml.

Schema validation issues currently result in a warning log currently which
can be easily ignored because warnings do not bubble up to cloud-init
status output.

In the case of the live-installer, we want cloud-init to raise an error
to set overall cloud-init status to 'error' so it is more discoverable
in installer environments.

# TODO(Drop this validation When cloud-init schema is strict and errors)

:raise: SchemaValidationError if any known schema values are present.
"""
autoinstall_cfg = cfg["autoinstall"]
if not isinstance(autoinstall_cfg, dict):
raise SchemaValidationError(
[
SchemaProblem(
"autoinstall",
"Expected dict type but found:"
f" {type(autoinstall_cfg).__name__}",
)
]
)

if "version" not in autoinstall_cfg:
raise SchemaValidationError(
[SchemaProblem("autoinstall", "Missing required 'version' key")]
)
elif not isinstance(autoinstall_cfg.get("version"), int):
raise SchemaValidationError(
[
SchemaProblem(
"autoinstall.version",
f"Expected int type but found:"
f" {type(autoinstall_cfg['version']).__name__}",
)
]
)
2 changes: 1 addition & 1 deletion cloudinit/config/schemas/schema-cloud-config-v1.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -670,7 +670,7 @@
"type": "object",
"properties": {
"autoinstall": {
"description": "Opaque autoinstall schema definition for Ubuntu autoinstall. Full schema processed by live-installer. See: https://ubuntu.com/server/docs/install/autoinstall-reference.",
"description": "Cloud-init ignores this key and its values. It is used by Subiquity, the Ubuntu Autoinstaller. See: https://ubuntu.com/server/docs/install/autoinstall-reference.",
"type": "object",
"properties": {
"version": {
Expand Down
21 changes: 12 additions & 9 deletions doc/module-docs/cc_ubuntu_autoinstall/data.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,21 @@
cc_ubuntu_autoinstall:
description: |
The ``autoinstall`` key indicates a configuration for the Ubuntu installer.
It is not acted on by cloud-init other than to ensure that the
configuration is schema compliant and that the installer package is
present on the system.
Cloud-init is used by the Ubuntu installer in two stages.
The ``autoinstall`` key may contain a configuration for the Ubuntu
installer.

Cloud-init verifies that an ``autoinstall`` key contains a ``version`` key
and that the installer package is present on the system.

.. note::
The installer may use the provided configuration to instrument
cloud-init on the target system. See
`the Ubuntu installer documentation <https://canonical-subiquity.readthedocs-hosted.com/en/latest/reference/autoinstall-reference.html#user-data>`_
for more information.
The Ubuntu installer might pass part of this configuration to cloud-init
during a later boot as part of the install process.
See `the Ubuntu installer documentation <https://canonical-subiquity.readthedocs-hosted.com/en/latest/reference/autoinstall-reference.html#user-data>`_
for more information. Please direct Ubuntu installer questions to
their IRC channel (#ubuntu-server on Libera).
examples:
- comment: |
Example 1:
file: cc_ubuntu_autoinstall/example1.yaml
name: Ubuntu Autoinstall
title: Support Ubuntu live-server install syntax
title: Autoinstall configuration is ignored (but validated) by cloud-init.
37 changes: 2 additions & 35 deletions tests/unittests/config/test_cc_ubuntu_autoinstall.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,33 +38,6 @@
)


class TestvalidateConfigSchema:
Copy link
Member Author

Choose a reason for hiding this comment

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

Coverage on this module remains at 100% after removing these tests.

@pytest.mark.parametrize(
"src_cfg,error_msg",
[
pytest.param(
{"autoinstall": 1},
"autoinstall: Expected dict type but found: int",
id="err_non_dict",
),
pytest.param(
{"autoinstall": {}},
"autoinstall: Missing required 'version' key",
id="err_require_version_key",
),
pytest.param(
{"autoinstall": {"version": "v1"}},
"autoinstall.version: Expected int type but found: str",
id="err_version_non_int",
),
],
)
def test_runtime_validation_errors(self, src_cfg, error_msg):
"""cloud-init raises errors at runtime on invalid autoinstall config"""
with pytest.raises(SchemaValidationError, match=error_msg):
cc_ubuntu_autoinstall.validate_config_schema(src_cfg)


@mock.patch(MODPATH + "util.wait_for_snap_seeded")
@mock.patch(MODPATH + "subp.subp")
class TestHandleAutoinstall:
Expand All @@ -73,14 +46,6 @@ class TestHandleAutoinstall:
@pytest.mark.parametrize(
"cfg,snap_list,subp_calls,logs,snap_wait_called",
[
pytest.param(
Copy link
Member Author

@holmanb holmanb Jan 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

This never happens in the codebase due to activate_by_schema_keys: autoinstall.

{},
SAMPLE_SNAP_LIST_OUTPUT,
[],
["Skipping module named name, no 'autoinstall' key"],
False,
id="skip_no_cfg",
),
pytest.param(
{"autoinstall": {"version": 1}},
SAMPLE_SNAP_LIST_OUTPUT,
Expand Down Expand Up @@ -149,6 +114,8 @@ class TestAutoInstallSchema:
{"autoinstall": {}},
"autoinstall: 'version' is a required property",
),
({"autoinstall": {"version": 1}}, None),
({"autoinstall": {"version": "v1"}}, "is not of type 'integer'"),
),
)
@skipUnlessJsonSchema()
Expand Down
Loading