Skip to content

Commit

Permalink
more comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@TheRealFalcon
TheRealFalcon committed Jul 26, 2024
1 parent f4e3094 commit a59274d
Showing 1 changed file with 67 additions and 73 deletions.
140 changes: 67 additions & 73 deletions doc/rtd/explanation/format.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,31 +5,22 @@ User data formats

User data is configuration data provided by a user of a cloud platform to an
instance at launch. User data can be passed to cloud-init in any of many
formats documented here. Most formats include a header or
content-type that must be present in the user data to be recognized
by cloud-init.
formats documented here.

Configuration types
===================

User data can be categorized into **base config**
or **meta config**.
User data formats can be categorized into those that directly configure the
instance, and those that serve as a container, template, or means to obtain
or modify another configuration.

Base config
-----------

Any of the base configs will be used to directly configure the instance.
These include:
Formats that directly configure the instance:

- `Cloud config data`_
- `User data script`_
- `Cloud boothook`_

Meta config
-----------

Meta configs serve as a container, template, or means to obtain or modify
a base config. These include
Formats that deal with other user data formats:

- `MIME multi-part archive`_
- `Cloud config archive`_
Expand All @@ -43,9 +34,6 @@ a base config. These include
Cloud config data
=================

| **Header:** #cloud-config
| **Content-Type:** text/cloud-config
Example
-------

Expand Down Expand Up @@ -83,9 +71,6 @@ supported cloud config formats.
User data script
================

| **Header:** #!
| **Content-Type:** text/x-shellscript
Example
-------

Expand All @@ -99,16 +84,15 @@ Explanation

A user data script is a single shell script to be executed once per instance.
User data scripts are run relatively late in the boot process, during the
'modules:final' stage as part of the "cc_scripts_user" module.
cloud-init's final stage as part of the "cc_scripts_user" module. When run,
the environment variable ``INSTANCE_ID`` is set to the current instance ID
for use within the script.

.. _user_data_formats-cloud_boothook:

Cloud boothook
==============

| **Header:** #cloud-boothook
| **Content-Type:** text/cloud-boothook
Simple Example
--------------

Expand Down Expand Up @@ -141,20 +125,19 @@ Explanation
-----------

A cloud boothook is similar to a :ref:`user data script<user_data_script>`
in that it is a shell script run on boot. The boothook is different in that:
in that it is a shell script run on boot. When run,
the environment variable ``INSTANCE_ID`` is set to the current instance ID
for use within the script.

The boothook is different in that:

* It is run very early in boot, during the 'init' stage, before any
cloud-init modules are run.
* It is run on every boot
* The environment variable ``INSTANCE_ID`` is set to the current instance ID
for use within the script.

MIME multi-part archive
=======================

| **Header:** Content-Type: multipart/mixed;
| **Content-Type:** multipart/mixed
Example
-------

Expand Down Expand Up @@ -191,30 +174,15 @@ Using a MIME multi-part file, the user can specify more than one type of data.
For example, both a user data script and a cloud-config type could be
specified.

Supported content-types are listed from the ``cloud-init`` subcommand
Each part must specify a valid
:ref:`content types<user_data_formats-content_types>`. Supported content-types
may also be listed from the ``cloud-init`` subcommand
:command:`make-mime`:

.. code-block:: shell-session
$ cloud-init devel make-mime --list-types
Example output:

.. code-block::
cloud-boothook
cloud-config
cloud-config-archive
cloud-config-jsonp
jinja2
part-handler
x-include-once-url
x-include-url
x-shellscript
x-shellscript-per-boot
x-shellscript-per-instance
x-shellscript-per-once
Helper subcommand to generate MIME messages
-------------------------------------------

Expand Down Expand Up @@ -248,9 +216,6 @@ Create user data containing 3 shell scripts:
Cloud config archive
====================

| **Header:** #cloud-config-archive
| **Content-Type:** text/cloud-config-archive
Example
-------

Expand All @@ -270,30 +235,31 @@ Explanation
-----------

