Try Compass

Compass Production Environment - An Illustration of Compass Magic


For those users who look to use Compass in their production environment, this instruction gives a thorough walkthrough on how to use Compass Web UI to achieve your deployment goals. Screenshot examples are also used for better understanding and illustration. The whole process can be divided into two main parts: 1. Install Compass and 2. Use Compass to deploy a cluster. The following installation of process demonstrates “singel controller multi compute” scenario deployed on CentOS.

Getting Start

To get started, we need to have an environment ready for Compass and target system. Physical machines are recommended in production environments. For the sakes of simplicity and ease of demonstration, four virtual machines are used in this instruction:

  • One Compass VM
  • Three VMs for Compass to deploy OpenStack on.

There are some basic network requirements as well, please refer to the following image:

compass network configuration

  • Management network in this instruction is also overlapped by Storage and Tenant network.
  • Compass server needs to have at least two network interfaces. One connects to the internet, and the other one connects to the management network.
  • Network node(also controller and storage node, in this case) needs to have at least two interfaces, one connects to the management network and the other one connects to the external network.
  • All other nodes only need to connect to the management network.(Details about these networks will be further discussed in later steps)

The machines you are going to deploy OpenStack on need to be baremetals, even the operation system that already exists will be forcibly removed.

Step 1 - Install Compass

Compass VM needs to have a running operating system. Compass has an automatic install script to set up itself, but currently it only supports CentOS.

Once you have installed CentOS, run yum -y install git to get git.

When git is ready, run the command: git clone git://

clone repository

Go to compass-core directory: cd compass-core Run ./install/ to install compass.

install compass

The install scripts will be asking some questions to allow users to customize their environments. The content bewteen parenthesis is the default setting. Press “Enter” to go with default setting. Here we will explain those questions to make them easier to understand.

  • Please enter the nic

    Compass uses PXE(BOOTP) and DHCP to install OSes onto servers using network installation. This is asking you to input which nic on the Compass server you would like the DHCP service to listen on. Please note that although the default DHCP server setting listens to all interfaces on Compass server, it is recommended that you set this as the interface that is connected to the Management network.


  • Please enter the ipaddr

    This is asking you for your server’s IP address. The example value is calculated using the input from Q1. It gets the IP address of the interface you chose in Q1. In most cases, you only need to hit enter.


  • Please enter the netmask

    This is self-explanatory. Please enter the netmask you have set up for management network.


  • Please enter the option_router

    The option_router variable is used as the gateway for PXE to route the TFTP request traffic. The example value is calculated from Compass server’s default gateway. Thus it is not always correct. It is important that you enter the gateway you have set up for your management network, because a wrong value may FAIL your future deployment.


  • Please enter the ip_start

    The ip_start variable is for DHCP server to assign IPs. The ip_start and ip_end values give DHCP server an IP pool.


  • Please enter the ip_end

    See Q5.


  • Please enter the nextserver

    The next_server acts as the TFTP server. The example value gets it from Compass server’s IP on the management interface. In most cases the example values are correct.


  • Would you like to set up a local repository

    This question cannot be answered by just hitting enter. A local repo is a repo that contains all the packages to install OpenStack. Setting up a local repo on Compass server makes the deployment much faster. Also it makes it possible to have an isolated OpenStack environment without internet access. Upon entering “y”, Compass will drag the local repo from the internet and make it available to all the hosts.

    local repo

  • Please enter the nameserver_domains

    This helps you setup the FQDN for Compass and its hosts.

    name domain

  • Please enter the web_source

    This question is asking for the source code url for Compass web UI. Just hit enter, it will be downloaded.

    web source

  • Please enter the adapters_source

    Compass adapters are also some source code for Cobbler and Chef to use. See Q10 for instructions.

    adapters source

Once you answered all above questions, you can hand the installation over to Compass installation script. It will take a while to finish, depending on your location and network bandwidth.


Step 2 - Compass-Web

Once you completed the installation, open your browser(Chrome and Firefox are recommended) and type the IP of Compass server on the address bar. Then the UI will take you to the login page.

log in

Use the below username and password to login.

Password: admin

Step 3 - Create Cluster

After you log in, you will see this page, click on “+ New Cluster” on the top right.

home page

  1. Cluster name: enter your cluster name

  2. Target system: target system is what you would like your cluster to be. Currently we support OpenStack and OpenStack+Ceph. In this instruction, we use OpenStack Icehouse as the target system.

  3. OS: The OS breeds that will be installed to the hosts. We support both CentOS-6.5 and Ubuntu-12.04.

  4. Flavor: This is essentially how you fabric your cluster. There are following options:

    a. All-in-one: Choose this if you only have one server, and all components of your target system will be deployed to that server.

    b. Single-Controller, Multi-Compute. This flavor is designed specifically for OpenStack. If you have a relatively small number of servers(e.g: 2-10 servers). You may consider this option. Compass will prepare and render some environment templates into cluster deployment configurations for one controller node and multiple compute nodes.

    c. Multinodes: Choose this option if you have a relatively larger number of servers(10+ servers). This gives a finer granularity of roles for you to assign. The concept of roles will be further discussed in later steps. Keep in mind that this flavor is designed for more advanced users who possess a deeper knowledge of the target system.

