cloud-init: fixes and additions

Fixed syntax issues with the config file example and added
little more information.

1 files changed, 42 insertions, 28 deletions

diff --git a/docs/automation/cloud-init.rst b/docs/automation/cloud-init.rst
index 7b2d53fb..4ea24bd1 100644
--- a/docs/automation/cloud-init.rst
+++ b/docs/automation/cloud-init.rst
@@ -1,4 +1,4 @@
-:lastproofread: 2021-06-27
+:lastproofread: 2021-07-12
 
 . _cloud-init:
 
@@ -6,10 +6,10 @@
 VyOS cloud-init
 ###############
 
-Cloud instances of VyOS are initialized using the industry-standard
-cloud-init. Via cloud-init, the system performs tasks such as injecting
-SSH keys and configuring the network. In addition, the user can supply a custom
-configuration at the time of instance launch.
+Cloud and virtualized instances of VyOS are initialized using the
+industry-standard cloud-init. Via cloud-init, the system performs tasks such as
+injecting SSH keys and configuring the network. In addition, the user can supply
+a custom configuration at the time of instance launch.
 
 **************
 Config Sources
@@ -20,34 +20,46 @@ VyOS support three types of config sources.
 * Metadata - Metadata is sourced by the cloud platform or hypervisor.
   In some clouds, there is implemented as an HTTP endpoint at
   http://169.254.169.254.
-
 * Network configuration - This config source informs the system about the
-  network.
-
+  network settings like IP addresses, routes, DNS. Available only in several
+  cloud and virtualization platforms.
 * User-data - User-data is specified by the user. This config source offers the
-  most flexibility and will be the focus of this documentation.
-
+  ability to insert any CLI configuration commands into the configuration before
+  the first boot.
 
 *********
 User-data
 *********
 
-Major cloud providers offer a means of providing user-data at the time
-of instance launch. Typically the user includes user-data as plain
-text and the cloud provider's platform base64 encodes the user-data
-before injecting it into the instance. 
+Major cloud providers offer a means of providing user-data at the time of
+instance launch. It can be provided as plain text or as base64-encoded text,
+depending on cloud provider. Also, it can be compressed using gzip, which makes
+sense with a long configuration commands list, because of the hard limit to
+~16384 bytes for the whole user-data.
 
-VyOS implements a user-data format called cloud-config.
+The easiest way to configure the system via user-data is the Cloud-config syntax
+described below.
 
+********************
+Cloud-config modules
+********************
+
+In VyOS, by default, enabled only two modules:
+
+* ``write_files`` - this module allows to insert any files into the filesystem
+  before the first boot, for example, pre-generated encryption keys,
+  certificates, or even a whole ``config.boot`` file.
+* ``vyos_userdata`` - the module accepts a list of CLI configuration commands in
+  a ``vyos_config_commands`` section, which gives an easy way to configure the
+  system during deployment.
 
 ************************
 cloud-config file format
 ************************
 
-
 A cloud-config document is written in YAML. The file must begin
-with "#cloud-config". The key used to designate a VyOS configuration
-is "vyos_config_commands". What follows is VyOS configuration using
+with ``#cloud-config`` line. The key used to designate a VyOS configuration
+is ``vyos_config_commands``. What follows is VyOS configuration using
 the "set-style" syntax. Both "set" and "delete" commands are supported.
 
 Commands requirements:
@@ -56,13 +68,12 @@ Commands requirements:
 * if command ends in a value, it must be inside single quotes
 * a single-quote symbol is not allowed inside command or value
 
-
-The commands list produced by the `show configuration commands` command on a
+The commands list produced by the ``show configuration commands`` command on a
 VyOS router should comply with all the requirements, so it is easy to get a 
 proper commands list by copying it from another router.
 
-The configuration specified in the cloud-config document is merged with
-the default configuration and saved to /config/config.boot.
+The configuration specified in the cloud-config document overwrites default
+configuration values and values configured via Metadata.
 
 Here is an example cloud-config.
 
@@ -74,8 +85,8 @@ Here is an example cloud-config.
      - set system ntp server 1.pool.ntp.org
      - set system ntp server 2.pool.ntp.org
      - delete interfaces ethernet eth1 address 'dhcp'
-     - set interfaces ethernet eth1 address '172.31.7.247/20'
-     - set protocols static route '172.31.0.0/16' next-hop '100.64.16.1'
+     - set interfaces ethernet eth1 address '192.0.2.247/24'
+     - set protocols static route 198.51.100.0/24 next-hop '192.0.2.1'
 
 *************************
 System Defaults/Fallbacks
@@ -84,13 +95,11 @@ System Defaults/Fallbacks
 These are the VyOS defaults and fallbacks.
 
 * SSH is configured on port 22
-* vyos/vyos credentials if no others specified by data source
+* ``vyos``/``vyos`` credentials if no others specified by data source
 * DHCP on first Ethernet interface if no network configuration is provided
 
-
 All of these can be overridden using the configuration in user-data.
 
-
 ***************
 Troubleshooting
 ***************
@@ -100,5 +109,10 @@ valid YAML. Online resources such as https://yamlvalidator.com/ provide
 a simple tool for validating YAML.
 
 cloud-init logs to /var/log/cloud-init.log. This file can be helpful in
-determining why the configuration varies from what you expect.
+determining why the configuration varies from what you expect. You can fetch the
+most important data filtering output for ``vyos`` keyword:
+
+.. code-block:: none
+
+    sudo grep vyos /var/log/cloud-init.log