Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?


Contrail Insights Installation and Configuration for OpenStack

Getting Started with OpenStack

Contrail Insights provides resource control and visibility for hosts and virtual machines in an OpenStack cluster. This topic explains how to install Contrail Insights for an OpenStack cluster. Contrail Insights Agent runs on a host to monitor resource consumption of the host itself and the virtual machines executing on that host. Figure 1 shows the Contrail Insights architecture with OpenStack.

Figure 1: Contrail Insights Architecture with OpenStackContrail Insights Architecture with OpenStack
  • Contrail Insights Agent monitors resource usage on the compute nodes.

  • Contrail Insights Platform offers REST APIs to configure the system.

  • Contrail Insights DataManager stores data from multiple Agents.

  • Contrail Insights Dashboard provides a Web-based user interface.

  • An adapter discovers platform-specific resources and configures the Contrail Insights Platform.

  • Adapters exist for OpenStack and Kubernetes.


The following are the requirements for installing Contrail Insights for OpenStack.

  • Supported OpenStack versions: Icehouse, Juno, Kilo, Liberty, Mitaka, Newton, Ocata.

  • See Contrail Insights General Requirements for software and hardware requirements.

  • An administrator account for OpenStack.

  • API access to OpenStack services: Cinder, Glance, Heat, Keystone, Neutron, Nova, and Swift. Contrail Insights reads information from these services. The administrator account must provide sufficient permission for read-only API calls. Further, Contrail Insights Platform must be able to open connections to the host and port on which these services listen. Contrail Insights can be configured to use the admin, internal, or public service endpoints. See OS_ENDPOINT_TYPE in OpenStack environment variables in the section Installing Contrail Insights.

  • Note:

    Upgrade notice: Starting with Contrail Insights 3.2.6, the requirement for a license file is removed. If you are installing a version earlier than 3.2.6, a license is required prior to installation.

    You can obtain a license key from Provide the following information in your request:

Workflow in Three Steps

Installation consists of the following steps:

  1. Configure OpenStack.

  2. Create Ansible inventory.

  3. Install Contrail Insights.

Configure OpenStack

To create an administrator account for Contrail Insights, perform the following steps in the OpenStack Horizon dashboard:

  1. Create a user account and name it appformix.

  2. Select a new project for the user account.

  3. Select role as admin.

Create Ansible Inventory

Ansible is used to deploy the software to the compute node(s) and the Platform 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 reused for an upgrade.

Contrail Insights requires two groups compute and appformix_controller. Each group lists the hosts in that group. Only the agent is installed on the compute hosts. The agent and the Contrail Insights Platform services are installed on the appformix_controller host.

Optionally, an openstack_controller group can be defined. The agent is 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 file and a group_vars/all file. For example:

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

See Ansible inventory documentation.

Ansible Configuration Variables

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

In the inventory/group_vars/all file, configure the following variables for installation of Contrail Insights for OpenStack.

Refer to Platform Dependencies for steps to install dependencies on a Platform Host that cannot fetch files from the Internet.

