Contribute to the code#
For a run-through of the entire process, the following pages will be your best starting point:
On the rest of this page you’ll find the key resources you’ll need to start contributing to the cloud-init codebase.
Testing#
Submissions to cloud-init must include testing. Unit testing and integration testing are integral parts of contributing code.
Popular contributions#
The two most popular contributions we receive are new cloud config modules and new datasources; these pages will provide instructions on how to create them.
Note that any new modules should use underscores in any new config options and
not hyphens (e.g. new_option
and not new-option
).
Code style and design#
We generally adhere to PEP 8, and this is enforced by our use of black
,
isort
and ruff
.
Python support#
Cloud-init upstream currently supports Python 3.6 and above.
Cloud-init upstream will stay compatible with a particular Python version for 6 years after release. After 6 years, we will stop testing upstream changes against the unsupported version of Python and may introduce breaking changes. This policy may change as needed.
The following table lists the cloud-init versions in which the minimum Python version changed:
Cloud-init version |
Python version |
---|---|
22.1 |
3.6+ |
20.3 |
3.5+ |
19.4 |
2.7+ |
Type annotations#
The cloud-init codebase uses Python’s annotation support for storing type annotations in the style specified by PEP-484 and PEP-526. Their use in the codebase is encouraged.
Other resources#
Feature flags#
Feature flags are used as a way to easily toggle configuration at build time. They are provided to accommodate feature deprecation and downstream configuration changes.
Currently used upstream values for feature flags are set in
cloudinit/features.py
. Overrides to these values should be
patched directly (e.g., via quilt patch) by downstreams.
Each flag should include a short comment regarding the reason for the flag and intended lifetime.
Tests are required for new feature flags, and tests must verify all valid states of a flag, not just the default state.
- cloudinit.features.ALLOW_EC2_MIRRORS_ON_NON_AWS_INSTANCE_TYPES = False#
When configuring apt mirrors, if
ALLOW_EC2_MIRRORS_ON_NON_AWS_INSTANCE_TYPES
isTrue
cloud-init will detect that a datasource’savailability_zone
property looks like an EC2 availability zone and set theec2_region
variable when generating mirror URLs; this can lead to incorrect mirrors being configured in clouds whose AZs follow EC2’s naming pattern.As of 20.3,
ALLOW_EC2_MIRRORS_ON_NON_AWS_INSTANCE_TYPES
isFalse
so we no longer includeec2_region
in mirror determination on non-AWS cloud platforms.If the old behavior is desired, users can provide the appropriate mirrors via
apt:
directives in cloud-config.
- cloudinit.features.APT_DEB822_SOURCE_LIST_FILE = True#
On Debian and Ubuntu systems, cc_apt_configure will write a deb822 compatible /etc/apt/sources.list.d/(debian|ubuntu).sources file. When set False, continue to write /etc/apt/sources.list directly.
- cloudinit.features.ERROR_ON_USER_DATA_FAILURE = True#
If there is a failure in obtaining user data (i.e., #include or decompress fails) and
ERROR_ON_USER_DATA_FAILURE
isFalse
, cloud-init will log a warning and proceed. If it isTrue
, cloud-init will instead raise an exception.As of 20.3,
ERROR_ON_USER_DATA_FAILURE
isTrue
.(This flag can be removed after Focal is no longer supported.)
- cloudinit.features.EXPIRE_APPLIES_TO_HASHED_USERS = True#
If
EXPIRE_APPLIES_TO_HASHED_USERS
is True, then when expire is set true in cc_set_passwords, hashed passwords will be expired. Previous to 22.3, only non-hashed passwords were expired.(This flag can be removed after Jammy is no longer supported.)
- cloudinit.features.NETPLAN_CONFIG_ROOT_READ_ONLY = True#
If
NETPLAN_CONFIG_ROOT_READ_ONLY
is True, then netplan configuration will be written as a single root readon-only file /etc/netplan/50-cloud-init.yaml. This prevents wifi passwords in network v2 configuration from being world-readable. Prior to 23.1, netplan configuration is world-readable.(This flag can be removed after Jammy is no longer supported.)
- cloudinit.features.NOCLOUD_SEED_URL_APPEND_FORWARD_SLASH = True#
Append a forward slash ‘/’ if NoCloud seedurl does not end with either a querystring or forward slash. Prior to 23.1, nocloud seedurl would be used unaltered, appending meta-data, user-data and vendor-data to without URL path separators.
(This flag can be removed when Jammy is no longer supported.)