create cluster

Step 4 - Discover Servers

Once you have created the cluster. You will enter a wizard. The first step on the navigation bar is “Server Selection”. Right now there should be nothing in the server table(unless you run a server discovery prior to creation of the cluster). Compass has a mechanism to discover all the server’s MAC addresses of the interfaces that are connected to a specific switch using SNMP. Click on the “Discover Servers” button to get the servers.

discover servers

As you can see in the image below, Compass UI pops up a form for you to fill in your switch information. This switch should be the switch of your management network. First you need to make sure the Switch has SNMP enabled and uses standard MIBs. Compass currently supports Huawei, HP, Arista and PICA8 switches. You need to enter your Switch IP, version and Community for Compass to discover servers. The default version is “2c” and default community is “public”. If you are cannot proceed with default values and having trouble getting the specific values for your switch, please consult the switch manufacturers for correct information.


Once you have filled in the switch information, click add and the switch will show up on the right hand side. Select the switches from the list of switches, then click “Discover Servers”. Compass will discover all the servers that are connected to the switch ip you entered.

switch ip

After a few seconds, you should be able to get a list of servers with their MAC addresses, switches they are connected to and their port numbers. Select the servers you would like to deploy, by checking their switch IPs and port numbers based on your deployment plan. The search bar allows you to find the desired server quickly, and by checking the “Hide Unselected Servers” box, you can get a clearer view of the servers you have selected. If you are unable to find server, please refer to Appendix for more information.


Step 5 - OS Global Config

In this step you are going to tell Compass what OS configuration you would like to have on your servers. Most of them are self-explanatory, some of them have been pre-filled. But the following items should be dealt with carefully:

NTP Server: Compass manages NTP service. You can fill in Compass server IP here. Or if you have existing NTP servers in your cluster/data center. You can fill one of them here.

DNS Servers: Same as NTP server, if you do not have an existing DNS server, Compass also takes care of DNS service. You can fill in Compass server IP here.

Local Repository: This is the repository for Compass to drag packages during the deployment. If you have pre-setup the repository somewhere reachable in your cluster or you chose ‘y’ when Compass install script asked you if you would like to setup a local repository, you may fill in the value here. Local repo behavior will be enabled in a global scope once a value is set in this step.

os global config

When you have filled in all the required fields, click “Next” and it will bring you to the network step.

Step 6 - Network

Network configurations have always been complicated when deploying distributed systems. Compass has made network configurations of OpenStack easy and intuitive. As you can see in the image below, by default, Compass lists 4 network interfaces. Click on “Autofill” button and you will get a detailed view of networks. You can add or remove interfaces by clicking on the “+” and “-“ on the right. Once you have the correct number of interfaces, choose one of them as your management network interface(this interface should match your network plan). This can be done by checking the box of the interface under “is Mgmt Network” column. You then need to set one interface in “promisc” mode. Such interface is used for assigning external floating IPs. Do not set promisc and management on the same network interface.


Now add subnets to the interfaces by clicking on “Add Subnet” button. Then you can type in your subnet config. Subnets should follow the CIDR format such as You can click on “+” to add more subnets.

auto fill

add subnet

Once you complete creating subnets, Compass will go back to the network page. Now you need to map subnets to interfaces. There are drop-down menus for each interface under “subnet” column. You should carefully choose the correct subnet for each interface.


After mapping subnets to interfaces, you can start assigning IPs to individual servers. Compass-web can help you batch assign IPs. For each network interface, there is an Autofill rule. You can set a starting IP for each interface, and give an incremental rule for Compass to automatically assign IPs to all hosts on that network. You may also autofill hostnames for all servers. Currently we provide hostname autofill in Host and Switch-IP patterns. Click on “Fill Values” button after finishing filling in the values. You will be able to see in the bottom that all servers have been assigned with IPs and hostnames. Please make necessary changes to the servers and proceed to the next step by clicking “Next”.

full value

Step 7 - Partition

This step helps you do the partition. Compass provides LVM partitions. You can add/remove mount points during this step. /root mount point’s existence is mandatory and please keep in mind that although other mount points are optional, most operating systems require /usr and /var. So having /usr and /var in your partition is strongly recommended. You can give each mount point a specific percentage, and its maximum size. Once you have finished, click “Next” to proceed.


Step 8 - Security

In this step, you are able to assign server and service credentials services and components of the target system. We have already pre-filled the values for you, which you can see when you go to the last step of this wizard: review and deploy. You may also customize these credentials yourself. Again, you will get a chance to review them before deploying.

Set OpenStack interior components credentials under the “OpenStack Database and Queue credentials” tab. security

Set OpenStack authentication(including RESTful API and dashboard) credentials under the “OpenStack Keystone User Credentials” tab. security1

Step 9 - Role Assignment

