diff --git a/doc/examples/cloud-config-datasources.txt b/doc/examples/cloud-config-datasources.txt index 0e1527bf952e..fd95b3a81fb0 100644 --- a/doc/examples/cloud-config-datasources.txt +++ b/doc/examples/cloud-config-datasources.txt @@ -38,7 +38,7 @@ datasource: # right here user-data: | # This is the user-data verbatim - meta-data: + meta-data: | instance-id: i-87018aed local-hostname: myhost.internal diff --git a/doc/rtd/reference/datasources/nocloud.rst b/doc/rtd/reference/datasources/nocloud.rst index 3033869f6820..bf32ad3458bb 100644 --- a/doc/rtd/reference/datasources/nocloud.rst +++ b/doc/rtd/reference/datasources/nocloud.rst @@ -4,99 +4,241 @@ NoCloud ******* The data source ``NoCloud`` is a flexible datasource that can be used in -multiple different ways. With NoCloud, one can provide configurations to -the instance without running a network service (or even without having a -network at all). Alternatively, one can use HTTP/HTTPS or FTP/FTPS to provide -a configuration. +multiple different ways. -Configuration Methods: +With NoCloud, one can provide configuration to the instance locally (without +network access) or alternatively NoCloud can fetch the configuration from a +remote server. + +Much of the following documentation describes how to tell cloud-init where +to get its configuration. + +Runtime configurations ====================== -.. warning:: - User data placed under ``/etc/cloud/`` will **not** be recognized as a - source of configuration data by the NoCloud datasource. While it may - be acted upon by cloud-init, using - :ref:`DataSourceNone` should be preferred. +Cloud-init discovers four types of configuration at runtime. The source of +these configuration types is configurable with a discovery configuration. This +discovery configuration can be delivered to cloud-init in different ways, but +is different from the configurations that cloud-init uses to configure the +instance at runtime. + +user data +--------- + +User data is a :ref:`configuration format` that allows a +user to configure an instance. + +metadata +-------- + +The ``meta-data`` file is a YAML-formatted file. + +vendor data +----------- + +Vendor data may be used to provide default cloud-specific configurations which +may be overriden by user data. This may be useful, for example, to configure an +instance with a cloud provider's repository mirror for faster package +installation. + +network config +-------------- + +Network configuration typically comes from the cloud provider to set +cloud-specific network configurations, or a reasonable default is set by +cloud-init (typically cloud-init brings up an interface using DHCP). -Method 1: Labeled filesystem +Since NoCloud is a generic datasource, network configuration may be set the +same way as user data, metadata, vendor data. + +See the :ref:`network configuration` documentation for +information on network configuration formats. + +Discovery configuration +======================= + +The purpose of the discovery configuration is to tell cloud-init where it can +find the runtime configurations described above. + +There are two methods for cloud-init to receive a discovery configuration. + +Method 1: Line configuration ---------------------------- -A labeled `vfat`_ or `iso9660` filesystem may be used. The filesystem volume -must be labelled ``CIDATA``. +The "line configuration" is a single string of text which is passed to an +instance at boot time via either the kernel command line or in the serial +number exposed via DMI (sometimes called SMBIOS). +Example: :: -Method 2: Custom webserver --------------------------- + ds=nocloud;s=https://10.42.42.42/configs/ -Configuration files can be provided to cloud-init over HTTP(s). To tell -cloud-init the URI to use, arguments must be passed to the instance via the -kernel command line or SMBIOS serial number. This argument might look like: :: +In the above line configuration, ``ds=nocloud`` tells cloud-init to use the +NoCloud datasource, and ``s=https://10.42.42.42/configs/`` tells cloud-init to +fetch configurations using ``https`` from the URI +``https://10.42.42.42/configs/``. - ds=nocloud;s=https://10.42.42.42/cloud-init/configs/ +We will describe the possible values in a line configuration in the following +sections. See :ref:`this section` for more details on line +configuration. .. note:: + If using kernel command line arguments with GRUB, note that an unescaped semicolon is intepreted as the end of a statement. - Consider using single-quotes to avoid this pitfall. See: `GRUB quoting`_ - ds=nocloud;s=http://10.42.42.42/cloud-init/configs/ + See: `GRUB quoting`_ + +Method 2: System configuration +------------------------------ + +System configurations are YAML-formatted files and have names that end in +``.cfg``. These are located under :file:`/etc/cloud/cloud.cfg.d/`. + +Example: + +.. code-block:: yaml + + datasource: + NoCloud: + seedfrom: https://10.42.42.42/configs/ + +The above system configuration tells cloud-init that it is using NoCloud and +that it can find configurations at ``https://10.42.42.42/configs/``. + +The scope of this section is limited to its use for selecting the source of +its configuration, however it is worth mentioning that the system configuration +provides more than just the discovery configuration. + +In addition to defining where cloud-init can find runtime configurations, the +system configuration also controls many of cloud-init's default behaviors. +Most users shouldn't need to modify these defaults, however it is worth noting +that downstream distributions often use them to set reasonable default +behaviors for cloud-init. This includes things such as which distro to behave +as and which networking backend to use. + +The default values in :file:`/etc/cloud/cloud.cfg` may be overriden by drop-in +files which are stored in :file:`/etc/cloud/cloud.cfg.d`. + +Configuration sources +===================== -Alternatively, this URI may be defined in a configuration in a file -:file:`/etc/cloud/cloud.cfg.d/*.cfg` like this: :: +User-data, metadata, network config, and vendor data may be sourced from one +of several possible locations, either locally or remotely. + +Source 1: Local filesystem +-------------------------- + +System configuration may provide cloud-init runtime configuration directly + +.. code-block:: yaml + + datasource: + NoCloud: + meta-data: | + instance-id: l-eadfbe + user-data: | + #cloud-config + runcmd: [ echo "it worked!" > /tmp/example.txt ] + +Local filesystem: custom location +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Cloud-init makes it possible to find system configuration in a custom +filesystem path for those that require more flexibility. This may be +done with a line configuration: :: + + + ds=nocloud;s=file://path/to/directory/ + +Or a system configuration: + +.. code-block:: yaml + + datasource: + NoCloud: + seedfrom: file://path/to/directory + +Source 2: Drive with labeled filesystem +--------------------------------------- + +A labeled `vfat`_ or `iso9660` filesystem may be used. The filesystem volume +must be labelled ``CIDATA``. The :ref:`configuration files` must +be in the root directory of the filesystem. + +Source 3: Custom webserver +-------------------------- + +Configuration files can be provided to cloud-init over HTTP(S) using a +line configuration: :: + + ds=nocloud;s=https://10.42.42.42/cloud-init/configs/ + +or using system configuration: + +.. code-block:: yaml datasource: NoCloud: seedfrom: https://10.42.42.42/cloud-init/configs/ -Method 3: FTP Server +Source 4: FTP Server -------------------- Configuration files can be provided to cloud-init over unsecured FTP -or alternatively with FTP over TLS. To tell cloud-init the URL to use, -arguments must be passed to the instance via the kernel command line or SMBIOS -serial number. This argument might look like: :: +or alternatively with FTP over TLS using a line configuration :: ds=nocloud;s=ftps://10.42.42.42/cloud-init/configs/ -Alternatively, this URI may be defined in a configuration in a file -:file:`/etc/cloud/cloud.cfg.d/*.cfg` like this: :: +or using system configuration + +.. code-block:: yaml datasource: NoCloud: seedfrom: ftps://10.42.42.42/cloud-init/configs/ -Method 4: Local filesystem --------------------------- +.. _source_files: -Configuration files can be provided on the local filesystem at specific -filesystem paths using kernel command line arguments or SMBIOS serial number to -tell cloud-init where on the filesystem to look. +Source files +------------ -.. note:: - Unless arbitrary filesystem paths are required, one might prefer to use - :ref:`DataSourceNone`, since it does not require - modifying the kernel command line or SMBIOS. +The base path pointed to by the URI in the above sources provides content +using the following final path components: -This argument might look like: :: +* ``user-data`` +* ``meta-data`` +* ``vendor-data`` +* ``network-config`` - ds=nocloud;s=file://path/to/directory/ +For example, if the ``seedfrom`` value of ``seedfrom`` is +``https://10.42.42.42/``, then the following files will be fetched from the +webserver at first boot: -Alternatively, this URI may be defined in a configuration in a file -:file:`/etc/cloud/cloud.cfg.d/*.cfg` like this: :: +.. code-block:: sh - datasource: - NoCloud: - seedfrom: file://10.42.42.42/cloud-init/configs/ + https://10.42.42.42/user-data + https://10.42.42.42/vendor-data + https://10.42.42.42/meta-data + https://10.42.42.42/network-config + +If the required files don't exist, this datasource will be skipped. + +.. _line_config_detail: +Line configuration in detail +============================ -Permitted keys -============== +The line configuration has several options. -Currently three keys (and their aliases) are permitted for configuring -cloud-init. +Permitted keys (DMI and kernel command line) +-------------------------------------------- -The only required key is: +Currently three keys (and their aliases) are permitted in cloud-init's kernel +command line and DMI (sometimes called SMBIOS) serial number. -* ``seedfrom`` alias: ``s`` +There is only one required key in a line configuration: + +* ``seedfrom`` (alternatively ``s``) A valid ``seedfrom`` value consists of a URI which must contain a trailing ``/``. @@ -104,15 +246,11 @@ A valid ``seedfrom`` value consists of a URI which must contain a trailing Some optional keys may be used, but their use is discouraged and may be removed in the future. -* ``local-hostname`` alias: ``h`` (:ref:`cloud-config` - preferred) -* ``instance-id`` alias: ``i`` (set instance id in :file:`meta-data` instead) -.. note:: +* ``local-hostname`` (alternatively ``h``) +* ``instance-id`` (alternatively ``i``) - The aliases ``s`` , ``h`` and ``i`` are only supported by kernel - command line or SMBIOS. When configured in a ``*.cfg`` file, the long key - name is required. +Both of these can be set in :file:`meta-data` instead. Seedfrom: HTTP and HTTPS ------------------------ @@ -138,26 +276,37 @@ Where ``scheme`` can be ``ftp`` or ``ftps``, ``userinfo`` will be ``host`` can be an IP address or DNS name, and ``port`` is which network port to use (default is ``21``). -Seedfrom: Files ---------------- +Discovery configuration considerations +====================================== + +Above, we describe the two methods of providing discovery configuration (system +configuration and line configuration). Two methods exist because there are +advantages and disadvantages to each option, neither is clearly a better +choice - so it is left to the user to decide. + +Line configuration +------------------ + +**Advantages** -The path pointed to by the URI can contain the following -files: +* it may be possible to set kernel command line and DMI variables at boot time + without modifying the base image -``user-data`` (required) -``meta-data`` (required) -``vendor-data`` (optional) -``network-config`` (optional) +**Disadvantages** -If the seedfrom URI doesn't contain the required files, this datasource -will be skipped. +* requires control and modification of the hypervisor or the bootloader +* DMI / SMBIOS is architecture specific -The ``user-data`` file uses :ref:`user data format`. The -``meta-data`` file is a YAML-formatted file. +System configuration +-------------------- + +**Advantages** + +* simple: requires only modifying a file -The ``vendor-data`` file adheres to -:ref:`user data formats`. The ``network-config`` file -follows cloud-init's :ref:`Network Configuration Formats`. +**Disadvantages** + +* requires modifying the filesystem prior to booting an instance DMI-specific kernel command line ================================ @@ -189,7 +338,7 @@ wanted. - ``dmi.system-uuid`` - ``dmi.system-version`` -For example, you can pass this option to QEMU: :: +For example, you can pass this line configuration to QEMU: :: -smbios type=1,serial=ds=nocloud;s=http://10.10.0.1:8000/__dmi.chassis-serial-number__/ @@ -268,14 +417,10 @@ sufficient disk by following the following example. user data you will also have to change the ``instance-id``, or start the disk fresh. -Also, you can inject an :file:`/etc/network/interfaces` file by providing the -content for that file in the ``network-interfaces`` field of -:file:`meta-data`. - Example ``meta-data`` --------------------- -:: +.. code-block:: yaml instance-id: iid-abcdefg network-interfaces: | @@ -288,17 +433,14 @@ Example ``meta-data`` hostname: myhost +``network-config`` +------------------ + Network configuration can also be provided to ``cloud-init`` in either :ref:`network_config_v1` or :ref:`network_config_v2` by providing that -YAML formatted data in a file named :file:`network-config`. If found, -this file will override a :file:`network-interfaces` file. +YAML formatted data in a file named :file:`network-config`. -See an example below. Note specifically that this file does not -have a top level ``network`` key as it is already assumed to -be network configuration based on the filename. - -Example config --------------- +Example network v1: .. code-block:: yaml @@ -314,6 +456,8 @@ Example config gateway: 192.168.1.254 +Example network v2: + .. code-block:: yaml version: 2