diff options
Diffstat (limited to 'docs/automation/cloud-init.md')
| -rw-r--r-- | docs/automation/cloud-init.md | 380 |
1 files changed, 380 insertions, 0 deletions
diff --git a/docs/automation/cloud-init.md b/docs/automation/cloud-init.md new file mode 100644 index 00000000..01ad360d --- /dev/null +++ b/docs/automation/cloud-init.md @@ -0,0 +1,380 @@ +--- +lastproofread: '2026-04-13' +--- + +(cloud-init)= + +# VyOS cloud-init + +VyOS instances in cloud and virtualized environments are initialized using the +industry-standard `cloud-init`. Through `cloud-init`, VyOS injects SSH +keys, configures network settings, and applies custom configurations during the +initial instance boot. + +## Configuration sources + +VyOS `cloud-init` obtains configuration data from the following sources: + +- `meta-data`: Instance-specific details provided by the cloud platform or + hypervisor. In some cloud environments, this data is available via an HTTP + endpoint at `http://169.254.169.254`. +- `network configuration`: Network settings such as IP addresses, routes, and + DNS (only available on certain cloud and virtualization platforms). +- `user-data`: User-supplied CLI configuration commands. + +## User-data + +Major cloud providers support injecting `user-data` as plain text or base64 +encoding text during initial instance boot. As `user-data` has a strict size +limit of \~16384 bytes, long configuration command lists can be compressed using +`gzip`. + +The recommended method for configuring VyOS instances via `user-data` is to +use the `cloud-config` syntax described below. + +## Cloud-config modules + +By default, VyOS enables only two `cloud-config` modules: + +- `write_files`: Inserts user-provided files such as encryption keys, + certificates, or `config.boot` into the filesystem during the initial + instance boot. See [Cloud-init-write_files] for file syntax and file format + requirements. +- `vyos_userdata`: Executes user-provided CLI configuration commands during + the initial instance boot. + +The files to insert and the CLI commands to execute must be provided in a +`cloud-config` YAML file. + +## Cloud-config file format + +`cloud-config` files are written in YAML and must begin with the +`#cloud-config` line. Only `vyos_config_commands` and `write_files` are +supported as top-level keys. The use of these keys is described in the +following two sections. + +## Vyos_config_commands key + +Use the `vyos_config_commands` key to define configuration commands for +initializing your VyOS instance. Commands must follow the set-style syntax +and can include both `set` and `delete` statements. + +Syntax requirements: + +- Place one command per line. +- Enclose values in single quotes. +- Avoid single quotes within commands or values. + +Applying commands from `cloud-config` overrides both settings configured via +`meta-data` and default VyOS settings. After commands are applied, +`cloud-init` automatically performs `commit` and `save`. + +The following is an example of a `cloud-config` file: + +```yaml +#cloud-config +vyos_config_commands: + - set system host-name 'vyos-prod-ashburn' + - set service ntp server 1.pool.ntp.org + - set service ntp server 2.pool.ntp.org + - delete interfaces ethernet eth1 address 'dhcp' + - 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' +``` + + +### Instance defaults/fallbacks + +If no external configuration data is provided, VyOS applies the following +defaults: + +- **SSH:** port 22. +- **Credentials:** `vyos`/`vyos`. +- **Networking:** DHCP is enabled on the first Ethernet interface. + +All defaults can be overridden via `user-data` configurations. + +## Write_files key + +VyOS allows you to run custom scripts during the initial instance boot to +execute operational, configuration, and standard Linux commands. + +Use the `write_files` key to insert these scripts into the +`/opt/vyatta/etc/config/scripts/` directory. + +Depending on when your commands need to run, use one of the following paths: + +- `/opt/vyatta/etc/config/scripts/vyos-preconfig-bootup.script`: Commands + defined here are executed before the system configuration is applied. +- `/opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script`: Commands + defined here are executed after the system configuration is applied. + +In both cases, commands are executed with `root` privileges. + +:::{note} +Use the `/opt/vyatta/etc/config/` path instead of `/config/scripts/` as +referenced in the {ref}`command-scripting` section. The `/config/scripts/` +directory is not mounted when the `write_files` module runs. +::: + +The following example shows how to use `write_files` to execute an +operational command **after** the initial configuration is complete: + +```yaml +#cloud-config +write_files: + - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script + owner: root:vyattacfg + permissions: '0775' + content: | + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + filename=/tmp/bgp_status_`date +"%Y_%m_%d_%I_%M_%p"`.log + run show ip bgp summary >> $filename +``` + +You can combine standard Linux commands to fetch data and VyOS configuration +commands (like `set` and `commit`) in the same script. + +The following example sets the `hostname` based on the instance identifier +obtained from the EC2 Instance Metadata Service (IMDS). + +```yaml +#cloud-config +write_files: + - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script + owner: root:vyattacfg + permissions: '0775' + content: | + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + hostname=`curl -s http://169.254.169.254/latest/meta-data/instance-id` + configure + set system host-name $hostname + commit + exit +``` + + +## NoCloud + +Injecting configuration data is not limited to cloud platforms. The NoCloud +data source allows you to inject `user-data` and `meta-data` on +virtualization platforms such as VMware, Hyper-V, and KVM. + +The simplest way to use the NoCloud data source is to create a `seed.iso` +file and attach it to the virtual machine as a CD drive. The volume must be +formatted as a VFAT or ISO 9660 file system with the label `cidata` or +`CIDATA`. + +Create text files named `user-data` and `meta-data`. On Linux-based +systems, use the `mkisofs` utility to create the `seed.iso` file. The +following syntax adds these files to the ISO 9660 file system: + +```none +mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data user-data +``` + +Once generated, attach the `seed.iso` file to your virtual machine. The +following example shows how to attach the file as a CD drive using KVM: + +```none +$ virt-install -n vyos_r1 \ + --ram 4096 \ + --vcpus 2 \ + --cdrom seed.iso \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ + --import \ + --noautoconsole +``` + +For more information on the NoCloud data source, visit the [NoCloud] page in +the `cloud-init` documentation. + +## Troubleshooting + +If your configuration does not apply as expected, follow these troubleshooting +steps: + +1. **Validate your YAML**: Ensure your `cloud-config` file follows proper + YAML syntax. Online resources such as [YAML Lint](https://www.yamllint.com/) + provide simple validation tools. +2. **Check the logs**: `cloud-init` writes logs to `/var/log/cloud-init.log`. + Filter for VyOS-specific entries using: + +```none +sudo grep vyos /var/log/cloud-init.log +``` + + +## Cloud-init on Proxmox + +Before you begin, review the `cloud-init` [network-config-docs] to +understand how to import user and network configuration data. + +Key considerations: + +- Define VyOS configuration commands in the `user-data` file. +- Avoid including network configuration data in the `user-data` file. +- If no network configuration data is provided, the DHCP client is enabled on + the first interface. This happens at the OS level and is not reflected in the + VyOS CLI. + +The following example shows how to disable the DHCP client on `eth0` to +address this behavior. + +In this example: + +- **Proxmox IP address**: `192.168.0.253/24`. +- **Storage**: The `local` volume is mounted at `/var/lib/vz` and contains + all content types, including snippets. + +The goal is to remove the default DHCP client from the first interface and +apply a custom configuration during the initial instance boot using +`cloud-init`. + +### Generate .qcow2 image + +First, generate a VyOS `.qcow2` image with `cloud-init` support from the +[vyos-vm-images] repository: + +1. Clone the `vyos-vm-images` repository and comment out the `download-iso` + role in `qemu.yml`. +2. Download your preferred VyOS `.iso` file and save it as `/tmp/vyos.iso`. +3. Generate the `.qcow2` image (using a 10G disk size for this example): + +```sh +sudo ansible-playbook qemu.yml -e disk_size=10 \ + -e iso_local=/tmp/vyos.iso -e grub_console=serial -e vyos_version=1.5.0 \ + -e cloud_init=true -e cloud_init_ds=NoCloud +``` + +This generates your new image at `/tmp/vyos-1.5.0-cloud-init-10G-qemu.qcow2`. + +4. Copy the resulting image to the Proxmox server: + +```sh +sudo scp /tmp/vyos-1.5.0-cloud-init-10G-qemu.qcow2 root@192.168.0.253:/tmp/ +``` + + +### Prepare cloud-init files + +Create the following files on your Proxmox server to proceed with this setup: + +- `user-data`: Contains VyOS configuration commands. +- `network-config`: Disables the DHCP client on the first interface. +- `meta-data`: An empty file (required by `cloud-init`). + +All files must be placed in the `/tmp/` directory. + +Follow these steps to create the required files: + +1. Navigate to the `/tmp/` directory: + + ```sh + cd /tmp/ + ``` + +2. Create the `user-data` file. Begin the file with `#cloud-config` and + include VyOS configuration commands. + + ```none + #cloud-config + vyos_config_commands: + - set system host-name 'vyos-BRAS' + - set service ntp server '1.pool.ntp.org' + - set service ntp server '2.pool.ntp.org' + - delete interfaces ethernet eth0 address 'dhcp' + - set interfaces ethernet eth0 address '198.51.100.2/30' + - set interfaces ethernet eth0 description 'WAN - ISP01' + - set interfaces ethernet eth1 address '192.168.25.1/24' + - set interfaces ethernet eth1 description 'Coming through VLAN 25' + - set interfaces ethernet eth2 address '192.168.26.1/24' + - set interfaces ethernet eth2 description 'Coming through VLAN 26' + - set protocols static route 0.0.0.0/0 next-hop '198.51.100.1' + ``` + +3. Create the `network-config` file. Include the following: + + ```none + version: 2 + ethernets: + eth0: + dhcp4: false + dhcp6: false + ``` + +4. Create the required empty `meta-data` file. + +### Create seed.iso + +Once you have created the necessary files, generate the `seed.iso` image and +mount it as a CD drive to the new VM. + +```sh +mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data \ +user-data network-config +``` + +:::{note} +Be careful while copying and pasting the above commands. Double quotes may need +to be corrected. +::: + +### Create the VM + +Note that the following settings apply to this particular example and may +require adjustment for other setups: + +- **VM ID**: `555`. +- **VM and .iso file storage**: The local volume (`directory` type, + mounted at `/var/lib/vz`). +- **VM resources**: Can be modified as needed. + +The `seed.iso` file was previously created in the `/tmp/` directory. Move +it to `/var/lib/vz/template/iso`: + +```sh +mv /tmp/seed.iso /var/lib/vz/template/iso/ +``` + +On the Proxmox server: + +```none +## Create VM, import disk and define boot order +qm create 555 --name vyos-1.5.0-cloudinit --memory 1024 --net0 virtio,bridge=vmbr0 +qm importdisk 555 vyos-1.5.0-cloud-init-10G-qemu.qcow2 local +qm set 555 --virtio0 local:555/vm-555-disk-0.raw +qm set 555 --boot order=virtio0 + +## Import seed.iso for cloud init +qm set 555 --ide2 media=cdrom,file=local:iso/seed.iso + +## Since this server has 1 nic, lets add network intefaces (vlan 25 and 26) +qm set 555 --net1 virtio,bridge=vmbr0,firewall=1,tag=25 +qm set 555 --net2 virtio,bridge=vmbr0,firewall=1,tag=26 +``` + + +### Power on and verify the VM + +Power on the VM using the CLI or GUI. After it boots, verify the configuration. + +### References + +- Cloud-init [network-config-docs]. +- Proxmox [Cloud-init-Support]. + +[cloud-init-docs]: https://docs.vyos.io/en/equuleus/automation/cloud-init.html?highlight=cloud-init#vyos-cloud-init +[cloud-init-support]: <https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_cloud_init> +[cloud-init-write_files]: https://cloudinit.readthedocs.io/en/latest/topics/examples.html#writing-out-arbitrary-files +[network-config-docs]: https://cloudinit.readthedocs.io/en/latest/topics/network-config.html +[nocloud]: https://cloudinit.readthedocs.io/en/latest/reference/datasources/nocloud.html +[vyos-vm-images]: https://github.com/vyos/vyos-vm-images |