A cloud-config-archive is a way to specify more than one type of data
using YAML. It can be seen as an alternative to building a MIME multi-part
archive for those that would prefer to use YAML.
using YAML. Since building a MIME multipart archive can be somewhat unwieldly
to build by hand or requires using a cloud-init helper utility, the
cloud-config-archive provides a simpler alternative to building the MIME
multi-part archive for those that would prefer to use YAML.

The format is a list of dictionaries.

Required fields:

* ``type``: The content type of the MIME part
* ``content``: The configuration for the MIME part
* ``type``: The :ref:`Content-Type<user_data_formats-content_types>`
identifier for the type of user data in content
* ``content``: The user data configuration

Optional fields:

* ``launch-index``: The EC2 Launch-Index header in the MIME part
* ``filename``: The filename of the Content-Disposition header in the MIME
part. This does not correspond to any local system file.
* ``launch-index``: The EC2 Launch-Index (if applicable)
* ``filename``: This field is only used if using a user data format that
requires a filename in a MIME part. This is unrelated to any local system
file.

All other fields will be added unedited to the MIME part as headers.
All other fields will be interpreted as a MIME part header.

Jinja template
==============

| **Header:** ## template: jinja
| **Content-Type:** text/jinja
Example cloud-config
--------------------

Expand Down Expand Up @@ -330,9 +296,6 @@ the original header along with the new jinja header above it.
Include file
============

| **Header:** #include
| **Content-Type:** text/x-include-url
Example
-------

Expand All @@ -353,9 +316,6 @@ will not be read.
Gzip compressed content
=======================

| **Header** n/a
| **Content-Type** n/a
Content found to be gzip compressed will be uncompressed.
The uncompressed data will then be used as if it were not compressed.
This is typically useful because user data size may be limited based on
Expand All @@ -364,9 +324,6 @@ cloud platform.
Part handler
============

| **Header:** #part-handler
| **Content-Type:** text/part-handler
Example
-------

Expand All @@ -385,7 +342,8 @@ This must be Python code that contains a ``list_types`` function and a
``handle_part`` function.

The ``list_types`` function must return a list
of mime-types that this `part-handler` handles. Since MIME parts are
of :ref:`content types<user_data_formats-content_types>` that this
`part-handler` handles. Since MIME parts are
processed in order, a `part-handler` part must precede any parts with
mime-types it is expected to handle in the same user data.

Expand All @@ -397,6 +355,42 @@ or after receiving any parts.
The provided example can be used as a template for creating a custom part
handler. `This blog post`_ offers another example for more advanced usage.

.. _user_data_formats-content_types:

Headers and content types
=========================

In order for cloud-init to recognize which user data format is being used,
the user data must contain a header. Additionally, if the user data
is being passed as a multi-part message, such as MIME, cloud-config-archive,
or part-handler, the content-type for each part must also be set
appropriately.

The table below lists the headers and content types for each user data format.
Note that gzip compressed content is not represented here as it gets passed
as binary data and so may be processed automatically.

+--------------------+-----------------------------+-------------------------+
|User data format |Header |Content-Type |
+====================+=============================+=========================+
|Cloud config data |#cloud-config |text/cloud-config |
+--------------------+-----------------------------+-------------------------+
|User data script |#! |text/x-shellscript |
+--------------------+-----------------------------+-------------------------+
|Cloud boothook |#cloud-boothook |text/cloud-boothook |
+--------------------+-----------------------------+-------------------------+
|MIME multi-part |Content-Type: multipart/mixed|multipart/mixed |
+--------------------+-----------------------------+-------------------------+
|Cloud config archive|#cloud-config-archive |text/cloud-config-archive|
+--------------------+-----------------------------+-------------------------+
|Jinja template |## template: jinja |text/jinja |
+--------------------+-----------------------------+-------------------------+
|Include file |#include |text/x-include-url |
+--------------------+-----------------------------+-------------------------+
|Part handler |#part-handler |text/part-handler |
+--------------------+-----------------------------+-------------------------+


.. _make-mime: https://github.com/canonical/cloud-init/blob/main/cloudinit/cmd/devel/make_mime.py
.. _YAML: https://yaml.org/spec/1.1/current.html
.. _This blog post: http://foss-boss.blogspot.com/2011/01/advanced-cloud-init-custom-handlers.html

0 comments on commit a59274d

Please sign in to comment.