Configure 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:

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 ( 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.

Install Contrail Insights

To install Contrail Insights:

  1. Install Ansible on the Contrail Insights Platform node. Ansible will install docker and docker-py on the platform.


    For RHEL, the following IPtables rule is needed to access port 9000.

  2. Install libvirt on the compute nodes using the following command:

    This installs the KVM (Kernel-based Virtual Machine) and associated packages for collecting data from virtual machines running on the compute nodes.

  3. On the compute nodes where Contrail Insights Agent runs, verify that python virtualenv is installed.

  4. Enable passwordless login to facilitate Contrail Insights Platform node with Ansible to install agents on the nodes. Create a SSH public key on the node where Ansible playbooks are run, and then copy the key to the appformix_controller node.

  5. Use the Sample_Inventory file as a template to create a host file.

  6. Verify that all the hosts listed in the inventory file are reachable from the Contrail Insights Platform.

  7. At the top-level of the distribution, create a directory named group_vars.

  8. Download the Contrail Insights installation packages from software downloads to the Contrail Insights Platform node. Get the following files:

    If you are installing a version earlier than 3.2.6, copy the Contrail Insights license file to the Contrail Insights Platform node.

  9. In group_vars directory, create a file named all. Add the following:

    If you are installing a version earlier than 3.2.6, include the path to the Contrail Insights license file in group_vars/all:

  10. Contrail Insights must be configured to communicate with the OpenStack cluster. The Ansible playbooks use OpenStack environment variables to configure Contrail Insights with details of the OpenStack environment.

  11. Source the openrc file that contains the (step 10) environment variables and ensure the variables are in the environment of the shell from which the Ansible-playbooks are going to be executed. Then, install Contrail Insights by executing the appformix_openstack.yml playbook. Specify the path to the inventory directory that you created earlier.

  12. Open the Contrail Insights Dashboard in a Web browser. For example:

    Select Skip Installation because the initial configuration was performed by Ansible using the OpenStack environment variables in step 10. Log in to Contrail Insights Dashboard using OpenStack Keystone credentials.

Additional Ansible Configuration

To set up additional Ansible configurations:

  1. To install in a Keystone SSL-enabled cluster, include the following variables in the group_vars/all file:

    Contrail Insights Ansible will distribute this Keystone CA to all of the Contrail Insights Platform nodes and ask Contrail Insights components to talk to Keystone using this CA file with SSL enabled.


    Deprecation Notice: The appformix_mongo_cache_size_gb parameter previously available starting in Contrail Insights 2.19.5 is now deprecated and no longer supported from Contrail Insights 3.2.0 and going forward. Starting with Contrail Insights version 3.2.0, Mongo will be configured to use a maximum of 40 percent of the available memory on the Contrail Insights Platform nodes.

  2. To enable network device monitoring in the cluster, include the following in the group_vars/all file:

  3. To install Contrail Insights certified plug-ins on the cluster, include the following variables in the group_vars/all file:

    For example:

    For a list of all Contrail Insights certified plug-ins that can be installed, look for the entries starting with plugin_info in the file roles/appformix_defaults/defaults/main.yml.

    The OpenStack log parser plug-ins parse the API log files of each OpenStack service to collect metrics about API calls and response status codes. To install these plug-ins, add them to the variable appformix_openstack_log_plugins in group_vars/all, as shown above. Each plug-in entry in this list requires a parameter called log_file_path to be specified. This parameter should be set to the complete path to the service's API log file on the OpenStack Controller node(s). Multiple comma-separated paths may be specified.

    To identify the right log file to be specified in log_file_path, look for entries like the following, containing a client IP address, REST call type, and response status code:

    Default locations for these files are listed in the variable appformix_openstack_log_factory_plugins in roles/appformix_defaults/defaults/main.yml.

  4. In Contrail Insights version 2.19.8, a timeout value can be configured for connecting to OpenStack services. The default value of this timeout is 10 seconds and can be changed to a value between 5 and 20 seconds (both inclusive). To change the value, add the following variable to group_vars/all:

    To modify the timeout value after the Contrail Insights Platform has been installed, add the variable to the group_vars/all file as described above and re-run the Contrail Insights installation playbook. Restart the appformix-openstack-adapter Docker container after the playbook has completed:

Upgrade Notices


In Contrail Insights version 3.2.0, support for discovering OpenStack Octavia Load Balancer services is added. Contrail Insights only collects load balancer state information, such as provisioning_status and operating_status, as well as flavor information. To enable this service discovery, provide Octavia service's endpoint as variable appformix_octavia_endpoint_url in the group_vars/all file. For example:

Chargeback costs can also be configured for the Octavia Load Balancer services. See Configure Load Balancer Costs.

Run Ansible with the created inventory file.


In Contrail Insights version 3.0, the variable appformix_openstack_factory_plugins is deprecated. All OpenStack log parser plug-ins have to be specified in the variable appformix_openstack_log_plugins. When upgrading from an older version to version 3.0, make sure to move all OpenStack log parser plug-ins defined in appformix_openstack_factory_plugins or appformix_plugins to appformix_openstack_log_plugins. Also, in Contrail Insights version 3.0, all entries in this list have to be specified with a log_file_path value, as described in step 3 above.

When upgrading from version 2.18.x to version 3.0, make the following changes in the group_vars/all file:

In version 2.18.x:

In version 3.0.x:

Source the openrc file from the OpenStack controller node (/etc/contrail/openstackrc) to the Contrail Insights Platform node to authenticate the adapter to access administrator privileges over the controller services. The file should look like the following:

Run Ansible with the created inventory file.

Remove a Node from Contrail Insights

To remove a node from Contrail Insights:

  1. Edit the inventory file and add appformix_state=absent to each node that you want to remove from Contrail Insights.

  2. Run Ansible with the edited inventory file. This will remove the node and all its resources from Contrail Insights.

Upgrade Contrail Insights for an OpenStack Cluster

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

Uninstall Contrail Insights from an OpenStack Cluster

To uninstall Contrail Insights and destroy all data, execute the following command: