diff options
| -rw-r--r-- | docs/automation/cloud-init.rst | 72 |
1 files changed, 43 insertions, 29 deletions
diff --git a/docs/automation/cloud-init.rst b/docs/automation/cloud-init.rst index 7b2d53fb..2be66f7f 100644 --- a/docs/automation/cloud-init.rst +++ b/docs/automation/cloud-init.rst @@ -1,15 +1,15 @@ -:lastproofread: 2021-06-27 +:lastproofread: 2021-07-12 -. _cloud-init: +.. _cloud-init: ############### 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 |