diff --git a/doc/source/deploy_install_guides/release/index-install-r7-8966076f0e81.rst b/doc/source/deploy_install_guides/release/index-install-r7-8966076f0e81.rst index 71879dc4a..588e305a2 100644 --- a/doc/source/deploy_install_guides/release/index-install-r7-8966076f0e81.rst +++ b/doc/source/deploy_install_guides/release/index-install-r7-8966076f0e81.rst @@ -23,6 +23,7 @@ Install StarlingX Kubernetes in a virtual environment .. toctree:: :maxdepth: 1 + virtual/automated_install virtual/aio_simplex virtual/aio_duplex virtual/controller_storage diff --git a/doc/source/deploy_install_guides/release/virtual/aio_simplex.rst b/doc/source/deploy_install_guides/release/virtual/aio_simplex.rst index a3109bbfc..c8108d25a 100644 --- a/doc/source/deploy_install_guides/release/virtual/aio_simplex.rst +++ b/doc/source/deploy_install_guides/release/virtual/aio_simplex.rst @@ -1,6 +1,6 @@ .. _virtual-aio-simplex: -======================================= +======================================= Virtual All-in-one Simplex Installation ======================================= diff --git a/doc/source/deploy_install_guides/release/virtual/automated_install.rst b/doc/source/deploy_install_guides/release/virtual/automated_install.rst new file mode 100644 index 000000000..98d7cbb9c --- /dev/null +++ b/doc/source/deploy_install_guides/release/virtual/automated_install.rst @@ -0,0 +1,152 @@ +============================== +Automated Virtual Installation +============================== + +This automated installer provides you with an easy way to install StarlingX +|this-ver| in different configuration options in a virtual environment. + +.. contents:: + :local: + :depth: 1 + +------------------------------------ +Physical host requirements and setup +------------------------------------ + +This section describes how to prepare the physical host and virtual +environment for an automated StarlingX |this-ver| virtual deployment in +VirtualBox. + +.. include:: automated_setup.txt + +--------------------------- +Installation Configurations +--------------------------- + +The configurations available from this script, via the ``--setup-type`` +parameter, are: + +* **AIO-SX** or "All-In-One Simplex" will set up one single VM that will be + both a controller and a worker node. + +* **AIO-DX** or "All-In-One Duplex" will set up two controller VMs with one of + them also being a worker. + +* **STANDARD** setup is currently under review. + +* **STORAGE** setup is currently under review. + + +------------------ +Deployment Example +------------------ + +.. rubric:: |proc| + +The following commands are an example on how to run the script for the +deployment of an All-In-One Simplex configuration. + +#. Set the password for the StarlingX system + + .. code-block:: none + + export STX_INSTALL_PASSWORD= + + + The script validates the password as it must contain: + + - Minimum of 7 characters. + - At least 1 uppercase letter. + - At least 1 number. + - At least 1 non-alphanumeric character. + + +#. Run the script + + .. code-block:: none + + cd $HOME/virtual-deployment/virtualbox/pybox + source ./venv/bin/activate + + python3 ./install_vbox.py \ + --setup-type \ + --iso-location "$HOME/Downloads/stx-8.iso" \ + --labname StarlingX --install-mode \ + --config-files-dir ./myconfig/labSetupFiles/ \ + --ansible-controller-config ./myconfig/ansibleFiles/localhost.yml \ + --kubernetes-config-files ./myconfig/kubeFiles/ \ + --vboxnet-type nat \ + --vboxnet-name NatNetwork \ + --nat-controller0-local-ssh-port \ + --nat-controller1-local-ssh-port \ + --password $STX_INSTALL_PASSWORD + + +.. note:: + All available configuration options can be found using ``--help``. + Parameters as ``--snapshot`` and ``--headless`` may be benefitial if + working in a development enviroment. + + +.. note:: + The ``localhost.yml`` file can be modified for further configurations + during the Ansible bootstrap, refer to :ref:`Ansible Bootstrap + Configurations ` for information on + additional configurations for advanced Ansible bootstrap scenarios, such as + Docker proxies when deploying behind a firewall, etc. Refer to :ref:`Docker + Proxy Configuration ` for details about Docker proxy + settings. + +.. important:: + In a machine with the physical host requirements described on this page, + the script will take 60 to 90 minutes to be fully completed (from creating + a VM and installing an OS to configuring StarlingX). The total amount of + time will depend on the deployment configurations. Several restarts will + occur, and a VirtualBox window with a prompt may appear. + + +.. rubric:: |result| + +After the completion of the script your StarlingX cluster is now up and +running. + + +---------- +Dashboards +---------- + +********************* +Starlingx Horizon GUI +********************* + +The script automatically sets up a port-forwarding rule in VirtualBox for +accessing the StarlingX Horizon GUI. The default port is ``8080``, if none was +chosen. + +Access the StarlingX Horizon GUI with the following steps: + +.. rubric:: |proc| + +#. Enter the the following address in your browser: + ``http://localhost:8080``. + +#. Log in to Horizon with an admin/. + + +******************** +Kubernetes Dashboard +******************** + +The script automatically sets up a port-forwarding rule in VirtualBox for +accessing the Kubernetes dashboard. The default port is ``32000``, if none was +chosen. + +.. rubric:: |proc| + +#. Enter the the following address in your browser: + ``http://localhost:32000``. + +#. Log in to the Kubernetes dashboard using the ``admin-user`` token. + + The token can be found in the token.txt file sent to $HOME in the host + machine. \ No newline at end of file diff --git a/doc/source/deploy_install_guides/release/virtual/automated_setup.txt b/doc/source/deploy_install_guides/release/virtual/automated_setup.txt new file mode 100644 index 000000000..067499e75 --- /dev/null +++ b/doc/source/deploy_install_guides/release/virtual/automated_setup.txt @@ -0,0 +1,82 @@ +The following sections describe the system requirements and host setup for a +workstation hosting virtual machine(s) where StarlingX will be deployed. + +********************* +Hardware requirements +********************* + +The host system should have at least: + +* **Processor:** x86_64 only supported architecture with BIOS enabled hardware + virtualization extensions + +* **Cores:** 8 + +* **Memory:** 32GB RAM + +* **Hard Disk:** 500GB HDD + +* **Network:** One network adapter with active Internet connection + +********************* +Software requirements +********************* + +The host system should have at least: + +* A workstation computer with Ubuntu 20.04 LTS 64-bit + + +********** +Host setup +********** + +Set up the host with the following steps: + +#. Update OS and install dependencies: + + .. code-block:: none + + apt-get update + sudo apt install -y virtualbox socat git rsync sshpass openssh-client python3-pip python3-venv + +#. Clone the StarlingX tools repository: + + .. code-block:: none + + cd $HOME + git clone https://opendev.org/starlingx/virtual-deployment.git + +#. Set up Python's Virtual Environment: + + .. code-block:: none + + cd $HOME/virtual-deployment/virtualbox/pybox + python3 -m venv venv + source ./venv/bin/activate + pip install --upgrade pip + pip install -r requirements.txt + +#. Create NatNetwork: + + .. code-block:: none + + VBoxManage natnetwork add --netname NatNetwork --network 10.10.10.0/24 --dhcp off --ipv6 on + +#. Get the StarlingX ISO: + + .. code-block:: none + + wget https://mirror.starlingx.cengn.ca/mirror/starlingx/release/8.0.0/debian/monolithic/outputs/iso/starlingx-intel-x86-64-cd.iso -O $HOME/Downloads/stx-8.iso + +#. Create a local copy of the config file templates. + + .. code-block:: none + + mkdir myconfig + cp -r config myconfig + + Make the desired changes in the config files on the new directory. + +.. note:: + This setup guide can be found in the README.md file in $HOME/virtual-deployment/virtualbox/pybox \ No newline at end of file