WIP

doc/howto/autoinstall-validation.rst

@@ -0,0 +1,100 @@
+.. _autoinstall_validation:
+
+Autoinstall Validation
+=====================================
+
+Autoinstall config is validated against a :doc:`JSON schema <../reference/autoinstall-schema>` during runtime before it is applied. This check ensures existence of required keys and their data types, but does not guarantee the validity of the data provided (e.g., a bad `match directive <../../reference/autoinstall-reference#disk-selection-extensions>`__).
+
+There are some related checks that run before Autoinstall validation, such as the delivery method consistency checks (which you can read more about in the :ref:`providing autoinstall configuration<providing-autoinstall>` tutorial), but the rest of this tutorial is focused on validating the Autoinstall configuration *after* it has been delivered to the installer.
+
+.. note::
+ See the cloud-init documentation for `how to validate your cloud-config`_.
+
+
+Pre-validating the Autoinstall configuration
+--------------------------------------------
+
+Validation of the autoinstall config can be done ahead of time by using the `validate-autoinstall-user-data script <https://github.com/canonical/subiquity/blob/main/scripts/validate-autoinstall-user-data.py>`_ in the Subiquity GitHub repository.
+
+Setup
+^^^^^
+
+Clone the Subiquity repo and ``cd`` into the root of the repository:
+
+.. code:: none
+
+ git clone [email protected]:canonical/subiquity.git && cd subiquity/
+
+Install the required dependencies:
+
+.. code:: none
+
+ make install_deps
+
+
+Now you can invoke the validation script with:
+
+.. code:: none
+
+ ./scripts/validate-autoinstall-user-data <path-to-config>
+
+
+Examples
+^^^^^^^^
+
+By default, the validation script expects that your autoinstall config is wrapped in cloud-config like so:
+
+.. code:: none
+
+ #cloud-config
+
+ # some cloud-init directives
+
+ autoinstall:
+ # autoinstall directives
+
+This way, you can use the script on your cloud-config data directly. The script will parse out the autoinstall configuration and perform the validation on the extracted autoinstall config. Note that if your cloud-config does not contain an autoinstall section, then the validation script will report a failure. **This does not indicate a crash at runtime**, as you can definitely provide cloud-config without autoinstall, but it is useful for checking common formatting mistakes. For example, the following cloud-config has misspelled the ``autoinstall`` keyword, which under normal circumstances would cause the installer to miss the autoinstall config and present an interactive session:
+
+.. code:: none
+
+ #cloud-config
+ autoinstll:
+ # autoinstall directives
+
+But when provided to the validation script, an error is shown:
+
+.. code:: none
+
+ $ ./scripts/validate-autoinstall-user-data.py <path-to-config>
+ AssertionError: Expected data to be wrapped in cloud-config but could not find top level 'autoinstall' key.
+
+A similar common error is to forget the ``#cloud-config`` header:
+
+.. code:: none
+
+ autoinstall:
+ # autoinstall directives
+
+.. code:: none
+
+ $ ./scripts/validate-autoinstall-user-data.py <path-to-config>
+ AssertionError: Expected data to be wrapped in cloud-config but first line is not '#cloud-config'. Try passing --no-expect-cloudconfig.
+
+
+If you're not sending autoinstall via cloud-config, you use the ``--no-expect-cloudconfig`` flag which will bypass the above checks.
+
+.. code:: none
+
+ autoinstall:
+ # autoinstall directives
+
+.. code:: none
+
+ $ ./scripts/validate-autoinstall-user-data.py <path-to-config>
+ Success: The provided autoinstall config validated succesfully
+
+
+
+.. LINKS
+
+.. _how to validate your cloud-config: https://cloudinit.readthedocs.io/en/latest/howto/debug_user_data.html

doc/howto/index.rst

@@ -19,6 +19,7 @@ Getting started with autoinstall
  autoinstall-quickstart-s390x
  basic-server-installation
  configure-storage
+ autoinstall-validation
 
 Found a problem?
 ----------------

doc/reference/autoinstall-schema.rst

@@ -8,7 +8,7 @@ The server installer validates the provided autoinstall configuration against a
 How the configuration is validated
 ----------------------------------
 
-This reference manual presents the schema as a single document. Use it pre-validate your configuration.
+This reference manual presents the schema as a single document. You can use it pre-validate your configuration manually or use the provided :doc:`pre-validation script <../howto/autoinstall-validation>`.
 
 At run time, the configuration is not validated against this document. Instead, configuration sections are loaded and validated in this order:
 
@@ -35,7 +35,7 @@ Regeneration
 
 To regenerate the schema, run ``make schema`` in the root directory of the `Subiquity source repository`_.
 
-.. LINKS 
+.. LINKS
 
 .. _JSON schema: https://json-schema.org/
 .. _Subiquity source repository: https://github.com/canonical/subiquity