In this step, you will be assigning roles to the servers. As we have discussed in earlier steps, roles of a server are essentially describing what that server does. Depending on the flavor you chose, roles will be appearing in different granularities. In this instruction, we are using “Single Controller, Multiple Compute” flavor, which gives us a few basic roles, such as: Controller, Compute node, Network node and storage node. If you chose to use “multi-node” flavor, you will get more detailed roles such as: queue node, database node and so on. Here are some explanations on nodes we used for this instruction:

  • Controller nodes are responsible for running the management software services needed for the OpenStack environment to function.
  • Compute nodes run the virtual machine instances in OpenStack.
  • Storage nodes store all the data required for the environment, including disk images in the Image Service library, and the persistent storage volumes created by the Block Storage service.
  • Network nodes are responsible for doing all the virtual networking needed for people to create public or private networks and uplink their virtual machines into external networks.

For auto assign, enter the number of each nodes that you would like to assign, then click “Assign”.


For manually assign, drag a specific role and drop it at the desired server.


Click “Next” when you are satisfied with role assignment.

Step 10 - Network Mapping

We are now mapping the networks to interfaces we created in “Networking” step. Different target systems have their specific networks. In this instruction, we are showing how to assign OpenStack networks to interfaces. There are four types of OpenStack networks:

  • Management network: this is self-explanatory. All “control plane” traffic goes through this network. For example, authentication, nova api request, database request and queue messaging, etc. Management network doesn not require a very large bandwidth.

  • Tenant network: Virtual machines created by OpenStack use this network to communicate with each other.

  • Storage network: This network is used for storage devices/components to communicate, such as failover, mirroring and load balancing. Typically storage network uses a relatively large bandwidth. So a 10g network interface is preferred if possible.

  • Public network. This network is only required to be assigned on the network node. Neutron uses the public network as the network for assigning floating IPs. We should map public network onto the promiscuous mode interface we created in “Network” step and isolate this network. So it is important that we DO NOT overlap any other networks with this network. The public network has to be absolutely isolated. Although only the network node needs to have a interface setup in promisc mode specifically for public network, we make this setting as a global config to avoid ambiguity.

Similar to role assignment, drag networks and drop them at interfaces.


Click “Next” once you have made sure all networks are properly assigned and no network overlaps with the public network.

Step 11 - Review and Deployment

This is the last step before the actual deployment. You should review this page carefully. Record the service and server credentials if needed. Once you have reviewed your cluster, click “Deploy” and you will be brought to a deployment status page.


You can see there is a progress bar for each server. If the progresses stay at 0 for a long time, please refer to Appendix for guidance.


Step 12 - OpenStack

Once all the progress bars are showing 100%. Your cluster is ready! Now you may open a new tab and type in the controller node’s IP address, if you installed OpenStack. The dashboard will show up.

Login to the OpenStack dashboard with the credentials you have set in security step. If you used our prefilled values, you may login with admin/admin.



you can start playing with openstack.

Appendix - Frequently Asked Questions

Q: After I filled in the switch information and clicked on find servers, nothing showed up. Why?

A: They may be various reasons that cause this issue.

Fisrt, the reason might be switch MAC address aging. you need to make sure if the servers you wish to install are still actively sending data to their uplink. If those servers have been halted or shutdown for a while, switches are aging their MAC-address tables periodically. You need to restart those servers to have them send signals to their uplinks.

If it still does not work. You might have to head down to the lab(if physical servers) to check the physical connections and health of those servers as well.

Q: Some errors occurred but I do not seem to understand, where can I see the logs?

A: Please login to your Compass server and go to /var/log/compass/ directory for service logs.

Q: The installation of Compass server seems to take a long time as well as occasionally get stuck at some point, how to resolve this?

A: All our mirrors and package resources are based in North America. If you are running this script on servers based in Asia or Europe, it is very common to take a long time to download packages. We will be working on better content delivery solutions in the next phase. Sometimes if the script is installing pip dependencies, it may look like the whole progress hangs, it is a known issue for pip and it will succeed eventually.

Q: I click “deploy”, there is still no progress after waited for a while. Why?

A: You will need to restart all the target servers, only by restarting hosts PXE can be triggered.

Q: I would like to delete a cluster that I create previously, but I do not find any delete button, how can I do this?

A: Currently there is not a cluster delete button on the web UI. But you may follow the steps below to delete a cluster:

  • Login to your compass server.

  • Run . ~/.virtualenvs/compass-core/bin/activate to set up the virtual environment.

  • Go to compass-core directory and run ./bin/ to clean database and restart services.

    As you can see from the image below, it will recommend you to run several commands to do the specifically clean. Run the commands as needed.


Q: I tried to deploy on Ubuntu, when I started deploy, I occured this error on my target machine. How to fix it? network error

A: That may be caused by interfaces disorder, which means the mac address the interface connected to does not match the mac address of the target machine. To avoid that problem, make sure every NIC uses the same adapter.

Q: I tried to deploy on Ubuntu, after I click the “Deploy” buttom, I restart my target machine, the progress still does not start.

A: Entry into BIOS setup screen, check “Boot” tap, make sure the network lists on the top, then exit.