Getting Started on OpenStack

AppFormix provides resource control and visibility for hosts and virtual machines in an OpenStack cluster.

This guide explains how to install AppFormix for an OpenStack cluster. See the Overview for general requirements before reading this guide.

Requirements

Easy Installation

Installation consists of the following steps:

  1. Configure OpenStack
  2. Create Ansible inventory
  3. Install AppFormix

1. Configure OpenStack

AppFormix reads information about all projects configured in your OpenStack cluster. The software requires administrator privilege. We recommend you create a new administrator account for AppFormix. If you do not create a new Administrator account, then you must provide the username and password of an existing Administrator account during the configuration of AppFormix.

To create an Administrator account for AppFormix, perform the following in the Horizon dashboard:

  1. Create a new user account with name "appformix".
  2. Select to create a new project for the user account.
  3. Select role as "admin".

2. Create Ansible inventory

Ansible is used to deploy the software to the compute node(s) and Controller host. An Ansible inventory file describes groups of hosts in your cluster. Define the inventory in a separate location than the release files, so that the inventory may be re-used for an upgrade.

AppFormix requires two groups "compute" and "appformix_controller". Each group lists the hosts in that group. Only the Agent will be installed on the "compute" hosts. The Agent and the AppFormix platform services will be installed on the "appformix_controller" host.

Optionally, an "openstack_controller" group may be defined. The Agent will be installed on hosts in this group to monitor the hosts that execute OpenStack controller services. (New in v2.3.0)

Create a directory inventory (or name of your choice) that contains a hosts and group_vars/all files. For example:

inventory/
    hosts           # inventory file
    group_vars/
        all         # configuration variables

The inventory/hosts file contains the list of hosts in each group. For example:

[appformix_controller]
appformix01

[compute]
compute01
compute02
compute03

[openstack_controller]
openstack_infra01
openstack_infra02

For more information, refer to Ansible inventory documentation.

Ansible configuration variables

AppFormix includes a number of Ansible roles to perform configuration of AppFormix settings. Define values of variables in a group_vars/all file, in order to be able to use the settings for future upgrades.

A mandatory setting is the source of the Docker images. Copy the appformix-docker-images-<version>.tar.gz file to the host on which Ansible will be executed. In the inventory/group_vars/all file, configure the following variables:

    appformix_docker_images_file: /path/to/appformix-docker-images-<version>.tar.gz
    appformix_license: /path/to/license_file

Please refer to Platform Dependencies for steps to install dependencies on a platform host that cannot fetch files from the Internet.

Configuring an HTTP proxy for fetching prerequisites

The Ansible playbook will fetch files from the Internet to install prerequisites on the platform host. If the platform host requires an HTTP proxy to access the Internet, configure the following variables in inventory/group_vars/all:

    http_proxy_url: 'http://proxy.example.com:1234'
    prerequisites_env:
        http_proxy: '{{ http_proxy_url }}'
        https_proxy: '{{ http_proxy_url }}'

The prerequisites_env is a dictionary that defines environment variables that will be used when invoking commands to install prerequisites. In the above example, the same proxy URL ('http://proxy.example.com:1234') is used for both the http_proxy and https_proxy environment variables because the single proxy can be used to access HTTP and HTTPS URLs. As a convenience, the proxy URL is defined once in the http_proxy_url variable. Adjust prerequisites_env as necessary for the proxy requirements of your network.

3. Install AppFormix

The following commands should be executed on the host from which Ansible will be run. This may be the Controller host, or any host with Ansible and SSH access to the compute node(s) and Controller host.

  1. Unpack the tarball, and change to the created directory:

    tar xzf appformix-<version>.tar.gz
    cd appformix-<version>
    
  2. AppFormix must be configured to communicate with the OpenStack cluster. The Ansible playbooks use OpenStack environment variables to configure AppFormix with details of the OpenStack environment.

    OS_AUTH_URL             Keystone URL (e.g., https://host:5000/)
    OS_ENDPOINT_TYPE        endpoint type to communicate with service (default: publicURL)
    OS_USERNAME             admin account to be used by AppFormix
    OS_PASSWORD             password for admin account
    OS_PROJECT_NAME         admin project created for AppFormix account
    OS_PROJECT_DOMAIN_NAME  domain for admin project
    OS_USER_DOMAIN_NAME     domain for admin user
    OS_DOMAIN_NAME          (optional) use domain-scoped token for admin account
    

    Source an openrc file that contains the above environment variables, and ensure the variables are in the environment of the shell from which ansible-playbook is run. Then, deploy and configure AppFormix by executing the appformix_openstack.yml playbook. Specify the path to the inventory directory created above:

    source ~/openrc
    ansible-playbook -i /path/to/inventory appformix_openstack.yml
    
  3. Open the AppFormix Dashboard in a web browser (e.g., http://appformix01:9000/appformix).

    Select "Skip Installation" because the initial configuration has been performed by Ansible using the OpenStack environment variables above. Login to AppFormix Dashboard using OpenStack Keystone credentials.

Upgrade

AppFormix can be easily upgraded by running the appformix_openstack.yml playbook of the new release. Follow the same procedure as installation.

Uninstall

If you want to uninstall AppFormix and destroy all data, execute the following:

ansible-playbook -i <inventory_file> clean_appformix_openstack.yml