summaryrefslogtreecommitdiff
path: root/doc/rtd/topics
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rtd/topics')
-rw-r--r--doc/rtd/topics/availability.rst19
-rw-r--r--doc/rtd/topics/boot.rst4
-rw-r--r--doc/rtd/topics/cli.rst16
-rw-r--r--doc/rtd/topics/code_review.rst256
-rw-r--r--doc/rtd/topics/datasources/azure.rst16
-rw-r--r--doc/rtd/topics/datasources/cloudstack.rst26
-rw-r--r--doc/rtd/topics/datasources/ec2.rst27
-rw-r--r--doc/rtd/topics/datasources/maas.rst2
-rw-r--r--doc/rtd/topics/datasources/nocloud.rst20
-rw-r--r--doc/rtd/topics/datasources/openstack.rst17
-rw-r--r--doc/rtd/topics/datasources/ovf.rst19
-rw-r--r--doc/rtd/topics/faq.rst21
-rw-r--r--doc/rtd/topics/format.rst55
-rw-r--r--doc/rtd/topics/instancedata.rst363
-rw-r--r--doc/rtd/topics/modules.rst1
-rw-r--r--doc/rtd/topics/network-config-format-v2.rst10
-rw-r--r--doc/rtd/topics/network-config.rst26
-rw-r--r--doc/rtd/topics/tests.rst66
18 files changed, 721 insertions, 243 deletions
diff --git a/doc/rtd/topics/availability.rst b/doc/rtd/topics/availability.rst
index 3f215b1b..8f56a7d2 100644
--- a/doc/rtd/topics/availability.rst
+++ b/doc/rtd/topics/availability.rst
@@ -14,17 +14,20 @@ distributions and clouds, both public and private.
Distributions
=============
-Cloud-init has support across all major Linux distributions and
-FreeBSD:
+Cloud-init has support across all major Linux distributions, FreeBSD, NetBSD
+and OpenBSD:
-- Ubuntu
-- SLES/openSUSE
-- RHEL/CentOS
-- Fedora
-- Gentoo Linux
-- Debian
+- Alpine Linux
- ArchLinux
+- Debian
+- Fedora
- FreeBSD
+- Gentoo Linux
+- NetBSD
+- OpenBSD
+- RHEL/CentOS
+- SLES/openSUSE
+- Ubuntu
Clouds
======
diff --git a/doc/rtd/topics/boot.rst b/doc/rtd/topics/boot.rst
index d846867b..4e79c958 100644
--- a/doc/rtd/topics/boot.rst
+++ b/doc/rtd/topics/boot.rst
@@ -129,7 +129,7 @@ Config
+---------+--------+----------------------------------------------------------+
This stage runs config modules only. Modules that do not really have an
-effect on other stages of boot are run here.
+effect on other stages of boot are run here, including ``runcmd``.
Final
=====
@@ -150,7 +150,7 @@ Things that run here include
* package installations
* configuration management plugins (puppet, chef, salt-minion)
- * user-scripts (including ``runcmd``).
+ * user-scripts (i.e. shell scripts passed as user-data)
For scripts external to cloud-init looking to wait until cloud-init is
finished, the ``cloud-init status`` subcommand can help block external
diff --git a/doc/rtd/topics/cli.rst b/doc/rtd/topics/cli.rst
index b32677b0..0ff230b5 100644
--- a/doc/rtd/topics/cli.rst
+++ b/doc/rtd/topics/cli.rst
@@ -106,17 +106,19 @@ Do **NOT** rely on the output of these commands as they can and will change.
Current subcommands:
- * ``schema``: a **#cloud-config** format and schema
- validator. It accepts a cloud-config yaml file and annotates potential
- schema errors locally without the need for deployment. Schema
- validation is work in progress and supports a subset of cloud-config
- modules.
-
+ * ``net-convert``: manually use cloud-init's network format conversion, useful
+ for testing configuration or testing changes to the network conversion logic
+ itself.
* ``render``: use cloud-init's jinja template render to
process **#cloud-config** or **custom-scripts**, injecting any variables
from ``/run/cloud-init/instance-data.json``. It accepts a user-data file
containing the jinja template header ``## template: jinja`` and renders
that content with any instance-data.json variables present.
+ * ``schema``: a **#cloud-config** format and schema
+ validator. It accepts a cloud-config yaml file and annotates potential
+ schema errors locally without the need for deployment. Schema
+ validation is work in progress and supports a subset of cloud-config
+ modules.
.. _cli_features:
@@ -162,7 +164,7 @@ declared to run in various boot stages in the file
* *cloud_init_modules*
* *cloud_config_modules*
-* *cloud_init_modules*
+* *cloud_final_modules*
Can be run on the command line, but each module is gated to run only once due
to semaphores in ``/var/lib/cloud/``.
diff --git a/doc/rtd/topics/code_review.rst b/doc/rtd/topics/code_review.rst
new file mode 100644
index 00000000..68c10405
--- /dev/null
+++ b/doc/rtd/topics/code_review.rst
@@ -0,0 +1,256 @@
+*******************
+Code Review Process
+*******************
+
+In order to manage incoming pull requests effectively, and provide
+timely feedback and/or acceptance this document serves as a guideline
+for the review process and outlines the expectations for those
+submitting code to the project as well as those reviewing the code.
+Code is reviewed for acceptance by at least one core team member (later
+referred to as committers), but comments and suggestions from others
+are encouraged and welcome.
+
+The process is intended to provide timely and actionable feedback for
+any submission.
+
+Asking For Help
+===============
+
+cloud-init contributors, potential contributors, community members and
+users are encouraged to ask for any help that they need. If you have
+questions about the code review process, or at any point during the
+code review process, these are the available avenues:
+
+* if you have an open Pull Request, comment on that pull request
+* join the ``#cloud-init`` channel on the Freenode IRC network and ask
+ away
+* send an email to the cloud-init mailing list,
+ cloud-init@lists.launchpad.net
+
+These are listed in rough order of preference, but use whichever of
+them you are most comfortable with.
+
+Goals
+=====
+
+This process has the following goals:
+
+* Ensure code reviews occur in a timely fashion and provide actionable
+ feedback if changes are desired.
+* Ensure the minimization of ancillary problems to increase the
+ efficiency for those reviewing the submitted code
+
+Role Definitions
+================
+
+Any code review process will have (at least) two involved parties. For
+our purposes, these parties are referred to as **Proposer** and
+**Reviewer**. (We also have the **Committer** role which is a special
+case of the **Reviewer** role.) The terms are defined here (and the
+use of the singular form is not meant to imply that they refer to a
+single person):
+
+Proposer
+ The person proposing a pull request (hereafter known as a PR).
+
+Reviewer
+ A person who is reviewing a PR.
+
+Committer
+ A cloud-init core developer (i.e. a person who has permission to
+ merge PRs into master).
+
+Prerequisites For Landing Pull Requests
+=======================================
+
+Before a PR can be landed into master, the following conditions *must*
+be met:
+
+* the CLA has been signed by the **Proposer** (or is covered by an
+ entity-level CLA signature)
+* all required status checks are passing
+* at least one "Approve" review from a **Committer**
+* no "Request changes" reviews from any **Committer**
+
+The following conditions *should* be met:
+
+* any Python functions/methods/classes have docstrings added/updated
+* any changes to config module behaviour are captured in the
+ documentation of the config module
+* any Python code added has corresponding unit tests
+* no "Request changes" reviews from any **Reviewer**
+
+These conditions can be relaxed at the discretion of the
+**Committers** on a case-by-case basis. Generally, for accountability,
+this should not be the decision of a single **Committer**, and the
+decision should be documented in comments on the PR.
+
+(To take a specific example, the ``cc_phone_home`` module had no tests
+at the time `PR #237
+<https://github.com/canonical/cloud-init/pull/237>`_ was submitted, so
+the **Proposer** was not expected to write a full set of tests for
+their minor modification, but they were expected to update the config
+module docs.)
+
+Non-Committer Reviews
+=====================
+
+Reviews from non-**Committers** are *always* welcome. Please feel
+empowered to review PRs and leave your thoughts and comments on any
+submitted PRs, regardless of the **Proposer**.
+
+Much of the below process is written in terms of the **Committers**.
+This is not intended to reflect that reviews should only come from that
+group, but acknowledges that we are ultimately responsible for
+maintaining the standards of the codebase. It would be entirely
+reasonable (and very welcome) for a **Reviewer** to only examine part
+of a PR, but it would not be appropriate for a **Committer** to merge a
+PR without full scrutiny.
+
+Opening Phase
+=============
+
+In this phase, the **Proposer** is responsible for opening a pull
+request and meeting the prerequisites laid out above.
+
+If they need help understanding the prerequisites, or help meeting the
+prerequisites, then they can (and should!) ask for help. See the
+:ref:`Asking For Help` section above for the ways to do that.
+
+These are the steps that comprise the opening phase:
+
+1. The **Proposer** opens PR
+
+2. CI runs automatically, and if
+
+ CI fails
+ The **Proposer** is expected to fix CI failures. If the
+ **Proposer** doesn't understand the nature of the failures they
+ are seeing, they should comment in the PR to request assistance,
+ or use another way of :ref:`Asking For Help`.
+
+ (Note that if assistance is not requested, the **Committers**
+ will assume that the **Proposer** is working on addressing the
+ failures themselves. If you require assistance, please do ask
+ for help!)
+
+ CI passes
+ Move on to the :ref:`Review phase`.
+
+Review Phase
+============
+
+In this phase, the **Proposer** and the **Reviewers** will iterate
+together to, hopefully, get the PR merged into the cloud-init codebase.
+There are three potential outcomes: merged, rejected permanently, and
+temporarily closed. (The first two are covered in this section; see
+:ref:`Inactive Pull Requests` for details about temporary closure.)
+
+(In the below, when the verbs "merge" or "squash merge" are used, they
+should be understood to mean "squash merged using the GitHub UI", which
+is the only way that changes can land in cloud-init's master branch.)
+
+These are the steps that comprise the review phase:
+
+1. **The Committers** assign a **Committer** to the PR
+
+ This **Committer** is expected to shepherd the PR to completion (and
+ merge it, if that is the outcome reached). This means that they
+ will perform an initial review, and monitor the PR to ensure that
+ the **Proposer** is receiving any assistance that they require. The
+ **Committers** will perform this assignment on a daily basis.
+
+ This assignment is intended to ensure that the **Proposer** has a
+ clear point of contact with a cloud-init core developer, and that
+ they get timely feedback after submitting a PR. It *is not*
+ intended to preclude reviews from any other **Reviewers**, nor to
+ imply that the **Committer** has ownership over the review process.
+
+ The assigned **Committer** may choose to delegate the code review of
+ a PR to another **Reviewer** if they think that they would be better
+ suited.
+
+ (Note that, in GitHub terms, this is setting an Assignee, not
+ requesting a review.)
+
+2. That **Committer** performs an initial review of the PR, resulting
+ in one of the following:
+
+ Approve
+ If the submitted PR meets all of the :ref:`Prerequisites for
+ Landing Pull Requests` and passes code review, then the
+ **Committer** will squash merge immediately.
+
+ There may be circumstances where a PR should not be merged
+ immediately. The ``wip`` label will be applied to PRs for which
+ this is true. Only **Committers** are able to apply labels to
+ PRs, so anyone who believes that this label should be applied to a
+ PR should request its application in a comment on the PR.
+
+ The review process is **DONE**.
+
+ Approve (with nits)
+ If the **Proposer** submits their PR with "Allow edits from
+ maintainer" enabled, and the only changes the **Committer**
+ requests are minor "nits", the **Committer** can push fixes for
+ those nits and *immediately* squash merge. If the **Committer**
+ does not wish to fix these nits but believes they should block a
+ straight-up Approve, then their review should be "Needs Changes"
+ instead.
+
+ A nit is understood to be something like a minor style issue or a
+ spelling error, generally confined to a single line of code.
+
+ If a **Committer** is unsure as to whether their requested change
+ is a nit, they should not treat it as a nit.
+
+ (If a **Proposer** wants to opt-out of this, then they should
+ uncheck "Allow edits from maintainer" when submitting their PR.)
+
+ The review process is **DONE**.
+
+ Outright rejection
+ The **Committer** will close the PR, with useful messaging for the
+ **Proposer** as to why this has happened.
+
+ This is reserved for cases where the proposed change is completely
+ unfit for landing, and there is no reasonable path forward. This
+ should only be used sparingly, as there are very few cases where
+ proposals are completely unfit.
+
+ If a different approach to the same problem is planned, it should
+ be submitted as a separate PR. The **Committer** should include
+ this information in their message when the PR is closed.
+
+ The review process is **DONE**.
+
+ Needs Changes
+ The **Committer** will give the **Proposer** a clear idea of what
+ is required for an Approve vote or, for more complex PRs, what the
+ next steps towards an Approve vote are.
+
+ The **Proposer** will ask questions if they don't understand, or
+ disagree with, the **Committer**'s review comments.
+
+ Once consensus has been reached, the **Proposer** will address the
+ review comments.
+
+ Once the review comments are addressed (as well as, potentially,
+ in the interim), CI will run. If CI fails, the **Proposer** is
+ expected to fix CI failures. If CI passes, the **Proposer**
+ should indicate that the PR is ready for re-review (by @ing the
+ assigned reviewer), effectively moving back to the start of this
+ section.
+
+Inactive Pull Requests
+======================
+
+PRs will be temporarily closed if they have been waiting on
+**Proposer** action for a certain amount of time without activity. A
+PR will be marked as stale (with an explanatory comment) after 14 days
+of inactivity. It will be closed after a further 7 days of inactivity.
+
+These closes are not considered permanent, and the closing message
+should reflect this for the **Proposer**. However, if a PR is reopened,
+it should effectively enter the :ref:`Opening phase` again, as it may
+need some work done to get CI passing again.
diff --git a/doc/rtd/topics/datasources/azure.rst b/doc/rtd/topics/datasources/azure.rst
index 1427fb3d..fdb919a5 100644
--- a/doc/rtd/topics/datasources/azure.rst
+++ b/doc/rtd/topics/datasources/azure.rst
@@ -114,19 +114,19 @@ An example configuration with the default values is provided below:
.. sourcecode:: yaml
datasource:
- Azure:
- agent_command: __builtin__
- apply_network_config: true
- data_dir: /var/lib/waagent
- dhclient_lease_file: /var/lib/dhcp/dhclient.eth0.leases
- disk_aliases:
+ Azure:
+ agent_command: __builtin__
+ apply_network_config: true
+ data_dir: /var/lib/waagent
+ dhclient_lease_file: /var/lib/dhcp/dhclient.eth0.leases
+ disk_aliases:
ephemeral0: /dev/disk/cloud/azure_resource
- hostname_bounce:
+ hostname_bounce:
interface: eth0
command: builtin
policy: true
hostname_command: hostname
- set_hostname: true
+ set_hostname: true
Userdata
diff --git a/doc/rtd/topics/datasources/cloudstack.rst b/doc/rtd/topics/datasources/cloudstack.rst
index da183226..a24de34f 100644
--- a/doc/rtd/topics/datasources/cloudstack.rst
+++ b/doc/rtd/topics/datasources/cloudstack.rst
@@ -9,14 +9,20 @@ dhcp lease information given to the instance.
For more details on meta-data and user-data,
refer the `CloudStack Administrator Guide`_.
-URLs to access user-data and meta-data from the Virtual Machine. Here 10.1.1.1
-is the Virtual Router IP:
+URLs to access user-data and meta-data from the Virtual Machine.
+`data-server.` is a well-known hostname provided by the CloudStack virtual
+router that points to the next UserData server (which is usually also
+the virtual router).
.. code:: bash
- http://10.1.1.1/latest/user-data
- http://10.1.1.1/latest/meta-data
- http://10.1.1.1/latest/meta-data/{metadata type}
+ http://data-server./latest/user-data
+ http://data-server./latest/meta-data
+ http://data-server./latest/meta-data/{metadata type}
+
+If `data-server.` cannot be resolved, cloud-init will try to obtain the
+virtual router's address from the system's DHCP leases. If that fails,
+it will use the system's default gateway.
Configuration
-------------
@@ -37,11 +43,11 @@ An example configuration with the default values is provided below:
.. sourcecode:: yaml
datasource:
- CloudStack:
- max_wait: 120
- timeout: 50
- datasource_list:
- - CloudStack
+ CloudStack:
+ max_wait: 120
+ timeout: 50
+ datasource_list:
+ - CloudStack
.. _Apache CloudStack: http://cloudstack.apache.org/
diff --git a/doc/rtd/topics/datasources/ec2.rst b/doc/rtd/topics/datasources/ec2.rst
index a90f3779..274ca1e4 100644
--- a/doc/rtd/topics/datasources/ec2.rst
+++ b/doc/rtd/topics/datasources/ec2.rst
@@ -42,6 +42,7 @@ Note that there are multiple versions of this data provided, cloud-init
by default uses **2009-04-04** but newer versions can be supported with
relative ease (newer versions have more data exposed, while maintaining
backward compatibility with the previous versions).
+Version **2016-09-02** is required for secondary IP address support.
To see which versions are supported from your cloud provider use the following
URL:
@@ -80,16 +81,26 @@ The settings that may be configured are:
* **timeout**: the timeout value provided to urlopen for each individual http
request. This is used both when selecting a metadata_url and when crawling
the metadata service. (default: 50)
+ * **apply_full_imds_network_config**: Boolean (default: True) to allow
+ cloud-init to configure any secondary NICs and secondary IPs described by
+ the metadata service. All network interfaces are configured with DHCP (v4)
+ to obtain an primary IPv4 address and route. Interfaces which have a
+ non-empty 'ipv6s' list will also enable DHCPv6 to obtain a primary IPv6
+ address and route. The DHCP response (v4 and v6) return an IP that matches
+ the first element of local-ipv4s and ipv6s lists respectively. All
+ additional values (secondary addresses) in the static ip lists will be
+ added to interface.
An example configuration with the default values is provided below:
.. sourcecode:: yaml
datasource:
- Ec2:
- metadata_urls: ["http://169.254.169.254:80", "http://instance-data:8773"]
- max_wait: 120
- timeout: 50
+ Ec2:
+ metadata_urls: ["http://169.254.169.254:80", "http://instance-data:8773"]
+ max_wait: 120
+ timeout: 50
+ apply_full_imds_network_config: true
Notes
-----
@@ -102,4 +113,12 @@ Notes
The check for the instance type is performed by is_classic_instance()
method.
+ * For EC2 instances with multiple network interfaces (NICs) attached, dhcp4
+ will be enabled to obtain the primary private IPv4 address of those NICs.
+ Wherever dhcp4 or dhcp6 is enabled for a NIC, a dhcp route-metric will be
+ added with the value of ``<device-number + 1> * 100`` to ensure dhcp
+ routes on the primary NIC are preferred to any secondary NICs.
+ For example: the primary NIC will have a DHCP route-metric of 100,
+ the next NIC will be 200.
+
.. vi: textwidth=78
diff --git a/doc/rtd/topics/datasources/maas.rst b/doc/rtd/topics/datasources/maas.rst
index 85c853e9..427fba24 100644
--- a/doc/rtd/topics/datasources/maas.rst
+++ b/doc/rtd/topics/datasources/maas.rst
@@ -5,6 +5,6 @@ MAAS
*TODO*
-For now see: http://maas.ubuntu.com/
+For now see: https://maas.io/docs
diff --git a/doc/rtd/topics/datasources/nocloud.rst b/doc/rtd/topics/datasources/nocloud.rst
index bc96f7fe..0ca79102 100644
--- a/doc/rtd/topics/datasources/nocloud.rst
+++ b/doc/rtd/topics/datasources/nocloud.rst
@@ -32,7 +32,7 @@ The permitted keys are:
With ``ds=nocloud``, the ``seedfrom`` value must start with ``/`` or
``file://``. With ``ds=nocloud-net``, the ``seedfrom`` value must start
-with ``http://``, ``https://`` or ``ftp://``
+with ``http://`` or ``https://``.
e.g. you can pass this option to QEMU:
@@ -53,6 +53,12 @@ These user-data and meta-data files are expected to be in the following format.
Basically, user-data is simply user-data and meta-data is a yaml formatted file
representing what you'd find in the EC2 metadata service.
+You may also optionally provide a vendor-data file in the following format.
+
+::
+
+ /vendor-data
+
Given a disk ubuntu 12.04 cloud image in 'disk.img', you can create a
sufficient disk by following the example below.
@@ -133,12 +139,12 @@ be network configuration based on the filename.
version: 2
ethernets:
interface0:
- match:
- mac_address: "52:54:00:12:34:00"
- set-name: interface0
- addresses:
- - 192.168.1.10/255.255.255.0
- gateway4: 192.168.1.254
+ match:
+ mac_address: "52:54:00:12:34:00"
+ set-name: interface0
+ addresses:
+ - 192.168.1.10/255.255.255.0
+ gateway4: 192.168.1.254
.. _iso9660: https://en.wikipedia.org/wiki/ISO_9660
diff --git a/doc/rtd/topics/datasources/openstack.rst b/doc/rtd/topics/datasources/openstack.rst
index 8ce2a53d..b23b4b7c 100644
--- a/doc/rtd/topics/datasources/openstack.rst
+++ b/doc/rtd/topics/datasources/openstack.rst
@@ -5,7 +5,7 @@ OpenStack
This datasource supports reading data from the
`OpenStack Metadata Service
-<https://docs.openstack.org/nova/latest/admin/networking-nova.html#metadata-service>`_.
+<https://docs.openstack.org/nova/latest/admin/metadata-service.html>`_.
Discovery
-------------
@@ -19,7 +19,8 @@ checks the following environment attributes as a potential OpenStack platform:
* **/proc/1/environ**: Nova-lxd contains *product_name=OpenStack Nova*
* **DMI product_name**: Either *Openstack Nova* or *OpenStack Compute*
- * **DMI chassis_asset_tag** is *OpenTelekomCloud*
+ * **DMI chassis_asset_tag** is *OpenTelekomCloud*, *SAP CCloud VM*,
+ *OpenStack Nova* (since 19.2) or *OpenStack Compute* (since 19.2)
Configuration
@@ -50,12 +51,12 @@ An example configuration with the default values is provided below:
.. sourcecode:: yaml
datasource:
- OpenStack:
- metadata_urls: ["http://169.254.169.254"]
- max_wait: -1
- timeout: 10
- retries: 5
- apply_network_config: True
+ OpenStack:
+ metadata_urls: ["http://169.254.169.254"]
+ max_wait: -1
+ timeout: 10
+ retries: 5
+ apply_network_config: True
Vendor Data
diff --git a/doc/rtd/topics/datasources/ovf.rst b/doc/rtd/topics/datasources/ovf.rst
index c312617f..6256e624 100644
--- a/doc/rtd/topics/datasources/ovf.rst
+++ b/doc/rtd/topics/datasources/ovf.rst
@@ -11,4 +11,23 @@ transport.
For further information see a full working example in cloud-init's
source code tree in doc/sources/ovf
+Configuration
+-------------
+On VMware platforms, VMTools use is required for OVF datasource configuration
+settings as well as vCloud and vSphere admin configuration. User could change
+the VMTools configuration options with command::
+
+ vmware-toolbox-cmd config set <section> <key> <value>
+
+The following VMTools configuration options affect cloud-init's behavior on a booted VM:
+ * a: [deploypkg] enable-custom-scripts
+ If this option is absent in VMTools configuration, the custom script is
+ disabled by default for security reasons. Some VMware products could
+ change this default behavior (for example: enabled by default) via
+ customization specification settings.
+
+VMWare admin can refer to (https://github.com/canonical/cloud-init/blob/master/cloudinit/sources/helpers/vmware/imc/config.py) and set the customization specification settings.
+
+For more information, see [VMware vSphere Product Documentation](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-9A5093A5-C54F-4502-941B-3F9C0F573A39.html) and specific VMTools parameters consumed.
+
.. vi: textwidth=78
diff --git a/doc/rtd/topics/faq.rst b/doc/rtd/topics/faq.rst
index 98c0cfaa..aa1be142 100644
--- a/doc/rtd/topics/faq.rst
+++ b/doc/rtd/topics/faq.rst
@@ -104,6 +104,23 @@ The force parameter allows the command to be run again since the instance has
already launched. The other options increase the verbosity of logging and
put the logs to STDERR.
+How can I re-run datasource detection and cloud-init?
+=====================================================
+
+If a user is developing a new datasource or working on debugging an issue it
+may be useful to re-run datasource detection and the initial setup of
+cloud-init.
+
+To do this, force ds-identify to re-run, clean up any logs, and re-run
+cloud-init:
+
+.. code-block:: shell-session
+
+ $ sudo DI_LOG=stderr /usr/lib/cloud-init/ds-identify --force
+ $ sudo cloud-init clean --logs
+ $ sudo cloud-init init --local
+ $ sudo cloud-init init
+
How can I debug my user data?
=============================
@@ -206,8 +223,8 @@ values or the LXD `Custom Network Configuration`_ document for more about
custom network config.
.. _LXD: https://linuxcontainers.org/
-.. _Instance Configuration: https://lxd.readthedocs.io/en/latest/instances/
-.. _Custom Network Configuration: https://lxd.readthedocs.io/en/latest/cloud-init/
+.. _Instance Configuration: https://linuxcontainers.org/lxd/docs/master/instances
+.. _Custom Network Configuration: https://linuxcontainers.org/lxd/docs/master/cloud-init
Where can I learn more?
========================================
diff --git a/doc/rtd/topics/format.rst b/doc/rtd/topics/format.rst
index 2b60bdd3..d03e4caf 100644
--- a/doc/rtd/topics/format.rst
+++ b/doc/rtd/topics/format.rst
@@ -23,44 +23,35 @@ 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:
+Supported content-types are listed from the cloud-init subcommand make-mime::
-- text/cloud-boothook
-- text/cloud-config
-- text/cloud-config-archive
-- text/jinja2
-- text/part-handler
-- text/upstart-job
-- text/x-include-once-url
-- text/x-include-url
-- text/x-shellscript
+ % cloud-init devel make-mime --list-types
+ cloud-boothook
+ cloud-config
+ cloud-config-archive
+ cloud-config-jsonp
+ jinja2
+ part-handler
+ upstart-job
+ x-include-once-url
+ x-include-url
+ x-shellscript
-Helper script to generate mime messages
----------------------------------------
-.. code-block:: python
-
- #!/usr/bin/python
-
- import sys
+Helper subcommand to generate mime messages
+-------------------------------------------
- from email.mime.multipart import MIMEMultipart
- from email.mime.text import MIMEText
+The cloud-init subcommand can generate MIME multi-part files: `make-mime`_.
- if len(sys.argv) == 1:
- print("%s input-file:type ..." % (sys.argv[0]))
- sys.exit(1)
+``make-mime`` subcommand takes pairs of (filename, "text/" mime subtype)
+separated by a colon (e.g. ``config.yaml:cloud-config``) and emits a MIME
+multipart message to stdout. An example invocation, assuming you have your
+cloud config in ``config.yaml`` and a shell script in ``script.sh`` and want
+to store the multipart message in ``user-data``::
- combined_message = MIMEMultipart()
- for i in sys.argv[1:]:
- (filename, format_type) = i.split(":", 1)
- with open(filename) as fh:
- contents = fh.read()
- sub_message = MIMEText(contents, format_type, sys.getdefaultencoding())
- sub_message.add_header('Content-Disposition', 'attachment; filename="%s"' % (filename))
- combined_message.attach(sub_message)
+ % cloud-init devel make-mime -a config.yaml:cloud-config -a script.sh:x-shellscript > user-data
- print(combined_message)
+.. _make-mime: https://github.com/canonical/cloud-init/blob/master/cloudinit/cmd/devel/make_mime.py
User-Data Script
@@ -126,7 +117,7 @@ Begins with: ``#cloud-config`` or ``Content-Type: text/cloud-config`` when
using a MIME archive.
.. note::
- New in cloud-init v. 18.4: Cloud config dta can also render cloud instance
+ New in cloud-init v. 18.4: Cloud config data can also render cloud instance
metadata variables using jinja templating. See
:ref:`instance_metadata` for more information.
diff --git a/doc/rtd/topics/instancedata.rst b/doc/rtd/topics/instancedata.rst
index e7dd0d62..255245a4 100644
--- a/doc/rtd/topics/instancedata.rst
+++ b/doc/rtd/topics/instancedata.rst
@@ -76,6 +76,11 @@ There are three basic top-level keys:
'security sensitive'. Only the keys listed here will be redacted from
instance-data.json for non-root users.
+* **merged_cfg**: Merged cloud-init 'system_config' from `/etc/cloud/cloud.cfg`
+ and `/etc/cloud/cloud-cfg.d`. Values under this key could contain sensitive
+ information such as passwords, so it is included in the **sensitive-keys**
+ list which is only readable by root.
+
* **ds**: Datasource-specific metadata crawled for the specific cloud
platform. It should closely represent the structure of the cloud metadata
crawled. The structure of content and details provided are entirely
@@ -83,6 +88,9 @@ There are three basic top-level keys:
The content exposed under the 'ds' key is currently **experimental** and
expected to change slightly in the upcoming cloud-init release.
+* **sys_info**: Information about the underlying os, python, architecture and
+ kernel. This represents the data collected by `cloudinit.util.system_info`.
+
* **v1**: Standardized cloud-init metadata keys, these keys are guaranteed to
exist on all cloud platforms. They will also retain their current behavior
and format and will be carried forward even if cloud-init introduces a new
@@ -103,7 +111,7 @@ v1.cloud_name
-------------
Where possible this will indicate the 'name' of the cloud the system is running
on. This is different than the 'platform' item. For example, the cloud name of
-Amazone Web Services is 'aws', while the platform is 'ec2'.
+Amazon Web Services is 'aws', while the platform is 'ec2'.
If determining a specific name is not possible or provided in meta-data, then
this filed may contain the same content as 'platform'.
@@ -117,6 +125,22 @@ Example output:
- nocloud
- ovf
+v1.distro, v1.distro_version, v1.distro_release
+-----------------------------------------------
+This shall be the distro name, version and release as determined by
+`cloudinit.util.get_linux_distro`.
+
+Example output:
+
+- alpine, 3.12.0, ''
+- centos, 7.5, core
+- debian, 9, stretch
+- freebsd, 12.0-release-p10,
+- opensuse, 42.3, x86_64
+- opensuse-tumbleweed, 20180920, x86_64
+- redhat, 7.5, 'maipo'
+- sles, 12.3, x86_64
+- ubuntu, 20.04, focal
v1.instance_id
--------------
@@ -126,6 +150,14 @@ Examples output:
- i-<hash>
+v1.kernel_release
+-----------------
+This shall be the running kernel `uname -r`
+
+Example output:
+
+- 5.3.0-1010-aws
+
v1.local_hostname
-----------------
The internal or local hostname of the system.
@@ -135,6 +167,17 @@ Examples output:
- ip-10-41-41-70
- <user-provided-hostname>
+v1.machine
+----------
+This shall be the running cpu machine architecture `uname -m`
+
+Example output:
+
+- x86_64
+- i686
+- ppc64le
+- s390x
+
v1.platform
-------------
An attempt to identify the cloud platfrom instance that the system is running
@@ -154,7 +197,7 @@ v1.subplatform
Additional platform details describing the specific source or type of metadata
used. The format of subplatform will be:
-``<subplatform_type> (<url_file_or_dev_path>``
+``<subplatform_type> (<url_file_or_dev_path>)``
Examples output:
@@ -171,6 +214,15 @@ Examples output:
- ['ssh-rsa AA...', ...]
+v1.python_version
+-----------------
+The version of python that is running cloud-init as determined by
+`cloudinit.util.system_info`
+
+Example output:
+
+- 3.7.6
+
v1.region
---------
The physical region/data center in which the instance is deployed.
@@ -192,164 +244,265 @@ Examples output:
Example Output
--------------
-Below is an example of ``/run/cloud-init/instance_data.json`` on an EC2
-instance:
+Below is an example of ``/run/cloud-init/instance-data-sensitive.json`` on an
+EC2 instance:
.. sourcecode:: json
{
+ "_beta_keys": [
+ "subplatform"
+ ],
+ "availability_zone": "us-east-1b",
"base64_encoded_keys": [],
+ "merged_cfg": {
+ "_doc": "Merged cloud-init system config from /etc/cloud/cloud.cfg and /etc/cloud/cloud.cfg.d/",
+ "_log": [
+ "[loggers]\nkeys=root,cloudinit\n\n[handlers]\nkeys=consoleHandler,cloudLogHandler\n\n[formatters]\nkeys=simpleFormatter,arg0Formatter\n\n[logger_root]\nlevel=DEBUG\nhandlers=consoleHandler,cloudLogHandler\n\n[logger_cloudinit]\nlevel=DEBUG\nqualname=cloudinit\nhandlers=\npropagate=1\n\n[handler_consoleHandler]\nclass=StreamHandler\nlevel=WARNING\nformatter=arg0Formatter\nargs=(sys.stderr,)\n\n[formatter_arg0Formatter]\nformat=%(asctime)s - %(filename)s[%(levelname)s]: %(message)s\n\n[formatter_simpleFormatter]\nformat=[CLOUDINIT] %(filename)s[%(levelname)s]: %(message)s\n",
+ "[handler_cloudLogHandler]\nclass=FileHandler\nlevel=DEBUG\nformatter=arg0Formatter\nargs=('/var/log/cloud-init.log',)\n",
+ "[handler_cloudLogHandler]\nclass=handlers.SysLogHandler\nlevel=DEBUG\nformatter=simpleFormatter\nargs=(\"/dev/log\", handlers.SysLogHandler.LOG_USER)\n"
+ ],
+ "cloud_config_modules": [
+ "emit_upstart",
+ "snap",
+ "ssh-import-id",
+ "locale",
+ "set-passwords",
+ "grub-dpkg",
+ "apt-pipelining",
+ "apt-configure",
+ "ubuntu-advantage",
+ "ntp",
+ "timezone",
+ "disable-ec2-metadata",
+ "runcmd",
+ "byobu"
+ ],
+ "cloud_final_modules": [
+ "package-update-upgrade-install",
+ "fan",
+ "landscape",
+ "lxd",
+ "ubuntu-drivers",
+ "puppet",
+ "chef",
+ "mcollective",
+ "salt-minion",
+ "rightscale_userdata",
+ "scripts-vendor",
+ "scripts-per-once",
+ "scripts-per-boot",
+ "scripts-per-instance",
+ "scripts-user",
+ "ssh-authkey-fingerprints",
+ "keys-to-console",
+ "phone-home",
+ "final-message",
+ "power-state-change"
+ ],
+ "cloud_init_modules": [
+ "migrator",
+ "seed_random",
+ "bootcmd",
+ "write-files",
+ "growpart",
+ "resizefs",
+ "disk_setup",
+ "mounts",
+ "set_hostname",
+ "update_hostname",
+ "update_etc_hosts",
+ "ca-certs",
+ "rsyslog",
+ "users-groups",
+ "ssh"
+ ],
+ "datasource_list": [
+ "Ec2",
+ "None"
+ ],
+ "def_log_file": "/var/log/cloud-init.log",
+ "disable_root": true,
+ "log_cfgs": [
+ [
+ "[loggers]\nkeys=root,cloudinit\n\n[handlers]\nkeys=consoleHandler,cloudLogHandler\n\n[formatters]\nkeys=simpleFormatter,arg0Formatter\n\n[logger_root]\nlevel=DEBUG\nhandlers=consoleHandler,cloudLogHandler\n\n[logger_cloudinit]\nlevel=DEBUG\nqualname=cloudinit\nhandlers=\npropagate=1\n\n[handler_consoleHandler]\nclass=StreamHandler\nlevel=WARNING\nformatter=arg0Formatter\nargs=(sys.stderr,)\n\n[formatter_arg0Formatter]\nformat=%(asctime)s - %(filename)s[%(levelname)s]: %(message)s\n\n[formatter_simpleFormatter]\nformat=[CLOUDINIT] %(filename)s[%(levelname)s]: %(message)s\n",
+ "[handler_cloudLogHandler]\nclass=FileHandler\nlevel=DEBUG\nformatter=arg0Formatter\nargs=('/var/log/cloud-init.log',)\n"
+ ]
+ ],
+ "output": {
+ "all": "| tee -a /var/log/cloud-init-output.log"
+ },
+ "preserve_hostname": false,
+ "syslog_fix_perms": [
+ "syslog:adm",
+ "root:adm",
+ "root:wheel",
+ "root:root"
+ ],
+ "users": [
+ "default"
+ ],
+ "vendor_data": {
+ "enabled": true,
+ "prefix": []
+ }
+ },
+ "cloud_name": "aws",
+ "distro": "ubuntu",
+ "distro_release": "focal",
+ "distro_version": "20.04",
"ds": {
"_doc": "EXPERIMENTAL: The structure and format of content scoped under the 'ds' key may change in subsequent releases of cloud-init.",
"_metadata_api_version": "2016-09-02",
"dynamic": {
- "instance-identity": {
+ "instance_identity": {
"document": {
- "accountId": "437526006925",
+ "accountId": "329910648901",
"architecture": "x86_64",
- "availabilityZone": "us-east-2b",
+ "availabilityZone": "us-east-1b",
"billingProducts": null,
"devpayProductCodes": null,
- "imageId": "ami-079638aae7046bdd2",
- "instanceId": "i-075f088c72ad3271c",
+ "imageId": "ami-02e8aa396f8be3b6d",
+ "instanceId": "i-0929128ff2f73a2f1",
"instanceType": "t2.micro",
"kernelId": null,
"marketplaceProductCodes": null,
- "pendingTime": "2018-10-05T20:10:43Z",
- "privateIp": "10.41.41.95",
+ "pendingTime": "2020-02-27T20:46:18Z",
+ "privateIp": "172.31.81.43",
"ramdiskId": null,
- "region": "us-east-2",
+ "region": "us-east-1",
"version": "2017-09-30"
},
"pkcs7": [
- "MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAaCAJIAEggHbewog",
- "ICJkZXZwYXlQcm9kdWN0Q29kZXMiIDogbnVsbCwKICAibWFya2V0cGxhY2VQcm9kdWN0Q29kZXMi",
- "IDogbnVsbCwKICAicHJpdmF0ZUlwIiA6ICIxMC40MS40MS45NSIsCiAgInZlcnNpb24iIDogIjIw",
- "MTctMDktMzAiLAogICJpbnN0YW5jZUlkIiA6ICJpLTA3NWYwODhjNzJhZDMyNzFjIiwKICAiYmls",
- "bGluZ1Byb2R1Y3RzIiA6IG51bGwsCiAgImluc3RhbmNlVHlwZSIgOiAidDIubWljcm8iLAogICJh",
- "Y2NvdW50SWQiIDogIjQzNzUyNjAwNjkyNSIsCiAgImF2YWlsYWJpbGl0eVpvbmUiIDogInVzLWVh",
- "c3QtMmIiLAogICJrZXJuZWxJZCIgOiBudWxsLAogICJyYW1kaXNrSWQiIDogbnVsbCwKICAiYXJj",
- "aGl0ZWN0dXJlIiA6ICJ4ODZfNjQiLAogICJpbWFnZUlkIiA6ICJhbWktMDc5NjM4YWFlNzA0NmJk",
- "ZDIiLAogICJwZW5kaW5nVGltZSIgOiAiMjAxOC0xMC0wNVQyMDoxMDo0M1oiLAogICJyZWdpb24i",
- "IDogInVzLWVhc3QtMiIKfQAAAAAAADGCARcwggETAgEBMGkwXDELMAkGA1UEBhMCVVMxGTAXBgNV",
- "BAgTEFdhc2hpbmd0b24gU3RhdGUxEDAOBgNVBAcTB1NlYXR0bGUxIDAeBgNVBAoTF0FtYXpvbiBX",
- "ZWIgU2VydmljZXMgTExDAgkAlrpI2eVeGmcwCQYFKw4DAhoFAKBdMBgGCSqGSIb3DQEJAzELBgkq",
- "hkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTE4MTAwNTIwMTA0OFowIwYJKoZIhvcNAQkEMRYEFK0k",
- "Tz6n1A8/zU1AzFj0riNQORw2MAkGByqGSM44BAMELjAsAhRNrr174y98grPBVXUforN/6wZp8AIU",
- "JLZBkrB2GJA8A4WJ1okq++jSrBIAAAAAAAA="
+ "MIAGCSqGSIb3DQ...",
+ "REDACTED",
+ "AhQUgq0iPWqPTVnT96tZE6L1XjjLHQAAAAAAAA=="
],
"rsa2048": [
- "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwGggCSABIIB",
- "23sKICAiZGV2cGF5UHJvZHVjdENvZGVzIiA6IG51bGwsCiAgIm1hcmtldHBsYWNlUHJvZHVjdENv",
- "ZGVzIiA6IG51bGwsCiAgInByaXZhdGVJcCIgOiAiMTAuNDEuNDEuOTUiLAogICJ2ZXJzaW9uIiA6",
- "ICIyMDE3LTA5LTMwIiwKICAiaW5zdGFuY2VJZCIgOiAiaS0wNzVmMDg4YzcyYWQzMjcxYyIsCiAg",
- "ImJpbGxpbmdQcm9kdWN0cyIgOiBudWxsLAogICJpbnN0YW5jZVR5cGUiIDogInQyLm1pY3JvIiwK",
- "ICAiYWNjb3VudElkIiA6ICI0Mzc1MjYwMDY5MjUiLAogICJhdmFpbGFiaWxpdHlab25lIiA6ICJ1",
- "cy1lYXN0LTJiIiwKICAia2VybmVsSWQiIDogbnVsbCwKICAicmFtZGlza0lkIiA6IG51bGwsCiAg",
- "ImFyY2hpdGVjdHVyZSIgOiAieDg2XzY0IiwKICAiaW1hZ2VJZCIgOiAiYW1pLTA3OTYzOGFhZTcw",
- "NDZiZGQyIiwKICAicGVuZGluZ1RpbWUiIDogIjIwMTgtMTAtMDVUMjA6MTA6NDNaIiwKICAicmVn",
- "aW9uIiA6ICJ1cy1lYXN0LTIiCn0AAAAAAAAxggH/MIIB+wIBATBpMFwxCzAJBgNVBAYTAlVTMRkw",
- "FwYDVQQIExBXYXNoaW5ndG9uIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYDVQQKExdBbWF6",
- "b24gV2ViIFNlcnZpY2VzIExMQwIJAM07oeX4xevdMA0GCWCGSAFlAwQCAQUAoGkwGAYJKoZIhvcN",
- "AQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUxDxcNMTgxMDA1MjAxMDQ4WjAvBgkqhkiG9w0B",
- "CQQxIgQgkYz0pZk3zJKBi4KP4egeOKJl/UYwu5UdE7id74pmPwMwDQYJKoZIhvcNAQEBBQAEggEA",
- "dC3uIGGNul1OC1mJKSH3XoBWsYH20J/xhIdftYBoXHGf2BSFsrs9ZscXd2rKAKea4pSPOZEYMXgz",
- "lPuT7W0WU89N3ZKviy/ReMSRjmI/jJmsY1lea6mlgcsJXreBXFMYucZvyeWGHdnCjamoKWXkmZlM",
- "mSB1gshWy8Y7DzoKviYPQZi5aI54XK2Upt4kGme1tH1NI2Cq+hM4K+adxTbNhS3uzvWaWzMklUuU",
- "QHX2GMmjAVRVc8vnA8IAsBCJJp+gFgYzi09IK+cwNgCFFPADoG6jbMHHf4sLB3MUGpiA+G9JlCnM",
- "fmkjI2pNRB8spc0k4UG4egqLrqCz67WuK38tjwAAAAAAAA=="
+ "MIAGCSqGSIb...",
+ "REDACTED",
+ "clYQvuE45xXm7Yreg3QtQbrP//owl1eZHj6s350AAAAAAAA="
],
"signature": [
- "Tsw6h+V3WnxrNVSXBYIOs1V4j95YR1mLPPH45XnhX0/Ei3waJqf7/7EEKGYP1Cr4PTYEULtZ7Mvf",
- "+xJpM50Ivs2bdF7o0c4vnplRWe3f06NI9pv50dr110j/wNzP4MZ1pLhJCqubQOaaBTF3LFutgRrt",
- "r4B0mN3p7EcqD8G+ll0="
+ "dA+QV+LLCWCRNddnrKleYmh2GvYo+t8urDkdgmDSsPi",
+ "REDACTED",
+ "kDT4ygyJLFkd3b4qjAs="
]
}
},
- "meta-data": {
- "ami-id": "ami-079638aae7046bdd2",
- "ami-launch-index": "0",
- "ami-manifest-path": "(unknown)",
- "block-device-mapping": {
+ "meta_data": {
+ "ami_id": "ami-02e8aa396f8be3b6d",
+ "ami_launch_index": "0",
+ "ami_manifest_path": "(unknown)",
+ "block_device_mapping": {
"ami": "/dev/sda1",
- "ephemeral0": "sdb",
- "ephemeral1": "sdc",
"root": "/dev/sda1"
},
- "hostname": "ip-10-41-41-95.us-east-2.compute.internal",
- "instance-action": "none",
- "instance-id": "i-075f088c72ad3271c",
- "instance-type": "t2.micro",
- "local-hostname": "ip-10-41-41-95.us-east-2.compute.internal",
- "local-ipv4": "10.41.41.95",
- "mac": "06:74:8f:39:cd:a6",
+ "hostname": "ip-172-31-81-43.ec2.internal",
+ "instance_action": "none",
+ "instance_id": "i-0929128ff2f73a2f1",
+ "instance_type": "t2.micro",
+ "local_hostname": "ip-172-31-81-43.ec2.internal",
+ "local_ipv4": "172.31.81.43",
+ "mac": "12:7e:c9:93:29:af",
"metrics": {
"vhostmd": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
},
"network": {
"interfaces": {
"macs": {
- "06:74:8f:39:cd:a6": {
- "device-number": "0",
- "interface-id": "eni-052058bbd7831eaae",
- "ipv4-associations": {
- "18.218.221.122": "10.41.41.95"
- },
- "local-hostname": "ip-10-41-41-95.us-east-2.compute.internal",
- "local-ipv4s": "10.41.41.95",
- "mac": "06:74:8f:39:cd:a6",
- "owner-id": "437526006925",
- "public-hostname": "ec2-18-218-221-122.us-east-2.compute.amazonaws.com",
- "public-ipv4s": "18.218.221.122",
- "security-group-ids": "sg-828247e9",
- "security-groups": "Cloud-init integration test secgroup",
- "subnet-id": "subnet-282f3053",
- "subnet-ipv4-cidr-block": "10.41.41.0/24",
- "subnet-ipv6-cidr-blocks": "2600:1f16:b80:ad00::/64",
- "vpc-id": "vpc-252ef24d",
- "vpc-ipv4-cidr-block": "10.41.0.0/16",
- "vpc-ipv4-cidr-blocks": "10.41.0.0/16",
- "vpc-ipv6-cidr-blocks": "2600:1f16:b80:ad00::/56"
- }
+ "12:7e:c9:93:29:af": {
+ "device_number": "0",
+ "interface_id": "eni-0c07a0474339b801d",
+ "ipv4_associations": {
+ "3.89.187.177": "172.31.81.43"
+ },
+ "local_hostname": "ip-172-31-81-43.ec2.internal",
+ "local_ipv4s": "172.31.81.43",
+ "mac": "12:7e:c9:93:29:af",
+ "owner_id": "329910648901",
+ "public_hostname": "ec2-3-89-187-177.compute-1.amazonaws.com",
+ "public_ipv4s": "3.89.187.177",
+ "security_group_ids": "sg-0100038b68aa79986",
+ "security_groups": "launch-wizard-3",
+ "subnet_id": "subnet-04e2d12a",
+ "subnet_ipv4_cidr_block": "172.31.80.0/20",
+ "vpc_id": "vpc-210b4b5b",
+ "vpc_ipv4_cidr_block": "172.31.0.0/16",
+ "vpc_ipv4_cidr_blocks": "172.31.0.0/16"
+ }
}
}
},
"placement": {
- "availability-zone": "us-east-2b"
+ "availability_zone": "us-east-1b"
},
"profile": "default-hvm",
- "public-hostname": "ec2-18-218-221-122.us-east-2.compute.amazonaws.com",
- "public-ipv4": "18.218.221.122",
- "public-keys": {
- "cloud-init-integration": [
- "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDSL7uWGj8cgWyIOaspgKdVy0cKJ+UTjfv7jBOjG2H/GN8bJVXy72XAvnhM0dUM+CCs8FOf0YlPX+Frvz2hKInrmRhZVwRSL129PasD12MlI3l44u6IwS1o/W86Q+tkQYEljtqDOo0a+cOsaZkvUNzUyEXUwz/lmYa6G4hMKZH4NBj7nbAAF96wsMCoyNwbWryBnDYUr6wMbjRR1J9Pw7Xh7WRC73wy4Va2YuOgbD3V/5ZrFPLbWZW/7TFXVrql04QVbyei4aiFR5n//GvoqwQDNe58LmbzX/xvxyKJYdny2zXmdAhMxbrpFQsfpkJ9E/H5w0yOdSvnWbUoG5xNGoOB cloud-init-integration"
- ]
- },
- "reservation-id": "r-0594a20e31f6cfe46",
- "security-groups": "Cloud-init integration test secgroup",
+ "public_hostname": "ec2-3-89-187-177.compute-1.amazonaws.com",
+ "public_ipv4": "3.89.187.177",
+ "reservation_id": "r-0c481643d15766a02",
+ "security_groups": "launch-wizard-3",
"services": {
"domain": "amazonaws.com",
"partition": "aws"
}
}
},
+ "instance_id": "i-0929128ff2f73a2f1",
+ "kernel_release": "5.3.0-1010-aws",
+ "local_hostname": "ip-172-31-81-43",
+ "machine": "x86_64",
+ "platform": "ec2",
+ "public_ssh_keys": [],
+ "python_version": "3.7.6",
+ "region": "us-east-1",
"sensitive_keys": [],
+ "subplatform": "metadata (http://169.254.169.254)",
+ "sys_info": {
+ "dist": [
+ "ubuntu",
+ "20.04",
+ "focal"
+ ],
+ "platform": "Linux-5.3.0-1010-aws-x86_64-with-Ubuntu-20.04-focal",
+ "python": "3.7.6",
+ "release": "5.3.0-1010-aws",
+ "system": "Linux",
+ "uname": [
+ "Linux",
+ "ip-172-31-81-43",
+ "5.3.0-1010-aws",
+ "#11-Ubuntu SMP Thu Jan 16 07:59:32 UTC 2020",
+ "x86_64",
+ "x86_64"
+ ],
+ "variant": "ubuntu"
+ },
+ "system_platform": "Linux-5.3.0-1010-aws-x86_64-with-Ubuntu-20.04-focal",
+ "userdata": "#cloud-config\nssh_import_id: [<my-launchpad-id>]\n...",
"v1": {
"_beta_keys": [
"subplatform"
],
- "availability-zone": "us-east-2b",
- "availability_zone": "us-east-2b",
+ "availability_zone": "us-east-1b",
"cloud_name": "aws",
- "instance_id": "i-075f088c72ad3271c",
- "local_hostname": "ip-10-41-41-95",
+ "distro": "ubuntu",
+ "distro_release": "focal",
+ "distro_version": "20.04",
+ "instance_id": "i-0929128ff2f73a2f1",
+ "kernel": "5.3.0-1010-aws",
+ "local_hostname": "ip-172-31-81-43",
+ "machine": "x86_64",
"platform": "ec2",
- "public_ssh_keys": [
- "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDSL7uWGj8cgWyIOaspgKdVy0cKJ+UTjfv7jBOjG2H/GN8bJVXy72XAvnhM0dUM+CCs8FOf0YlPX+Frvz2hKInrmRhZVwRSL129PasD12MlI3l44u6IwS1o/W86Q+tkQYEljtqDOo0a+cOsaZkvUNzUyEXUwz/lmYa6G4hMKZH4NBj7nbAAF96wsMCoyNwbWryBnDYUr6wMbjRR1J9Pw7Xh7WRC73wy4Va2YuOgbD3V/5ZrFPLbWZW/7TFXVrql04QVbyei4aiFR5n//GvoqwQDNe58LmbzX/xvxyKJYdny2zXmdAhMxbrpFQsfpkJ9E/H5w0yOdSvnWbUoG5xNGoOB cloud-init-integration"
- ],
- "region": "us-east-2",
- "subplatform": "metadata (http://169.254.169.254)"
- }
+ "public_ssh_keys": [],
+ "python": "3.7.6",
+ "region": "us-east-1",
+ "subplatform": "metadata (http://169.254.169.254)",
+ "system_platform": "Linux-5.3.0-1010-aws-x86_64-with-Ubuntu-20.04-focal",
+ "variant": "ubuntu"
+ },
+ "variant": "ubuntu",
+ "vendordata": ""
}
diff --git a/doc/rtd/topics/modules.rst b/doc/rtd/topics/modules.rst
index 9c9be804..e30fe0fe 100644
--- a/doc/rtd/topics/modules.rst
+++ b/doc/rtd/topics/modules.rst
@@ -6,6 +6,7 @@ Modules
*******
.. contents:: Table of Contents
+.. automodule:: cloudinit.config.cc_apk_configure
.. automodule:: cloudinit.config.cc_apt_configure
.. automodule:: cloudinit.config.cc_apt_pipelining
.. automodule:: cloudinit.config.cc_bootcmd
diff --git a/doc/rtd/topics/network-config-format-v2.rst b/doc/rtd/topics/network-config-format-v2.rst
index 7f857550..c93e29be 100644
--- a/doc/rtd/topics/network-config-format-v2.rst
+++ b/doc/rtd/topics/network-config-format-v2.rst
@@ -50,9 +50,8 @@ currently being defined.
There are two physically/structurally different classes of device definitions,
and the ID field has a different interpretation for each:
-Physical devices
-
-: (Examples: ethernet, wifi) These can dynamically come and go between
+Physical devices (Examples: ethernet, wifi):
+ These can dynamically come and go between
reboots and even during runtime (hotplugging). In the generic case, they
can be selected by ``match:`` rules on desired properties, such as
name/name pattern, MAC address, driver, or device paths. In general these
@@ -69,9 +68,8 @@ Physical devices
which is only being used for references from definitions of compound
devices in the config.
-Virtual devices
-
-: (Examples: veth, bridge, bond) These are fully under the control of the
+Virtual devices (Examples: veth, bridge, bond):
+ These are fully under the control of the
config file(s) and the network stack. I. e. these devices are being created
instead of matched. Thus ``match:`` and ``set-name:`` are not applicable for
these, and the ID field is the name of the created virtual device.
diff --git a/doc/rtd/topics/network-config.rst b/doc/rtd/topics/network-config.rst
index 1520ba9a..08db04d8 100644
--- a/doc/rtd/topics/network-config.rst
+++ b/doc/rtd/topics/network-config.rst
@@ -25,17 +25,23 @@ For example, OpenStack may provide network config in the MetaData Service.
**System Config**
-A ``network:`` entry in /etc/cloud/cloud.cfg.d/* configuration files.
+A ``network:`` entry in ``/etc/cloud/cloud.cfg.d/*`` configuration files.
**Kernel Command Line**
-``ip=`` or ``network-config=<YAML config string>``
+``ip=`` or ``network-config=<Base64 encoded YAML config string>``
User-data cannot change an instance's network configuration. In the absence
of network configuration in any of the above sources , `Cloud-init`_ will
write out a network configuration that will issue a DHCP request on a "first"
network interface.
+.. note::
+
+ The network-config value is expected to be a Base64 encoded YAML string in
+ :ref:`network_config_v1` or :ref:`network_config_v2` format. Optionally it
+ can be compressed with ``gzip`` prior to Base64 encoding.
+
Disabling Network Configuration
===============================
@@ -48,19 +54,19 @@ on other methods, such as embedded configuration or other customizations.
**Kernel Command Line**
-`Cloud-init`_ will check for a parameter ``network-config`` and the
-value is expected to be YAML string in the :ref:`network_config_v1` format.
-The YAML string may optionally be ``Base64`` encoded, and optionally
-compressed with ``gzip``.
+`Cloud-init`_ will check additionally check for the parameter
+``network-config=disabled`` which will automatically disable any network
+configuration.
Example disabling kernel command line entry: ::
- network-config={config: disabled}
+ network-config=disabled
**cloud config**
-In the combined cloud-init configuration dictionary. ::
+In the combined cloud-init configuration dictionary, merged from
+``/etc/cloud/cloud.cfg`` and ``/etc/cloud/cloud.cfg.d/*``::
network:
config: disabled
@@ -159,7 +165,7 @@ supported formats. The following ``renderers`` are supported in cloud-init:
- **ENI**
/etc/network/interfaces or ``ENI`` is supported by the ``ifupdown`` package
-found in Ubuntu and Debian.
+found in Alpine Linux, Debian and Ubuntu.
- **Netplan**
@@ -191,7 +197,7 @@ supplying an updated configuration in cloud-config. ::
system_info:
network:
- renderers: ['netplan', 'eni', 'sysconfig', 'freebsd']
+ renderers: ['netplan', 'eni', 'sysconfig', 'freebsd', 'netbsd', 'openbsd']
Network Configuration Tools
diff --git a/doc/rtd/topics/tests.rst b/doc/rtd/topics/tests.rst
index aee3d7fc..f03b5969 100644
--- a/doc/rtd/topics/tests.rst
+++ b/doc/rtd/topics/tests.rst
@@ -467,11 +467,11 @@ Set region in platforms.yaml
.. code-block:: yaml
azurecloud:
- enabled: true
- region: West US 2
- vm_size: Standard_DS1_v2
- storage_sku: standard_lrs
- tag: ci
+ enabled: true
+ region: West US 2
+ vm_size: Standard_DS1_v2
+ storage_sku: standard_lrs
+ tag: ci
Architecture
@@ -546,38 +546,38 @@ The following demonstrates merge behavior:
.. code-block:: yaml
defaults:
- list_item:
- - list_entry_1
- - list_entry_2
- int_item_1: 123
- int_item_2: 234
- dict_item:
- subkey_1: 1
- subkey_2: 2
- subkey_dict:
- subsubkey_1: a
- subsubkey_2: b
+ list_item:
+ - list_entry_1
+ - list_entry_2
+ int_item_1: 123
+ int_item_2: 234
+ dict_item:
+ subkey_1: 1
+ subkey_2: 2
+ subkey_dict:
+ subsubkey_1: a
+ subsubkey_2: b
overrides:
- list_item:
- - overridden_list_entry
- int_item_1: 0
- dict_item:
- subkey_2: false
- subkey_dict:
- subsubkey_2: 'new value'
+ list_item:
+ - overridden_list_entry
+ int_item_1: 0
+ dict_item:
+ subkey_2: false
+ subkey_dict:
+ subsubkey_2: 'new value'
result:
- list_item:
- - overridden_list_entry
- int_item_1: 0
- int_item_2: 234
- dict_item:
- subkey_1: 1
- subkey_2: false
- subkey_dict:
- subsubkey_1: a
- subsubkey_2: 'new value'
+ list_item:
+ - overridden_list_entry
+ int_item_1: 0
+ int_item_2: 234
+ dict_item:
+ subkey_1: 1
+ subkey_2: false
+ subkey_dict:
+ subsubkey_1: a
+ subsubkey_2: 'new value'
Image Config
generated by cgit v1.2.3 (git 2.39.1) at 2025-03-09 14:58:55 +0000