summaryrefslogtreecommitdiff
path: root/docs/automation
diff options
context:
space:
mode:
authorYuriy Andamasov <yuriy@vyos.io>2026-05-06 14:41:08 +0300
committerGitHub <noreply@github.com>2026-05-06 12:41:08 +0100
commit22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e (patch)
tree8d97f7766d9bbd2d0e3a55e5643a60b387308675 /docs/automation
parentc21b38dbe24088eaca73dbc8030cfebc898d2186 (diff)
downloadvyos-documentation-22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e.tar.gz
vyos-documentation-22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e.zip
Add incremental RST-to-MyST swap mechanism (sagitta) (#1868)
* feat(swap-sagitta): add incremental RST-to-MyST swap mechanism Backport of the swap mechanism from feat/incremental-myst-swap onto the sagitta release branch. Built directly on top of origin/sagitta, so the underlying RST tree is sagitta's (not current's). Mechanism: - scripts/import_myst.py — import md from myst/* with md- prefix - scripts/swap_sources.py — rename md-{name}.md → {name}.md before Sphinx builds, restore after; writes _build/_swap_state.json and _build/_swap_exclude.txt - docs/Makefile — html/dirhtml/pdf/livehtml all run swap → build → trap restore; explicit `swap` and `restore` targets too - docs/conf.py — MyST extensions enabled; swap exclude_patterns loader; _prefer_webp builder hook so html prefers webp over png Content: - 202 md-prefixed pages from origin/myst/sagitta (md-{name}.md alongside each {name}.rst counterpart) - 1 plain MyST-only page from myst/sagitta where no .rst exists (already at canonical name on sagitta: docs/copyright.md) - 240 .webp images from myst/sagitta (added alongside the existing PNG/JPG so RST builds keep their assets) - docs/_swap.txt populated with all 202 stems → MyST is served by default, revert a page by removing its stem from _swap.txt 🤖 Generated by [robots](https://vyos.io) * feat(conf): copy .md sources into HTML output for plain-text serving Adds a build-finished hook that mirrors every .md file from the Sphinx source tree into the HTML output directory verbatim, making unrendered MyST sources accessible alongside HTML renders at the same URL path. 🤖 Generated by [robots](https://vyos.io) * docs: address review feedback (backport from PR #1857) Fix conversion artifacts, typos, and technical inaccuracies applicable to the sagitta branch: curly quotes, typos (deamonless, cammans, amdifferent, trough), incorrect firewall command paths, missing closing brace in zone-policy, peer name inconsistencies, hardcoded passwords replaced with vault references, and md-*.md exclusion in conf.py. 🤖 Generated by [robots](https://vyos.io) * docs: port .readthedocs.yml jobs, _ext/vyos.py fallback and swap-script tests from PR #1857 Parity backport from PR #1857 (current) — three pieces were missing on sagitta. - .readthedocs.yml: add build.jobs.pre_build / post_build hooks that run scripts/swap_sources.py --swap before the Sphinx build and --restore after. Without this, the swap mechanism ships but never runs on RTD builds for this branch — the swap is a silent no-op. - docs/_ext/vyos.py: CmdInclude.run() now falls back to nested_parse() when self.state._renderer is not present. Required for cfgcmd / opcmd / cmdincludemd directives to render correctly when included from MyST pages (the swap mechanism's whole point). Sagitta-only delta on _ext/vyos.py (the path = str(path) line on 224) is intentionally untouched. - tests/test_import_myst.py, tests/test_swap_sources.py: tests for the swap scripts. The scripts on this branch are byte-identical to current's, so the same tests apply. Travels with the branch so CI catches per-branch regressions if the scripts ever drift. 🤖 Generated by [robots](https://vyos.io) * fix(conf): skip md-*.md staging files in _copy_md_sources Agent-Logs-Url: https://github.com/vyos/vyos-documentation/sessions/919695a7-688d-41b9-89f0-540684625dbc Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>
Diffstat (limited to 'docs/automation')
-rw-r--r--docs/automation/md-cloud-init.md376
-rw-r--r--docs/automation/md-command-scripting.md219
-rw-r--r--docs/automation/md-index.md14
-rw-r--r--docs/automation/md-vyos-ansible.md86
-rw-r--r--docs/automation/md-vyos-api.md380
-rw-r--r--docs/automation/md-vyos-napalm.md137
-rw-r--r--docs/automation/md-vyos-netmiko.md67
-rw-r--r--docs/automation/md-vyos-salt.md204
-rw-r--r--docs/automation/terraform/md-index.md11
-rw-r--r--docs/automation/terraform/md-terraformAWS.md493
-rw-r--r--docs/automation/terraform/md-terraformAZ.md466
-rw-r--r--docs/automation/terraform/md-terraformGoogle.md1
-rw-r--r--docs/automation/terraform/md-terraformvSphere.md372
-rw-r--r--docs/automation/terraform/md-terraformvyos.md31
14 files changed, 2857 insertions, 0 deletions
diff --git a/docs/automation/md-cloud-init.md b/docs/automation/md-cloud-init.md
new file mode 100644
index 00000000..446d0f64
--- /dev/null
+++ b/docs/automation/md-cloud-init.md
@@ -0,0 +1,376 @@
+lastproofread
+2021-07-12
+
+# VyOS cloud-init
+
+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
+
+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 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
+ 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. 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.
+
+The easiest way to configure the system via user-data is the Cloud-config syntax
+described below.
+
+## Cloud-config modules
+
+In VyOS, by default, enables 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. The format is described in the cloudinit documentation [Cloud-init-write_files](https://cloudinit.readthedocs.io/en/latest/topics/examples.html#writing-out-arbitrary-files).
+- `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` line. The only supported top-level keys are
+`vyos_config_commands` and `write_files`. The use of these keys is described
+in the following two sections.
+
+## Initial Configuration
+
+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 overwrites default
+configuration values and values configured via Metadata.
+
+Here is an example cloud-config that appends configuration at the time of
+first boot.
+
+``` 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'
+```
+
+### 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 the configuration in user-data.
+
+## Command Execution at Initial Boot
+
+VyOS supports the execution of operational commands and linux commands at
+initial boot. This is accomplished using `write_files` to certain
+files in the /opt/vyatta/etc/config/scripts directory. Commands specified
+in opt/vyatta/etc/config/scripts/vyos-preconfig-bootup.script are executed
+prior to configuration. The
+/opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script file contains
+commands to be executed after configuration. In both cases, commands are
+executed as the root user.
+
+Note that the /opt/vyatta/etc/config is used instead of the /config/scripts
+directory referenced in the `command-scripting` section of the
+documentation because the /config/script directory isn't mounted when the
+`write_files` module executes.
+
+The following example shows how to execute commands after the initial
+configuration.
+
+``` 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
+```
+
+If you need to gather information from linux commands to configure VyOS, you
+can execute commands and then configure VyOS in the same script.
+
+The following example sets the hostname based on the instance identifier
+obtained from the EC2 metadata service.
+
+Please observe that the same configuration pitfall described in `command-scripting`
+exists here when running `configure` in any context as without user group
+'vyattacfg' will cause the error message `Set failed` to appear.
+We therefore need to wrap it and have the script re-execute itself with the correct
+group permissions.
+
+``` yaml
+#cloud-config
+write_files:
+ - path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script
+ owner: root:vyattacfg
+ permissions: '0775'
+ content: |
+ #!/bin/vbash
+ if [ "$(id -g -n)" != 'vyattacfg' ] ; then
+ exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@"
+ fi
+ 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. Users can
+employ the NoCloud data source to inject user-data and meta-data on
+virtualization platforms such as VMware, Hyper-V and KVM.
+
+While other methods exist, the most straightforward method for using the
+NoCloud data source is creating a seed ISO and attaching 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,
+the mkisofs utility can be used to create the seed ISO. The following
+syntax will add these files to the ISO 9660 file system.
+
+``` none
+mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data user-data
+```
+
+The seed.iso file can be attached to the virtual machine. As an example,
+the method with KVM to attach the ISO as a CD drive follows.
+
+``` 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 its [page](https://cloudinit.readthedocs.io/en/latest/reference/datasources/nocloud.html)
+in the cloud-init documentation.
+
+## Troubleshooting
+
+If you encounter problems, verify that the cloud-config document contains
+valid YAML. Online resources such as <https://www.yamllint.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. You can fetch the
+most important data filtering output for `vyos` keyword:
+
+``` none
+sudo grep vyos /var/log/cloud-init.log
+```
+
+## Cloud-init on Proxmox
+
+Before starting, please refer to cloud-init [network-config-docs](https://cloudinit.readthedocs.io/en/latest/topics/network-config.html) in order to
+know how to import user and network configurations.
+
+Most important keys that needs to be considered:
+
+- VyOS configuration commands are defined in user-data file.
+
+- Networking configurations shouldn't be passed in user-data file.
+
+- If no networking configuration is provided, then dhcp client is going to be
+ enabled on first interface. Bare in mind that this configuration will be
+ inyected at an OS level, so don't expect to find dhcp client configuration
+ on vyos cli. Because of this behavior, in next example lab we will disable
+ dhcp-client configuration on eth0.
+
+ Also, this lab considers:
+
+- Proxmox IP address: **192.168.0.253/24**
+
+- Storaged used: volume local, which is mounted on directory **/var/lib/vz**,
+ and contains all type of content, including snippets.
+
+- Remove default dhcp client on first interface, and load other
+ configuration during first boot, using cloud-init.
+
+### Generate qcow image
+
+A VyOS qcow image with cloud-init options is needed. This can be obtained
+using [vyos-vm-images](https://github.com/vyos/vyos-vm-images) repo. After cloning the repo, edit the file
+**qemu.yml** and comment the **download-iso** role.
+
+In this lab, we are using 1.3.0 VyOS version and setting a disk of 10G.
+Download VyOS .iso file and save it as `/tmp/vyos.iso`. Command used for
+generating qcow image:
+
+``` sh
+sudo ansible-playbook qemu.yml -e disk_size=10 \
+ -e iso_local=/tmp/vyos.iso -e grub_console=serial -e vyos_version=1.3.0 \
+ -e cloud_init=true -e cloud_init_ds=NoCloud
+```
+
+File generated with previous command:
+`/tmp/vyos-1.3.0-cloud-init-10G-qemu.qcow2`
+
+Now, that file needs to be copied to proxmox server:
+
+``` sh
+sudo scp /tmp/vyos-1.3.0-cloud-init-10G-qemu.qcow2 root@192.168.0.253:/tmp/
+```
+
+### Prepare cloud-init files
+
+In Proxmox server three files are going to be used for this setup:
+
+- **network-config**: file that will indicate to avoid dhcp client on first
+ interface.
+- **user-data**: includes vyos-commands.
+- **meta-data**: empty file (required).
+
+In this lab, all files are located in `/tmp/`. So, before going on, lets
+move to that directory:
+
+``` sh
+cd /tmp/
+```
+
+**user-data** file must start with `#cloud-config` and contains
+vyos-commands. For example:
+
+``` 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 'Comming through VLAN 25'
+ - set interfaces ethernet eth2 address '192.168.26.1/24'
+ - set interfaces ethernet eth2 description 'Comming through VLAN 26'
+ - set protocols static route 0.0.0.0/0 next-hop '198.51.100.1'
+```
+
+**network-config** file only has configuration that disables the automatic
+dhcp client on first interface.
+
+Content of network-config file:
+
+``` none
+version: 2
+ethernets:
+ eth0:
+ dhcp4: false
+ dhcp6: false
+```
+
+Finally, file **meta-data** has no content, but it's required.
+
+### Create seed.iso
+
+Once the three files were created, it's time to generate the `seed.iso`
+image, which needs to be mounted to the new VM as a cd.
+
+Command for generating `seed.iso`
+
+``` sh
+mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data \
+user-data network-config
+```
+
+**NOTE**: be careful while copying and pasting previous commands. Double
+quotes may need to be corrected.
+
+### Creating the VM
+
+Notes for this particular example, that may need to be modified in other
+setups:
+
+- VM ID: in this example, VM ID used is 555.
+- VM Storage: `local` volume is used.
+- ISO files storage: `local` volume is used for `.iso` file storage. In
+ this scenario `local` volume type is set to **directory**, abd attached to
+ `/var/lib/vz`.
+- VM Resources: these parameters can be modified as needed.
+
+`seed.iso` was previously created in directory `/tmp/`. It's necessary to
+move it to `/var/lib/vz/template/iso`
+
+``` sh
+mv /tmp/seed.iso /var/lib/vz/template/iso/
+```
+
+On proxmox server:
+
+``` none
+## Create VM, import disk and define boot order
+qm create 555 --name vyos-1.3.0-cloudinit --memory 1024 --net0 virtio,bridge=vmbr0
+qm importdisk 555 vyos-1.3.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 VM and verifications
+
+From cli or GUI, power on VM, and after it boots, verify configuration
+
+### References
+
+- VyOS [cloud-init-docs](https://docs.vyos.io/en/equuleus/automation/cloud-init.html?highlight=cloud-init#vyos-cloud-init).
+- Cloud-init [network-config-docs](https://cloudinit.readthedocs.io/en/latest/topics/network-config.html).
+- Proxmox [Cloud-init-Support](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_cloud_init).
diff --git a/docs/automation/md-command-scripting.md b/docs/automation/md-command-scripting.md
new file mode 100644
index 00000000..5c2d8f19
--- /dev/null
+++ b/docs/automation/md-command-scripting.md
@@ -0,0 +1,219 @@
+lastproofread
+2023-01-16
+
+# Command Scripting
+
+VyOS supports executing configuration and operational commands non-interactively
+from shell scripts.
+
+To include VyOS specific functions and aliases you need to `source /opt/vyatta/etc/functions/script-template` files at the top of your script.
+
+``` none
+#!/bin/vbash
+source /opt/vyatta/etc/functions/script-template
+exit
+```
+
+## Run configuration commands
+
+Configuration commands are executed just like from a normal config session. For
+example, if you want to disable a BGP peer on VRRP transition to backup:
+
+``` none
+#!/bin/vbash
+source /opt/vyatta/etc/functions/script-template
+configure
+set protocols bgp system-as 65536
+set protocols bgp neighbor 192.168.2.1 shutdown
+commit
+exit
+```
+
+## Run operational commands
+
+Unlike a normal configuration session, all operational commands must be
+prepended with `run`, even if you haven't created a session with configure.
+
+``` none
+#!/bin/vbash
+source /opt/vyatta/etc/functions/script-template
+run show interfaces
+exit
+```
+
+## Run commands remotely
+
+Sometimes you simply want to execute a bunch of op-mode commands via SSH on
+a remote VyOS system.
+
+``` none
+ssh 192.0.2.1 'vbash -s' <<EOF
+source /opt/vyatta/etc/functions/script-template
+run show interfaces
+exit
+EOF
+```
+
+Will return:
+
+``` none
+Welcome to VyOS
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface IP Address S/L Description
+--------- ---------- --- -----------
+eth0 192.0.2.1/24 u/u
+lo 127.0.0.1/8 u/u
+ ::1/128
+```
+
+## Other script languages
+
+If you want to script the configs in a language other than bash you can have
+your script output commands and then source them in a bash script.
+
+Here is a simple example:
+
+``` python
+#!/usr/bin/env python3
+print("delete firewall group address-group somehosts")
+print("set firewall group address-group somehosts address '192.0.2.3'")
+print("set firewall group address-group somehosts address '203.0.113.55'")
+```
+
+``` none
+#!/bin/vbash
+source /opt/vyatta/etc/functions/script-template
+configure
+source < /config/scripts/setfirewallgroup.py
+commit
+```
+
+## Executing Configuration Scripts
+
+There is a pitfall when working with configuration scripts. It is tempting to
+call configuration scripts with "sudo" (i.e., temporary root permissions),
+because that's the common way on most Linux platforms to call system commands.
+
+On VyOS this will cause the following problem: After modifying the configuration
+via script like this once, it is not possible to manually modify the config
+anymore:
+
+``` none
+sudo ./myscript.sh # Modifies config
+configure
+set ... # Any configuration parameter
+```
+
+This will result in the following error message: `Set failed` If this happens,
+a reboot is required to be able to edit the config manually again.
+
+To avoid these problems, the proper way is to call a script with the
+`vyattacfg` group, e.g., by using the `sg` (switch group) command:
+
+``` none
+sg vyattacfg -c ./myscript.sh
+```
+
+To make sure that a script is not accidentally called without the `vyattacfg`
+group, the script can be safeguarded like this:
+
+``` none
+if [ "$(id -g -n)" != 'vyattacfg' ] ; then
+ exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@"
+fi
+```
+
+## Executing pre-hooks/post-hooks Scripts
+
+VyOS has the ability to run custom scripts before and after each commit
+
+The default directories where your custom Scripts should be located are:
+
+``` none
+/config/scripts/commit/pre-hooks.d - Directory with scripts that run before
+ each commit.
+
+/config/scripts/commit/post-hooks.d - Directory with scripts that run after
+ each commit.
+```
+
+Scripts are run in alphabetical order. Their names must consist entirely of
+ASCII upper- and lower-case letters,ASCII digits, ASCII underscores, and
+ASCII minus-hyphens.No other characters are allowed.
+
+<div class="note">
+
+<div class="title">
+
+Note
+
+</div>
+
+Custom scripts are not executed with root privileges
+(Use sudo inside if this is necessary).
+
+</div>
+
+A simple example is shown below, where the ops command executed in
+the post-hook script is "show interfaces".
+
+``` none
+vyos@vyos# set interfaces ethernet eth1 address 192.0.2.3/24
+vyos@vyos# commit
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface IP Address S/L Description
+--------- ---------- --- -----------
+eth0 198.51.100.10/24 u/u
+eth1 192.0.2.3/24 u/u
+eth2 - u/u
+eth3 - u/u
+lo 203.0.113.5/24 u/u
+```
+
+## Preconfig on boot
+
+The `/config/scripts/vyos-preconfig-bootup.script` script is called on boot
+before the VyOS configuration during boot process.
+
+Any modifications were done to work around unfixed bugs and implement
+enhancements that are not complete in the VyOS system can be placed here.
+
+The default file looks like this:
+
+``` none
+#!/bin/sh
+# This script is executed at boot time before VyOS configuration is applied.
+# Any modifications required to work around unfixed bugs or use
+# services not available through the VyOS CLI system can be placed here.
+```
+
+## Postconfig on boot
+
+The `/config/scripts/vyos-postconfig-bootup.script` script is called on boot
+after the VyOS configuration is fully applied.
+
+Any modifications were done to work around unfixed bugs and implement
+enhancements that are not complete in the VyOS system can be placed here.
+
+The default file looks like this:
+
+``` none
+#!/bin/sh
+# This script is executed at boot time after VyOS configuration is fully
+# applied. Any modifications required to work around unfixed bugs or use
+# services not available through the VyOS CLI system can be placed here.
+```
+
+<div class="hint">
+
+<div class="title">
+
+Hint
+
+</div>
+
+For configuration/upgrade management issues, modification of this
+script should be the last option. Always try to find solutions based on CLI
+commands first.
+
+</div>
diff --git a/docs/automation/md-index.md b/docs/automation/md-index.md
new file mode 100644
index 00000000..bf456f0d
--- /dev/null
+++ b/docs/automation/md-index.md
@@ -0,0 +1,14 @@
+# VyOS Automation
+
+<div class="toctree" maxdepth="2">
+
+vyos-api
+vyos-ansible
+terraform/index
+vyos-napalm
+vyos-netmiko
+vyos-salt
+command-scripting
+cloud-init
+
+</div>
diff --git a/docs/automation/md-vyos-ansible.md b/docs/automation/md-vyos-ansible.md
new file mode 100644
index 00000000..ba348ca1
--- /dev/null
+++ b/docs/automation/md-vyos-ansible.md
@@ -0,0 +1,86 @@
+lastproofread
+2023-01-16
+
+# Ansible
+
+VyOS supports configuration via ansible.
+Need to install `ansible` and `python3-paramiko` module
+
+Structure of files
+
+``` none
+.
+├── ansible.cfg
+├── files
+│   └── id_rsa_docker.pub
+├── hosts
+└── main.yml
+```
+
+## File contents
+
+ansible.cfg
+
+``` none
+[defaults]
+host_key_checking = no
+retry_files_enabled = False
+ANSIBLE_INVENTORY_UNPARSED_FAILED = true
+```
+
+id_rsa_docker.pub. Needs to declare only public key exactly.
+
+``` none
+AAAAB3NzaC1yc2EAAAADAQABAAABAQCoDgfhQJuJRFWJijHn7ZinZ3NWp4hWVrt7HFcvn0kgtP/5PeCtMt
+```
+
+hosts
+
+``` none
+[vyos_hosts]
+r11 ansible_ssh_host=192.0.2.11
+
+[vyos_hosts:vars]
+ansible_python_interpreter=/usr/bin/python3
+ansible_user=vyos
+ansible_ssh_pass=vyos
+ansible_network_os=vyos
+ansible_connection=network_cli
+```
+
+main.yml
+
+``` none
+---
+
+- hosts: r11
+
+ connection: network_cli
+ gather_facts: 'no'
+
+ tasks:
+ - name: Configure remote r11
+ vyos_config:
+ lines:
+ - set system host-name r11
+ - set system name-server 203.0.113.254
+ - set service ssh disable-host-validation
+ - set system login user vyos authentication public-keys docker@work type ssh-rsa
+ - set system login user vyos authentication public-keys docker@work key "{{ lookup('file', 'id_rsa_docker.pub') }}"
+ - set system time-zone America/Los_Angeles
+ - set interfaces ethernet eth0 description WAN
+```
+
+## Run ansible
+
+``` none
+$ ansible-playbook -i hosts main.yml
+
+PLAY [r11] ******************************************************************************************************************************************************************************************************
+
+TASK [Configure remote r11] *************************************************************************************************************************************************************************************
+changed: [r11]
+
+PLAY RECAP *****************************************************************************************************************************************************************************************************
+r11 : ok=1 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
+```
diff --git a/docs/automation/md-vyos-api.md b/docs/automation/md-vyos-api.md
new file mode 100644
index 00000000..7618e262
--- /dev/null
+++ b/docs/automation/md-vyos-api.md
@@ -0,0 +1,380 @@
+lastproofread
+2023-01-16
+
+# VyOS API
+
+For configuration and enabling the API see `http-api`
+
+## Authentication
+
+All endpoints only listen on HTTP POST requests and the API KEY must set as
+`key` in the formdata.
+
+Below see one example for curl and one for python.
+The rest of the documentation is reduced to curl.
+
+``` none
+curl --location --request POST 'https://vyos/retrieve' \
+--form data='{"op": "showConfig", "path": []}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+```
+
+``` python
+import requests
+url = "https://vyos/retrieve"
+payload={'data': '{"op": "showConfig", "path": []}',
+ 'key': 'MY-HTTPS-API-PLAINTEXT-KEY'
+ }
+headers = {}
+response = requests.request("POST", url, headers=headers, data=payload)
+print(response.text)
+```
+
+## API Endpoints
+
+### /retrieve
+
+With the `retrieve` endpoint you get parts or the whole configuration.
+
+To get the whole configuration, pass an empty list to the `path` field
+
+``` none
+curl --location --request POST 'https://vyos/retrieve' \
+--form data='{"op": "showConfig", "path": []}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+
+response (shorted)
+{
+ "success": true,
+ "data": {
+ "interfaces": {
+ "ethernet": {
+ "eth0": {
+ "address": "dhcp",
+ "duplex": "auto",
+ "hw-id": "50:00:00:01:00:00",
+ "speed": "auto"
+ },
+ "eth1": {
+ "duplex": "auto",
+ "hw-id": "50:00:00:01:00:01",
+ "speed": "auto"
+ ...
+ },
+ "error": null
+}
+```
+
+To only get a part of the configuration, for example `system syslog`.
+
+``` none
+curl -k --location --request POST 'https://vyos/retrieve' \
+--form data='{"op": "showConfig", "path": ["system", "syslog"]}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+
+response:
+{
+ "success": true,
+ "data": {
+ "global": {
+ "facility": {
+ "all": {
+ "level": "info"
+ },
+ "protocols": {
+ "level": "debug"
+ }
+ }
+ }
+ },
+ "error": null
+}
+```
+
+if you just want the Value of a multi-valued node, use the `returnValues`
+operation.
+
+For example, get the addresses of a `dum0` interface.
+
+``` none
+curl -k --location --request POST 'https://vyos/retrieve' \
+--form data='{"op": "returnValues", "path": ["interfaces","dummy","dum0","address"]}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+respone:
+{
+ "success": true,
+ "data": [
+ "10.10.10.10/24",
+ "10.10.10.11/24",
+ "10.10.10.12/24"
+ ],
+ "error": null
+}
+```
+
+To check existence of a configuration path, use the `exists` operation.
+
+For example, check an existing path:
+
+``` none
+curl -k --location --request POST 'https://vyos/retrieve' \
+--form data='{"op": "exists", "path": ["service","https","api"]}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+response:
+{
+ "success": true,
+ "data": true,
+ "error": null
+}
+```
+
+versus a non-existent path:
+
+``` none
+curl -k --location --request POST 'https://vyos/retrieve' \
+--form data='{"op": "exists", "path": ["service","non","existent","path"]}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+response:
+{
+ "success": true,
+ "data": false,
+ "error": null
+}
+```
+
+### /reset
+
+The `reset` endpoint run a `reset` command.
+
+``` none
+curl --location --request POST 'https://vyos/reset' \
+--form data='{"op": "reset", "path": ["ip", "bgp", "192.0.2.11"]}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+respone:
+{
+ "success": true,
+ "data": "",
+ "error": null
+}
+```
+
+### /reboot
+
+To initiate a reboot use the `reboot` endpoint.
+
+``` none
+curl --location --request POST 'https://vyos/reboot' \
+--form data='{"op": "reboot", "path": ["now"]}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+respone:
+{
+ "success": true,
+ "data": "",
+ "error": null
+}
+```
+
+### /poweroff
+
+To power off the system use the `poweroff` endpoint.
+
+``` none
+curl --location --request POST 'https://vyos/poweroff' \
+--form data='{"op": "poweroff", "path": ["now"]}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+respone:
+{
+ "success": true,
+ "data": "",
+ "error": null
+}
+```
+
+### /image
+
+To add or delete an image, use the `/image` endpoint.
+
+add an image
+
+``` none
+curl -k --location --request POST 'https://vyos/image' \
+--form data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+respone (shorted):
+{
+ "success": true,
+ "data": "Trying to fetch ISO file from https://downloads.vyos.io/rolling-latest.iso\n
+ ...
+ Setting up grub configuration...\nDone.\n",
+ "error": null
+}
+```
+
+delete an image, for example `1.3-rolling-202006070117`
+
+``` none
+curl -k --location --request POST 'https://vyos/image' \
+--form data='{"op": "delete", "name": "1.3-rolling-202006070117"}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+response:
+{
+ "success": true,
+ "data": "Deleting the \"1.3-rolling-202006070117\" image...\nDone\n",
+ "error": null
+}
+```
+
+### /show
+
+The `/show` endpoint is to show everything in the operational mode.
+
+For example, show which images are installed.
+
+``` none
+curl -k --location --request POST 'https://vyos/show' \
+--form data='{"op": "show", "path": ["system", "image"]}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+response:
+{
+ "success": true,
+ "data": "The system currently has the following image(s) installed:\n\n
+ 1: 1.4-rolling-202102280559 (default boot)\n
+ 2: 1.4-rolling-202102230218\n
+ 3: 1.3-beta-202102210443\n\n",
+ "error": null
+}
+```
+
+### /generate
+
+The `generate` endpoint run a `generate` command.
+
+``` none
+curl -k --location --request POST 'https://vyos/generate' \
+--form data='{"op": "generate", "path": ["pki", "wireguard", "key-pair"]}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+response:
+{
+ "success": true,
+ "data": "Private key: CFZR2eyhoVZwk4n3JFPMJx3E145f1EYgDM+ubytXYVY=\n
+ Public key: jjtpPT8ycI1Q0bNtrWuxAkO4k88Xwzg5VHV9xGZ58lU=\n\n",
+ "error": null
+}
+```
+
+### /configure
+
+You can pass a `set`, `delete` or `comment` command to the
+`/configure` endpoint.
+
+`set` a single command
+
+``` none
+curl -k --location --request POST 'https://vyos/configure' \
+--form data='{"op": "set", "path": ["interfaces", "dummy", "dum1", "address", "10.11.0.1/32"]}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+response:
+{
+ "success": true,
+ "data": null,
+ "error": null
+}
+```
+
+`delete` a single command
+
+``` none
+curl -k --location --request POST 'https://vyos/configure' \
+--form data='{"op": "delete", "path": ["interfaces", "dummy", "dum1", "address", "10.11.0.1/32"]}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+response:
+{
+ "success": true,
+ "data": null,
+ "error": null
+}
+```
+
+The API pushes every request to a session and commit it.
+But some of VyOS components like DHCP and PPPoE Servers, IPSec, VXLAN, and
+other tunnels require full configuration for commit.
+The endpoint will process multiple commands when you pass them as a list to
+the `data` field.
+
+``` none
+curl -k --location --request POST 'https://vyos/configure' \
+--form data='[{"op": "set","path":["interfaces","vxlan","vxlan1","remote","203.0.113.99"]}, {"op": "set","path":["interfaces","vxlan","vxlan1","vni","1"]}]' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+response:
+{
+ "success": true,
+ "data": null,
+ "error": null
+}
+```
+
+### /config-file
+
+The endpoint `/config-file` is to save or load a configuration.
+
+Save a running configuration to the startup configuration.
+When you don't specify the file when saving, it saves to
+`/config/config.boot`.
+
+``` none
+curl -k --location --request POST 'https://vyos/config-file' \
+--form data='{"op": "save"}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+response:
+{
+ "success": true,
+ "data": "Saving configuration to '/config/config.boot'...\nDone\n",
+ "error": null
+}
+```
+
+Save a running configuration to a file.
+
+``` none
+curl -k --location --request POST 'https://vyos/config-file' \
+--form data='{"op": "save", "file": "/config/test.config"}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+response:
+{
+ "success": true,
+ "data": "Saving configuration to '/config/test.config'...\nDone\n",
+ "error": null
+}
+```
+
+To Load a configuration file.
+
+``` none
+curl -k --location --request POST 'https://vyos/config-file' \
+--form data='{"op": "load", "file": "/config/test.config"}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+response:
+{
+ "success": true,
+ "data": null,
+ "error": null
+}
+```
diff --git a/docs/automation/md-vyos-napalm.md b/docs/automation/md-vyos-napalm.md
new file mode 100644
index 00000000..ca3fd97c
--- /dev/null
+++ b/docs/automation/md-vyos-napalm.md
@@ -0,0 +1,137 @@
+lastproofread
+2023-01-16
+
+# Napalm
+
+VyOS supports some [napalm](https://napalm.readthedocs.io/en/latest/base.html) functions for configuration and op-mode.
+It requires more tests.
+
+Install `napalm-vyos` module
+
+``` none
+apt install python3-pip
+pip3 install napalm
+pip3 install napalm-vyos
+```
+
+## Op-mode
+
+``` none
+#!/usr/bin/env python3
+
+import json
+from napalm import get_network_driver
+
+driver = get_network_driver('vyos')
+
+vyos_router = driver(
+ hostname="192.0.2.1",
+ username="vyos",
+ password="vyospass",
+ optional_args={"port": 22},
+)
+
+vyos_router.open()
+output = vyos_router.get_facts()
+print(json.dumps(output, indent=4))
+
+output = vyos_router.get_arp_table()
+print(json.dumps(output, indent=4))
+
+vyos_router.close()
+```
+
+Output op-mode
+
+``` none
+$ ./vyos-napalm.py
+{
+ "uptime": 7185,
+ "vendor": "VyOS",
+ "os_version": "1.3.0-rc5",
+ "serial_number": "",
+ "model": "Standard PC (Q35 + ICH9, 2009)",
+ "hostname": "r4-1.3",
+ "fqdn": "vyos.local",
+ "interface_list": [
+ "eth0",
+ "eth1",
+ "eth2",
+ "lo",
+ "vtun10"
+ ]
+}
+[
+ {
+ "interface": "eth1",
+ "mac": "52:54:00:b2:38:2c",
+ "ip": "192.0.2.2",
+ "age": 0.0
+ },
+ {
+ "interface": "eth0",
+ "mac": "52:54:00:a2:b9:5b",
+ "ip": "203.0.113.11",
+ "age": 0.0
+ }
+]
+```
+
+## Configuration
+
+We need 2 files, commands.conf and script itself.
+
+Content of commands.conf
+
+``` none
+set service ssh disable-host-validation
+set service ssh port '2222'
+set system name-server '192.0.2.8'
+set system name-server '203.0.113.8'
+set interfaces ethernet eth1 description 'FOO'
+```
+
+Script vyos-napalm.py
+
+``` none
+#!/usr/bin/env python3
+
+from napalm import get_network_driver
+
+driver = get_network_driver('vyos')
+
+vyos_router = driver(
+ hostname="192.0.2.1",
+ username="vyos",
+ password="vyospass",
+ optional_args={"port": 22},
+)
+
+vyos_router.open()
+vyos_router.load_merge_candidate(filename='commands.conf')
+diffs = vyos_router.compare_config()
+
+if bool(diffs) == True:
+ print(diffs)
+ vyos_router.commit_config()
+else:
+ print('No configuration changes to commit')
+ vyos_router.discard_config()
+
+vyos_router.close()
+```
+
+Output
+
+``` none
+$./vyos-napalm.py
+[edit interfaces ethernet eth1]
++description FOO
+[edit service ssh]
++disable-host-validation
++port 2222
+[edit system]
++name-server 192.0.2.8
++name-server 203.0.113.8
+[edit]
+```
diff --git a/docs/automation/md-vyos-netmiko.md b/docs/automation/md-vyos-netmiko.md
new file mode 100644
index 00000000..84622a0d
--- /dev/null
+++ b/docs/automation/md-vyos-netmiko.md
@@ -0,0 +1,67 @@
+lastproofread
+2023-01-16
+
+# Netmiko
+
+VyOS supports configuration via [netmiko](https://github.com/ktbyers/netmiko).
+It requires to install `python3-netmiko` module.
+
+## Example
+
+``` none
+#!/usr/bin/env python3
+
+from netmiko import ConnectHandler
+
+vyos_router = {
+ "device_type": "vyos",
+ "host": "192.0.2.1",
+ "username": "vyos",
+ "password": "vyospass",
+ "port": 22,
+ }
+
+net_connect = ConnectHandler(**vyos_router)
+
+config_commands = [
+ 'set interfaces ethernet eth0 description WAN',
+ 'set interfaces ethernet eth1 description LAN',
+ ]
+
+# set configuration
+output = net_connect.send_config_set(config_commands, exit_config_mode=False)
+print(output)
+
+# commit configuration
+output = net_connect.commit()
+print(output)
+
+# op-mode commands
+output = net_connect.send_command("run show interfaces")
+print(output)
+```
+
+Output
+
+``` none
+$ ./vyos-netmiko.py
+configure
+set interfaces ethernet eth0 description WAN
+[edit]
+vyos@r4-1.3# set interfaces ethernet eth1 description LAN
+[edit]
+vyos@r4-1.3#
+commit
+[edit]
+vyos@r4-1.3#
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface IP Address S/L Description
+--------- ---------- --- -----------
+eth0 203.0.113.1/24 u/u WAN
+eth1 192.0.2.1/30 u/u LAN
+eth2 - u/u
+lo 127.0.0.1/8 u/u
+ ::1/128
+vtun10 10.10.0.1/24 u/u
+[edit]
+```
diff --git a/docs/automation/md-vyos-salt.md b/docs/automation/md-vyos-salt.md
new file mode 100644
index 00000000..8b770a8f
--- /dev/null
+++ b/docs/automation/md-vyos-salt.md
@@ -0,0 +1,204 @@
+lastproofread
+2023-01-16
+
+<div id="vyos-salt">
+
+</div>
+
+# Salt
+
+VyOS supports op-mode and configuration via [salt](https://docs.saltproject.io/en/latest/contents.html).
+
+Without proxy it requires VyOS minion configuration
+and supports op-mode data:
+
+``` none
+set service salt-minion id 'r14'
+set service salt-minion master '192.0.2.250'
+```
+
+Check salt-keys on the salt master
+
+``` none
+/ # salt-key --list-all
+Accepted Keys:
+r11
+Denied Keys:
+Unaccepted Keys:
+r14
+Rejected Keys:
+```
+
+Accept minion key
+
+``` none
+/ # salt-key --accept r14
+The following keys are going to be accepted:
+Unaccepted Keys:
+r14
+Proceed? [n/Y] y
+Key for minion r14 accepted.
+```
+
+Check that salt master can communicate with minions
+
+``` none
+/ # salt '*' test.ping
+r14:
+ True
+r11:
+ True
+```
+
+At this step we can get some op-mode information from VyOS nodes:
+
+``` none
+/ # salt '*' network.interface eth0
+r11:
+ |_
+ ----------
+ address:
+ 192.0.2.11
+ broadcast:
+ 192.0.2.255
+ label:
+ eth0
+ netmask:
+ 255.255.255.0
+r14:
+ |_
+ ----------
+ address:
+ 192.0.2.14
+ broadcast:
+ 192.0.2.255
+ label:
+ eth0
+ netmask:
+ 255.255.255.0
+
+
+/ # salt r14 network.arp
+r14:
+ ----------
+ aa:bb:cc:dd:f3:db:
+ 192.0.2.1
+ aa:bb:cc:dd:2e:80:
+ 203.0.113.1
+```
+
+## Netmiko-proxy
+
+It is possible to configure VyOS via [netmiko](https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.netmiko_mod.html#module-salt.modules.netmiko_mod) proxy module.
+It requires a minion with installed packet `python3-netmiko` module
+who has a connection to VyOS nodes. Salt-minion have to communicate
+with salt master
+
+### Configuration
+
+Salt master configuration:
+
+``` none
+/ # cat /etc/salt/master
+file_roots:
+ base:
+ - /srv/salt/states
+
+pillar_roots:
+ base:
+ - /srv/salt/pillars
+```
+
+Structure of /srv/salt:
+
+``` none
+/ # tree /srv/salt/
+/srv/salt/
+|___ pillars
+| |__ r11-proxy.sls
+| |__ top.sls
+|___ states
+ |__ commands.txt
+```
+
+top.sls
+
+``` none
+/ # cat /srv/salt/pillars/top.sls
+base:
+ r11-proxy:
+ - r11-proxy
+```
+
+r11-proxy.sls Includes parameters for connecting to salt-proxy minion
+
+``` none
+/ # cat /srv/salt/pillars/r11-proxy.sls
+proxy:
+ proxytype: netmiko # how to connect to proxy minion, change it
+ device_type: vyos #
+ host: 192.0.2.250
+ username: user
+ password: secret_passwd
+```
+
+commands.txt
+
+``` none
+/ # cat /srv/salt/states/commands.txt
+set interfaces ethernet eth0 description 'WAN'
+set interfaces ethernet eth1 description 'LAN'
+```
+
+Check that proxy minion is alive:
+
+``` none
+/ # salt r11-proxy test.ping
+r11-proxy:
+ True
+/ #
+```
+
+### Examples
+
+Example of op-mode:
+
+``` none
+/ # salt r11-proxy netmiko.send_command 'show interfaces ethernet eth0 brief' host=192.0.2.14 device_type=vyos username=vyos password=vyos
+r11-proxy:
+ Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+ Interface IP Address S/L Description
+ --------- ---------- --- -----------
+ eth0 192.0.2.14/24 u/u Upstream
+/ #
+```
+
+Example of configuration:
+
+``` none
+/ # salt r11-proxy netmiko.send_config config_commands=['set interfaces ethernet eth0 description Link_to_WAN'] commit=True host=192.0.2.14 device_type=vyos username=vyos password=vyos
+r11-proxy:
+ configure
+ set interfaces ethernet eth0 description Link_to_WAN
+ [edit]
+ vyos@r14# commit
+ [edit]
+ vyos@r14#
+/ #
+```
+
+Example of configuration commands from the file "/srv/salt/states/commands.txt"
+
+``` none
+/ # salt r11-proxy netmiko.send_config config_file=salt://commands.txt commit=True host=192.0.2.11 device_type=vyos username=vyos password=vyos
+r11-proxy:
+ configure
+ set interfaces ethernet eth0 description 'WAN'
+ [edit]
+ vyos@r1# set interfaces ethernet eth1 description 'LAN'
+ [edit]
+ vyos@r1# commit
+ [edit]
+ vyos@r1#
+/ #
+```
diff --git a/docs/automation/terraform/md-index.md b/docs/automation/terraform/md-index.md
new file mode 100644
index 00000000..9d02b913
--- /dev/null
+++ b/docs/automation/terraform/md-index.md
@@ -0,0 +1,11 @@
+# VyOS Terraform
+
+<div class="toctree" maxdepth="1" caption="Content">
+
+terraformvyos
+terraformAWS
+terraformAZ
+terraformvSphere
+terraformGoogle
+
+</div>
diff --git a/docs/automation/terraform/md-terraformAWS.md b/docs/automation/terraform/md-terraformAWS.md
new file mode 100644
index 00000000..7485b3eb
--- /dev/null
+++ b/docs/automation/terraform/md-terraformAWS.md
@@ -0,0 +1,493 @@
+lastproofread
+2024-01-11
+
+# Deploying VyOS in the AWS cloud
+
+With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the AWS cloud. If necessary, the infrastructure can be removed using terraform.
+Also we will make provisioning using Ansible.
+
+<img src="/_static/images/aws.webp" class="align-center" style="width:50.0%" alt="Network Topology Diagram" />
+
+In this case, we'll create the necessary files for Terraform and Ansible next using Terraform we'll create a single instance on the AWS cloud and make provisioning using Ansible.
+
+## Preparation steps for deploying VyOS on AWS
+
+How to create a single instance and install your configuration using Terraform+Ansible+AWS
+Step by step:
+
+AWS
+
+1 Create an account with AWS and get your "access_key", "secret key"
+
+2 Create a key [pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html) and download your .pem key
+
+<img src="/_static/images/keypairs.webp" class="align-center" style="width:50.0%" alt="Network Topology Diagram" />
+
+3 Create a security [group](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-ec2-sg.html) for the new VyOS instance and open all traffic
+
+<img src="/_static/images/sg.webp" class="align-center" style="width:50.0%" alt="Network Topology Diagram" />
+
+<img src="/_static/images/traffic.webp" class="align-center" style="width:50.0%" alt="Network Topology Diagram" />
+
+Terraform
+
+> 1 Create an UNIX or Windows instance
+>
+> 2 Download and install Terraform
+>
+> 3 Create the folder for example /root/awsterraform
+
+``` none
+mkdir /root/awsterraform
+
+ 4 Copy all files into your Terraform project "/root/awsterraform" (vyos.tf, var.tf, terraform.tfvars,version.tf), more detailed see `Structure of files Terrafom for AWS`_
+
+ 5 Type the commands :
+```
+
+``` none
+cd /<your folder>
+terraform init
+```
+
+Ansible
+
+> 1 Create an UNIX instance whenever you want (local, cloud, and so on)
+>
+> 2 Download and install Ansible
+>
+> 3 Create the folder for example /root/aws/
+>
+> 4 Copy all files into your Ansible project "/root/aws/" (ansible.cfg, instance.yml, mykey.pem and "all"), more detailed see [Structure of files Ansible for AWS](#structure-of-files-ansible-for-aws)
+
+mykey.pem you have to get using step 1.2
+
+Start
+
+Type the commands on your Terrafom instance:
+
+``` none
+cd /<your folder>
+terraform plan
+terraform apply
+yes
+```
+
+## Start creating an AWS instance and check the result
+
+``` none
+root@localhost:~/awsterraform# terraform apply
+
+Terraform used the selected providers to generate the following execution plan.
+Resource actions are indicated with the following symbols:
+ + create
+
+Terraform will perform the following actions:
+
+ # aws_instance.myVyOSec2 will be created
+ + resource "aws_instance" "myVyOSec2" {
+ + ami = "ami-************62c2d"
+ + arn = (known after apply)
+ + associate_public_ip_address = (known after apply)
+ + availability_zone = (known after apply)
+ + cpu_core_count = (known after apply)
+ + cpu_threads_per_core = (known after apply)
+ + disable_api_stop = (known after apply)
+ + disable_api_termination = (known after apply)
+ + ebs_optimized = (known after apply)
+ + get_password_data = false
+ + host_id = (known after apply)
+ + host_resource_group_arn = (known after apply)
+ + iam_instance_profile = (known after apply)
+ + id = (known after apply)
+ + instance_initiated_shutdown_behavior = (known after apply)
+ + instance_lifecycle = (known after apply)
+ + instance_state = (known after apply)
+ + instance_type = "t2.micro"
+ + ipv6_address_count = (known after apply)
+ + ipv6_addresses = (known after apply)
+ + key_name = "awsterraform"
+ + monitoring = (known after apply)
+ + outpost_arn = (known after apply)
+ + password_data = (known after apply)
+ + placement_group = (known after apply)
+ + placement_partition_number = (known after apply)
+ + primary_network_interface_id = (known after apply)
+ + private_dns = (known after apply)
+ + private_ip = (known after apply)
+ + public_dns = (known after apply)
+ + public_ip = (known after apply)
+ + secondary_private_ips = (known after apply)
+ + security_groups = [
+ + "awsterraformsg",
+ ]
+ + source_dest_check = true
+ + spot_instance_request_id = (known after apply)
+ + subnet_id = (known after apply)
+ + tags = {
+ + "name" = "VyOS System"
+ }
+ + tags_all = {
+ + "name" = "VyOS System"
+ }
+ + tenancy = (known after apply)
+ + user_data = (known after apply)
+ + user_data_base64 = (known after apply)
+ + user_data_replace_on_change = false
+ + vpc_security_group_ids = (known after apply)
+ }
+
+ # local_file.ip will be created
+ + resource "local_file" "ip" {
+ + content = (known after apply)
+ + content_base64sha256 = (known after apply)
+ + content_base64sha512 = (known after apply)
+ + content_md5 = (known after apply)
+ + content_sha1 = (known after apply)
+ + content_sha256 = (known after apply)
+ + content_sha512 = (known after apply)
+ + directory_permission = "0777"
+ + file_permission = "0777"
+ + filename = "ip.txt"
+ + id = (known after apply)
+ }
+
+ # null_resource.SSHconnection1 will be created
+ + resource "null_resource" "SSHconnection1" {
+ + id = (known after apply)
+ }
+
+ # null_resource.SSHconnection2 will be created
+ + resource "null_resource" "SSHconnection2" {
+ + id = (known after apply)
+ }
+
+Plan: 4 to add, 0 to change, 0 to destroy.
+
+Changes to Outputs:
+ + my_IP = (known after apply)
+
+Do you want to perform these actions?
+ Terraform will perform the actions described above.
+ Only 'yes' will be accepted to approve.
+
+ Enter a value: yes
+
+aws_instance.myVyOSec2: Creating...
+aws_instance.myVyOSec2: Still creating... [10s elapsed]
+aws_instance.myVyOSec2: Still creating... [20s elapsed]
+aws_instance.myVyOSec2: Still creating... [30s elapsed]
+aws_instance.myVyOSec2: Still creating... [40s elapsed]
+aws_instance.myVyOSec2: Creation complete after 44s [id=i-09edfca15aac2fe0a]
+null_resource.SSHconnection1: Creating...
+null_resource.SSHconnection2: Creating...
+null_resource.SSHconnection1: Provisioning with 'file'...
+null_resource.SSHconnection2: Provisioning with 'remote-exec'...
+null_resource.SSHconnection2 (remote-exec): Connecting to remote host via SSH...
+null_resource.SSHconnection2 (remote-exec): Host: 10.217.80.104
+null_resource.SSHconnection2 (remote-exec): User: root
+null_resource.SSHconnection2 (remote-exec): Password: true
+null_resource.SSHconnection2 (remote-exec): Private key: false
+null_resource.SSHconnection2 (remote-exec): Certificate: false
+null_resource.SSHconnection2 (remote-exec): SSH Agent: false
+null_resource.SSHconnection2 (remote-exec): Checking Host Key: false
+null_resource.SSHconnection2 (remote-exec): Target Platform: unix
+local_file.ip: Creating...
+local_file.ip: Creation complete after 0s [id=e8e91f2e24579cd28b92e2d152c0c24c3bf4b52c]
+null_resource.SSHconnection2 (remote-exec): Connected!
+null_resource.SSHconnection1: Creation complete after 0s [id=7070868940858935600]
+
+null_resource.SSHconnection2 (remote-exec): PLAY [integration of terraform and ansible] ************************************
+
+null_resource.SSHconnection2 (remote-exec): TASK [Wait 300 seconds, but only start checking after 60 seconds] **************
+null_resource.SSHconnection2: Still creating... [10s elapsed]
+null_resource.SSHconnection2: Still creating... [20s elapsed]
+null_resource.SSHconnection2: Still creating... [30s elapsed]
+null_resource.SSHconnection2: Still creating... [40s elapsed]
+null_resource.SSHconnection2: Still creating... [50s elapsed]
+null_resource.SSHconnection2: Still creating... [1m0s elapsed]
+null_resource.SSHconnection2 (remote-exec): ok: [54.xxx.xxx.xxx]
+
+null_resource.SSHconnection2 (remote-exec): TASK [Configure general settings for the vyos hosts group] *********************
+null_resource.SSHconnection2: Still creating... [1m10s elapsed]
+null_resource.SSHconnection2 (remote-exec): changed: [54.xxx.xxx.xxx]
+
+null_resource.SSHconnection2 (remote-exec): PLAY RECAP *********************************************************************
+null_resource.SSHconnection2 (remote-exec): 54.xxx.xxx.xxx : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
+
+null_resource.SSHconnection2: Creation complete after 1m16s [id=4902256962410024771]
+
+Apply complete! Resources: 4 added, 0 changed, 0 destroyed.
+
+Outputs:
+
+my_IP = "54.xxx.xxx.xxx"
+```
+
+After executing all the commands you will have your VyOS instance on the AWS cloud with your configuration, it's a very convenient desition.
+If you need to delete the instance please type the command:
+
+``` none
+terraform destroy
+```
+
+## Troubleshooting
+
+1 Ansible doesn't connect via SSH to your AWS instance: you have to check that your SSH key has copied into the path /root/aws/.
+Also, increase the time in the file instance.yml from 300 sec to 500 sec or more. (It depends on your location).
+Make sure that you have opened access to the instance in the security group.
+
+> 2 Terraform doesn't connect via SSH to your Ansible instance: you have to check the correct login and password in the part of the file VyOS. tf
+
+``` none
+connection {
+ type = "ssh"
+ user = "root" # open root access using login and password on your Ansible
+ password = var.password # check password in the file terraform.tfvars isn't empty
+ host = var.host # check the correct IP address of your Ansible host
+}
+```
+
+Make sure that Ansible is pinging from Terrafom.
+
+## Structure of files Terrafom for AWS
+
+``` none
+.
+├── vyos.tf # The main script
+├── var.tf # The file of all variables in "vyos.tf"
+├── versions.tf # File for the changing version of Terraform.
+└── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on)
+```
+
+## File contents of Terrafom for AWS
+
+vyos.tf
+
+``` none
+##############################################################################
+# Build an VyOS VM from the Marketplace
+# To finde nessesery AMI image_ in AWS
+#
+# In the script vyos.tf we'll use default values (you can chang it as you need)
+# AWS Region = "us-east-1"
+# AMI = "standard AMI of VyOS from AWS Marketplace"
+# Size of VM = "t2.micro"
+# AWS Region = "us-east-1"
+# After deploying the AWS instance and getting an IP address, the IP address is copied into the file
+#"ip.txt" and copied to the Ansible node for provisioning.
+##############################################################################
+
+provider "aws" {
+ access_key = var.access
+ secret_key = var.secret
+ region = var.region
+}
+
+variable "region" {
+ default = "us-east-1"
+ description = "AWS Region"
+}
+
+variable "ami" {
+ default = "ami-**************3b3" # ami image please enter your details
+ description = "Amazon Machine Image ID for VyOS"
+}
+
+variable "type" {
+ default = "t2.micro"
+ description = "Size of VM"
+}
+
+# my resource for VyOS
+
+resource "aws_instance" "myVyOSec2" {
+ ami = var.ami
+ key_name = "awsterraform" # Please enter your details from 1.2 of Preparation steps for deploying VyOS on AWS
+ security_groups = ["awsterraformsg"] # Please enter your details from 1.3 of Preparation steps for deploying VyOS on AWS
+ instance_type = var.type
+ tags = {
+ name = "VyOS System"
+ }
+}
+
+##############################################################################
+# specific variable (to getting type "terraform plan"):
+# aws_instance.myVyOSec2.public_ip - the information about public IP address
+# of our instance, needs for provisioning and ssh connection from Ansible
+##############################################################################
+
+output "my_IP"{
+value = aws_instance.myVyOSec2.public_ip
+}
+
+##############################################################################
+#
+# IP of aws instance copied to a file ip.txt in local system Terraform
+# ip.txt looks like:
+# cat ./ip.txt
+# ххх.ххх.ххх.ххх
+##############################################################################
+
+resource "local_file" "ip" {
+ content = aws_instance.myVyOSec2.public_ip
+ filename = "ip.txt"
+}
+
+#connecting to the Ansible control node using SSH connection
+
+##############################################################################
+# Steps "SSHconnection1" and "SSHconnection2" need to get file ip.txt from the terraform node and start remotely the playbook of Ansible.
+##############################################################################
+
+resource "null_resource" "SSHconnection1" {
+depends_on = [aws_instance.myVyOSec2]
+connection {
+ type = "ssh"
+ user = "root"
+ password = var.password
+ host = var.host
+}
+
+#copying the ip.txt file to the Ansible control node from local system
+
+ provisioner "file" {
+ source = "ip.txt"
+ destination = "/root/aws/ip.txt" # The folder of your Ansible project
+ }
+}
+
+resource "null_resource" "SSHconnection2" {
+depends_on = [aws_instance.myVyOSec2]
+connection {
+ type = "ssh"
+ user = "root"
+ password = var.password
+ host = var.host
+}
+#command to run Ansible playbook on remote Linux OS
+provisioner "remote-exec" {
+ inline = [
+ "cd /root/aws/",
+ "ansible-playbook instance.yml" # more detailed in "File contents of Ansible for AWS"
+]
+}
+}
+```
+
+var.tf
+
+``` none
+variable "password" {
+ description = "pass for Ansible"
+ type = string
+ sensitive = true
+}
+variable "host"{
+ description = "The IP of my Ansible"
+ type = string
+}
+variable "access" {
+ description = "my access_key for AWS"
+ type = string
+ sensitive = true
+}
+variable "secret" {
+ description = "my secret_key for AWS"
+ type = string
+ sensitive = true
+}
+```
+
+versions.tf
+
+``` none
+terraform {
+ required_providers {
+ aws = {
+ source = "hashicorp/aws"
+ version = "~> 5.0"
+ }
+ }
+}
+```
+
+terraform.tfvars
+
+``` none
+password = "" # password for Ansible SSH
+host = "" # IP of my Ansible
+access = "" # access_key for AWS
+secret = "" # secret_key for AWS
+```
+
+## Structure of files Ansible for AWS
+
+``` none
+.
+├── group_vars
+ └── all
+├── ansible.cfg
+├── mykey.pem
+└── instance.yml
+```
+
+## File contents of Ansible for AWS
+
+ansible.cfg
+
+``` none
+[defaults]
+inventory = /root/aws/ip.txt
+host_key_checking= False
+private_key_file = /root/aws/awsterraform.pem # check the name
+remote_user=vyos
+```
+
+mykey.pem
+
+``` none
+Copy your key.pem from AWS
+```
+
+instance.yml
+
+``` none
+##############################################################################
+# About tasks:
+# "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds
+# "Configure general settings for the VyOS hosts group" - make provisioning into AWS VyOS node
+# You have to add all necessary cammans of VyOS under the block "lines:"
+##############################################################################
+
+
+- name: integration of terraform and ansible
+ hosts: all
+ gather_facts: 'no'
+
+ tasks:
+
+ - name: "Wait 300 seconds, but only start checking after 60 seconds"
+ wait_for_connection:
+ delay: 60
+ timeout: 300
+
+ - name: "Configure general settings for the VyOS hosts group"
+ vyos_config:
+ lines:
+ - set system name-server xxx.xxx.xxx.xxx
+ save:
+ true
+```
+
+group_vars/all
+
+``` none
+ansible_connection: ansible.netcommon.network_cli
+ansible_network_os: vyos.vyos.vyos
+ansible_user: vyos
+```
+
+## Sourse files for AWS from GIT
+
+All files about the article can be found [here](https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/AWS_terraform_ansible_single_vyos_instance-main)
diff --git a/docs/automation/terraform/md-terraformAZ.md b/docs/automation/terraform/md-terraformAZ.md
new file mode 100644
index 00000000..e4ed9de9
--- /dev/null
+++ b/docs/automation/terraform/md-terraformAZ.md
@@ -0,0 +1,466 @@
+lastproofread
+2024-03-03
+
+# Deploying VyOS in the Azure cloud
+
+With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the Azure cloud. If necessary, the infrastructure can be removed using terraform.
+Also we will make provisioning using Ansible.
+
+In this case, we'll create the necessary files for Terraform and Ansible next using Terraform we'll create a single instance on the Azure cloud and make provisioning using Ansible.
+
+## Preparation steps for deploying VyOS on Azure
+
+How to create a single instance and install your configuration using Terraform+Ansible+Azure
+Step by step:
+
+Azure
+
+> 1 Create an account with Azure
+
+Terraform
+
+> 1 Create an UNIX or Windows instance
+>
+> 2 Download and install Terraform
+>
+> 3 Create the folder for example /root/azvyos/
+
+``` none
+mkdir /root/azvyos
+
+ 4 Copy all files into your Terraform project "/root/azvyos" (vyos.tf, var.tf, terraform.tfvars), more detailed see `Structure of files Terrafom for Azure`_
+
+ 5 Login with Azure using the command
+```
+
+``` none
+az login
+```
+
+2.6 Type the commands :
+
+``` none
+cd /<your folder>
+terraform init
+```
+
+Ansible
+
+> 1 Create an UNIX instance whenever you want (local, cloud, and so on)
+>
+> 2 Download and install Ansible
+>
+> 3 Create the folder for example /root/az/
+>
+> 4 Copy all files into your Ansible project "/root/az/" (ansible.cfg, instance.yml,"all"), more detailed see [Structure of files Ansible for Azure](#structure-of-files-ansible-for-azure)
+
+Start
+
+Type the commands on your Terrafom instance:
+
+``` none
+cd /<your folder>
+terraform plan
+terraform apply
+yes
+```
+
+After executing all the commands you will have your VyOS instance on the Azure cloud with your configuration, it's a very convenient desition.
+If you need to delete the instance please type the command:
+
+``` none
+terraform destroy
+```
+
+## Structure of files Terrafom for Azure
+
+``` none
+.
+├── vyos.tf # The main script
+├── var.tf # File for the changing version of Terraform.
+└── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on)
+```
+
+## File contents of Terrafom for Azure
+
+vyos.tf
+
+``` none
+##############################################################################
+# HashiCorp Guide to Using Terraform on Azure
+# This Terraform configuration will create the following:
+# Resource group with a virtual network and subnet
+# An VyOS server without ssh key (only login+password)
+##############################################################################
+
+# Chouse a provider
+
+provider "azurerm" {
+ features {}
+}
+
+# Create a resource group. In Azure every resource belongs to a
+# resource group.
+
+resource "azurerm_resource_group" "azure_vyos" {
+ name = "${var.resource_group}"
+ location = "${var.location}"
+}
+
+# The next resource is a Virtual Network.
+
+resource "azurerm_virtual_network" "vnet" {
+ name = "${var.virtual_network_name}"
+ location = "${var.location}"
+ address_space = ["${var.address_space}"]
+ resource_group_name = "${var.resource_group}"
+}
+
+# Build a subnet to run our VMs in.
+
+resource "azurerm_subnet" "subnet" {
+ name = "${var.prefix}subnet"
+ virtual_network_name = "${azurerm_virtual_network.vnet.name}"
+ resource_group_name = "${var.resource_group}"
+ address_prefixes = ["${var.subnet_prefix}"]
+}
+
+##############################################################################
+# Build an VyOS VM from the Marketplace
+# To finde nessesery image use the command:
+#
+# az vm image list --offer vyos --all
+#
+# Now that we have a network, we'll deploy an VyOS server.
+# An Azure Virtual Machine has several components. In this example we'll build
+# a security group, a network interface, a public ip address, a storage
+# account and finally the VM itself. Terraform handles all the dependencies
+# automatically, and each resource is named with user-defined variables.
+##############################################################################
+
+
+# Security group to allow inbound access on port 22 (ssh)
+
+resource "azurerm_network_security_group" "vyos-sg" {
+ name = "${var.prefix}-sg"
+ location = "${var.location}"
+ resource_group_name = "${var.resource_group}"
+
+ security_rule {
+ name = "SSH"
+ priority = 100
+ direction = "Inbound"
+ access = "Allow"
+ protocol = "Tcp"
+ source_port_range = "*"
+ destination_port_range = "22"
+ source_address_prefix = "${var.source_network}"
+ destination_address_prefix = "*"
+ }
+}
+
+# A network interface.
+
+resource "azurerm_network_interface" "vyos-nic" {
+ name = "${var.prefix}vyos-nic"
+ location = "${var.location}"
+ resource_group_name = "${var.resource_group}"
+
+ ip_configuration {
+ name = "${var.prefix}ipconfig"
+ subnet_id = "${azurerm_subnet.subnet.id}"
+ private_ip_address_allocation = "Dynamic"
+ public_ip_address_id = "${azurerm_public_ip.vyos-pip.id}"
+ }
+}
+
+# Add a public IP address.
+
+resource "azurerm_public_ip" "vyos-pip" {
+ name = "${var.prefix}-ip"
+ location = "${var.location}"
+ resource_group_name = "${var.resource_group}"
+ allocation_method = "Dynamic"
+}
+
+# Build a virtual machine. This is a standard VyOS instance from Marketplace.
+
+resource "azurerm_virtual_machine" "vyos" {
+ name = "${var.hostname}-vyos"
+ location = "${var.location}"
+ resource_group_name = "${var.resource_group}"
+ vm_size = "${var.vm_size}"
+
+ network_interface_ids = ["${azurerm_network_interface.vyos-nic.id}"]
+ delete_os_disk_on_termination = "true"
+
+# To finde an information about the plan use the command:
+# az vm image list --offer vyos --all
+
+ plan {
+ publisher = "sentriumsl"
+ name = "vyos-1-3"
+ product = "vyos-1-2-lts-on-azure"
+ }
+
+ storage_image_reference {
+ publisher = "${var.image_publisher}"
+ offer = "${var.image_offer}"
+ sku = "${var.image_sku}"
+ version = "${var.image_version}"
+ }
+
+ storage_os_disk {
+ name = "${var.hostname}-osdisk"
+ managed_disk_type = "Standard_LRS"
+ caching = "ReadWrite"
+ create_option = "FromImage"
+ }
+
+ os_profile {
+ computer_name = "${var.hostname}"
+ admin_username = "${var.admin_username}"
+ admin_password = "${var.admin_password}"
+ }
+
+ os_profile_linux_config {
+ disable_password_authentication = false
+ }
+}
+
+data "azurerm_public_ip" "example" {
+ depends_on = ["azurerm_virtual_machine.vyos"]
+ name = "vyos-ip"
+ resource_group_name = "${var.resource_group}"
+}
+output "public_ip_address" {
+ value = data.azurerm_public_ip.example.ip_address
+}
+
+# IP of AZ instance copied to a file ip.txt in local system
+
+resource "local_file" "ip" {
+ content = data.azurerm_public_ip.example.ip_address
+ filename = "ip.txt"
+}
+
+#Connecting to the Ansible control node using SSH connection
+
+resource "null_resource" "nullremote1" {
+depends_on = ["azurerm_virtual_machine.vyos"]
+connection {
+ type = "ssh"
+ user = "root"
+ password = var.password
+ host = var.host
+}
+
+# Copying the ip.txt file to the Ansible control node from local system
+
+ provisioner "file" {
+ source = "ip.txt"
+ destination = "/root/az/ip.txt"
+ }
+}
+
+resource "null_resource" "nullremote2" {
+depends_on = ["azurerm_virtual_machine.vyos"]
+connection {
+ type = "ssh"
+ user = "root"
+ password = var.password
+ host = var.host
+}
+
+# Command to run ansible playbook on remote Linux OS
+
+provisioner "remote-exec" {
+
+ inline = [
+ "cd /root/az/",
+ "ansible-playbook instance.yml"
+]
+}
+}
+```
+
+var.tf
+
+``` none
+##############################################################################
+# Variables File
+#
+# Here is where we store the default values for all the variables used in our
+# Terraform code.
+##############################################################################
+
+variable "resource_group" {
+ description = "The name of your Azure Resource Group."
+ default = "my_resource_group"
+}
+
+variable "prefix" {
+ description = "This prefix will be included in the name of some resources."
+ default = "vyos"
+}
+
+variable "hostname" {
+ description = "Virtual machine hostname. Used for local hostname, DNS, and storage-related names."
+ default = "vyos_terraform"
+}
+
+variable "location" {
+ description = "The region where the virtual network is created."
+ default = "centralus"
+}
+
+variable "virtual_network_name" {
+ description = "The name for your virtual network."
+ default = "vnet"
+}
+
+variable "address_space" {
+ description = "The address space that is used by the virtual network. You can supply more than one address space. Changing this forces a new resource to be created."
+ default = "10.0.0.0/16"
+}
+
+variable "subnet_prefix" {
+ description = "The address prefix to use for the subnet."
+ default = "10.0.10.0/24"
+}
+
+variable "storage_account_tier" {
+ description = "Defines the storage tier. Valid options are Standard and Premium."
+ default = "Standard"
+}
+
+variable "storage_replication_type" {
+ description = "Defines the replication type to use for this storage account. Valid options include LRS, GRS etc."
+ default = "LRS"
+}
+
+# The most chippers size
+
+variable "vm_size" {
+ description = "Specifies the size of the virtual machine."
+ default = "Standard_B1s"
+}
+
+variable "image_publisher" {
+ description = "Name of the publisher of the image (az vm image list)"
+ default = "sentriumsl"
+}
+
+variable "image_offer" {
+ description = "Name of the offer (az vm image list)"
+ default = "vyos-1-2-lts-on-azure"
+}
+
+variable "image_sku" {
+ description = "Image SKU to apply (az vm image list)"
+ default = "vyos-1-3"
+}
+
+variable "image_version" {
+ description = "Version of the image to apply (az vm image list)"
+ default = "1.3.3"
+}
+
+variable "admin_username" {
+ description = "Administrator user name"
+ default = "vyos"
+}
+
+variable "admin_password" {
+ description = "Administrator password"
+ type = string
+ sensitive = true
+}
+
+variable "source_network" {
+ description = "Allow access from this network prefix. Defaults to '*'."
+ default = "*"
+}
+
+variable "password" {
+ description = "pass for Ansible"
+ type = string
+ sensitive = true
+}
+variable "host"{
+ description = "IP of my Ansible"
+}
+```
+
+terraform.tfvars
+
+``` none
+password = "" # password for Ansible SSH
+host = "" # IP of my Ansible
+```
+
+## Structure of files Ansible for Azure
+
+``` none
+.
+├── group_vars
+ └── all
+├── ansible.cfg
+└── instance.yml
+```
+
+## File contents of Ansible for Azure
+
+ansible.cfg
+
+``` none
+[defaults]
+inventory = /root/az/ip.txt
+host_key_checking= False
+remote_user=vyos
+```
+
+instance.yml
+
+``` none
+##############################################################################
+# About tasks:
+# "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds
+# "Configure general settings for the VyOS hosts group" - make provisioning into Azure VyOS node
+# You have to add all necessary cammans of VyOS under the block "lines:"
+##############################################################################
+
+
+- name: integration of terraform and ansible
+ hosts: all
+ gather_facts: 'no'
+
+ tasks:
+
+ - name: "Wait 300 seconds, but only start checking after 60 seconds"
+ wait_for_connection:
+ delay: 60
+ timeout: 300
+
+ - name: "Configure general settings for the VyOS hosts group"
+ vyos_config:
+ lines:
+ - set system name-server xxx.xxx.xxx.xxx
+ save:
+ true
+```
+
+group_vars/all
+
+``` none
+ansible_connection: ansible.netcommon.network_cli
+ansible_network_os: vyos.vyos.vyos
+
+# user and password gets from terraform variables "admin_username" and "admin_password" in the file /root/azvyos/var.tf
+ansible_user: vyos
+ansible_ssh_pass: "{{ vault_vyos_ssh_pass }}"
+```
+
+## Sourse files for Azure from GIT
+
+All files about the article can be found [here](https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Azure_terraform_ansible_single_vyos_instance-main)
diff --git a/docs/automation/terraform/md-terraformGoogle.md b/docs/automation/terraform/md-terraformGoogle.md
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/docs/automation/terraform/md-terraformGoogle.md
@@ -0,0 +1 @@
+
diff --git a/docs/automation/terraform/md-terraformvSphere.md b/docs/automation/terraform/md-terraformvSphere.md
new file mode 100644
index 00000000..2e5d3927
--- /dev/null
+++ b/docs/automation/terraform/md-terraformvSphere.md
@@ -0,0 +1,372 @@
+lastproofread
+2024-03-03
+
+# Deploying VyOS in the vSphere infrastructure
+
+With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the vSphere.
+Also we will make provisioning using Ansible.
+
+In this case, we'll create the necessary files for Terraform and Ansible next using Terraform we'll create a single instance on the vSphere cloud and make provisioning using Ansible.
+
+## Preparation steps for deploying VyOS on vSphere
+
+How to create a single instance and install your configuration using Terraform+Ansible+vSphere
+Step by step:
+
+vSphere
+
+> 1 Collect all data in to file "terraform.tfvars" and create resources for example "terraform"
+
+Terraform
+
+> 1 Create an UNIX or Windows instance
+>
+> 2 Download and install Terraform
+>
+> 3 Create the folder for example /root/vsphereterraform
+
+``` none
+mkdir /root/vsphereterraform
+
+
+ 4 Copy all files into your Terraform project "/root/vsphereterraform" (vyos.tf, var.tf, terraform.tfvars,version.tf), more detailed see `Structure of files Terrafom for vSphere`_
+
+ 5 Type the commands :
+```
+
+``` none
+cd /<your folder>
+terraform init
+```
+
+Ansible
+
+> 1 Create an UNIX instance whenever you want (local, cloud, and so on)
+>
+> 2 Download and install Ansible
+>
+> 3 Create the folder for example /root/vsphereterraform/
+>
+> 4 Copy all files into your Ansible project "/root/vsphereterraform/" (ansible.cfg, instance.yml,"all"), more detailed see [Structure of files Ansible for vSphere](#structure-of-files-ansible-for-vsphere)
+
+Start
+
+Type the commands on your Terrafom instance:
+
+``` none
+cd /<your folder>
+terraform plan
+terraform apply
+yes
+```
+
+After executing all the commands you will have your VyOS instance on the vSphere with your configuration, it's a very convenient desition.
+If you need to delete the instance please type the command:
+
+``` none
+terraform destroy
+```
+
+## Structure of files Terrafom for vSphere
+
+``` none
+.
+├── vyos.tf # The main script
+├── versions.tf # File for the changing version of Terraform.
+├── var.tf # File for the changing version of Terraform.
+└── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on)
+```
+
+## File contents of Terrafom for vSphere
+
+vyos.tf
+
+``` none
+provider "vsphere" {
+ user = var.vsphere_user
+ password = var.vsphere_password
+ vsphere_server = var.vsphere_server
+ allow_unverified_ssl = true
+}
+
+data "vsphere_datacenter" "datacenter" {
+ name = var.datacenter
+}
+
+data "vsphere_datastore" "datastore" {
+ name = var.datastore
+ datacenter_id = data.vsphere_datacenter.datacenter.id
+}
+
+data "vsphere_compute_cluster" "cluster" {
+ name = var.cluster
+ datacenter_id = data.vsphere_datacenter.datacenter.id
+}
+
+data "vsphere_resource_pool" "default" {
+ name = format("%s%s", data.vsphere_compute_cluster.cluster.name, "/Resources/terraform") # set as you need
+ datacenter_id = data.vsphere_datacenter.datacenter.id
+}
+
+data "vsphere_host" "host" {
+ name = var.host
+ datacenter_id = data.vsphere_datacenter.datacenter.id
+}
+
+data "vsphere_network" "network" {
+ name = var.network_name
+ datacenter_id = data.vsphere_datacenter.datacenter.id
+}
+
+# Deployment of VM from Remote OVF
+resource "vsphere_virtual_machine" "vmFromRemoteOvf" {
+ name = var.remotename
+ datacenter_id = data.vsphere_datacenter.datacenter.id
+ datastore_id = data.vsphere_datastore.datastore.id
+ host_system_id = data.vsphere_host.host.id
+ resource_pool_id = data.vsphere_resource_pool.default.id
+ network_interface {
+ network_id = data.vsphere_network.network.id
+ }
+ wait_for_guest_net_timeout = 2
+ wait_for_guest_ip_timeout = 2
+
+ ovf_deploy {
+ allow_unverified_ssl_cert = true
+ remote_ovf_url = var.url_ova
+ disk_provisioning = "thin"
+ ip_protocol = "IPv4"
+ ip_allocation_policy = "dhcpPolicy"
+ ovf_network_map = {
+ "Network 1" = data.vsphere_network.network.id
+ "Network 2" = data.vsphere_network.network.id
+ }
+ }
+ vapp {
+ properties = {
+ "password" = "12345678",
+ "local-hostname" = "terraform_vyos"
+ }
+ }
+}
+
+output "ip" {
+ description = "default ip address of the deployed VM"
+ value = vsphere_virtual_machine.vmFromRemoteOvf.default_ip_address
+}
+
+# IP of vSphere instance copied to a file ip.txt in local system
+
+resource "local_file" "ip" {
+ content = vsphere_virtual_machine.vmFromRemoteOvf.default_ip_address
+ filename = "ip.txt"
+}
+
+#Connecting to the Ansible control node using SSH connection
+
+resource "null_resource" "nullremote1" {
+depends_on = ["vsphere_virtual_machine.vmFromRemoteOvf"]
+connection {
+ type = "ssh"
+ user = "root"
+ password = var.ansiblepassword
+ host = var.ansiblehost
+
+}
+
+# Copying the ip.txt file to the Ansible control node from local system
+
+ provisioner "file" {
+ source = "ip.txt"
+ destination = "/root/vsphere/ip.txt"
+ }
+}
+
+resource "null_resource" "nullremote2" {
+depends_on = ["vsphere_virtual_machine.vmFromRemoteOvf"]
+connection {
+ type = "ssh"
+ user = "root"
+ password = var.ansiblepassword
+ host = var.ansiblehost
+}
+
+# Command to run ansible playbook on remote Linux OS
+
+provisioner "remote-exec" {
+
+ inline = [
+ "cd /root/vsphere/",
+ "ansible-playbook instance.yml"
+]
+}
+}
+```
+
+versions.tf
+
+``` none
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+terraform {
+ required_providers {
+ vsphere = {
+ source = "hashicorp/vsphere"
+ version = "2.4.0"
+ }
+ }
+}
+```
+
+var.tf
+
+``` none
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+variable "vsphere_server" {
+ description = "vSphere server"
+ type = string
+}
+
+variable "vsphere_user" {
+ description = "vSphere username"
+ type = string
+}
+
+variable "vsphere_password" {
+ description = "vSphere password"
+ type = string
+ sensitive = true
+}
+
+variable "datacenter" {
+ description = "vSphere data center"
+ type = string
+}
+
+variable "cluster" {
+ description = "vSphere cluster"
+ type = string
+}
+
+variable "datastore" {
+ description = "vSphere datastore"
+ type = string
+}
+
+variable "network_name" {
+ description = "vSphere network name"
+ type = string
+}
+
+variable "host" {
+ description = "name if yor host"
+ type = string
+}
+
+variable "remotename" {
+ description = "the name of you VM"
+ type = string
+}
+
+variable "url_ova" {
+ description = "the URL to .OVA file or cloude store"
+ type = string
+}
+
+variable "ansiblepassword" {
+ description = "Ansible password"
+ type = string
+}
+
+variable "ansiblehost" {
+ description = "Ansible host name or IP"
+ type = string
+}
+```
+
+terraform.tfvars
+
+``` none
+vsphere_user = ""
+vsphere_password = ""
+vsphere_server = ""
+datacenter = ""
+datastore = ""
+cluster = ""
+network_name = ""
+host = ""
+url_ova = ""
+ansiblepassword = ""
+ansiblehost = ""
+remotename = ""
+```
+
+## Structure of files Ansible for vSphere
+
+``` none
+.
+├── group_vars
+ └── all
+├── ansible.cfg
+└── instance.yml
+```
+
+## File contents of Ansible for vSphere
+
+ansible.cfg
+
+``` none
+[defaults]
+inventory = /root/vsphere/ip.txt
+host_key_checking= False
+remote_user=vyos
+```
+
+instance.yml
+
+``` none
+##############################################################################
+# About tasks:
+# "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds
+# "Configure general settings for the VyOS hosts group" - make provisioning into vSphere VyOS node
+# You have to add all necessary commands of VyOS under the block "lines:"
+##############################################################################
+
+
+- name: integration of terraform and ansible
+ hosts: all
+ gather_facts: 'no'
+
+ tasks:
+
+ - name: "Wait 300 seconds, but only start checking after 60 seconds"
+ wait_for_connection:
+ delay: 60
+ timeout: 300
+
+ - name: "Configure general settings for the VyOS hosts group"
+ vyos_config:
+ lines:
+ - set system name-server 8.8.8.8
+ save:
+ true
+```
+
+group_vars/all
+
+``` none
+ansible_connection: ansible.netcommon.network_cli
+ansible_network_os: vyos.vyos.vyos
+
+# user and password gets from terraform variables "admin_username" and "admin_password"
+ansible_user: vyos
+# get from vyos.tf "vapp"
+ansible_ssh_pass: 12345678
+```
+
+## Sourse files for vSphere from GIT
+
+All files about the article can be found [here](https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Vsphere_terraform_ansible_single_vyos_instance-main)
diff --git a/docs/automation/terraform/md-terraformvyos.md b/docs/automation/terraform/md-terraformvyos.md
new file mode 100644
index 00000000..78606cba
--- /dev/null
+++ b/docs/automation/terraform/md-terraformvyos.md
@@ -0,0 +1,31 @@
+lastproofread
+2024-03-03
+
+# Terraform for VyOS
+
+VyOS supports development infrastructure via Terraform and provisioning via Ansible.
+Terraform allows you to automate the process of deploying instances on many cloud and virtual platforms.
+In this article, we will look at using terraforms to deploy VyOS on platforms - AWS, Azure, and vSphere.
+For more details about Terraform please have a look here [link](https://developer.hashicorp.com/terraform/intro).
+
+Need to [install](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) Terraform
+
+Structure of files in the standard Terraform project:
+
+``` none
+.
+├── main.tf # The main script
+├── version.tf # File for the changing version of Terraform.
+├── variables.tf # The file of all variables in "main.tf"
+└── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on)
+```
+
+General commands that we will use for running Terraform scripts
+
+``` none
+cd /<your folder> # go to the Terrafom project
+terraform init # install all addons and provider (aws az and so on)
+terraform plan # show what is changing
+terraform apply # run script
+yes # apply running
+```
generated by cgit v1.2.3 (git 2.39.1) at 2026-08-31 21:21:29 +0000