diff options
author | Robert Göhler <github@ghlr.de> | 2021-04-12 21:09:24 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-04-12 21:09:24 +0200 |
commit | 8286245984632d941da0496107e417e7db7c9760 (patch) | |
tree | ca5f62a9654a20fe48f73147d8c33e002dbba2be /docs/automation/cloud-init.rst | |
parent | fef30ef32cb00c65a4e773d525a8ff8bf56344db (diff) | |
parent | 9d2f16ab7309779065f123579542beae9d1247e6 (diff) | |
download | vyos-documentation-8286245984632d941da0496107e417e7db7c9760.tar.gz vyos-documentation-8286245984632d941da0496107e417e7db7c9760.zip |
Merge pull request #502 from jeffbrl/cloud-init
Add initial cloud-init documentation
Diffstat (limited to 'docs/automation/cloud-init.rst')
-rw-r--r-- | docs/automation/cloud-init.rst | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/docs/automation/cloud-init.rst b/docs/automation/cloud-init.rst new file mode 100644 index 00000000..be585321 --- /dev/null +++ b/docs/automation/cloud-init.rst @@ -0,0 +1,102 @@ +.. _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. + +************** +Config Sources +************** + +VyOS support three type of config sources. + +.. stop_vyoslinter + +* 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 - Ths config source informs the system about the network. + +* User-data - User-data is specified by the user. This config source offers the most flexibility and will be the focus of this documentation. + +.. start_vyoslinter + + +********* +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. + +VyOS implements a user-data format called cloud-config. + + +************************ +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. Both "set" and "delete" commands are supported. + +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 + - 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' + +************************* +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 +* DHCP on first Ethernet interface if no network configuration is provided + + +All of these can be overridden using configuration in user-data. + + +*************** +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. + |