Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Installing AppFormix for OpenStack Helm

 

OpenStack Helm is a project that provides Helm charts for deploying OpenStack services on a Kubernetes cluster. AppFormix can be deployed to monitor both the Kubernetes resources as well as the OpenStack resources from a single Dashboard.

Terminology

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

Requirements

The following are the requirements for installing AppFormix for OpenStack Helm.

  • Supported Kubernetes versions: 1.8.x and later

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

  • API access to OpenStack services. AppFormix 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. Further, AppFormix Platform must be able to open a connection to the host and port on which the API server runs.

Workflow

The installation consists of the following steps:

  1. Initial setup.

  2. Prerequisites for Agent installation.

  3. Configuring Kubernetes.

  4. Configuring OpenStack.

  5. Installing AppFormix.

  6. Optional configuration.

Initial Setup

Run the following commands for initial setup:

  1. Install these required packages on the AppFormix Platform node.
  2. Edit the /etc/hosts file on the AppFormix Platform node and enter the IP addresses of the Kubernetes cluster nodes.
  3. Set up password-less SSH between the AppFormix Platform node and the Kubernetes cluster nodes. Run the following commands to generate and copy the SSH public keys to all the nodes.

Prerequisites for Agent installation

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

Configuring Kubernetes

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

To create a new Service Account with the required access for AppFormix, perform the following steps in the Kubernetes cluster master node:

  1. Create a YAML file with the following:
  2. Create the appformix Service Account using the file created in 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 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. AppFormix must be configured to communicate with the Kubernetes cluster. Get the following details from the Kubernetes cluster to use during the AppFormix installation.
    kubernetes_cluster_urlThis is the URL of the Kubernetes API Server. To get this value, run the following command on the Kubernetes cluster:
    kubernetes_auth_tokenThis is the authentication token of the appformix Service Account. To get this value, run the following commands on the Kubernetes cluster:

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

Installing AppFormix

  1. Get the following AppFormix packages:
  2. Unzip appformix-<version>.tar.gz. This package contains all the Ansible playbooks required to install AppFormix.
    Note

    The remaining steps should be executed from within the appformix-<version>/ directory.

  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 AppFormix 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 called all inside this directory with configuration variables required by AppFormix.
  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 AppFormix Dashboard at:

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

    OpenStackLog in with OpenStack credentials and view only OpenStack resources.
    KubernetesLog in with AppFormix credentials and view only Kubernetes resources.
    AppFormixLog in with AppFormix 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 AppFormix Platform node.

Optional Configuration

To install AppFormix certified plugins on the cluster, include the following variables in the group_vars/all file:

For example:

For a list of all AppFormix certified plugins 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 plugins parse the API log files of each OpenStack service to collect metrics about API calls and response status codes. To install these plugins, add them to the variable appformix_openstack_log_plugins in group_vars/all, as shown above. Each plugin 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 AppFormix plugins 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.

Note

In AppFormix 3.0, all OpenStack log parser plugins have to be specified in the variable appformix_openstack_log_plugins. When upgrading from an earlier version to 3.0, make sure to move all OpenStack log parser plugins defined in appformix_plugins' to appformix_openstack_log_plugins. Also, in AppFormix 3.0, all entries in this list have to be specified with a log_file_pathvalue, as described example above.

Removing a Node from AppFormix

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

Run Ansible with the edited inventory file.

This removes the node and all its resources from AppFormix.