1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
.. _module_creation:
Module creation
***************
Much of ``cloud-init``'s functionality is provided by :ref:`modules<modules>`.
All modules follow a similar layout in order to provide consistent execution
and documentation. Use the example provided here to create a new module.
.. _module_creation-Guidelines:
Your Python module
==================
Modules are located in the ``cloudinit/config/`` directory, where the naming
convention for modules is to use ``cc_<module_name>`` (with underscores as the
separators).
The handle function
-------------------
Your module must include a ``handle`` function. The arguments are:
- ``name``: The module name specified in the configuration.
- ``cfg``: A configuration object that is the result of the merging of
cloud-config configuration with any datasource-provided configuration.
- ``cloud``: A cloud object that can be used to access various datasource
and paths for the given distro and data provided by the various datasource
instance types.
- ``args``: An argument list. This is usually empty and is only populated
if the module is called independently from the command line or if the
module definition in :file:`/etc/cloud/cloud.cfg[.d]` has been modified
to pass arguments to this module.
Schema definition
-----------------
If your module introduces any new cloud-config keys, you must provide a schema
definition in `cloud-init-schema.json`_.
- The ``meta`` variable must exist and be of type `MetaSchema`_.
- ``id``: The module ID. In most cases this will be the filename without
the ``.py`` extension.
- ``distros``: Defines the list of supported distros. It can contain
any of the values (not keys) defined in the `OSFAMILIES`_ map or
``[ALL_DISTROS]`` if there is no distro restriction.
- ``frequency``: Defines how often module runs. It must be one of:
- ``PER_ALWAYS``: Runs on every boot.
- ``ONCE``: Runs only on first boot.
- ``PER_INSTANCE``: Runs once per instance. When exactly this happens
is dependent on the datasource, but may be triggered any time there
would be a significant change to the instance-data. An example
could be an instance being moved to a different subnet.
- ``activate_by_schema_keys``: Optional list of cloud-config keys that will
activate this module. When this list not empty, the config module will be
skipped unless one of the ``activate_by_schema_keys`` are present in merged
cloud-config instance-data.
Example module.py file
======================
.. code-block:: python
# This file is part of cloud-init. See LICENSE file for license information.
"""Example Module: Shows how to create a module"""
import logging
from cloudinit.cloud import Cloud
from cloudinit.config import Config
from cloudinit.config.schema import MetaSchema
from cloudinit.distros import ALL_DISTROS
from cloudinit.settings import PER_INSTANCE
LOG = logging.getLogger(__name__)
meta: MetaSchema = {
"id": "cc_example",
"distros": [ALL_DISTROS],
"frequency": PER_INSTANCE,
"activate_by_schema_keys": ["example_key, example_other_key"],
} # type: ignore
def handle(
name: str, cfg: Config, cloud: Cloud, args: list
) -> None:
LOG.debug(f"Hi from module {name}")
Module documentation
====================
Every module has a folder in the ``doc/module-docs/`` directory, containing
a ``data.yaml`` file, and one or more ``example*.yaml`` files.
- The ``data.yaml`` file contains most of the documentation fields. At a
minimum, your module should be provided with this file. Examples are not
strictly required, but are helpful to readers of the documentation so it is
preferred for at least one example to be included.
- The ``example*.yaml`` files are illustrative demonstrations of using the
module, but should be self-contained and in correctly-formatted YAML. These
will be automatically tested against the defined schema.
Example data.yaml file
----------------------
.. code-block:: yaml
cc_module_name:
description: >
This module provides some functionality, which you can describe here.
For straightforward text examples, use a greater-than (``>``) symbol
next to ``description: `` to ensure proper rendering in the
documentation. Empty lines will be respected, but line-breaks are
folded together to create proper paragraphs.
If you need to use call-outs or code blocks, use a pipe (``|``) symbol
instead of ``>`` so that reStructuredText formatting (e.g. for
directives, which take varying levels of indentation) is respected.
examples:
- comment: |
Example 1: (optional) description of the expected behavior of the example
file: cc_module_name/example1.yaml
- comment: |
Example 2: (optional) description of a second example.
file: cc_module_name/example2.yaml
name: Module Name
title: Very brief (1 sentence) tag line describing what your module does
Rendering the module docs
-------------------------
The module documentation is auto-generated via the
:file:`doc/rtd/reference/modules.rst` file.
For your module documentation to be shown in the cloud-init docs, you will
need to add an entry to this page. Modules are listed in alphabetical order.
The entry should be in the following reStructuredText format:
.. code-block:: text
.. datatemplate:yaml:: ../../module-docs/cc_ansible/data.yaml
:template: modules.tmpl
The template pulls information from both your ``module.py`` file, and from its
corresponding entry in the the ``module-docs`` directory.
Module execution
================
For a module to be run, it must be defined in a module run section in
:file:`/etc/cloud/cloud.cfg` or :file:`/etc/cloud/cloud.cfg.d` on the launched
instance. The three module sections are
`cloud_init_modules`_, `cloud_config_modules`_, and `cloud_final_modules`_,
corresponding to the :ref:`Network<boot-Network>`, :ref:`Config<boot-Config>`,
and :ref:`Final<boot-Final>` boot stages respectively.
Add your module to `cloud.cfg.tmpl`_ under the appropriate module section.
Each module gets run in the order listed, so ensure your module is defined
in the correct location based on dependencies. If your module has no particular
dependencies or is not necessary for a later boot stage, it should be placed
in the ``cloud_final_modules`` section before the ``final-message`` module.
Benefits of including your config module in upstream cloud-init
===============================================================
Config modules included in upstream cloud-init benefit from ongoing
maintenance,
compatibility with the rest of the codebase, and security fixes by the upstream
development team.
If this is not possible, one can add
:ref:`custom out-of-tree config modules<custom_configuration_module>`
to cloud-init.
.. _MetaSchema: https://github.com/canonical/cloud-init/blob/3bcffacb216d683241cf955e4f7f3e89431c1491/cloudinit/config/schema.py#L58
.. _OSFAMILIES: https://github.com/canonical/cloud-init/blob/3bcffacb216d683241cf955e4f7f3e89431c1491/cloudinit/distros/__init__.py#L35
.. _settings.py: https://github.com/canonical/cloud-init/blob/3bcffacb216d683241cf955e4f7f3e89431c1491/cloudinit/settings.py#L66
.. _cloud-init-schema.json: https://github.com/canonical/cloud-init/blob/main/cloudinit/config/schemas/versions.schema.cloud-config.json
.. _cloud.cfg.tmpl: https://github.com/canonical/cloud-init/blob/main/config/cloud.cfg.tmpl
.. _cloud_init_modules: https://github.com/canonical/cloud-init/blob/b4746b6aed7660510071395e70b2d6233fbdc3ab/config/cloud.cfg.tmpl#L70
.. _cloud_config_modules: https://github.com/canonical/cloud-init/blob/b4746b6aed7660510071395e70b2d6233fbdc3ab/config/cloud.cfg.tmpl#L101
.. _cloud_final_modules: https://github.com/canonical/cloud-init/blob/b4746b6aed7660510071395e70b2d6233fbdc3ab/config/cloud.cfg.tmpl#L144
|
