feat: flip swap mechanism — MD as primary, RST as override (Phase 1)

This is the first of three phases inverting the per-page swap mechanism
so MD becomes the canonical primary and RST becomes the rare override.

Phase 1 — file renames + conf.py exclude_patterns flip only:
- Rename docs/**/md-<stem>.md to docs/**/<stem>.md (drop md- prefix)
  for all 254 stems previously listed in docs/_swap.txt
- Rename docs/**/<stem>.rst to docs/**/rst-<stem>.rst (add rst- prefix)
  for the same 254 stems
- Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty
  comment-only since no pages need the RST fallback right now
- conf.py exclude_patterns flipped: rst-*.rst is now excluded by default
  instead of md-*.md
- conf.py runtime-artifact references updated to _rst_override_state.json
  and _md_exclude.txt (Phase 2 will rewrite swap_sources.py to produce
  these names; for now no swap script runs because overrides list is empty)

Phase 2 (next commit on this branch) will rewrite scripts/swap_sources.py
with inverted rename direction, delete scripts/import_myst.py + tests, and
update tests/test_swap_sources.py for the new semantics.

Phase 3 will be the cleanup pass and ready-for-review flip.

Generated by robots https://vyos.io

1 files changed, 378 insertions, 0 deletions

diff --git a/docs/automation/cloud-init.md b/docs/automation/cloud-init.md
new file mode 100644
index 00000000..b6350b54
--- /dev/null
+++ b/docs/automation/cloud-init.md
@@ -0,0 +1,378 @@
+---
+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-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