diff options
| -rw-r--r-- | docs/automation/cloud-init.rst | 64 | ||||
| -rw-r--r-- | docs/automation/index.rst | 3 |
2 files changed, 66 insertions, 1 deletions
diff --git a/docs/automation/cloud-init.rst b/docs/automation/cloud-init.rst new file mode 100644 index 00000000..f59c1a7b --- /dev/null +++ b/docs/automation/cloud-init.rst @@ -0,0 +1,64 @@ +.. _cloud-init: + +############### +VyOS cloud-init +############### + +Cloud instances of VyOS are initialized using the industry-standard cloud-init. +Via cloud-init, users can execute shell commands and configure the router. + +The initialization is guided by a set of instructions--known as user +data--provided by the user at launch time. VyOS implements a user-data +format called cloud-config. + +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. + + +************************ +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 +the "set-style" syntax. + +Commands requirements: + +* one command per line +* 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 +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. + +Here is an example cloud-config. + +.. code-block:: yaml + + #cloud-config + vyos_config_commands: + - set system host-name 'vyos-prod-ashburn' + - set system ntp server 1.pool.ntp.org + - set system ntp server 2.pool.ntp.org + +*************** +Troubleshooting +*************** + +If you encounter problems, verify that the cloud-config document contains +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. + diff --git a/docs/automation/index.rst b/docs/automation/index.rst index 935748d0..044505b9 100644 --- a/docs/automation/index.rst +++ b/docs/automation/index.rst @@ -12,4 +12,5 @@ VyOS Automation vyos-api vyos-ansible - command-scripting
\ No newline at end of file + command-scripting + cloud-init |