Contrail Insights Installation for OpenStack Helm

Architecture and Terminology

Kubernetes cluster nodes	Primary and worker nodes of the Kubernetes cluster being monitored by Contrail Insights. These nodes will run the Contrail Insights Agent.
OpenStack cluster nodes	Kubernetes nodes from the cluster above that are running OpenStack services (Keystone, Nova, Neutron, and so on) in containers.
Contrail Insights Platform node	Node on which Contrail Insights Platform components will be installed. Should be able to reach the Kubernetes cluster nodes. Figure 1: Contrail Insights and OpenStack Helm Workflow

Requirements

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

• Supported Kubernetes versions: 1.8.x and later

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

• API access to Kubernetes API server. Contrail Insights reads information about the Kubernetes cluster from the API server. The token provided during configuration must provide sufficient permission for read-only API calls. In addition, Contrail Insights Platform must be able to open a connection to the host and port on which the API server runs.

• API access to OpenStack services. Contrail Insights reads information about the OpenStack cluster through the APIs exposed by the various OpenStack services. The user credentials provided during configuration must provide sufficient permission for read-only API calls. In addition, Contrail Insights Platform must be able to open a connection to the host and port on which the API server runs.

• 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 mailto:APPFORMIX-KEY-REQUEST@juniper.net. Provide the following information in your request:

Workflow

The installation consists of the following steps:

1. Initial setup.

2. Prerequisites for Agent installation.

3. Configuring Kubernetes.

4. Configuring OpenStack.

5. Installing Contrail Insights.

6. Optional configuration.

Initial Setup

Run the following commands for initial setup:

1. Install these required packages on the Contrail Insights Platform node.

   Note:

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

2. Edit the /etc/hosts file on the Contrail Insights Platform node and enter the IP addresses of the OpenStack on Kubernetes cluster nodes.

3. Set up passwordless SSH between the Contrail Insights Platform node and the OpenStack on Kubernetes cluster nodes. Run the following commands to generate and copy the SSH public keys to all the nodes.

Prerequisites for Agent Installation

Contrail Insights uses the libvirt library to collect data from virtual machines running on an OpenStack compute node. Run the following command on all OpenStack computes to install the library:

Configure Kubernetes

Contrail Insights reads information about resources in your Kubernetes clusters. The software requires the cluster-admin role or another role that gives it read-only access to all objects in the cluster. We recommend that you create a new Service Account for Contrail Insights and assign it the cluster-admin role. If you do not create a new Service Account, then you must provide the token from an existing Service Account that has the required access during the configuration of Contrail Insights.

To create a new Service Account with the required access for Contrail Insights, perform the following steps in the OpenStack on Kubernetes cluster primary node:

1. Create a YAML file with the following:

2. Create the appformix Service Account using the file created in Step 1.

3. Confirm that the Service Account has been created. Make a note of its namespace.

4. Add the cluster-admin role to the appformix Service Account as follows, substituting namespace for the namespace noted in Step 3.

5. Run the following command to confirm that the appformix Service Account has the required access:

   The output of the command should be yes.

6. Contrail Insights must be configured to communicate with the Kubernetes cluster. Get the following details from the Kubernetes cluster to use during the Contrail Insights installation.

   kubernetes_cluster_url	This is the URL of the Kubernetes API Server. To get this value, run the following command on the OpenStack on Kubernetes cluster:
   kubernetes_auth_token	This is the authentication token of the appformix Service Account. To get this value, run the following commands on the OpenStack on Kubernetes cluster:

Configure OpenStack Administrator Account for Contrail Insights

Contrail Insights reads information about all projects configured in your OpenStack cluster. The software requires administrator privilege. We recommend you create a new administrator account for Contrail Insights. 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 Contrail Insights.

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.

Install Contrail Insights

To install Contrail Insights:

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

2. Unzip contrail-insights-<version>.tar.gz. This package contains all the Ansible playbooks required to install Contrail Insights.

   Note:

   The remaining steps should be executed from within the contrail-insights-<version>/ directory. Although the product name changed from "AppFormix" to "Contrail Insights," the UI and internal command paths continue to show AppFormix and will reflect the new name at a later date.

3. Using sample_inventory as a template, create an inventory file for the installation. List the Kubernetes cluster nodes in the compute section and the Contrail Insights Platform node in the appformix_controller section. List the node running the OpenStack controller services in the openstack_controller section.

4. Create a directory called group_vars. Create a file named all inside this directory with configuration variables required by Contrail Insights.

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

5. Source the openrc file from the OpenStack Controller node in the environment in which the Ansible playbooks are going to be executed. The file should look like the following:

6. Run the Ansible playbook.

   Playbook should run to completion without any errors.

7. Log into the Contrail Insights Dashboard at:

   In the Auth Service dropdown list, three options are provided:

   OpenStack	Log in with OpenStack credentials and view only OpenStack resources.
   Kubernetes	Log in with Contrail Insights credentials and view only Kubernetes resources.
   AppFormix	Log in with Contrail Insights credentials and view both OpenStack and Kubernetes resources.

   For the last two options, the token to use for login is available at /opt/appformix/etc/appformix_token.rst on the Contrail Insights Platform node.

Optional Configuration

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 can be specified.

To identify the correct 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.

On containerized OpenStack environments, log files are generated inside the containers running the OpenStack services. However, they have to be available on the OpenStack controller host for the Contrail Insights plug-ins to be able to read them. The path specified in log_file_path should be the location of the file on the OpenStack Controller host.

Remove a Node from Contrail Insights

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

Run Ansible with the edited inventory file.

This removes the node and all its resources from Contrail Insights.