From b6ff49dc4873e370083205d2f12bb2eb3894c7bc Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Sun, 10 May 2026 17:23:58 +0300 Subject: chore: remove RST swap mechanism, archive rst-*.rst under docs/_rst_legacy/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The swap mechanism (RST-as-fallback for migrated MD pages) is dormant — docs/_rst_overrides.txt has been empty since the MyST flip trio (#1899/#1900/#1901) landed. The mechanism's surface area is dead weight and the rst-*.rst shadows scattered across the source tree cause Context7's parser to misclassify the project as RST. Sibling PR on rolling: yuriy/remove-rst-swap-mechanism Changes: - Move 253 rst-*.rst shadow files into docs/_rst_legacy/ preserving subdirectory structure. They remain in the repo for reference; Sphinx excludes the folder via exclude_patterns. - Strip swap_sources.py invocation from docs/Makefile. - Strip jobs: pre_build/post_build block from .readthedocs.yml. - Strip rst-*.rst exclude entry and the _md_exclude.txt loader from docs/conf.py; replace with a single _rst_legacy exclude. - Delete scripts/swap_sources.py, tests/test_swap_sources.py, docs/_rst_overrides.txt. - Update AGENTS.md: drop the "RST override mechanism" section and the test-runner snippet for the deleted test. Verified: sphinx-build -b html with --keep-going produces identical warning set (68 unique), identical sitemap entry count (267), identical llms.txt entry count (22), zero rst-* URLs in any artifact. 🤖 Generated by [robots](https://vyos.io) --- docs/automation/rst-cloud-init.rst | 435 ------------- docs/automation/rst-command-scripting.rst | 224 ------- docs/automation/rst-index.rst | 17 - docs/automation/rst-vyos-ansible.rst | 93 --- docs/automation/rst-vyos-api.rst | 596 ----------------- docs/automation/rst-vyos-govyos.rst | 203 ------ docs/automation/rst-vyos-napalm.rst | 144 ----- docs/automation/rst-vyos-netmiko.rst | 72 --- docs/automation/rst-vyos-pyvyos.rst | 156 ----- docs/automation/rst-vyos-salt.rst | 216 ------- docs/automation/terraform/rst-index.rst | 14 - docs/automation/terraform/rst-terraformAWS.rst | 547 ---------------- docs/automation/terraform/rst-terraformAZ.rst | 488 -------------- docs/automation/terraform/rst-terraformGoogle.rst | 708 --------------------- docs/automation/terraform/rst-terraformvSphere.rst | 415 ------------ 15 files changed, 4328 deletions(-) delete mode 100644 docs/automation/rst-cloud-init.rst delete mode 100644 docs/automation/rst-command-scripting.rst delete mode 100644 docs/automation/rst-index.rst delete mode 100644 docs/automation/rst-vyos-ansible.rst delete mode 100644 docs/automation/rst-vyos-api.rst delete mode 100644 docs/automation/rst-vyos-govyos.rst delete mode 100644 docs/automation/rst-vyos-napalm.rst delete mode 100644 docs/automation/rst-vyos-netmiko.rst delete mode 100644 docs/automation/rst-vyos-pyvyos.rst delete mode 100644 docs/automation/rst-vyos-salt.rst delete mode 100644 docs/automation/terraform/rst-index.rst delete mode 100644 docs/automation/terraform/rst-terraformAWS.rst delete mode 100644 docs/automation/terraform/rst-terraformAZ.rst delete mode 100644 docs/automation/terraform/rst-terraformGoogle.rst delete mode 100644 docs/automation/terraform/rst-terraformvSphere.rst (limited to 'docs/automation') diff --git a/docs/automation/rst-cloud-init.rst b/docs/automation/rst-cloud-init.rst deleted file mode 100644 index f2ecaa77..00000000 --- a/docs/automation/rst-cloud-init.rst +++ /dev/null @@ -1,435 +0,0 @@ -:lastproofread: 2024-07-03 - -.. _cloud-init: - -############### -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`_. - -* ``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. - -After the ``vyos_config_commands`` are executed, cloud-init will -automatically perform a ``commit`` and ``save`` operation. - -Here is an example cloud-config that appends configuration at the time of -first boot. - -.. code-block:: 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 :ref:`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. - -.. code-block:: 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. - -.. code-block:: 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. 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. - -.. code-block:: 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. - -.. code-block:: 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 `nocloud`_ 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: - -.. code-block:: none - - sudo grep vyos /var/log/cloud-init.log - -********************* -Cloud-init on Proxmox -********************* - -Before starting, please refer to cloud-init `network-config-docs`_ 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. Bear in mind that this configuration will be - injected 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`_ 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: - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: sh - - cd /tmp/ - -**user-data** file must start with ``#cloud-config`` and contains -vyos-commands. For example: - -.. code-block:: 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: - -.. code-block:: 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`` - -.. code-block:: 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`` - -.. code-block:: sh - - mv /tmp/seed.iso /var/lib/vz/template/iso/ - -On proxmox server: - -.. code-block:: 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`_. - -* Cloud-init `network-config-docs`_. - -* Proxmox `Cloud-init-Support`_. - -.. stop_vyoslinter - -.. _network-config-docs: https://cloudinit.readthedocs.io/en/latest/topics/network-config.html -.. _vyos-vm-images: https://github.com/vyos/vyos-vm-images -.. _cloud-init-docs: https://docs.vyos.io/en/equuleus/automation/cloud-init.html?highlight=cloud-init#vyos-cloud-init -.. _Cloud-init-Support: https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_cloud_init -.. _Cloud-init-write_files: https://cloudinit.readthedocs.io/en/latest/topics/examples.html#writing-out-arbitrary-files -.. _nocloud: https://cloudinit.readthedocs.io/en/latest/reference/datasources/nocloud.html -.. start_vyoslinter diff --git a/docs/automation/rst-command-scripting.rst b/docs/automation/rst-command-scripting.rst deleted file mode 100644 index 91086b42..00000000 --- a/docs/automation/rst-command-scripting.rst +++ /dev/null @@ -1,224 +0,0 @@ -:lastproofread: 2026-03-16 - -.. _command-scripting: - -Command scripting -================= - -VyOS supports executing configuration and operational commands non-interactively -from shell scripts. - -To include VyOS-specific functions and aliases, source the -``/opt/vyatta/etc/functions/script-template`` file at the beginning of your -script. - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - exit - -Script execute permissions --------------------------- - -Simply placing script files in ``/config/scripts/`` does not mean the system -can execute them. - -To make your scripts executable, grant them **execute permissions**. Use the -following command: - -.. code-block:: none - - chmod +x /config/scripts/script-name.sh - -Run configuration commands --------------------------- - -In scripts, present configuration commands as in a standard configuration -session. - -For example, to disable a BGP peer during a VRRP transition to the backup -state, use the following syntax: - -.. code-block:: 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 ------------------------- - -In scripts, **always** prefix operational commands with ``run``. - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - run show interfaces - exit - -Run commands remotely ---------------------- - -You can execute multiple **operational commands** on a remote VyOS system by -passing a script block over SSH. - -.. code-block:: none - - ssh 192.0.2.1 'vbash -s' < 0. An example follows, in the alternative JSON format, for brevity, -although the standard form-data format is fine: - -.. code-block:: none - - curl -k -X POST -d '{"key": "MY-HTTPS-API-PLAINTEXT-KEY", "op": "merge", "string": "interfaces {\nethernet eth1 {\naddress '192.168.137.1/24'\ndescription 'internal'\n}\n}\n", "confirm_time": 1}' https://vyos/config-file - - response: - { - "success": true, - "data": "Initialized commit-confirm; 1 minutes to confirm before reload\n", - "error": null - } - -The committed changes will be reverted at the timeout unless confirmed. -To confirm and keep the changes: - -.. code-block:: none - - curl -k -X POST -d '{"key": "MY-HTTPS-API-PLAINTEXT-KEY", "op": "confirm"}' https://vyos/config-file - - response: - { - "success": true, - "data": "Reload timer stopped\n", - "error": null - } - -If allowed to revert to the previous configuration, the manner in which -changes are reverted is governed by: - -.. code-block:: none - - vyos@vyos# set system config-management commit-confirm action - Possible completions: - reload Reload previous configuration if not confirmed - reboot Reboot to saved configuration if not confirmed (default) diff --git a/docs/automation/rst-vyos-govyos.rst b/docs/automation/rst-vyos-govyos.rst deleted file mode 100644 index 32222441..00000000 --- a/docs/automation/rst-vyos-govyos.rst +++ /dev/null @@ -1,203 +0,0 @@ -:lastproofread: 2024-03-10 - -.. _vyos-govyos: - -go-vyos -======= - -go-vyos is a Go library designed for interacting with VyOS devices through -their REST API. This documentation is intended to guide you in using go-vyos for -programmatic management of your VyOS devices. - -- `go-vyos Documentation & Source Code on GitHub `_ - allows you to access and contribute to the library's code. -- `go-vyos on pkg.go.dev `_ for detailed instructions - on the installation, configuration, and operation of the go-vyos library. - - -Installation ------------- - -You can install go-vyos: - -.. code-block:: bash - - go install "github.com/ganawaj/go-vyos/vyos" - -Getting Started ---------------- - -Importing and Disabling TLS Verification -------------------------------------------------- - -.. code-block:: none - - import "github.com/ganawaj/go-vyos/vyos" - client := vyos.NewClient(nil).WithToken("AUTH_KEY").WithURL("https://192.168.0.1").Insecure() - -Initializing a VyDevice Object ------------------------------- - -.. code-block:: none - - import ( - "github.com/ganawaj/go-vyos/vyos" - "os" - ) - - hostname := os.Getenv('VYDEVICE_HOSTNAME') - port := os.Getenv('VYDEVICE_PORT') - url := fmt.Sprintf("https://%s:%s", hostname, port) - - apikey := os.Getenv('VYDEVICE_APIKEY') - verify_ssl := os.Getenv('VYDEVICE_VERIFY_SSL') - - client := vyos.NewClient(nil).WithToken(apikey).WithURL(url) - - if verify_ssl == "false" { - client = client.Insecure() - } - -Using go-vyos ----------------- - -Configure, then Set -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - out, resp, err := c.Conf.Set(ctx, "interfaces ethernet eth0 address 192.168.1.1/24") - if err != nil { - panic("Error: %v", err) - } - - fmt.Println(out.Success) - -Show a Single Object Value -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - out, resp, err := c.Show.Do(ctx, "interfaces dummy dum1 address") - if err != nil { - panic("Error: %v", err) - } - - fmt.Println(out.Success) - fmt.Printf("Data: %v\n", out.Data) - -Configure, then Show Object -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - out, resp, err := c.Conf.Get(ctx, "interfaces dummy dum1", nil) - if err != nil { - panic("Error: %v", err) - } - - fmt.Println(out.Success) - fmt.Printf("Data: %v\n", out.Data) - -Configure, then Show Multivalue Object -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - options := RetrieveOptions{ - Multivalue: true, - } - - out, resp, err := c.Conf.Get(ctx, "interfaces dummy dum1", options) - if err != nil { - panic("Error: %v", err) - } - - fmt.Println(out.Success) - - -Configure, then Delete Object -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - out, resp, err := c.Conf.Delete(ctx, "interfaces dummy dum1") - if err != nil { - panic("Error: %v", err) - } - - fmt.Println(out.Success) - -Configure, then Save -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - out, resp, err := c.Conf.Save(ctx, "") - - if err != nil { - panic("Error: %v", err) - } - - fmt.Println(out.Success) - -Configure, then Save File -------------------------- - -.. code-block:: none - - out, resp, err := c.Conf.Save(ctx, "/config/test300.config") - - if err != nil { - panic("Error: %v", err) - } - - fmt.Println(out.Success) - -Show Object -^^^^^^^^^^^^^^ - -.. code-block:: none - - out, resp, err := c.Show.Do(ctx, "system image") - if err != nil { - panic("Error: %v", err) - } - - fmt.Println(out.Success) - fmt.Printf("Data: %v\n", out.Data) - -Generate Object -^^^^^^^^^^^^^^^^ - -.. code-block:: none - - out, resp, err := c.Generate.Do(ctx, "pki wireguard key-pair") - if err != nil { - panic("Error: %v", err) - } - - fmt.Println(out.Success) - fmt.Printf("Data: %v\n", out.Data) - -Reset Object -^^^^^^^^^^^^^^ - -.. code-block:: none - - out, resp, err := c.Reset.Do(ctx, "ip bgp 192.0.2.11") - if err != nil { - panic("Error: %v", err) - } - - fmt.Println(out.Success) - fmt.Printf("Data: %v\n", out.Data) - -Configure, then Load File -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - out, resp, err := c.ConfigFile.Load(ctx, "/config/test300.config") - -.. _go-vyos: https://github.com/ganawaj/go-vyos \ No newline at end of file diff --git a/docs/automation/rst-vyos-napalm.rst b/docs/automation/rst-vyos-napalm.rst deleted file mode 100644 index 75e20b3c..00000000 --- a/docs/automation/rst-vyos-napalm.rst +++ /dev/null @@ -1,144 +0,0 @@ -:lastproofread: 2023-01-16 - -.. _vyos-napalm: - -Napalm -====== - -VyOS supports some napalm_ functions for configuration and op-mode. -It requires more tests. - -Install ``napalm-vyos`` module - -.. code-block:: none - - apt install python3-pip - pip3 install napalm - pip3 install napalm-vyos - - -Op-mode -------- - -.. code-block:: 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 - -.. code-block:: 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 - -.. code-block:: 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 - -.. code-block:: 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 - -.. code-block:: 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] - -.. _napalm: https://napalm.readthedocs.io/en/latest/base.html \ No newline at end of file diff --git a/docs/automation/rst-vyos-netmiko.rst b/docs/automation/rst-vyos-netmiko.rst deleted file mode 100644 index 075b0f34..00000000 --- a/docs/automation/rst-vyos-netmiko.rst +++ /dev/null @@ -1,72 +0,0 @@ -:lastproofread: 2023-01-16 - -.. _vyos-netmiko: - -Netmiko -======= - -VyOS supports configuration via netmiko_. -It requires to install ``python3-netmiko`` module. - -Example -------- - -.. code-block:: 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 - -.. code-block:: 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] - -.. _netmiko: https://github.com/ktbyers/netmiko diff --git a/docs/automation/rst-vyos-pyvyos.rst b/docs/automation/rst-vyos-pyvyos.rst deleted file mode 100644 index 948534f8..00000000 --- a/docs/automation/rst-vyos-pyvyos.rst +++ /dev/null @@ -1,156 +0,0 @@ -:lastproofread: 2024-03-10 - -.. _vyos-pyvyos: - -pyvyos -====== - -pyvyos is a Python library designed for interacting with VyOS devices through -their API. This documentation is intended to guide you in using pyvyos for -programmatic management of your VyOS devices. - -- `pyvyos Documentation on Read the Docs - `_ provides detailed instructions - on the installation, configuration, and operation of the pyvyos library. -- `pyvyos Source Code on GitHub `_ - allows you to access and contribute to the library's code. -- `pyvyos on PyPI `_ for easy installation - via pip, the Python package installer. Execute `pip install pyvyos` in your - terminal to install. - - -Installation ------------- - -You can install pyvyos using pip: - -.. code-block:: bash - - pip install pyvyos - -Getting Started ---------------- - -Importing and Disabling Warnings for verify=False -------------------------------------------------- - -.. code-block:: none - - import urllib3 - urllib3.disable_warnings() - -Using API Response Class ------------------------- - -.. code-block:: none - - @dataclass - class ApiResponse: - status: int - request: dict - result: dict - error: str - -Initializing a VyDevice Object ------------------------------- - -.. code-block:: none - - from dotenv import load_dotenv - load_dotenv() - - hostname = os.getenv('VYDEVICE_HOSTNAME') - apikey = os.getenv('VYDEVICE_APIKEY') - port = os.getenv('VYDEVICE_PORT') - protocol = os.getenv('VYDEVICE_PROTOCOL') - verify_ssl = os.getenv('VYDEVICE_VERIFY_SSL') - - verify = verify_ssl.lower() == "true" if verify_ssl else True - - device = VyDevice(hostname=hostname, apikey=apikey, port=port, protocol=protocol, verify=verify) - -Using pyvyos ------------- - -Configure, then Set -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - response = device.configure_set(path=["interfaces", "ethernet", "eth0", "address", "192.168.1.1/24"]) - if not response.error: - print(response.result) - -Configure, then Show a Single Object Value -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - response = device.retrieve_return_values(path=["interfaces", "dummy", "dum1", "address"]) - print(response.result) - -Configure, then Show Object -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - response = device.retrieve_show_config(path=[]) - if not response.error: - print(response.result) - -Configure, then Delete Object -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - response = device.configure_delete(path=["interfaces", "dummy", "dum1"]) - -Configure, then Save -^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - response = device.config_file_save() - -Configure, then Save File -------------------------- - -.. code-block:: none - - response = device.config_file_save(file="/config/test300.config") - -Show Object -^^^^^^^^^^^^^^ - -.. code-block:: none - - response = device.show(path=["system", "image"]) - print(response.result) - -Generate Object -^^^^^^^^^^^^^^^^ - -.. code-block:: none - - randstring = ''.join(random.choice(string.ascii_letters + string.digits) for _ in range(20)) - keyrand = f'/tmp/key_{randstring}' - response = device.generate(path=["ssh", "client-key", keyrand]) - -Reset Object -^^^^^^^^^^^^^^ - -.. code-block:: none - - response = device.reset(path=["conntrack-sync", "internal-cache"]) - if not response.error: - print(response.result) - -Configure, then Load File -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - response = device.config_file_load(file="/config/test300.config") - - -.. _pyvyos: https://github.com/robertoberto/pyvyos diff --git a/docs/automation/rst-vyos-salt.rst b/docs/automation/rst-vyos-salt.rst deleted file mode 100644 index 12be32a1..00000000 --- a/docs/automation/rst-vyos-salt.rst +++ /dev/null @@ -1,216 +0,0 @@ -:lastproofread: 2023-01-16 - -.. _vyos-salt: - -.. include:: /_include/need_improvement.txt - -Salt -==== - -VyOS supports op-mode and configuration via salt_. - -Without proxy it requires VyOS minion configuration -and supports op-mode data: - -.. code-block:: none - - set service salt-minion id 'r14' - set service salt-minion master '192.0.2.250' - -Check salt-keys on the salt master - -.. code-block:: none - - / # salt-key --list-all - Accepted Keys: - r11 - Denied Keys: - Unaccepted Keys: - r14 - Rejected Keys: - -Accept minion key - -.. code-block:: 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 - -.. code-block:: none - - / # salt '*' test.ping - r14: - True - r11: - True - -At this step we can get some op-mode information from VyOS nodes: - -.. code-block:: 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_ 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: - -.. code-block:: none - - / # cat /etc/salt/master - file_roots: - base: - - /srv/salt/states - - pillar_roots: - base: - - /srv/salt/pillars - -Structure of /srv/salt: - -.. code-block:: none - - / # tree /srv/salt/ - /srv/salt/ - |___ pillars - | |__ r11-proxy.sls - | |__ top.sls - |___ states - |__ commands.txt - -top.sls - -.. code-block:: none - - / # cat /srv/salt/pillars/top.sls - base: - r11-proxy: - - r11-proxy - - -r11-proxy.sls Includes parameters for connecting to salt-proxy minion - -.. code-block:: 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 - -.. code-block:: 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: - -.. code-block:: none - - / # salt r11-proxy test.ping - r11-proxy: - True - / # - -Examples -^^^^^^^^ - -Example of op-mode: - -.. code-block:: 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: - -.. code-block:: 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" - -.. code-block:: 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# - / # - -.. _salt: https://docs.saltproject.io/en/latest/contents.html -.. _netmiko: https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.netmiko_mod.html#module-salt.modules.netmiko_mod \ No newline at end of file diff --git a/docs/automation/terraform/rst-index.rst b/docs/automation/terraform/rst-index.rst deleted file mode 100644 index 42af58bd..00000000 --- a/docs/automation/terraform/rst-index.rst +++ /dev/null @@ -1,14 +0,0 @@ -############## -VyOS Terraform -############## - -.. toctree:: - :maxdepth: 1 - :caption: Content - - terraformvyos - terraformAWS - terraformAZ - terraformvSphere - terraformGoogle - diff --git a/docs/automation/terraform/rst-terraformAWS.rst b/docs/automation/terraform/rst-terraformAWS.rst deleted file mode 100644 index e068377d..00000000 --- a/docs/automation/terraform/rst-terraformAWS.rst +++ /dev/null @@ -1,547 +0,0 @@ -:lastproofread: 2024-01-11 - -.. _terraformAWS: - -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. - - -.. image:: /_static/images/aws.png - :width: 50% - :align: center - :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_ and download your .pem key - -.. image:: /_static/images/keypairs.png - :width: 50% - :align: center - :alt: Network Topology Diagram - -3 Create a security group_ for the new VyOS instance and open all traffic - -.. image:: /_static/images/sg.png - :width: 50% - :align: center - :alt: Network Topology Diagram - - -.. image:: /_static/images/traffic.png - :width: 50% - :align: center - :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 - -.. code-block:: 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 : - -.. code-block:: none - - cd / - 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`_ - -mykey.pem you have to get using step 1.2 - - -Start - - -Type the commands on your Terrafom instance: - -.. code-block:: none - - cd / - terraform plan - terraform apply - yes - - -Start creating an AWS instance and check the result ---------------------------------------------------- - -.. code-block:: 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: - -.. code-block:: 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 - -.. code-block:: 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 ------------------------------------ - -.. code-block:: 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 - -.. code-block:: 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 - -.. code-block:: 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 - -.. code-block:: none - - terraform { - required_providers { - aws = { - source = "hashicorp/aws" - version = "~> 5.0" - } - } - } - -terraform.tfvars - -.. code-block:: 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 ----------------------------------- - -.. code-block:: none - - . - ├── group_vars - └── all - ├── ansible.cfg - ├── mykey.pem - └── instance.yml - - -File contents of Ansible for AWS --------------------------------- - -ansible.cfg - -.. code-block:: 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 - -.. code-block:: none - - Copy your key.pem from AWS - - -instance.yml - - - -.. code-block:: 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 - -.. code-block:: 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_ - - -.. _link: https://developer.hashicorp.com/terraform/intro -.. _install: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli -.. _pair: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html -.. _group: https://docs.aws.amazon.com/cli/latest/userguide/cli-services-ec2-sg.html -.. _image: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html -.. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/AWS_terraform_ansible_single_vyos_instance-main \ No newline at end of file diff --git a/docs/automation/terraform/rst-terraformAZ.rst b/docs/automation/terraform/rst-terraformAZ.rst deleted file mode 100644 index a0fea023..00000000 --- a/docs/automation/terraform/rst-terraformAZ.rst +++ /dev/null @@ -1,488 +0,0 @@ -:lastproofread: 2024-03-03 - -.. _terraformAZ: - -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/ - -.. code-block:: 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 - -.. code-block:: none - - az login - -2.6 Type the commands : - -.. code-block:: none - - cd / - 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`_ - - -Start - - -Type the commands on your Terrafom instance: - -.. code-block:: none - - cd / - 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: - -.. code-block:: none - - terraform destroy - -Structure of files Terrafom for Azure -------------------------------------- - -.. code-block:: 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 - -.. code-block:: 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 - -.. code-block:: 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" - default = "Vyos0!" - } - - 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 - -.. code-block:: none - - password = "" # password for Ansible SSH - host = "" # IP of my Ansible - - -Structure of files Ansible for Azure ------------------------------------- - -.. code-block:: none - - . - ├── group_vars - └── all - ├── ansible.cfg - └── instance.yml - - -File contents of Ansible for Azure ----------------------------------- - -ansible.cfg - -.. code-block:: none - - [defaults] - inventory = /root/az/ip.txt - host_key_checking= False - remote_user=vyos - - -instance.yml - - -.. code-block:: 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 - -.. code-block:: 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: Vyos0! - -Sourse files for Azure from GIT -------------------------------- - -All files about the article can be found here_ - -.. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Azure_terraform_ansible_single_vyos_instance-main - - diff --git a/docs/automation/terraform/rst-terraformGoogle.rst b/docs/automation/terraform/rst-terraformGoogle.rst deleted file mode 100644 index 41a484c5..00000000 --- a/docs/automation/terraform/rst-terraformGoogle.rst +++ /dev/null @@ -1,708 +0,0 @@ -:lastproofread: 2024-03-25 - -.. _terraformgoogle: - -Deploying VyOS in the Google Cloud -================================== - -With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the Google 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 Google Cloud and make provisioning using Ansible. - -Preparation steps for deploying VyOS on Google ----------------------------------------------- - -How to create a single instance and install your configuration using Terraform+Ansible+Google -Step by step: - -Google Cloud - - -1 Create an account with Google Cloud and a new project - -.. image:: /_static/images/project.png - :width: 50% - :align: center - :alt: Network Topology Diagram - -2 Create a service aacount and download your key (.JSON) - -.. image:: /_static/images/service.png - :width: 50% - :align: center - :alt: Network Topology Diagram - -.. image:: /_static/images/key.png - :width: 50% - :align: center - :alt: Network Topology Diagram - -The .JSON file download automaticly after creating and will look like: - -.. image:: /_static/images/json.png - :width: 50% - :align: center - :alt: Network Topology Diagram - - -Terraform - - -1 Create an UNIX or Windows instance - -2 Download and install Terraform - -3 Create the folder for example /root/google - -.. code-block:: none - - mkdir /root/google - -4 Copy all files into your Terraform project "/root/google" (vyos.tf, var.tf, terraform.tfvars, .JSON), more detailed see `Structure of files Terrafom for google cloud`_ - -5 Type the commands : - - -.. code-block:: none - - cd / - 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/google/ - -4 Copy all files into your Ansible project "/root/google/" (ansible.cfg, instance.yml, mykey.json and "all"), more detailed see `Structure of files Ansible for Google Cloud`_ - -mykey.json you have to get using step 2 of the Google Cloud - - -Start - - -Type the commands on your Terraform instance: - -.. code-block:: none - - cd / - terraform plan - terraform apply - yes - - -Start creating a Google Cloud instance and check the result. ------------------------------------------------------------ - -.. code-block:: none - - # 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: - - # google_compute_firewall.tcp_22[0] will be created - + resource "google_compute_firewall" "tcp_22" { - + creation_timestamp = (known after apply) - + destination_ranges = (known after apply) - + direction = (known after apply) - + enable_logging = (known after apply) - + id = (known after apply) - + name = "vyos-tcp-22" - + network = "default" - + priority = 1000 - + project = "vyosproject" - + self_link = (known after apply) - + source_ranges = [ - + "0.0.0.0/0", - ] - + target_tags = [ - + "vyos-deployment", - ] - - + allow { - + ports = [ - + "22", - ] - + protocol = "tcp" - } - } - - # google_compute_firewall.udp_500_4500[0] will be created - + resource "google_compute_firewall" "udp_500_4500" { - + creation_timestamp = (known after apply) - + destination_ranges = (known after apply) - + direction = (known after apply) - + enable_logging = (known after apply) - + id = (known after apply) - + name = "vyos-udp-500-4500" - + network = "default" - + priority = 1000 - + project = "vyosproject" - + self_link = (known after apply) - + source_ranges = [ - + "0.0.0.0/0", - ] - + target_tags = [ - + "vyos-deployment", - ] - - + allow { - + ports = [ - + "500", - + "4500", - ] - + protocol = "udp" - } - } - - # google_compute_instance.default will be created - + resource "google_compute_instance" "default" { - + can_ip_forward = true - + cpu_platform = (known after apply) - + current_status = (known after apply) - + deletion_protection = false - + effective_labels = (known after apply) - + guest_accelerator = (known after apply) - + id = (known after apply) - + instance_id = (known after apply) - + label_fingerprint = (known after apply) - + machine_type = "n2-highcpu-4" - + metadata = { - + "enable-oslogin" = "FALSE" - + "serial-port-enable" = "TRUE" - + "user-data" = "" - } - + metadata_fingerprint = (known after apply) - + min_cpu_platform = (known after apply) - + name = "vyos" - + project = "vyosproject" - + self_link = (known after apply) - + tags_fingerprint = (known after apply) - + terraform_labels = (known after apply) - + zone = "us-west1-a" - - + boot_disk { - + auto_delete = true - + device_name = (known after apply) - + disk_encryption_key_sha256 = (known after apply) - + kms_key_self_link = (known after apply) - + mode = "READ_WRITE" - + source = (known after apply) - - + initialize_params { - + image = "projects/sentrium-public/global/images/vyos-1-3-5-20231222143039" - + labels = (known after apply) - + provisioned_iops = (known after apply) - + provisioned_throughput = (known after apply) - + size = (known after apply) - + type = (known after apply) - } - } - - + network_interface { - + internal_ipv6_prefix_length = (known after apply) - + ipv6_access_type = (known after apply) - + ipv6_address = (known after apply) - + name = (known after apply) - + network = "default" - + network_ip = (known after apply) - + nic_type = "GVNIC" - + stack_type = (known after apply) - + subnetwork = "default" - + subnetwork_project = (known after apply) - - + access_config { - + nat_ip = (known after apply) - + network_tier = (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: 6 to add, 0 to change, 0 to destroy. - - Changes to Outputs: - + public_ip_address = (known after apply) - ╷ - │ Warning: Quoted references are deprecated - │ - │ on vyos.tf line 126, in resource "null_resource" "SSHconnection1": - │ 126: depends_on = ["google_compute_instance.default"] - │ - │ In this context, references are expected literally rather than in quotes. Terraform 0.11 and earlier required quotes, but quoted references are now deprecated and will be removed in a - │ future version of Terraform. Remove the quotes surrounding this reference to silence this warning. - │ - │ (and one more similar warning elsewhere) - ╵ - - 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 - - google_compute_firewall.udp_500_4500[0]: Creating... - google_compute_firewall.tcp_22[0]: Creating... - google_compute_instance.default: Creating... - google_compute_firewall.udp_500_4500[0]: Still creating... [10s elapsed] - google_compute_firewall.tcp_22[0]: Still creating... [10s elapsed] - google_compute_instance.default: Still creating... [10s elapsed] - google_compute_firewall.tcp_22[0]: Creation complete after 16s [id=projects/vyosproject/global/firewalls/vyos-tcp-22] - google_compute_firewall.udp_500_4500[0]: Creation complete after 16s [id=projects/vyosproject/global/firewalls/vyos-udp-500-4500] - google_compute_instance.default: Creation complete after 20s [id=projects/vyosproject/zones/us-west1-a/instances/vyos] - 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.***.***.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=7d568c3b994a018c942a3cdb952ccbf3c729d0ca] - null_resource.SSHconnection2 (remote-exec): Connected! - null_resource.SSHconnection1: Creation complete after 4s [id=5175298735911137161] - - 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: Still creating... [1m10s elapsed] - null_resource.SSHconnection2 (remote-exec): ok: [104.***.***.158] - - null_resource.SSHconnection2 (remote-exec): TASK [Configure general settings for the vyos hosts group] ********************* - null_resource.SSHconnection2: Still creating... [1m20s elapsed] - null_resource.SSHconnection2 (remote-exec): changed: [104.***.***.158] - - null_resource.SSHconnection2 (remote-exec): PLAY RECAP ********************************************************************* - null_resource.SSHconnection2 (remote-exec): 104.***.***.158 : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - - null_resource.SSHconnection2: Creation complete after 1m22s [id=3355727070503709742] - - Apply complete! Resources: 6 added, 0 changed, 0 destroyed. - - Outputs: - - public_ip_address = "104.***.***.158" - - - -After executing all the commands, you will have your VyOS instance on the Google Cloud with your configuration; it's a very convenient decision. -If you need to delete the instance, please type the command: - -.. code-block:: none - - terraform destroy - - -Troubleshooting ---------------- - -1 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 - -.. code-block:: 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 Google Cloud --------------------------------------------- - -.. code-block:: none - - . - ├── vyos.tf # The main script - ├── ***.JSON # The credential file from Google Cloud - ├── var.tf # The file of all variables in "vyos.tf" - └── terraform.tfvars # The value of all variables (passwords, login, IP addresses and so on) - - - -File contents of Terrafom for Google Cloud ------------------------------------------- - -vyos.tf - -.. code-block:: none - - - ############################################################################## - # Build a VyOS VM from the Marketplace - # - # After deploying the GCP instance and getting an IP address, the IP address is copied into the file - #"ip.txt" and copied to the Ansible node for provisioning. - ############################################################################## - - terraform { - required_providers { - google = { - source = "hashicorp/google" - } - } - } - - provider "google" { - project = var.project_id - request_timeout = "60s" - credentials = file(var.gcp_auth_file) - } - - locals { - network_interfaces = [for i, n in var.networks : { - network = n, - subnetwork = length(var.sub_networks) > i ? element(var.sub_networks, i) : null - external_ip = length(var.external_ips) > i ? element(var.external_ips, i) : "NONE" - } - ] - } - - resource "google_compute_instance" "default" { - name = var.goog_cm_deployment_name - machine_type = var.machine_type - zone = var.zone - - metadata = { - enable-oslogin = "FALSE" - serial-port-enable = "TRUE" - user-data = var.vyos_user_data - } - boot_disk { - initialize_params { - image = var.image - } - } - - can_ip_forward = true - - dynamic "network_interface" { - for_each = local.network_interfaces - content { - network = network_interface.value.network - subnetwork = network_interface.value.subnetwork - nic_type = "GVNIC" - dynamic "access_config" { - for_each = network_interface.value.external_ip == "NONE" ? [] : [1] - content { - nat_ip = network_interface.value.external_ip == "EPHEMERAL" ? null : network_interface.value.external_ip - } - } - } - } - } - - resource "google_compute_firewall" "tcp_22" { - count = var.enable_tcp_22 ? 1 : 0 - - name = "${var.goog_cm_deployment_name}-tcp-22" - network = element(var.networks, 0) - - allow { - ports = ["22"] - protocol = "tcp" - } - - source_ranges = ["0.0.0.0/0"] - - target_tags = ["${var.goog_cm_deployment_name}-deployment"] - } - - resource "google_compute_firewall" "udp_500_4500" { - count = var.enable_udp_500_4500 ? 1 : 0 - - name = "${var.goog_cm_deployment_name}-udp-500-4500" - network = element(var.networks, 0) - - allow { - ports = ["500", "4500"] - protocol = "udp" - } - - source_ranges = ["0.0.0.0/0"] - - target_tags = ["${var.goog_cm_deployment_name}-deployment"] - } - - output "public_ip_address" { - value = google_compute_instance.default.network_interface[0].access_config[0].nat_ip - } - - ############################################################################## - # - # IP of google instance copied to a file ip.txt in local system Terraform - # ip.txt looks like: - # cat ./ip.txt - # ххх.ххх.ххх.ххх - ############################################################################## - - resource "local_file" "ip" { - content = google_compute_instance.default.network_interface[0].access_config[0].nat_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 = ["google_compute_instance.default"] - 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/google/ip.txt" # The folder of your Ansible project - } - } - - resource "null_resource" "SSHconnection2" { - depends_on = ["google_compute_instance.default"] - 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/google/", - "ansible-playbook instance.yml" # more detailed in "File contents of Ansible for Google Cloud" - ] - } - } - - -var.tf - -.. code-block:: none - - variable "image" { - type = string - default = "projects/sentrium-public/global/images/vyos-1-3-5-20231222143039" - } - - variable "project_id" { - type = string - } - - variable "zone" { - type = string - } - - ############################################################################## - # You can choose more chipper type than n2-highcpu-4 - ############################################################################## - - variable "machine_type" { - type = string - default = "n2-highcpu-4" - } - - variable "networks" { - description = "The network name to attach the VM instance." - type = list(string) - default = ["default"] - } - - variable "sub_networks" { - description = "The sub network name to attach the VM instance." - type = list(string) - default = ["default"] - } - - variable "external_ips" { - description = "The external IPs assigned to the VM for public access." - type = list(string) - default = ["EPHEMERAL"] - } - - variable "enable_tcp_22" { - description = "Allow SSH traffic from the Internet" - type = bool - default = true - } - - variable "enable_udp_500_4500" { - description = "Allow IKE/IPSec traffic from the Internet" - type = bool - default = true - } - - variable "vyos_user_data" { - type = string - default = "" - } - - // Marketplace requires this variable name to be declared - variable "goog_cm_deployment_name" { - description = "VyOS Universal Router Deployment" - type = string - default = "vyos" - } - - # GCP authentication file - variable "gcp_auth_file" { - type = string - description = "GCP authentication file" - } - - variable "password" { - description = "pass for Ansible" - type = string - sensitive = true - } - variable "host"{ - description = "The IP of my Ansible" - type = string - } - - -terraform.tfvars - -.. code-block:: none - - ############################################################################## - # Must be filled in - ############################################################################## - - zone = "us-west1-a" - gcp_auth_file = "/root/***/***.json" # path of your .json file - project_id = "" # the google project - password = "" # password for Ansible SSH - host = "" # IP of my Ansible - - -Structure of files Ansible for Google Cloud -------------------------------------------- - -.. code-block:: none - - . - ├── group_vars - └── all - ├── ansible.cfg - └── instance.yml - - -File contents of Ansible for Google Cloud ------------------------------------------ - -ansible.cfg - -.. code-block:: none - - [defaults] - inventory = /root/google/ip.txt - host_key_checking= False - remote_user=vyos - -instance.yml - -.. code-block:: 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 Google Cloud 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 - -.. code-block:: none - - ansible_connection: ansible.netcommon.network_cli - ansible_network_os: vyos.vyos.vyos - ansible_user: vyos - ansible_ssh_pass: vyos - -Sourse files for Google Cloud from GIT --------------------------------------- - -All files about the article can be found here_ - - -.. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Google_terraform_ansible_single_vyos_instance-main diff --git a/docs/automation/terraform/rst-terraformvSphere.rst b/docs/automation/terraform/rst-terraformvSphere.rst deleted file mode 100644 index 5a9aa8f5..00000000 --- a/docs/automation/terraform/rst-terraformvSphere.rst +++ /dev/null @@ -1,415 +0,0 @@ -:lastproofread: 2024-03-03 - -.. _terraformvSphere: - -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 - -.. code-block:: 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 Terraform for vSphere`_ - - 5 Type the commands : - -.. code-block:: none - - cd / - 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`_ - - -Start - - -Type the commands on your Terraform instance: - -.. code-block:: none - - cd / - 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 decision. -If you need to delete the instance please type the command: - -.. code-block:: none - - terraform destroy - - -Structure of files Terraform for vSphere ---------------------------------------- - -.. code-block:: 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 - - -File contents of Terraform for vSphere -------------------------------------- - -vyos.tf - -.. code-block:: 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 - -.. code-block:: none - - # Copyright (c) HashiCorp, Inc. - # SPDX-License-Identifier: MPL-2.0 - - terraform { - required_providers { - vsphere = { - source = "hashicorp/vsphere" - version = "2.4.0" - } - } - } - -var.tf - -.. code-block:: 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 - -.. code-block:: none - - vsphere_user = "" - vsphere_password = "" - vsphere_server = "" - datacenter = "" - datastore = "" - cluster = "" - network_name = "" - host = "" - url_ova = "" - ansiblepassword = "" - ansiblehost = "" - remotename = "" - - -Structure of files Ansible for vSphere --------------------------------------- - -.. code-block:: none - - . - ├── group_vars - └── all - ├── ansible.cfg - └── instance.yml - - -File contents of Ansible for vSphere ------------------------------------- - -ansible.cfg - -.. code-block:: none - - [defaults] - inventory = /root/vsphere/ip.txt - host_key_checking= False - remote_user=vyos - - -instance.yml - -.. code-block:: 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 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 192.0.2.1 - save: - true - - -group_vars/all - -.. code-block:: 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_ - -.. stop_vyoslinter - -.. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Vsphere_terraform_ansible_single_vyos_instance-main - -.. start_vyoslinter - -- cgit v1.2.3