.. _install_azure: Installing Azure ================ Azure for VOSS Automate is available as a docker image that installs by means of terraform scripts. During the run, terraform saves the plan file (``terraform.tfstate``) to the folder location created under VOSS Automate Azure Installation Procedure - Step 3. The file ``terraform.tfstate`` should be backed up. This will allow you to expand the installation in the future. Hardware Requirements --------------------- For details on Standard and Modular Topologies, refer to the VOSS Automate Architecture and Hardware Specification Guide and Platform Guide. Unified or Database Nodes: * VM Size: E4ds_v4 Standard * CPU: 4 * RAM: 32 * OS disk: 40GB, Premium_LRS * application disk: 50GB, Premium_LRS * backup disk: 55 GB, Standard LRS * DB disk: 250 GB, Premium_LRS * Total disk size: 395GB Application Nodes: * VM Size: E4ds_v4 Standard * CPU: 4 * RAM: 32 * OS disk: 40GB, Premium_LRS * application disk: 50GB, Premium_LRS * Total disk size: 90GB Network: * Address space: 10.0.0.0/16 * Subnet prefix: 10.0.0.0/24 Web Proxies: * Web Proxies are replaced by the Azure Load Balancer Network Communications External to the Cluster ---------------------------------------------- The following details are all based on the default settings. These can vary depending on the application setup and network design (such as NAT) of the solution, so may need adjustment accordingly. Where a dependant is noted, this is fully dependant on the configuration with no default. These communications are all related to communications with devices external to the cluster. * Outbound Communications to Devices from the Application/Unified nodes: .. tabularcolumns:: |p{7cm}|p{3cm}|p{4cm}| +--------------------------------------------+----------+---------------------------------+ | Communication | Protocol | Port | +============================================+==========+=================================+ | Cisco Unified Communications Manager (UCM) | HTTPS | TCP 8443 | +--------------------------------------------+----------+---------------------------------+ | Cisco Unity Connection (CUXN) | HTTPS | TCP 443 | +--------------------------------------------+----------+---------------------------------+ | Webex | HTTPS | TCP 443 | +--------------------------------------------+----------+---------------------------------+ | LDAP directory | LDAP | TCP/UDP 389 and/or 636(TLS/SSL) | +--------------------------------------------+----------+---------------------------------+ | Cisco HCM-F | HTTPS | TCP 8443 | +--------------------------------------------+----------+---------------------------------+ * Unified Node to Unified node This is relevant to the communications between the unified nodes (application and database combined). If the application and database nodes are split, then see the relevant application and database node details below. Database arbiters run on port 27030. +------------------------+----------+------------------------------------+ | Communication | Protocol | Port | +========================+==========+====================================+ | Database access | database | TCP 27020 and 27030 bi-directional | +------------------------+----------+------------------------------------+ | Cluster Communications | HTTPS | TCP 8443 | +------------------------+----------+------------------------------------+ Ubuntu and Docker Installation Procedure ---------------------------------------------- 1. Deploy a LTS version of Ubuntu on Azure Portal. The instructions to follow are a guide for Ubuntu 20.04 (Focal Fossa). :: https://ubuntu.com/#download 2. Install Docker on the newly deployed Ubuntu 20.04 VM. Docker can be installed either online from the repository or offline with the required packages downloaded. For the online procedure - follow the instructions from step 3. For the offline procedure - follow the instructions from step 4. 3. Online Docker installation 3.1. Open a terminal window. 3.2. Check if the system is up-to-date: :: sudo apt update 3.3. Install Docker: :: sudo apt install docker.io 3.4. Verify that Docker Engine - Community is installed correctly by running the hello-world image: :: sudo docker run hello-world 3.5. Manage Docker as a non-root user. Add your user to the docker group: :: sudo usermod -aG docker $USER 3.6. Reboot the system so that your group membership is re-evaluated. 3.7. Verify that you can run docker commands without sudo: :: docker run hello-world 4. Offline Docker Installation using downloaded packages. 4.1. Download the latest packages from the offical Docker website. :: https://download.docker.com/linux/ubuntu/dists//pool/stable/amd64/ For Ubuntu 20.04 (Focal Fossa) - https://download.docker.com/linux/ubuntu/dists/focal/pool/stable/amd64/ Files required are: containerd.io_.deb docker-ce-cli_.deb docker-ce_.deb 4.2. Open a terminal window. 4.3. cd to the folder with the downloaded packages. 4.4. Install the downloaded packages of Docker Engine - Community and containerd: :: sudo dpkg -i *.deb 4.5. Verify that Docker Engine - Community is installed correctly by running the hello-world image: :: sudo docker run hello-world 4.6. Manage Docker as a non-root user. Add your user to the docker group: :: sudo usermod -aG docker $USER 4.7. Reboot the system so that your group membership is re-evaluated. 4.8. Verify that you can run docker commands without sudo: :: docker run hello-world Azure Portal Configuration ---------------------------------------------- 1. Register an application :: Search for and select Azure Active Directory. Under Manage, select App registrations > New registration. 2. Create a new application secret :: From App registrations in Azure AD, select your application. Select Certificates & secrets. Select Client secrets -> New client secret. Provide a description of the secret, and a duration. When done, select Add. After saving the client secret, the value of the client secret is displayed. Copy this value because you won't be able to retrieve the key later. Store the key value where your application can retrieve it. 3. Assign a role to the application :: In the Azure portal, search for and select Subscriptions, or select Subscriptions on the Home page. Select the particular subscription to assign the application to. Select Access control (IAM). Select Add role assignment. Select the Contributor role. Assign access to Azure AD user, group, or service principal. To find your application, search for the name and select it as done in step 1. VOSS Automate Azure Installation Procedure ---------------------------------------------- 1. Download the VOSS Automate docker image along with the sha256 checksum from the provided location and verify the checksum. :: sha256sum platform-azure.tgz cat platform-azure.tgz.sha256 2. Run: **gunzip -c platform-azure.tgz | docker load** :: 77cae8ab23bf: Loading layer [======>] 5.815MB/5.815MB f7030b11e80f: Loading layer [======>] 25.69MB/25.69MB ebf6924cf16a: Loading layer [======>] 50.64MB/50.64MB 3cf5f2bba2c7: Loading layer [======>] 1.536kB/1.536kB fda51b70dfb1: Loading layer [======>] 14.85kB/14.85kB 75a157f47953: Loading layer [======>] 1.897GB/1.897GB e1dad0f87419: Loading layer [======>] 115.9MB/115.9MB Loaded image: voss-azure:19.3.1-1583240523 3. Create a directory to store the plan file (``terraform.tfstate``). For example, **mkdir -p /home/azure/plan** 4. For installations over ssh, it is recommanded to use a screen session. :: screen - start a new session screen -ls - show sessions already available screen -r [screen PID] - reconnect to a disconnected session 5. Run **docker run -it -v :/app/state voss-azure:** For example, **docker run -it -v /home/azure/plan/:/app/state/ voss-azure:19.3.1-1583240523** NB: Once the install is complete, please store this directory for future use. 6. Enter values at the prompt for the terraform script variables: * If installing on a standard, unified node topology, select: ``var.voss_count_app=0``, ``var.voss_count_unified=4``. * If installing a for a modular topology, select: ``var.voss_count_app=2``, ``var.voss_count_unified=0``. * For details on Standard and Modular Topologies, refer to the VOSS Automate Architecture and Hardware Specification Guide and Platform Guide. .. important:: The user input is in clear text. .. tabularcolumns:: |p{6cm}|p{11cm}| +------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | Variable | Description | +====================================+==========================================================================================================================+ | ``var.azure_client_id`` | The Azure user ID of deployer | | | | | | Azure portal: From App registrations in Azure AD, select your application. | +------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | ``var.azure_client_secret`` | The Azure password of deployer (secret) | | | | | | Azure portal: From App registrations in Azure AD, select your application. Select Certificates & secrets. | | | This value was required to be stored upon creation in step 2 of the Azure Portal Configuration. | +------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | ``var.azure_location`` | The location/region where the VOSS Automate system is created. Changing this forces a new resource to be created. | | | | | | List of available regions - centralus, eastasia, southeastasia, eastus, | | | eastus2, westus, westus2, northcentralus, southcentralus, westcentralus, | | | northeurope, westeurope, japaneast, japanwest, brazilsouth, | | | australiasoutheast, australiaeast, westindia, southindia, centralindia, | | | canadacentral, canadaeast, uksouth, ukwest, koreacentral, koreasouth, | | | francecentral, southafricanorth, uaenorth, australiacentral, | | | switzerlandnorth, germanywestcentral, norwayeast, jioindiawest, australiacentral2 | +------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | ``var.azure_resource_group_name`` | The name of the resource group in which to create the VOSS Automate system. | +------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | ``var.azure_subscription_id`` | The Azure subscription ID of deployer | | | | | | Azure portal: Under the Azure services heading, select Subscriptions. Your Subscription IDs are listed in the | | | second column. | +------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | ``var.azure_tenant_id`` | The Azure tenant ID of deployer | | | Azure portal: From App registrations in Azure AD, select your application. | +------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | ``var.fault_domain_count`` | Set the fault domain count. The number of fault domains varies depending on which Azure region you're using. | | | Refer to the official Azure documentation. | +------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | ``var.ntp_name`` | NTP server to be used by VOSS Automate (e.g. ntp.ubuntu.com). Please make sure this is a publicly accessible NTP server. | +------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | ``var.update_domain_count`` | Set the update domain count. This should match the fault_domain_count. | +------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | ``var.voss_env`` | Tag for the environment (Example QA/Production) | +------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | ``var.voss_password`` | Password to be used for VOSS Automate 'platform' user | +------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | ``var.voss_count_app`` | Number of VOSS Automate **application nodes** to deploy | +------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ | ``var.voss_count_unified`` | Number of VOSS Automate **unified nodes** to deploy | +------------------------------------+--------------------------------------------------------------------------------------------------------------------------+ 7. A terraform execution plan and resources are created (example resource): :: An execution plan has been generated and is shown below. Resource actions are indicated with the following symbols: + create Terraform will perform the following actions: # azurerm_availability_set.avset will be created + resource "azurerm_availability_set" "avset" { + id = (known after apply) + location = "southafricanorth" + managed = true + name = "vossavset" + platform_fault_domain_count = 3 + platform_update_domain_count = 3 + resource_group_name = "VOSS_Cloud" + tags = { + "environment" = "dev" + "systemname" = "voss" } } [...] Verify the resources in the plan: :: Do you want to perform these actions? Terraform will perform the actions described above. Only 'yes' will be accepted to approve. 8. When to execution plan is carried out successfully, the login details for the created nodes are shown, for example: * Unified topology :: azurerm_virtual_machine.voss_un[0]: Creation complete after 25m9s [id=...] Outputs: VM-ssh-access = tolist([ "ssh platform@102.37.108.121 -p 50001", "ssh platform@102.37.108.121 -p 50002", "ssh platform@102.37.108.121 -p 50003", "ssh platform@102.37.108.121 -p 50004", ]) VM-ssh-access-App_nodes = tolist([]) VM-ssh-access-DB_nodes = tolist([]) * Modular topology :: azurerm_virtual_machine.voss_app[1]: Creation complete after 24m23s [id=..] Outputs: VM-ssh-access = tolist([]) VM-ssh-access-App_nodes = tolist([ "ssh platform@102.37.107.75 -p 50011", "ssh platform@102.37.107.75 -p 50012", ]) VM-ssh-access-DB_nodes = tolist([ "ssh platform@102.37.107.75 -p 50021", "ssh platform@102.37.107.75 -p 50022", "ssh platform@102.37.107.75 -p 50023", ]) 9. *On each of the newly deployed nodes*, log in as the platform user, using the password selected. 9.1. For example ``ssh platform@10.13.168.197 -p 50001`` 9.2. Run: **system reboot**. Alternatively you can reset the Virtual Machine from the Azure Portal. This is to ensure all services are running before proceeding with the cluster configuration. 10. *On each of the newly deployed nodes*, log in as the platform user, using the password selected. 10.1. For example ``ssh platform@10.13.168.197 -p 50001`` 10.2. Run: **cluster prepnode** 10.3. Obtain the IP address. Run: **network interfaces** Example output: :: $ network interfaces interfaces: eth0: gateway: 10.0.0.1 ip: 10.0.0.4 netmask: 255.255.255.0 11. Log in to the first node above again, for example ``ssh platform@10.13.168.197 -p 50001``. 11.1. Add the IP addresses obtained in the previous step to the cluster: **cluster add , cluster add , ...** 11.2. Add database weights to your database nodes: Log in to the database node. For *modular deployment*, use the ``50021`` port to log into the database, for example: :: ssh platform@152.77.167.75 -p 50021 **database weight add , database weight add , ...** * Weights of 40, 30 are recommended for two Unified nodes * Weights of 40, 30, 20, and 10 are recommended for four Unified nodes * Weights of 60, 50, 40, 30, 20, and 10 are recommended for six Unified nodes The higher the value, the higher priority. 11.3. Run **cluster provision** 11.4. Run **voss cleardown** 11.5. Upload the provided template install file via the scp (secure copy protocol) to the media folder on the primary node 11.6. Install the templates. **app template media/