Welcome to Sahara!

The sahara project aims to provide users with a simple means to provision data processing frameworks (such as Hadoop, Spark and Storm) on OpenStack. This is accomplished by specifying configuration parameters such as the framework version, cluster topology, node hardware details and more.

Overview

Rationale

Introduction

Apache Hadoop is an industry standard and widely adopted MapReduce implementation, it is one among a growing number of data processing frameworks. The aim of this project is to enable users to easily provision and manage clusters with Hadoop and other data processing frameworks on OpenStack. It is worth mentioning that Amazon has provided Hadoop for several years as Amazon Elastic MapReduce (EMR) service.

Sahara aims to provide users with a simple means to provision Hadoop, Spark, and Storm clusters by specifying several parameters such as the version, cluster topology, hardware node details and more. After a user fills in all the parameters, sahara deploys the cluster in a few minutes. Also sahara provides means to scale an already provisioned cluster by adding or removing worker nodes on demand.

The solution will address the following use cases:

• fast provisioning of data processing clusters on OpenStack for development and quality assurance(QA).
• utilization of unused compute power from a general purpose OpenStack IaaS cloud.
• “Analytics as a Service” for ad-hoc or bursty analytic workloads (similar to AWS EMR).

Key features are:

• designed as an OpenStack component;

• managed through a REST API with a user interface(UI) available as part of OpenStack Dashboard;

• support for a variety of data processing frameworks:

  • multiple Hadoop vendor distributions
  • Apache Spark and Storm
  • pluggable system of Hadoop installation engines
  • integration with vendor specific management tools, such as Apache Ambari and Cloudera Management Console

• predefined configuration templates with the ability to modify parameters.

Details

The sahara product communicates with the following OpenStack services:

• Dashboard (horizon) - provides a GUI with ability to use all of sahara’s features.
• Identity (keystone) - authenticates users and provides security tokens that are used to work with OpenStack, limiting a user’s abilities in sahara to their OpenStack privileges.
• Compute (nova) - used to provision VMs for data processing clusters.
• Orchestration (heat) - used to provision and orchestrate the deployment of data processing clusters.
• Image (glance) - stores VM images, each image containing an operating system and a pre-installed data processing distribution or framework.
• Object Storage (swift) - can be used as storage for job binaries and data that will be processed or created by framework jobs.
• Block Storage (cinder) - can be used to provision block storage for VM instances.
• Networking (neutron) - provides networking services to data processing clusters.
• Telemetry (ceilometer) - used to collect measures of cluster usage for metering and monitoring purposes.
• Shared file systems (manila) - can be used for storage of framework job binaries and data that will be processed or created by jobs.

General Workflow

Sahara will provide two levels of abstraction for the API and UI based on the addressed use cases: cluster provisioning and analytics as a service.

For fast cluster provisioning a generic workflow will be as following:

• select a Hadoop (or framework) version.

• select a base image with or without pre-installed data processing framework:

  • for base images without a pre-installed framework, sahara will support pluggable deployment engines that integrate with vendor tooling.
  • you can download prepared up-to-date images from http://sahara-files.mirantis.com/images/upstream/liberty/

• define cluster configuration, including cluster size, topology, and framework parameters (for example, heap size):

  • to ease the configuration of such parameters, configurable templates are provided.

• provision the cluster; sahara will provision VMs, install and configure the data processing framework.

• perform operations on the cluster; add or remove nodes.

• terminate the cluster when it is no longer needed.

For analytics as a service, a generic workflow will be as follows:

• select one of the predefined data processing framework versions.

• configure a job:

  • choose the type of job: pig, hive, jar-file, etc.
  • provide the job script source or jar location.
  • select input and output data location.

• set the limit for the cluster size.

• execute the job:

  • all cluster provisioning and job execution will happen transparently to the user.
  • cluster will be removed automatically after job completion.

• get the results of computations (for example, from Swift).

User’s Perspective

While provisioning clusters through sahara, the user operates on three types of entities: Node Group Templates, Cluster Templates and Clusters.

A Node Group Template describes a group of nodes within cluster. It contains a list of hadoop processes that will be launched on each instance in a group. Also a Node Group Template may provide node scoped configurations for those processes. This kind of template encapsulates hardware parameters (flavor) for the node VM and configuration for data processing framework processes running on the node.

A Cluster Template is designed to bring Node Group Templates together to form a Cluster. A Cluster Template defines what Node Groups will be included and how many instances will be created in each. Some data processing framework configurations can not be applied to a single node, but to a whole Cluster. A user can specify these kinds of configurations in a Cluster Template. Sahara enables users to specify which processes should be added to an anti-affinity group within a Cluster Template. If a process is included into an anti-affinity group, it means that VMs where this process are going to be launched should be scheduled to different hardware hosts.

The Cluster entity represents a collection of VM instances that all have the same data processing framework installed. It is mainly characterized by a VM image with a pre-installed framework which will be used for cluster deployment. Users may choose one of the pre-configured Cluster Templates to start a Cluster. To get access to VMs after a Cluster has started, the user should specify a keypair.

Sahara provides several constraints on cluster framework topology. JobTracker and NameNode processes could be run either on a single VM or two separate VMs. Also a cluster could contain worker nodes of different types. Worker nodes could run both TaskTracker and DataNode, or either of these processes alone. Sahara allows a user to create a cluster with any combination of these options, but it will not allow the creation of a non working topology (for example: a set of workers with DataNodes, but without a NameNode).

Each Cluster belongs to some Identity service project determined by the user. Users have access only to objects located in projects they have access to. Users can edit and delete only objects they have created or exist in their project. Naturally, admin users have full access to every object. In this manner, sahara complies with general OpenStack access policy.

Integration with Object Storage

The swift project provides the standard Object Storage service for OpenStack environments; it is an analog of the Amazon S3 service. As a rule it is deployed on bare metal machines. It is natural to expect data processing on OpenStack to access data stored there. Sahara provides this option with a file system implementation for swift HADOOP-8545 and Change I6b1ba25b which implements the ability to list endpoints for an object, account or container. This makes it possible to integrate swift with software that relies on data locality information to avoid network overhead.

To get more information on how to enable swift support see Swift Integration.

Pluggable Deployment and Monitoring

In addition to the monitoring capabilities provided by vendor-specific Hadoop management tooling, sahara provides pluggable integration with external monitoring systems such as Nagios or Zabbix.

Both deployment and monitoring tools can be installed on stand-alone VMs, thus allowing a single instance to manage and monitor several clusters at once.

Architecture

The Sahara architecture consists of several components:

• Auth component - responsible for client authentication & authorization, communicates with the OpenStack Identity service (keystone).
• DAL - Data Access Layer, persists internal models in DB.
• Provisioning Engine - component responsible for communication with the Openstack Compute (nova), Orchestration (heat), Block Storage (cinder) and Image (glance) services.
• Vendor Plugins - pluggable mechanism responsible for configuring and launching data processing frameworks on provisioned VMs. Existing management solutions like Apache Ambari and Cloudera Management Console could be utilized for that purpose as well.
• EDP - Elastic Data Processing (EDP) responsible for scheduling and managing data processing jobs on clusters provisioned by sahara.
• REST API - exposes sahara functionality via REST HTTP interface.
• Python Sahara Client - like other OpenStack components, sahara has its own python client
• Sahara pages - a GUI for the sahara is located in the OpenStack Dashboard (horizon).

User guide

Installation

Sahara Installation Guide

We recommend installing sahara in a way that will keep your system in a consistent state. We suggest the following options:

• Install via Fuel
• Install via RDO
• Install into a virtual environment

To install with Fuel

1. Start by following the MOS Quickstart to install and setup OpenStack.
2. Enable the sahara service during installation.

To install with RDO

1. Start by following the RDO Quickstart to install and setup OpenStack.
2. Install sahara:

# yum install openstack-sahara

3. Configure sahara as needed. The configuration file is located in /etc/sahara/sahara.conf. For details see Sahara Configuration Guide
4. Create the database schema:

# sahara-db-manage --config-file /etc/sahara/sahara.conf upgrade head

5. Go through Common installation steps and make any necessary changes.
6. Start the sahara-all service:

# systemctl start openstack-sahara-all

7. (Optional) Enable sahara to start on boot

# systemctl enable openstack-sahara-all

To install into a virtual environment

1. First you need to install a number of packages with your OS package manager. The list of packages depends on the OS you use. For Ubuntu run:

$ sudo apt-get install python-setuptools python-virtualenv python-dev

For Fedora:

$ sudo yum install gcc python-setuptools python-virtualenv python-devel

For CentOS:

$ sudo yum install gcc python-setuptools python-devel
$ sudo easy_install pip
$ sudo pip install virtualenv

2. Setup a virtual environment for sahara:

$ virtualenv sahara-venv

This will install a python virtual environment into sahara-venv directory in your current working directory. This command does not require super user privileges and can be executed in any directory where the current user has write permissions.

3. You can install the latest sahara release from pypi:

$ sahara-venv/bin/pip install sahara

Or you can get a sahara archive from http://tarballs.openstack.org/sahara/ and install it using pip:

$ sahara-venv/bin/pip install 'http://tarballs.openstack.org/sahara/sahara-master.tar.gz'

Note that sahara-master.tar.gz contains the latest changes and might not be stable at the moment. We recommend browsing http://tarballs.openstack.org/sahara/ and selecting the latest stable release.

4. After installation you should create a configuration file from the sample file located in sahara-venv/share/sahara/sahara.conf.sample-basic:

$ mkdir sahara-venv/etc
$ cp sahara-venv/share/sahara/sahara.conf.sample-basic sahara-venv/etc/sahara.conf

Make any necessary changes to sahara-venv/etc/sahara.conf. For details see Sahara Configuration Guide

Common installation steps

The steps below are common to both the RDO and virtual environment installations of sahara.

1. If you use sahara with a MySQL database, then for storing big job binaries in the sahara internal database you must configure the size of the maximum allowed packet. Edit the my.cnf file and change the max_allowed_packet parameter as follows:

...
[mysqld]
...
max_allowed_packet          = 256M

Then restart the mysql server to ensure these changes are active.

2. Create the database schema:

$ sahara-venv/bin/sahara-db-manage --config-file sahara-venv/etc/sahara.conf upgrade head

3. To start sahara call:

$ sahara-venv/bin/sahara-all --config-file sahara-venv/etc/sahara.conf

4. For sahara to be accessible in the OpenStack Dashboard and for python-saharaclient to work properly you must register sahara in the Identity service catalog. For example:

keystone service-create --name sahara --type data-processing \
    --description "Sahara Data Processing"

keystone endpoint-create --service sahara --region RegionOne \
    --publicurl "http://10.0.0.2:8386/v1.1/%(tenant_id)s" \
    --adminurl "http://10.0.0.2:8386/v1.1/%(tenant_id)s" \
    --internalurl "http://10.0.0.2:8386/v1.1/%(tenant_id)s"

5. For more information on configuring sahara with the OpenStack Dashboard please see OpenStack Dashboard Configuration Guide.

Optional installation of default templates

Sahara bundles default templates that define simple clusters for the supported plugins. These templates may optionally be added to the sahara database using a simple CLI included with sahara.

The default template CLI is described in detail in a README file included with the sahara sources at <sahara_home>/db/templates/README.rst but it is summarized here.

Flavor id values must be specified for the default templates included with sahara. The recommended configuration values below correspond to the m1.medium and m1.large flavors in a default OpenStack installation (if these flavors have been edited, their corresponding values will be different). Values for flavor_id should be added to /etc/sahara/sahara.conf or another configuration file in the sections shown here:

[DEFAULT]
# Use m1.medium for {flavor_id} unless specified in another section
flavor_id = 2

[cdh-5-default-namenode]
# Use m1.large for {flavor_id} in the cdh-5-default-namenode template
flavor_id = 4

[cdh-530-default-namenode]
# Use m1.large for {flavor_id} in the cdh-530-default-namenode template
flavor_id = 4

The above configuration values are included in a sample configuration file at <sahara_home>/plugins/default_templates/template.conf

The command to install all of the default templates is as follows, where $TENANT_ID should be a valid tenant id and the above configuration values have been set in myconfig:

$ sahara-templates --config-file /etc/sahara/sahara.conf --config-file myconfig update -t $TENANT_ID

Help is available from the sahara-templates command:

$ sahara-templates --help
$ sahara-templates update --help

Notes:

Ensure that your operating system is not blocking the sahara port (default: 8386). You may need to configure iptables in CentOS and other Linux distributions to allow this access.

To get the list of all possible options run:

$ sahara-venv/bin/python sahara-venv/bin/sahara-all --help

Further, consider reading Getting Started for general sahara concepts and Provisioning Plugins for specific plugin features/requirements.

Sahara Configuration Guide

This guide covers the steps for a basic configuration of sahara. It will help you to configure the service in the most simple manner.

Basic configuration

Sahara is packaged with a basic sample configration file: sahara.conf.sample-basic. This file contains all the essential parameters that are required for sahara. We recommend creating your configuration file based on this basic example.

If a more thorough configuration is needed we recommend using the tox tool to create a full configuration file by executing the following command:

$ tox -e genconfig

Running this command will create a file named sahara.conf.sample in the etc/sahara directory of the project.

After creating a configuration file by either copying the basic example or generating one, edit the connection parameter in the [database] section. The URL provided here should point to an empty database. For example, the connection string for a MySQL database will be:

connection=mysql://username:password@host:port/database

Next you will configure the Identity service parameters in the [keystone_authtoken] section. The auth_uri parameter should point to the public Identity API endpoint. The identity_uri should point to the admin Identity API endpoint. For example:

auth_uri=http://127.0.0.1:5000/v2.0/
identity_uri=http://127.0.0.1:35357/

Specify the admin_user, admin_password and admin_tenant_name. These parameters must specify an Identity user who has the admin role in the given tenant. These credentials allow sahara to authenticate and authorize its users.

Next you will configure the default Networking service. If using neutron for networking the following parameter should be set in the [DEFAULT] section:

use_neutron=true

If you are using nova-network for networking then this parameter should be set to false.

With these paramaters set, sahara is ready to run.

If you wish to increase the logging levels for troubleshooting there are two parameters in the [DEFAULT] section of the configuration file which control the level of logging output; verbose and debug. With verbose set to true sahara’s default logging level will be set to INFO, and with debug set to true it will be set to DEBUG. By default the sahara’s log level is set to WARNING.

Networking configuration

By default sahara is configured to use the nova-network implementation of OpenStack Networking. If an OpenStack cluster uses neutron, then the use_neutron parameter should be set to True in the sahara configuration file. Additionally, if the cluster supports network namespaces the use_namespaces property can be used to enable their usage.

[DEFAULT]
use_neutron=True
use_namespaces=True

Note

If a user other than root will be running the Sahara server instance and namespaces are used, some additional configuration is required, please see Non-root users for more information.

Floating IP management

During cluster setup sahara must access instances through a secure shell(SSH). To establish this connection it may use either the fixed or floating IP address of an instance. By default sahara is configured to use floating IP addresses for access. This is controlled by the use_floating_ips configuration parameter. With this setup the user has two options for ensuring that all instances gain a floating IP address:

• If using the nova-network, it may be configured to assign floating IP addresses automatically by setting the auto_assign_floating_ip parameter to True in the nova configuration file (usually nova.conf).
• The user may specify a floating IP address pool for each node group directly.

Warning

When using floating IP addresses for management (use_floating_ip=True) every instance in the cluster must have a floating IP address, otherwise sahara will not be able to utilize that cluster.

If not using floating IP addresses (use_floating_ip=False) sahara will use fixed IP addresses for instance management. When using neutron for the Networking service the user will be able to choose the fixed IP network for all instances in a cluster. Whether using nova-network or neutron it is important to ensure that all instances running sahara have access to the fixed IP networks.

Notifications configuration

Sahara can be configured to send notifications to the OpenStack Telemetry module. To enable this functionality the following parameters should be set in the [DEFAULT] section of the configuration file:

enable_notifications = true
notification_driver = messaging

By default sahara is configured to use RabbitMQ as its message broker, but it can be configured to use Qpid instead if needed.

If you are using RabbitMQ as the message broker, then you should set the following parameter in the [DEFAULT] section:

rpc_backend = rabbit

You may also need to specify the connection parameters for your RabbitMQ installation. The following example shows the default values in the [oslo_messaging_rabbit] section which may need adjustment:

rabbit_host=localhost
rabbit_port=5672
rabbit_hosts=$rabbit_host:$rabbit_port
rabbit_userid=guest
rabbit_password=guest
rabbit_virtual_host=/

If you are using Qpid as the message broker, then you should set the rpc_backend as follows:

rpc_backend = qpid

You may also need to adjust the following default connection parameters in the [oslo_messaging_qpid] section:

qpid_hostname=localhost
qpid_port=5672
qpid_hosts=$qpid_hostname:$qpid_port
qpid_username=
qpid_password=

Orchestration configuration

By default sahara is configured to use the heat engine for instance creation. The heat engine uses the Openstack Orchestration service to provision instances. Sahara can be configured to use the direct engine for this purpose, but after the Liberty release it will be removed. This engine makes calls directly to the services required for instance provisioning. We recommend using the Openstack Orchestration service.

To configure sahara to use the direct engine for instance provisioning the infrastructure_engine parameter should be modified in the configuration file as follows:

[DEFAULT]
infrastructure_engine=direct

Warning

The direct engine will be removed after the Liberty release, we recommend using the heat engine.

Policy configuration

Sahara’s public API calls may be restricted to certain sets of users by using a policy configuration file. The location of the policy file(s) is controlled by the policy_file and policy_dirs parameters in the [oslo_policy] section. By default sahara will search for a policy.json file in the same directory as the configuration file.

Examples

Example 1. Allow all method to all users (default policy).

{
    "default": ""
}

Example 2. Disallow image registry manipulations to non-admin users.

{
    "default": "",

    "data-processing:images:register": "role:admin",
    "data-processing:images:unregister": "role:admin",
    "data-processing:images:add_tags": "role:admin",
    "data-processing:images:remove_tags": "role:admin"
}

OpenStack Dashboard Configuration Guide

Sahara UI panels are integrated into the OpenStack Dashboard repository. No additional steps are required to enable Sahara UI in OpenStack Dashboard. However there are a few configurations that should be made to configure OpenStack Dashboard.

Dashboard configurations are applied through the local_settings.py file. The sample configuration file is available here.

1. Networking

Depending on the Networking backend (Nova Network or Neutron) used in the cloud, Sahara panels will determine automatically which input fields should be displayed.

While using Nova Network backend the cloud may be configured to automatically assign floating IPs to instances. If Sahara service is configured to use those automatically assigned floating IPs the same configuration should be done to the dashboard through the SAHARA_AUTO_IP_ALLOCATION_ENABLED parameter.

Example:

SAHARA_AUTO_IP_ALLOCATION_ENABLED = True

2. Different endpoint

Sahara UI panels normally use data-processing endpoint from Keystone to talk to Sahara service. In some cases it may be useful to switch to another endpoint, for example use locally installed Sahara instead of the one on the OpenStack controller.

To switch the UI to another endpoint the endpoint should be registered in the first place.

Local endpoint example:

keystone service-create --name sahara_local --type data_processing_local \
    --description "Sahara Data Processing (local installation)"

keystone endpoint-create --service sahara_local --region RegionOne \
    --publicurl "http://127.0.0.1:8386/v1.1/%(tenant_id)s" \
    --adminurl "http://127.0.0.1:8386/v1.1/%(tenant_id)s" \
    --internalurl "http://127.0.0.1:8386/v1.1/%(tenant_id)s"

Then the endpoint name should be changed in sahara.py under the openstack_dashboard.contrib.sahara.api module.

# "type" of Sahara service registered in keystone
SAHARA_SERVICE = 'data_processing_local'

Sahara Advanced Configuration Guide

This guide addresses specific aspects of Sahara configuration that pertain to advanced usage. It is divided into sections about various features that can be utilized, and their related configurations.

Custom network topologies

Sahara accesses instances at several stages of cluster spawning through SSH and HTTP. Floating IPs and network namespaces (see Networking configuration) will be automatically used for access when present. When floating IPs are not assigned to instances and namespaces are not being used, sahara will need an alternative method to reach them.

The proxy_command parameter of the configuration file can be used to give sahara a command to access instances. This command is run on the sahara host and must open a netcat socket to the instance destination port. The {host} and {port} keywords should be used to describe the destination, they will be substituted at runtime. Other keywords that can be used are: {tenant_id}, {network_id} and {router_id}.

For example, the following parameter in the sahara configuration file would be used if instances are accessed through a relay machine:

[DEFAULT]
proxy_command='ssh relay-machine-{tenant_id} nc {host} {port}'

Whereas the following shows an example of accessing instances though a custom network namespace:

[DEFAULT]
proxy_command='ip netns exec ns_for_{network_id} nc {host} {port}'

Data-locality configuration

Hadoop provides the data-locality feature to enable task tracker and data nodes the capability of spawning on the same rack, Compute node, or virtual machine. Sahara exposes this functionality to the user through a few configuration parameters and user defined topology files.

To enable data-locality, set the enable_data_locality parameter to True in the sahara configuration file

[DEFAULT]
enable_data_locality=True

With data locality enabled, you must now specify the topology files for the Compute and Object Storage services. These files are specified in the sahara configuration file as follows:

[DEFAULT]
compute_topology_file=/etc/sahara/compute.topology
swift_topology_file=/etc/sahara/swift.topology

The compute_topology_file should contain mappings between Compute nodes and racks in the following format:

compute1 /rack1
compute2 /rack2
compute3 /rack2

Note that the Compute node names must be exactly the same as configured in OpenStack (host column in admin list for instances).

The swift_topology_file should contain mappings between Object Storage nodes and racks in the following format:

node1 /rack1
node2 /rack2
node3 /rack2

Note that the Object Storage node names must be exactly the same as configured in the object ring. Also, you should ensure that instances with the task tracker process have direct access to the Object Storage nodes.

Hadoop versions after 1.2.0 support four-layer topology (for more detail please see HADOOP-8468 JIRA issue). To enable this feature set the enable_hypervisor_awareness parameter to True in the configuration file. In this case sahara will add the Compute node ID as a second level of topology for virtual machines.

Distributed mode configuration

Sahara can be configured to run in a distributed mode that creates a separation between the API and engine processes. This allows the API process to remain relatively free to handle requests while offloading intensive tasks to the engine processes.

The sahara-api application works as a front-end and serves user requests. It offloads ‘heavy’ tasks to the sahara-engine process via RPC mechanisms. While the sahara-engine process could be loaded with tasks, sahara-api stays free and hence may quickly respond to user queries.

If sahara runs on several hosts, the API requests could be balanced between several sahara-api hosts using a load balancer. It is not required to balance load between different sahara-engine hosts as this will be automatically done via the message broker.

If a single host becomes unavailable, other hosts will continue serving user requests. Hence, a better scalability is achieved and some fault tolerance as well. Note that distributed mode is not a true high availability. While the failure of a single host does not affect the work of the others, all of the operations running on the failed host will stop. For example, if a cluster scaling is interrupted, the cluster will be stuck in a half-scaled state. The cluster might continue working, but it will be impossible to scale it further or run jobs on it via EDP.

To run sahara in distributed mode pick several hosts on which you want to run sahara services and follow these steps:

• On each host install and configure sahara using the installation guide except:

  • Do not run sahara-db-manage or launch sahara with sahara-all
  • Ensure that each configuration file provides a database connection string to a single database for all hosts.

• Run sahara-db-manage as described in the installation guide, but only on a single (arbitrarily picked) host.

• The sahara-api and sahara-engine processes use oslo.messaging to communicate with each other. You will need to configure it properly on each host (see below).

• Run sahara-api and sahara-engine on the desired hosts. You may run both processes on the same or separate hosts as long as they are configured to use the same message broker and database.

To configure oslo.messaging, first you will need to choose a message broker driver. Currently there are three drivers provided: RabbitMQ, Qpid or ZeroMQ. For the RabbitMQ or Qpid drivers please see the Notifications configuration documentation for an explanation of common configuration options.

For an expanded view of all the options provided by each message broker driver in oslo.messaging please refer to the options available in the respective source trees:

• For Rabbit MQ see
  • rabbit_opts variable in impl_rabbit.py
  • amqp_opts variable in amqp.py
• For Qpid see
  • qpid_opts variable in impl_qpid.py
  • amqp_opts variable in amqp.py
• For Zmq see
  • zmq_opts variable in impl_zmq.py
  • matchmaker_opts variable in matchmaker.py
  • matchmaker_redis_opts variable in matchmaker_redis.py
  • matchmaker_opts variable in matchmaker_ring.py

These options will also be present in the generated sample configuration file. For instructions on creating the configuration file please see the Sahara Configuration Guide.

External key manager usage (EXPERIMENTAL)

Sahara generates and stores several passwords during the course of operation. To harden sahara’s usage of passwords it can be instructed to use an external key manager for storage and retrieval of these secrets. To enable this feature there must first be an OpenStack Key Manager service deployed within the stack. Currently, the barbican project is the only key manager supported by sahara.

With a Key Manager service deployed on the stack, sahara must be configured to enable the external storage of secrets. This is accomplished by editing the sahara configuration file as follows:

[DEFAULT]
use_external_key_manager=True

Additionally, at this time there are two more values which must be provided to ensure proper access for sahara to the Key Manager service. These are the Identity domain for the administrative user and the domain for the administrative project. By default these values will appear as:

[DEFAULT]
admin_user_domain_name=default
admin_project_domain_name=default

With all of these values configured and the Key Manager service deployed, sahara will begin storing its secrets in the external manager.

Indirect instance access through proxy nodes

Warning

The indirect VMs access feature is in alpha state. We do not recommend using it in a production environment.

Sahara needs to access instances through SSH during cluster setup. This access can be obtained a number of different ways (see Networking configuration, Floating IP management, Custom network topologies). Sometimes it is impossible to provide access to all nodes (because of limited numbers of floating IPs or security policies). In these cases access can be gained using other nodes of the cluster as proxy gateways. To enable this set is_proxy_gateway=True for the node group you want to use as proxy. Sahara will communicate with all other cluster instances through the instances of this node group.

Note, if use_floating_ips=true and the cluster contains a node group with is_proxy_gateway=True, the requirement to have floating_ip_pool specified is applied only to the proxy node group. Other instances will be accessed through proxy instances using the standard private network.

Note, the Cloudera Hadoop plugin doesn’t support access to Cloudera manager through a proxy node. This means that for CDH clusters only nodes with the Cloudera manager can be designated as proxy gateway nodes.

Multi region deployment

Sahara supports multi region deployment. To enable this option each instance of sahara should have the os_region_name=<region> parameter set in the configuration file. The following example demonstrates configuring sahara to use the RegionOne region:

[DEFAULT]
os_region_name=RegionOne

Non-root users

In cases where a proxy command is being used to access cluster instances (for example, when using namespaces or when specifying a custom proxy command), rootwrap functionality is provided to allow users other than root access to the needed operating system facilities. To use rootwrap the following configuration parameter is required to be set:

[DEFAULT]
use_rootwrap=True

Assuming you elect to leverage the default rootwrap command (sahara-rootwrap), you will need to perform the following additional setup steps:

• Copy the provided sudoers configuration file from the local project file etc/sudoers.d/sahara-rootwrap to the system specific location, usually /etc/sudoers.d. This file is setup to allow a user named sahara access to the rootwrap script. It contains the following:

sahara ALL = (root) NOPASSWD: /usr/bin/sahara-rootwrap /etc/sahara/rootwrap.conf *

• Copy the provided rootwrap configuration file from the local project file etc/sahara/rootwrap.conf to the system specific location, usually /etc/sahara. This file contains the default configuration for rootwrap.
• Copy the provided rootwrap filters file from the local project file etc/sahara/rootwrap.d/sahara.filters to the location specified in the rootwrap configuration file, usually /etc/sahara/rootwrap.d. This file contains the filters that will allow the sahara user to access the ip netns exec, nc, and kill commands through the rootwrap (depending on proxy_command you may need to set additional filters). It should look similar to the followings:

[Filters]
ip: IpNetnsExecFilter, ip, root
nc: CommandFilter, nc, root
kill: CommandFilter, kill, root

If you wish to use a rootwrap command other than sahara-rootwrap you can set the following parameter in your sahara configuration file:

[DEFAULT]
rootwrap_command='sudo sahara-rootwrap /etc/sahara/rootwrap.conf'

For more information on rootwrap please refer to the official Rootwrap documentation

Object Storage access using proxy users

To improve security for clusters accessing files in Object Storage, sahara can be configured to use proxy users and delegated trusts for access. This behavior has been implemented to reduce the need for storing and distributing user credentials.

The use of proxy users involves creating an Identity domain that will be designated as the home for these users. Proxy users will be created on demand by sahara and will only exist during a job execution which requires Object Storage access. The domain created for the proxy users must be backed by a driver that allows sahara’s admin user to create new user accounts. This new domain should contain no roles, to limit the potential access of a proxy user.

Once the domain has been created, sahara must be configured to use it by adding the domain name and any potential delegated roles that must be used for Object Storage access to the sahara configuration file. With the domain enabled in sahara, users will no longer be required to enter credentials for their data sources and job binaries referenced in Object Storage.

Detailed instructions

First a domain must be created in the Identity service to hold proxy users created by sahara. This domain must have an identity backend driver that allows for sahara to create new users. The default SQL engine is sufficient but if your keystone identity is backed by LDAP or similar then domain specific configurations should be used to ensure sahara’s access. Please see the Keystone documentation for more information.

With the domain created, sahara’s configuration file should be updated to include the new domain name and any potential roles that will be needed. For this example let’s assume that the name of the proxy domain is sahara_proxy and the roles needed by proxy users will be Member and SwiftUser.

[DEFAULT]
use_domain_for_proxy_users=True
proxy_user_domain_name=sahara_proxy
proxy_user_role_names=Member,SwiftUser

A note on the use of roles. In the context of the proxy user, any roles specified here are roles intended to be delegated to the proxy user from the user with access to Object Storage. More specifically, any roles that are required for Object Storage access by the project owning the object store must be delegated to the proxy user for authentication to be successful.

Finally, the stack administrator must ensure that images registered with sahara have the latest version of the Hadoop swift filesystem plugin installed. The sources for this plugin can be found in the sahara extra repository. For more information on images or swift integration see the sahara documentation sections Building Images for Vanilla Plugin and Swift Integration.

Volume instance locality configuration

The Block Storage service provides the ability to define volume instance locality to ensure that instance volumes are created on the same host as the hypervisor. The InstanceLocalityFilter provides the mechanism for the selection of a storage provider located on the same physical host as an instance.

To enable this functionality for instances of a specific node group, the volume_local_to_instance field in the node group template should be set to True and some extra configurations are needed:

• The cinder-volume service should be launched on every physical host and at least one physical host should run both cinder-scheduler and cinder-volume services.

• InstanceLocalityFilter should be added to the list of default filters (scheduler_default_filters in cinder) for the Block Storage configuration.

• The Extended Server Attributes extension needs to be active in the Compute service (this is true by default in nova), so that the OS-EXT-SRV-ATTR:host property is returned when requesting instance info.

• The user making the call needs to have sufficient rights for the property to be returned by the Compute service. This can be done by:

  • by changing nova’s policy.json to allow the user access to the extended_server_attributes option.

  • by designating an account with privileged rights in the cinder configuration:

    os_privileged_user_name =
    os_privileged_user_password =
    os_privileged_user_tenant =
    

It should be noted that in a situation when the host has no space for volume creation, the created volume will have an Error state and can not be used.

Autoconfiguration for templates

Autoconfiguring templates

NTP service configuration

By default sahara will enable the NTP service on all cluster instances if the NTP package is included in the image (the sahara disk image builder will include NTP in all images it generates). The default NTP server will be pool.ntp.org; this can be overridden using the default_ntp_server setting in the DEFAULT section of the sahara configuration file. If you are creating cluster templates using the sahara UI and would like to specify a different NTP server for a particular cluster template, use the URL of NTP server setting in the General Parameters section when you create the template. If you would like to disable NTP for a particular cluster template, deselect the Enable NTP service checkbox in the General Parameters section when you create the template.

If you are creating clusters using the sahara CLI, you can specify another NTP server or disable NTP service using the examples below.

If you want to disable configuring the NTP service, you should specify the following configs for the cluster:

cluster_configs: {
    "general": {
        "URL of NTP server": "your_server.net",
    }
}

If you want to disable configuring NTP service, you should specify following configs for the cluster:

"cluster_configs": {
    "general": {
        "Enable NTP service": false,
    }
}

CORS (Cross Origin Resource Sharing) Configuration

Sahara provides direct API access to user-agents (browsers) via the HTTP CORS protocol. Detailed documentation, as well as troubleshooting examples, may be found in the OpenStack Cloud Admin Guide.

To get started quickly, use the example configuration block below, replacing the allowed origin field with the host(s) from which your API expects access.

[cors]
allowed_origin=https://we.example.com:443
max_age=3600
allow_credentials=true

[cors.additional_domain_1]
allowed_origin=https://additional_domain_1.example.com:443

[cors.additional_domain_2]
allowed_origin=https://additional_domain_2.example.com:443

For more information on Cross Origin Resource Sharing, please review the W3C CORS specification.

Sahara Upgrade Guide

This page contains details about upgrading sahara between releases such as configuration file updates, database migrations, and architectural changes.

Icehouse -> Juno

Main binary renamed to sahara-all

The All-In-One sahara binary has been renamed from sahara-api to sahara-all. The new name should be used in all cases where the All-In-One sahara is desired.

Authentication middleware changes

The custom auth_token middleware has been deprecated in favor of the keystone middleware. This change requires an update to the sahara configuration file. To update your configuration file you should replace the following parameters from the [DEFAULT] section with the new parameters in the [keystone_authtoken] section:

Old parameter name	New parameter name
os_admin_username	admin_user
os_admin_password	admin_password
os_admin_tenant_name	admin_tenant_name

Additionally, the parameters os_auth_protocol, os_auth_host, and os_auth_port have been combined to create the auth_uri and identity_uri parameters. These new parameters should be full URIs to the keystone public and admin endpoints, respectively.

For more information about these configuration parameters please see the Sahara Configuration Guide.

Database package changes

The oslo based code from sahara.openstack.common.db has been replaced by the usage of the oslo.db package. This change does not require any update to sahara’s configuration file.

Additionally, the usage of SQLite databases has been deprecated. Please use MySQL or PostgreSQL databases for sahara. SQLite has been deprecated because it does not, and is not going to, support the ALTER COLUMN and DROP COLUMN commands required for migrations between versions. For more information please see http://www.sqlite.org/omitted.html

Sahara integration into OpenStack Dashboard

The sahara dashboard package has been deprecated in the Juno release. The functionality of the dashboard has been fully incorporated into the OpenStack Dashboard. The sahara interface is available under the “Project” -> “Data Processing” tab.

The Data processing service endpoints must be registered in the Identity service catalog for the Dashboard to properly recognize and display those user interface components. For more details on this process please see registering Sahara in installation guide.

The sahara-dashboard project is now used solely to host sahara user interface integration tests.

Virtual machine user name changes

The HEAT infrastructure engine has been updated to use the same rules for instance user names as the direct engine. In previous releases the user name for instances created by sahara using HEAT was always ‘ec2-user’. As of Juno, the user name is taken from the image registry as described in the Registering an Image document.

This change breaks backward compatibility for clusters created using the HEAT infrastructure engine prior to the Juno release. Clusters will continue to operate, but we do not recommended using the scaling operations with them.

Anti affinity implementation changed

Starting with the Juno release the anti affinity feature is implemented using server groups. From the user perspective there will be no noticeable changes with this feature. Internally this change has introduced the following behavior:

1. Server group objects will be created for any clusters with anti affinity enabled.
2. Affected instances on the same host will not be allowed even if they do not have common processes. Prior to Juno, instances with differing processes were allowed on the same host. The new implementation guarantees that all affected instances will be on different hosts regardless of their processes.

The new anti affinity implementation will only be applied for new clusters. Clusters created with previous versions will continue to operate under the older implementation, this applies to scaling operations on these clusters as well.

Juno -> Kilo

Sahara requires policy configuration

Sahara now requires a policy configuration file. The policy.json file should be placed in the same directory as the sahara configuration file or specified using the policy_file parameter. For more details about the policy file please see the policy section in the configuration guide.

Kilo -> Liberty

Direct engine deprecation

In the Liberty release the direct infrastructure engine has been deprecated and the heat infrastructure engine is now default. This means, that it is preferable to use heat engine instead now. In the Liberty release you can continue to operate clusters with the direct engine (create, delete, scale). Using heat engine only the delete operation is available on clusters that were created by the direct engine. After the Liberty release the direct engine will be removed, this means that you will only be able to delete clusters created with the direct engine.

Policy namespace changed (policy.json)

The “data-processing:” namespace has been added to the beginning of the all Sahara’s policy based actions, so, you need to update the policy.json file by prepending all actions with “data-processing:”.

How To

Getting Started

Clusters

A cluster deployed by sahara consists of node groups. Node groups vary by their role, parameters and number of machines. The picture below illustrates an example of a Hadoop cluster consisting of 3 node groups each having a different role (set of processes).

Node group parameters include Hadoop parameters like io.sort.mb or mapred.child.java.opts, and several infrastructure parameters like the flavor for VMs or storage location (ephemeral drive or cinder volume).

A cluster is characterized by its node groups and its parameters. Like a node group, a cluster has data processing framework and infrastructure parameters. An example of a cluster-wide Hadoop parameter is dfs.replication. For infrastructure, an example could be image which will be used to launch cluster VMs.

Templates

In order to simplify cluster provisioning sahara employs the concept of templates. There are two kinds of templates: node group templates and cluster templates. The former is used to create node groups, the latter - clusters. Essentially templates have the very same parameters as corresponding entities. Their aim is to remove the burden of specifying all of the required parameters each time a user wants to launch a cluster.

In the REST interface, templates have extended functionality. First you can specify node-scoped parameters here, they will work as defaults for node groups. Also with the REST interface, during cluster creation a user can override template parameters for both cluster and node groups.

Provisioning Plugins

A provisioning plugin is a component responsible for provisioning a data processing cluster. Generally each plugin is capable of provisioning a specific data processing framework or Hadoop distribution. Also the plugin can install management and/or monitoring tools for a cluster.

Since framework configuration parameters vary depending on the distribution and the version, templates are always plugin and version specific. A template cannot be used if the plugin, or framework, versions are different than the ones they were created for.

You may find the list of available plugins on that page: Provisioning Plugins

Image Registry

OpenStack starts VMs based on a pre-built image with an installed OS. The image requirements for sahara depend on the plugin and data processing framework version. Some plugins require just a basic cloud image and will install the framework on the VMs from scratch. Some plugins might require images with pre-installed frameworks or Hadoop distributions.

The Sahara Image Registry is a feature which helps filter out images during cluster creation. See Registering an Image for details on how to work with Image Registry.

Features

Sahara has several interesting features. The full list could be found there: Features Overview

Sahara (Data Processing) UI User Guide

This guide assumes that you already have the Sahara service and Horizon dashboard up and running. Don’t forget to make sure that Sahara is registered in Keystone. If you require assistance with that, please see the installation guide.

The sections below give a panel by panel overview of setting up clusters and running jobs. For a description of using the guided cluster and job tools, look at Launching a cluster via the Cluster Creation Guide and Running a job via the Job Execution Guide.

Launching a cluster via the Sahara UI

Registering an Image

1. Navigate to the “Project” dashboard, then the “Data Processing” tab, then click on the “Image Registry” panel
2. From that page, click on the “Register Image” button at the top right
3. Choose the image that you’d like to register with Sahara
4. Enter the username of the cloud-init user on the image
5. Click on the tags that you want to add to the image. (A version ie: 1.2.1 and a type ie: vanilla are required for cluster functionality)
6. Click the “Done” button to finish the registration

Create Node Group Templates

1. Navigate to the “Project” dashboard, then the “Data Processing” tab, then click on the “Node Group Templates” panel
2. From that page, click on the “Create Template” button at the top right
3. Choose your desired Plugin name and Version from the dropdowns and click “Create”
4. Give your Node Group Template a name (description is optional)
5. Choose a flavor for this template (based on your CPU/memory/disk needs)
6. Choose the storage location for your instance, this can be either “Ephemeral Drive” or “Cinder Volume”. If you choose “Cinder Volume”, you will need to add additional configuration
7. Choose which processes should be run for any instances that are spawned from this Node Group Template
8. Click on the “Create” button to finish creating your Node Group Template

Create a Cluster Template

1. Navigate to the “Project” dashboard, then the “Data Processing” tab, then click on the “Cluster Templates” panel
2. From that page, click on the “Create Template” button at the top right
3. Choose your desired Plugin name and Version from the dropdowns and click “Create”
4. Under the “Details” tab, you must give your template a name
5. Under the “Node Groups” tab, you should add one or more nodes that can be based on one or more templates

• To do this, start by choosing a Node Group Template from the dropdown and click the “+” button
• You can adjust the number of nodes to be spawned for this node group via the text box or the “-” and “+” buttons
• Repeat these steps if you need nodes from additional node group templates

6. Optionally, you can adjust your configuration further by using the “General Parameters”, “HDFS Parameters” and “MapReduce Parameters” tabs
7. Click on the “Create” button to finish creating your Cluster Template

Launching a Cluster

1. Navigate to the “Project” dashboard, then the “Data Processing” tab, then click on the “Clusters” panel
2. Click on the “Launch Cluster” button at the top right
3. Choose your desired Plugin name and Version from the dropdowns and click “Create”
4. Give your cluster a name (required)
5. Choose which cluster template should be used for your cluster
6. Choose the image that should be used for your cluster (if you do not see any options here, see Registering an Image above)
7. Optionally choose a keypair that can be used to authenticate to your cluster instances
8. Click on the “Create” button to start your cluster

• Your cluster’s status will display on the Clusters table
• It will likely take several minutes to reach the “Active” state

Scaling a Cluster

1. From the Data Processing/Clusters page, click on the “Scale Cluster” button of the row that contains the cluster that you want to scale
2. You can adjust the numbers of instances for existing Node Group Templates
3. You can also add a new Node Group Template and choose a number of instances to launch

• This can be done by selecting your desired Node Group Template from the dropdown and clicking the “+” button
• Your new Node Group will appear below and you can adjust the number of instances via the text box or the “+” and “-” buttons

4. To confirm the scaling settings and trigger the spawning/deletion of instances, click on “Scale”

Elastic Data Processing (EDP)

Data Sources

Data Sources are where the input and output from your jobs are housed.

1. From the Data Processing/Data Sources page, click on the “Create Data Source” button at the top right
2. Give your Data Source a name
3. Enter the URL of the Data Source

• For a Swift object, enter <container>/<path> (ie: mycontainer/inputfile). Sahara will prepend swift:// for you
• For an HDFS object, enter an absolute path, a relative path or a full URL:
  • /my/absolute/path indicates an absolute path in the cluster HDFS
  • my/path indicates the path /user/hadoop/my/path in the cluster HDFS assuming the defined HDFS user is hadoop
  • hdfs://host:port/path can be used to indicate any HDFS location

4. Enter the username and password for the Data Source (also see Additional Notes)
5. Enter an optional description
6. Click on “Create”
7. Repeat for additional Data Sources

Job Binaries

Job Binaries are where you define/upload the source code (mains and libraries) for your job.

1. From the Data Processing/Job Binaries page, click on the “Create Job Binary” button at the top right
2. Give your Job Binary a name (this can be different than the actual filename)
3. Choose the type of storage for your Job Binary

• For “Swift”, enter the URL of your binary (<container>/<path>) as well as the username and password (also see Additional Notes)
• For “Internal database”, you can choose from “Create a script” or “Upload a new file”

4. Enter an optional description
5. Click on “Create”
6. Repeat for additional Job Binaries

Job Templates (Known as “Jobs” in the API)

Job templates are where you define the type of job you’d like to run as well as which “Job Binaries” are required.

1. From the Data Processing/Jobs page, click on the “Create Job Template” button at the top right
2. Give your Job Template a name
3. Choose the type of job you’d like to run
4. Choose the main binary from the dropdown
   • This is required for Hive, Pig, and Spark jobs
   • Other job types do not use a main binary
5. Enter an optional description for your Job Template
6. Click on the “Libs” tab and choose any libraries needed by your job template
   • MapReduce and Java jobs require at least one library
   • Other job types may optionally use libraries
7. Click on “Create”

Jobs (Known as “Job Executions” in the API)

Jobs are what you get by “Launching” a job template. You can monitor the status of your job to see when it has completed its run

1. From the Data Processing/Job Templates page, find the row that contains the job template you want to launch and click either “Launch on New Cluster” or “Launch on Existing Cluster” the right side of that row
2. Choose the cluster (already running–see Launching a Cluster above) on which you would like the job to run
3. Choose the Input and Output Data Sources (Data Sources defined above)
4. If additional configuration is required, click on the “Configure” tab

• Additional configuration properties can be defined by clicking on the “Add” button
• An example configuration entry might be mapred.mapper.class for the Name and org.apache.oozie.example.SampleMapper for the Value

5. Click on “Launch”. To monitor the status of your job, you can navigate to the Data Processing/Jobs panel
6. You can relaunch a Job from the Jobs page by using the “Relaunch on New Cluster” or “Relaunch on Existing Cluster” links

• Relaunch on New Cluster will take you through the forms to start a new cluster before letting you specify input/output Data Sources and job configuration
• Relaunch on Existing Cluster will prompt you for input/output Data Sources as well as allow you to change job configuration before launching the job

Example Jobs

There are sample jobs located in the Sahara repository. In this section, we will give a walkthrough on how to run those jobs via the Horizon UI. These steps assume that you already have a cluster up and running (in the “Active” state).

1. Sample Pig job - https://github.com/openstack/sahara/tree/master/etc/edp-examples/edp-pig/trim-spaces

• Load the input data file from https://github.com/openstack/sahara/tree/master/etc/edp-examples/edp-pig/trim-spaces/data/input into swift
  • Click on Project/Object Store/Containers and create a container with any name (“samplecontainer” for our purposes here)
  • Click on Upload Object and give the object a name (“piginput” in this case)
• Navigate to Data Processing/Data Sources, Click on Create Data Source
  • Name your Data Source (“pig-input-ds” in this sample)
  • Type = Swift, URL samplecontainer/piginput, fill-in the Source username/password fields with your username/password and click “Create”
• Create another Data Source to use as output for the job
  • Name = pig-output-ds, Type = Swift, URL = samplecontainer/pigoutput, Source username/password, “Create”
• Store your Job Binaries in the Sahara database
  • Navigate to Data Processing/Job Binaries, Click on Create Job Binary
  • Name = example.pig, Storage type = Internal database, click Browse and find example.pig wherever you checked out the sahara project <sahara root>/etc/edp-examples/edp-pig/trim-spaces
  • Create another Job Binary: Name = udf.jar, Storage type = Internal database, click Browse and find udf.jar wherever you checked out the sahara project <sahara root>/etc/edp-examples/edp-pig/trim-spaces
• Create a Job Template
  • Navigate to Data Processing/Job Templates, Click on Create Job Template
  • Name = pigsample, Job Type = Pig, Choose “example.pig” as the main binary
  • Click on the “Libs” tab and choose “udf.jar”, then hit the “Choose” button beneath the dropdown, then click on “Create”
• Launch your job
  • To launch your job from the Job Templates page, click on the down arrow at the far right of the screen and choose “Launch on Existing Cluster”
  • For the input, choose “pig-input-ds”, for output choose “pig-output-ds”. Also choose whichever cluster you’d like to run the job on
  • For this job, no additional configuration is necessary, so you can just click on “Launch”
  • You will be taken to the “Jobs” page where you can see your job progress through “PENDING, RUNNING, SUCCEEDED” phases
  • When your job finishes with “SUCCEEDED”, you can navigate back to Object Store/Containers and browse to the samplecontainer to see your output. It should be in the “pigoutput” folder

2. Sample Spark job - https://github.com/openstack/sahara/tree/master/etc/edp-examples/edp-spark

• Store the Job Binary in the Sahara database
  • Navigate to Data Processing/Job Binaries, Click on Create Job Binary
  • Name = sparkexample.jar, Storage type = Internal database, Browse to the location <sahara root>/etc/edp-examples/edp-spark and choose spark-example.jar, Click “Create”
• Create a Job Template
  • Name = sparkexamplejob, Job Type = Spark, Main binary = Choose sparkexample.jar, Click “Create”
• Launch your job
  • To launch your job from the Job Templates page, click on the down arrow at the far right of the screen and choose “Launch on Existing Cluster”
  • Choose whichever cluster you’d like to run the job on
  • Click on the “Configure” tab
  • Set the main class to be: org.apache.spark.examples.SparkPi
  • Under Arguments, click Add and fill in the number of “Slices” you want to use for the job. For this example, let’s use 100 as the value
  • Click on Launch
  • You will be taken to the “Jobs” page where you can see your job progress through “PENDING, RUNNING, SUCCEEDED” phases
  • When your job finishes with “SUCCEEDED”, you can see your results by sshing to the Spark “master” node
  • The output is located at /tmp/spark-edp/<name of job template>/<job id>. You can do cat stdout which should display something like “Pi is roughly 3.14156132”
  • It should be noted that for more complex jobs, the input/output may be elsewhere. This particular job just writes to stdout, which is logged in the folder under /tmp

Additional Notes

1. Throughout the Sahara UI, you will find that if you try to delete an object that you will not be able to delete it if another object depends on it. An example of this would be trying to delete a Job Template that has an existing Job. In order to be able to delete that job, you would first need to delete any Job Templates that relate to that job.
2. In the examples above, we mention adding your username/password for the Swift Data Sources. It should be noted that it is possible to configure Sahara such that the username/password credentials are not required. For more information on that, please refer to: Sahara Advanced Configuration Guide

Launching a cluster via the Cluster Creation Guide

1. Under the Data Processing group, choose “Guides” and then click on the “Cluster Creation Guide” button.
2. Click on the “Choose Plugin” button then select the cluster type from the Plugin Name dropdown and choose your target version. When done, click on “Select” to proceed.
3. Click on “Create a Master Node Group Template”. Give your template a name, choose a flavor and choose which processes should run on nodes launched for this node group. The processes chosen here should be things that are more server-like in nature (namenode, oozieserver, spark master, etc). Optionally, you can set other options here such as availability zone, storage, security and process specific parameters. Click on “Create” to proceed.
4. Click on “Create a Worker Node Group Template”. Give your template a name, choose a flavor and choose which processes should run on nodes launched for this node group. Processes chosen here should be more worker-like in nature (datanode, spark slave, task tracker, etc). Optionally, you can set other options here such as availability zone, storage, security and process specific parameters. Click on “Create” to proceed.
5. Click on “Create a Cluster Template”. Give your template a name. Next, click on the “Node Groups” tab and enter the count for each of the node groups (these are pre-populated from steps 3 and 4). It would be common to have 1 for the “master” node group type and some larger number of “worker” instances depending on you desired cluster size. Optionally, you can also set additional parameters for cluster-wide settings via the other tabs on this page. Click on “Create” to proceed.
6. Click on “Launch a Cluster”. Give your cluster a name and choose the image that you want to use for all instances in your cluster. The cluster template that you created in step 5 is already pre-populated. If you want ssh access to the instances of your cluster, select a keypair from the dropdown. Click on “Launch” to proceed. You will be taken to the Clusters panel where you can see your cluster progress toward the Active state.

Running a job via the Job Execution Guide

1. Under the Data Processing group, choose “Guides” and then click on the “Job Execution Guide” button.
2. Click on “Select type” and choose the type of job that you want to run.
3. If your job requires input/output data sources, you will have the option to create them via the “Create a Data Source” button (Note: This button will not be shown for job types that do not require data sources). Give your data source a name and choose the type. If you have chosen swift, you may also enter the username and password. Enter the URL for your data source. For more details on what the URL should look like, see Data Sources.
4. Click on “Create a job template”. Give your job template a name. Depending on the type of job that you’ve chosen, you may need to select your main binary and/or additional libraries (available from the “Libs” tab). If you have not yet uploaded the files to run your program, you can add them via the “+” icon next to the “Choose a main binary” select box.
5. Click on “Launch job”. Choose the active cluster where you want to run you job. Optionally, you can click on the “Configure” tab and provide any required configuration, arguments or parameters for your job. Click on “Launch” to execute your job. You will be taken to the Jobs panel where you can monitor the state of your job as it progresses.

Features Overview

This page highlights some of the most prominent features available in sahara. The guidance provided here is primarily focused on the runtime aspects of sahara. For discussions about configuring the sahara server processes please see the Sahara Configuration Guide and Sahara Advanced Configuration Guide.

Anti-affinity

One of the problems with running data processing applications on OpenStack is the inability to control where an instance is actually running. It is not always possible to ensure that two new virtual machines are started on different physical machines. As a result, any replication within the cluster is not reliable because all replicas may be co-located on one physical machine. To remedy this, sahara provides the anti-affinity feature to explicitly command all instances of the specified processes to spawn on different Compute nodes. This is especially useful for Hadoop data node processes to increase HDFS replica reliability.

Starting with the Juno release, sahara can create server groups with the anti-affinity policy to enable this feature. Sahara creates one server group per cluster and assigns all instances with affected processes to this server group. Refer to the Nova documentation on how server groups work.

This feature is supported by all plugins out of the box, and can be enabled during the cluster template creation.

Block Storage support

OpenStack Block Storage (cinder) can be used as an alternative for ephemeral drives on instances. Using Block Storage volumes increases the reliability of data which is important for HDFS services.

A user can set how many volumes will be attached to each instance in a node group and the size of each volume. All volumes are attached during cluster creation and scaling operations.

Cluster scaling

Cluster scaling allows users to change the number of running instances in a cluster without needing to recreate the cluster. Users may increase or decrease the number of instances in node groups or add new node groups to existing clusters. If a cluster fails to scale properly, all changes will be rolled back.

Data locality

For optimal performance, it is best for data processing applications to work on data local to the same rack, OpenStack Compute node, or virtual machine. Hadoop supports a data locality feature and can schedule jobs to task tracker nodes that are local for the input stream. In this manner the task tracker nodes can communicate directly with the local data nodes.

Sahara supports topology configuration for HDFS and Object Storage data sources. For more information on configuring this option please see the Data-locality configuration documentation.

Volume-to-instance locality

Having an instance and an attached volume on the same physical host can be very helpful in order to achieve high-performance disk I/O operations. To achieve this, sahara provides access to the Block Storage volume instance locality functionality.

For more information on using volume instance locality with sahara, please see the Volume instance locality configuration documentation.

Distributed Mode

The Sahara Installation Guide suggests launching sahara as a single sahara-all process. It is also possible to run sahara in distributed mode with sahara-api and sahara-engine processes running on several machines simultaneously. Running in distributed mode allows sahara to offload intensive tasks to the engine processes while keeping the API process free to handle requests.

For an expanded discussion of configuring sahara to run in distributed mode please see the Distributed mode configuration documentation.

Hadoop HDFS High Availability

Hadoop HDFS High Availability (HDFS HA) provides an architecture to ensure that HDFS will continue to work in the result of an active namenode failure. It uses 2 namenodes in an active/passive configuration to provide this availability.

High availability is achieved by using a set of journalnodes. Zookeeper servers, and ZooKeeper Failover Controllers (ZKFC), as well as additional configuration changes to HDFS and other services that use HDFS.

Currently HDFS HA is supported with the HDP 2.0.6 plugin and CDH 5.4.0 plugin. In HDP 2.0.6 plugin, the feature is enabled through a cluster_configs parameter in the cluster’s JSON:

"cluster_configs": {
        "HDFSHA": {
                "hdfs.nnha": true
        }
}

In CDH 5.4.0 plugin, the HDFS HA is enabled through adding several HDFS_JOURNALNODE roles in the node group templates of cluster template. When HDFS_JOURNALNODE roles are added and the roles setup meets below requirements, the HDFS HA is enabled.

• HDFS_JOURNALNODE number is odd, and at least 3.
• Zookeeper is enabled.
• NameNode and SecondaryNameNode are on different physical hosts by setting anti-affinity.

In this case, the original SecondrayNameNode node will be used as the Standby NameNode.

Networking support

Sahara supports both the nova-network and neutron implementations of OpenStack Networking. By default sahara is configured to behave as if the nova-network implementation is available. For OpenStack installations that are using the neutron project please see Networking configuration.

Object Storage support

Sahara can use OpenStack Object Storage (swift) to store job binaries and data sources utilized by its job executions and clusters. In order to leverage this support within Hadoop, including using Object Storage for data sources for EDP, Hadoop requires the application of a patch. For additional information about enabling this support, including patching Hadoop and configuring sahara, please refer to the Swift Integration documentation.

Shared Filesystem support

Sahara can also use NFS shares through the OpenStack Shared Filesystem service (manila) to store job binaries and data sources. See Elastic Data Processing (EDP) for more information on this feature.

Orchestration support

Sahara may use the OpenStack Orchestration engine (heat) to provision nodes for clusters. For more information about enabling Orchestration usage in sahara please see Orchestration configuration.

Plugin Capabilities

The following table provides a plugin capability matrix:

Feature	Plugin
	Vanilla	HDP	Cloudera	Spark
Nova and Neutron network	x	x	x	x
Cluster Scaling	x	Scale Up	x	x
Swift Integration	x	x	x	x
Cinder Support	x	x	x	x
Data Locality	x	x	N/A	x
EDP	x	x	x	x

Security group management

Sahara allows you to control which security groups will be used for created instances. This can be done by providing the security_groups parameter for the node group or node group template. The default for this option is an empty list, which will result in the default project security group being used for the instances.

Sahara may also create a security group for instances in the node group automatically. This security group will only contain open ports for required instance processes and the sahara engine. This option is useful for development and for when your installation is secured from outside environments. For production environments we recommend controlling the security group policy manually.

Shared and protected resources support

Sahara allows you to create resources that can be shared across tenants and protected from modifications.

To provide this feature all sahara objects that can be accessed through REST API have is_public and is_protected boolean fields. They can be initially created with enabled is_public and is_protected parameters or these parameters can be updated after creation. Both fields are set to False by default.

If some object has its is_public field set to True, it means that it’s visible not only from the tenant in which it was created, but from any other tenants too.

If some object has its is_protected field set to True, it means that it can not be modified (updated, scaled, canceled or deleted) unless this field is set to False.

Public objects created in one tenant can be used from other tenants (for example, a cluster can be created from a public cluster template which is created in another tenant), but modification operations are possible only from the tenant in which object was created.

Registering an Image

Sahara deploys a cluster of machines using images stored in Glance. Each plugin has its own requirements on the image contents (see specific plugin documentation for details). Two general requirements for an image are to have the cloud-init and the ssh-server packages installed.

Sahara requires the images to be registered in the Sahara Image Registry. A registered image must have two properties set:

• username - a name of the default cloud-init user.
• tags - certain tags mark image to be suitable for certain plugins.

The username depends on the image that is used and the tags depend on the plugin used. You can find both in the respective plugin’s documentation.

Plugins

Provisioning Plugins

This page lists all available provisioning plugins. In general a plugin enables sahara to deploy a specific data processing framework (for example, Hadoop) or distribution, and allows configuration of topology and management/monitoring tools.

• Vanilla Plugin - deploys Vanilla Apache Hadoop
• Hortonworks Data Platform Plugin - deploys Hortonworks Data Platform
• Spark Plugin - deploys Apache Spark with Cloudera HDFS
• MapR Distribution Plugin - deploys MapR plugin with MapR File System
• Cloudera Plugin - deploys Cloudera Hadoop

Vanilla Plugin

The vanilla plugin is a reference implementation which allows users to operate a cluster with Apache Hadoop.

For cluster provisioning prepared images should be used. They already have Apache Hadoop 2.7.1 installed.

You may build images by yourself using Building Images for Vanilla Plugin or you could download prepared images from http://sahara-files.mirantis.com/images/upstream/liberty/

Vanilla plugin requires an image to be tagged in Sahara Image Registry with two tags: ‘vanilla’ and ‘<hadoop version>’ (e.g. ‘2.7.1’).

The default username specified for these images is different for each distribution:

OS	username
Ubuntu 14.04	ubuntu
Fedora 20	fedora
CentOS 6.6	cloud-user
CentOS 7	centos

Known issue:

• Hive job has “KILLED” state after scaling cluster: https://bugs.launchpad.net/sahara/+bug/1413602

Cluster Validation

When user creates or scales a Hadoop cluster using a Vanilla plugin, the cluster topology requested by user is verified for consistency.

Currently there are the following limitations in cluster topology for Vanilla plugin:

For Vanilla Hadoop version 2.X.X:

• Cluster must contain exactly one namenode
• Cluster can contain at most one resourcemanager
• Cluster can contain at most one secondary namenode
• Cluster can contain at most one historyserver
• Cluster can contain at most one oozie and this process is also required for EDP
• Cluster can’t contain oozie without resourcemanager and without historyserver
• Cluster can’t have nodemanager nodes if it doesn’t have resourcemanager
• Cluster can have at most one hiveserver node.

Hortonworks Data Platform Plugin

The Hortonworks Data Platform (HDP) sahara plugin provides a way to provision HDP clusters on OpenStack using templates in a single click and in an easily repeatable fashion. As seen from the architecture diagram below, the sahara controller serves as the glue between Hadoop and OpenStack. The HDP plugin mediates between the sahara controller and Apache Ambari in order to deploy and configure Hadoop on OpenStack. Core to the HDP Plugin is Apache Ambari which is used as the orchestrator for deploying HDP on OpenStack.

The HDP plugin can make use of Ambari Blueprints for cluster provisioning.

Apache Ambari Blueprints

Apache Ambari Blueprints is a portable document definition, which provides a complete definition for an Apache Hadoop cluster, including cluster topology, components, services and their configurations. Ambari Blueprints can be consumed by the HDP plugin to instantiate a Hadoop cluster on OpenStack. The benefits of this approach is that it allows for Hadoop clusters to be configured and deployed using an Ambari native format that can be used with as well as outside of OpenStack allowing for clusters to be re-instantiated in a variety of environments.

For more information about Apache Ambari Blueprints, refer to: https://issues.apache.org/jira/browse/AMBARI-1783. Note that Apache Ambari Blueprints are not yet finalized.

Operation

The HDP Plugin performs the following four primary functions during cluster creation:

1. Software deployment - the plugin orchestrates the deployment of the required software to the target VMs
2. Services Installation - the Hadoop services configured for the node groups within the cluster are installed on the associated VMs
3. Services Configuration - the plugin merges the default configuration values and user provided configurations for each installed service to the cluster
4. Services Start - the plugin invokes the appropriate APIs to indicate to the Ambari Server that the cluster services should be started

Images

The sahara HDP plugin can make use of either minimal (operating system only) images or pre-populated HDP images. The base requirement for both is that the image is cloud-init enabled and contains a supported operating system (see http://docs.hortonworks.com/HDPDocuments/HDP1/HDP-1.2.4/bk_hdp1-system-admin-guide/content/sysadminguides_ha_chap2_3.html).

The advantage of a pre-populated image is that provisioning time is reduced, as packages do not need to be downloaded and installed which make up the majority of the time spent in the provisioning cycle. In addition, provisioning large clusters will put a burden on the network as packages for all nodes need to be downloaded from the package repository.

For more information about HDP images, refer to https://github.com/openstack/sahara-image-elements.

You could download well tested and up-to-date prepared images from http://sahara-files.mirantis.com/images/upstream/liberty/

HDP plugin requires an image to be tagged in sahara Image Registry with two tags: ‘hdp’ and ‘<hdp version>’ (e.g. ‘2.0.6’).

Also in the Image Registry you will need to specify username for an image. The username specified should be ‘cloud-user’.

HDFS NameNode High Availability

HDFS NameNode High Availability (Using the Quorum Journal Manager) can be deployed automatically with HDP 2.0.6. Currently the only way to deploy it is through the command line client (python-saharaclient) or sahara REST API by simply adding the following cluster_configs parameter in the cluster’s JSON :

"cluster_configs": {
        "HDFSHA": {
                "hdfs.nnha": true
        }
}

The NameNode High Availability is deployed using 2 NameNodes, one active and one standby. The NameNodes use a set of JOURNALNODES and ZOOKEEPER_SERVERS to ensure the necessary synchronization.

A typical Highly available HDP 2.0.6 cluster uses 2 separate NameNodes, at least 3 JOURNALNODES and at least 3 ZOOKEEPER_SERVERS.

When HDFS NameNode High Availability is enabled, the plugin will perform the following additional validations:

• Ensure the existence of 2 NAMENODES processes in the cluster
• Ensure the existence of at least 3 JOURNALNODES processes in the cluster
• Ensure the existence of at least 3 ZOOKEEPER_SERVERS processes in the cluster

Limitations

The HDP plugin currently has the following limitations:

• It is not possible to decrement the number of node-groups or hosts per node group in a sahara generated cluster.

HDP Version Support

The HDP plugin currently supports HDP 2.0.6.

Cluster Validation

Prior to Hadoop cluster creation, the HDP plugin will perform the following validation checks to ensure a successful Hadoop deployment:

• Ensure the existence of a NAMENODE process in the cluster
• Ensure the existence of a JOBTRACKER should any TASKTRACKER be deployed to the cluster
• Ensure the deployment of one Ambari Server instance to the cluster
• Ensure that each defined node group had an associated Ambari Agent configured

The HDP Plugin and sahara support

For more information, please contact Hortonworks.

Spark Plugin

The Spark plugin for sahara provides a way to provision Apache Spark clusters on OpenStack in a single click and in an easily repeatable fashion.

Currently Spark is installed in standalone mode, with no YARN or Mesos support.

Images

For cluster provisioning, prepared images should be used. The Spark plugin has been developed and tested with the images generated by sahara-image-elements:

• https://github.com/openstack/sahara-image-elements

The Ubuntu images generated by sahara-image-elements have Cloudera CDH 5.4.0 HDFS and Apache Spark installed. A prepared image for Spark 1.3.1 and CDH 5.4.0 HDFS can be found at the following location:

• http://sahara-files.mirantis.com/images/upstream/liberty/

The Spark plugin requires an image to be tagged in the sahara image registry with two tags: ‘spark’ and ‘<Spark version>’ (e.g. ‘1.3.1’).

Also you should specify the username of the default cloud-user used in the image. For the images available at the URLs listed above and for all the ones generated with the DIB it is ubuntu.

Note that the Spark cluster is deployed using the scripts available in the Spark distribution, which allow the user to start all services (master and slaves), stop all services and so on. As such (and as opposed to CDH HDFS daemons), Spark is not deployed as a standard Ubuntu service and if the virtual machines are rebooted, Spark will not be restarted.

Spark configuration

Spark needs few parameters to work and has sensible defaults. If needed they can be changed when creating the sahara cluster template. No node group options are available.

Once the cluster is ready, connect with ssh to the master using the ubuntu user and the appropriate ssh key. Spark is installed in /opt/spark and should be completely configured and ready to start executing jobs. At the bottom of the cluster information page from the OpenStack dashboard, a link to the Spark web interface is provided.

Cluster Validation

When a user creates an Hadoop cluster using the Spark plugin, the cluster topology requested by user is verified for consistency.

Currently there are the following limitations in cluster topology for the Spark plugin:

• Cluster must contain exactly one HDFS namenode
• Cluster must contain exactly one Spark master
• Cluster must contain at least one Spark slave
• Cluster must contain at least one HDFS datanode

The tested configuration co-locates the NameNode with the master and a DataNode with each slave to maximize data locality.

Cloudera Plugin

The Cloudera plugin is a Sahara plugin which allows the user to deploy and operate a cluster with Cloudera Manager.

The Cloudera plugin is enabled in Sahara by default. You can manually modify the Sahara configuration file (default /etc/sahara/sahara.conf) to explicitly enable or disable it in “plugins” line.

You need to build images using Building Images for Cloudera Plugin to produce images used to provision cluster or you could download prepared images from http://sahara-files.mirantis.com/images/upstream/liberty/ They already have Cloudera Express installed (5.0.0 or 5.3.0 version).

The cloudera plugin requires an image to be tagged in Sahara Image Registry with two tags: ‘cdh’ and ‘<cloudera version>’ (e.g. ‘5’ or ‘5.3.0’).

The default username specified for these images is different for each distribution:

OS	username
Ubuntu 12.04	ubuntu
CentOS 6.5	cloud-user

Services Supported

Currently below services are supported in both versions of Cloudera plugin: HDFS, Oozie, YARN, Spark, Zookeeper, Hive, Hue, HBase. 5.3.0 version of Cloudera Plugin also supported following services: Impala, Flume, Solr, Sqoop, and Key-value Store Indexer.

Note

Sentry service is enabled in Cloudera plugin. However, for we do not enable Kerberos authentication in the cluster, which is required for Sentry functionality, using Sentry service will not really take any effect, and other services depending on Sentry will not do any authentication too.

Cluster Validation

When the user performs an operation on the cluster using a Cloudera plugin, the cluster topology requested by the user is verified for consistency.

The following limitations are required in the cluster topology for the both cloudera plugin versions:

• Cluster must contain exactly one manager.
• Cluster must contain exactly one namenode.
• Cluster must contain exactly one secondarynamenode.
• Cluster must contain at least dfs_replication datanodes.
• Cluster can contain at most one resourcemanager and this process is also required by nodemanager.
• Cluster can contain at most one jobhistory and this process is also requried for resourcemanager.
• Cluster can contain at most one oozie and this process is also required for EDP.
• Cluster can’t contain oozie without datanode.
• Cluster can’t contain oozie without nodemanager.
• Cluster can’t contain oozie without jobhistory.
• Cluster can’t contain hive on the cluster without the following services: metastore, hive server, webcat and resourcemanager.
• Cluster can contain at most one hue server.
• Cluster can’t contain hue server without hive service and oozie.
• Cluster can contain at most one spark history server.
• Cluster can’t contain spark history server without resourcemanager.
• Cluster can’t contain hbase master service without at least one zookeeper and at least one hbase regionserver.
• Cluster can’t contain hbase regionserver without at least one hbase maser.

In case of 5.3.0 or 5.4.0 version of Cloudera Plugin there are few extra limitations in the cluster topology:

• Cluster can’t contain flume without at least one datanode.
• Cluster can contain at most one sentry server service.
• Cluster can’t contain sentry server service without at least one zookeeper and at least one datanode.
• Cluster can’t contain solr server without at least one zookeeper and at least one datanode.
• Cluster can contain at most one sqoop server.
• Cluster can’t contain sqoop server without at least one datanode, nodemanager and jobhistory.
• Cluster can’t contain hbase indexer without at least one datanode, zookeeper, solr server and hbase master.
• Cluster can contain at most one impala catalog server.
• Cluster can contain at most one impala statestore.
• Cluster can’t contain impala catalogserver without impala statestore, at least one impalad service, at least one datanode, and metastore.
• If using Imapala, the daemons must be installed on every datanode.

MapR Distribution Plugin

The MapR Sahara plugin allows to provision MapR clusters on OpenStack in an easy way and do it, quickly, conveniently and simply.

Operation

The MapR Plugin performs the following four primary functions during cluster creation:

1. MapR components deployment - the plugin manages the deployment of the required software to the target VMs
2. Services Installation - MapR services are installed according to provided roles list
3. Services Configuration - the plugin combines default settings with user provided settings
4. Services Start - the plugin starts appropriate services according to specified roles

Images

The Sahara MapR plugin can make use of either minimal (operating system only) images or pre-populated MapR images. The base requirement for both is that the image is cloud-init enabled and contains a supported operating system (see http://doc.mapr.com/display/MapR/OS+Support+Matrix).

The advantage of a pre-populated image is that provisioning time is reduced, as packages do not need to be downloaded which make up the majority of the time spent in the provisioning cycle. In addition, provisioning large clusters will put a burden on the network as packages for all nodes need to be downloaded from the package repository.

For more information about MapR images, refer to https://github.com/openstack/sahara-image-elements.

There are eight VM images provided for use with the MapR Plugin, that can also be built using the tools available in sahara-image-elements:

• https://s3-us-west-2.amazonaws.com/sahara-images/ubuntu_trusty_mapr_plain_latest.qcow2
• https://s3-us-west-2.amazonaws.com/sahara-images/centos_6.5_mapr_plain_latest.qcow2
• https://s3-us-west-2.amazonaws.com/sahara-images/ubuntu_trusty_mapr_3.1.1_latest.qcow2
• https://s3-us-west-2.amazonaws.com/sahara-images/centos_6.5_mapr_3.1.1_latest.qcow2
• https://s3-us-west-2.amazonaws.com/sahara-images/ubuntu_trusty_mapr_4.0.1_latest.qcow2
• https://s3-us-west-2.amazonaws.com/sahara-images/centos_6.5_mapr_4.0.1_latest.qcow2
• https://s3-us-west-2.amazonaws.com/sahara-images/ubuntu_trusty_mapr_4.0.2_latest.qcow2
• https://s3-us-west-2.amazonaws.com/sahara-images/centos_6.5_mapr_4.0.2_latest.qcow2

MapR plugin needs an image to be tagged in Sahara Image Registry with two tags: ‘mapr’ and ‘<MapR version>’ (e.g. ‘4.0.1.mrv2’).

Note that Spark should be run on plain or 4.0.1 images.

The default username specified for these images is different for each distribution:

OS	username
Ubuntu 14.04	ubuntu
CentOS 6.5	cloud-user

Hadoop Version Support

The MapR plugin currently supports Hadoop 0.20.2 (3.1.1, 4.0.1.mrv1, 4.0.2.mrv1), Hadoop 2.4.1 (4.0.2.mrv2) and Hadoop 2.5.1 (4.0.2.mrv2).

Cluster Validation

When the user creates or scales a Hadoop cluster using a mapr plugin, the cluster topology requested by the user is verified for consistency.

Every MapR cluster must contain:

• at least 1 CLDB process
• exactly 1 Webserver process
• odd number of ZooKeeper processes but not less than 1
• FileServer process on every node
• at least 1 Cinder volume or ephemeral drive per instance

Every Hadoop cluster must contain exactly 1 Oozie process

Every MapReduce v1 cluster must contain:

• at least 1 JobTracker process
• at least 1 TaskTracker process

Every MapReduce v2 cluster must contain:

• exactly 1 ResourceManager process
• exactly 1 HistoryServer process
• at least 1 NodeManager process

Every Spark cluster must contain:

• exactly 1 Spark Master process
• exactly 1 Spark HistoryServer process
• at least 1 Spark Slave (worker) process

HBase service is considered valid if:

• cluster has at least 1 HBase-Master process
• cluster has at least 1 HBase-RegionServer process

Hive service is considered valid if:

• cluster has exactly 1 HiveMetastore process
• cluster has exactly 1 HiveServer2 process

Hue service is considered valid if:

• cluster has exactly 1 Hue process
• Hue process resides on the same node as HttpFS process

HttpFS service is considered valid if cluster has exactly 1 HttpFS process

Sqoop service is considered valid if cluster has exactly 1 Sqoop2-Server process

The MapR Plugin

For more information, please contact MapR.

Elastic Data Processing

Elastic Data Processing (EDP)

Overview

Sahara’s Elastic Data Processing facility or EDP allows the execution of jobs on clusters created from sahara. EDP supports:

• Hive, Pig, MapReduce, MapReduce.Streaming, Java, and Shell job types on Hadoop clusters
• Spark jobs on Spark standalone clusters, MapR spark clusters, and CDH clusters (v5.3.0 or higher)
• storage of job binaries in the OpenStack Object Storage service (swift), the OpenStack Shared file systems service (manila), or sahara’s own database
• access to input and output data sources in
  • HDFS for all job types
  • swift for all types excluding Hive
  • manila (NFS shares only) for all types excluding Pig
• configuration of jobs at submission time
• execution of jobs on existing clusters or transient clusters

Interfaces

The EDP features can be used from the sahara web UI which is described in the Sahara (Data Processing) UI User Guide.

The EDP features also can be used directly by a client through the REST api

EDP Concepts

Sahara EDP uses a collection of simple objects to define and execute jobs. These objects are stored in the sahara database when they are created, allowing them to be reused. This modular approach with database persistence allows code and data to be reused across multiple jobs.

The essential components of a job are:

• executable code to run
• input and output data paths, as needed for the job
• any additional configuration values needed for the job run

These components are supplied through the objects described below.

Job Binaries

A Job Binary object stores a URL to a single script or Jar file and any credentials needed to retrieve the file. The file itself may be stored in the sahara internal database, in swift, or in manila.

Files in the sahara database are stored as raw bytes in a Job Binary Internal object. This object’s sole purpose is to store a file for later retrieval. No extra credentials need to be supplied for files stored internally.

Sahara requires credentials (username and password) to access files stored in swift unless swift proxy users are configured as described in Sahara Advanced Configuration Guide. The swift service must be running in the same OpenStack installation referenced by sahara.

To reference a binary file stored in manila, create the job binary with the URL manila//{share_id}/{path}. This assumes that you have already stored that file in the appropriate path on the share. The share will be automatically mounted to any cluster nodes which require access to the file, if it is not mounted already.

There is a configurable limit on the size of a single job binary that may be retrieved by sahara. This limit is 5MB and may be set with the job_binary_max_KB setting in the sahara.conf configuration file.

Jobs

A Job object specifies the type of the job and lists all of the individual Job Binary objects that are required for execution. An individual Job Binary may be referenced by multiple Jos. A Job object specifies a main binary and/or supporting libraries depending on its type:

Job type	Main binary	Libraries
Hive	required	optional
Pig	required	optional
MapReduce	not used	required
MapReduce.Streaming	not used	optional
Java	not used	required
Shell	required	optional
Spark	required	optional

Data Sources

A Data Source object stores a URL which designates the location of input or output data and any credentials needed to access the location.

Sahara supports data sources in swift. The swift service must be running in the same OpenStack installation referenced by sahara.

Sahara also supports data sources in HDFS. Any HDFS instance running on a sahara cluster in the same OpenStack installation is accessible without manual configuration. Other instances of HDFS may be used as well provided that the URL is resolvable from the node executing the job.

Sahara supports data sources in manila as well. To reference a path on an NFS share as a data source, create the data source with the URL manila//{share_id}/{path}. As in the case of job binaries, the specified share will be automatically mounted to your cluster’s nodes as needed to access the data source.

Some job types require the use of data source objects to specify input and output when a job is launched. For example, when running a Pig job the UI will prompt the user for input and output data source objects.

Other job types like Java or Spark do not require the user to specify data sources. For these job types, data paths are passed as arguments. For convenience, sahara allows data source objects to be referenced by name or id. The section Using Data Source References as Arguments gives further details.

Job Execution

Job objects must be launched or executed in order for them to run on the cluster. During job launch, a user specifies execution details including data sources, configuration values, and program arguments. The relevant details will vary by job type. The launch will create a Job Execution object in sahara which is used to monitor and manage the job.

To execute Hadoop jobs, sahara generates an Oozie workflow and submits it to the Oozie server running on the cluster. Familiarity with Oozie is not necessary for using sahara but it may be beneficial to the user. A link to the Oozie web console can be found in the sahara web UI in the cluster details.

For Spark jobs, sahara uses the spark-submit shell script and executes the Spark job from the master node. Logs of spark jobs run by sahara can be found on the master node under the /tmp/spark-edp directory.

General Workflow

The general workflow for defining and executing a job in sahara is essentially the same whether using the web UI or the REST API.

1. Launch a cluster from sahara if there is not one already available
2. Create all of the Job Binaries needed to run the job, stored in the sahara database, in swift, or in manila
   • When using the REST API and internal storage of job binaries, the Job Binary Internal objects must be created first
   • Once the Job Binary Internal objects are created, Job Binary objects may be created which refer to them by URL
3. Create a Job object which references the Job Binaries created in step 2
4. Create an input Data Source which points to the data you wish to process
5. Create an output Data Source which points to the location for output data
6. Create a Job Execution object specifying the cluster and Job object plus relevant data sources, configuration values, and program arguments
   • When using the web UI this is done with the Launch On Existing Cluster or Launch on New Cluster buttons on the Jobs tab
   • When using the REST API this is done via the /jobs/<job_id>/execute method

The workflow is simpler when using existing objects. For example, to construct a new job which uses existing binaries and input data a user may only need to perform steps 3, 5, and 6 above. Of course, to repeat the same job multiple times a user would need only step 6.

Specifying Configuration Values, Parameters, and Arguments

Jobs can be configured at launch. The job type determines the kinds of values that may be set:

Job type	Configuration Values	Parameters	Arguments
Hive	Yes	Yes	No
Pig	Yes	Yes	Yes
MapReduce	Yes	No	No
MapReduce.Streaming	Yes	No	No
Java	Yes	No	Yes
Shell	Yes	Yes	Yes
Spark	Yes	No	Yes

• Configuration values are key/value pairs.
  • The EDP configuration values have names beginning with edp. and are consumed by sahara
  • Other configuration values may be read at runtime by Hadoop jobs
  • Currently additional configuration values are not available to Spark jobs at runtime
• Parameters are key/value pairs. They supply values for the Hive and Pig parameter substitution mechanisms. In Shell jobs, they are passed as environment variables.
• Arguments are strings passed as command line arguments to a shell or main program

These values can be set on the Configure tab during job launch through the web UI or through the job_configs parameter when using the /jobs/<job_id>/execute REST method.

In some cases sahara generates configuration values or parameters automatically. Values set explicitly by the user during launch will override those generated by sahara.

Using Data Source References as Arguments

Sometimes it’s necessary or desirable to pass a data path as an argument to a job. In these cases, a user may simply type out the path as an argument when launching a job. If the path requires credentials, the user can manually add the credentials as configuration values. However, if a data source object has been created that contains the desired path and credentials there is no need to specify this information manually.

As a convenience, sahara allows data source objects to be referenced by name or id in arguments, configuration values, or parameters. When the job is executed, sahara will replace the reference with the path stored in the data source object and will add any necessary credentials to the job configuration. Referencing an existing data source object is much faster than adding this information by hand. This is particularly useful for job types like Java or Spark that do not use data source objects directly.

There are two job configuration parameters that enable data source references. They may be used with any job type and are set on the Configuration tab when the job is launched:

• edp.substitute_data_source_for_name (default False) If set to True, causes sahara to look for data source object name references in configuration values, arguments, and parameters when a job is launched. Name references have the form datasource://name_of_the_object.

  For example, assume a user has a WordCount application that takes an input path as an argument. If there is a data source object named my_input, a user may simply set the edp.substitute_data_source_for_name configuration parameter to True and add datasource://my_input as an argument when launching the job.

• edp.substitute_data_source_for_uuid (default False) If set to True, causes sahara to look for data source object ids in configuration values, arguments, and parameters when a job is launched. A data source object id is a uuid, so they are unique. The id of a data source object is available through the UI or the sahara command line client. A user may simply use the id as a value.

Creating an Interface for Your Job

In order to better document your job for cluster operators (or for yourself in the future), sahara allows the addition of an interface (or method signature) to your job template. A sample interface for the Teragen Hadoop example might be:

Name	Mapping Type	Location	Value Type	Required	Default
Example Class	args	0	string	false	teragen
Rows	args	1	number	true	unset
Output Path	args	2	data_source	false	hdfs://ip:port/path
Mapper Count	configs	mapred.map.tasks	number	false	unset

A “Description” field may also be added to each interface argument.

To create such an interface via the REST API, provide an “interface” argument, the value of which consists of a list of JSON objects, as below:

[
    {
        "name": "Example Class",
        "description": "Indicates which example job class should be used."
        "mapping_type": "args",
        "location": "0",
        "value_type": "string",
        "required": false,
        "default": "teragen"
    },
    # Other arguments above here, as JSON objects
]

Creating this interface would allow you to specify a configuration for any execution of the job template by passing an “interface” map similar to:

{
    "Rows": "1000000",
    "Mapper Count": "3",
    "Output Path": "hdfs://mycluster:8020/user/myuser/teragen-output"
}

The specified arguments would be automatically placed into the args, configs, and params for the job, according to the mapping type and location fields of each interface argument. The final job_configs map would be:

{
    "job_configs": {
        "configs": {"mapred.map.tasks": "3"},
        "args" ["teragen", "1000000", "hdfs://mycluster:8020/user/myuser/teragen-output"]
    }
}

Rules for specifying an interface are as follows:

• Mapping Type must be one of configs, params, or args. Only types supported for your job type are allowed (see above.)
• Location must be a string for configs and params, and an integer for args. The set of args locations must be an unbroken series of integers starting from 0.
• Value Type must be one of string, number, or data_source. Data sources may be passed as UUIDs or as valid paths (see above.) All values should be sent as JSON strings. (Note that booleans and null values are serialized differently in different languages. Please specify them as a string representation of the appropriate constants for your data processing engine.)
• args that are not required must be given a default value.

The additional one-time complexity of specifying an interface on your template allows a simpler repeated execution path, and also allows us to generate a customized form for your job in the Horizon UI. This may be particularly useful in cases in which an operator who is not a data processing job developer will be running and administering the jobs.

Generation of Swift Properties for Data Sources

If swift proxy users are not configured (see Sahara Advanced Configuration Guide) and a job is run with data source objects containing swift paths, sahara will automatically generate swift username and password configuration values based on the credentials in the data sources. If the input and output data sources are both in swift, it is expected that they specify the same credentials.

The swift credentials may be set explicitly with the following configuration values:

Name
fs.swift.service.sahara.username
fs.swift.service.sahara.password

Setting the swift credentials explicitly is required when passing literal swift paths as arguments instead of using data source references. When possible, use data source references as described in Using Data Source References as Arguments.

Additional Details for Hive jobs

Sahara will automatically generate values for the INPUT and OUTPUT parameters required by Hive based on the specified data sources.

Additional Details for Pig jobs

Sahara will automatically generate values for the INPUT and OUTPUT parameters required by Pig based on the specified data sources.

For Pig jobs, arguments should be thought of as command line arguments separated by spaces and passed to the pig shell.

Parameters are a shorthand and are actually translated to the arguments -param name=value

Additional Details for MapReduce jobs

Important!

If the job type is MapReduce, the mapper and reducer classes must be specified as configuration values.

Note that the UI will not prompt the user for these required values; they must be added manually with the Configure tab.

Make sure to add these values with the correct names:

Name	Example Value
mapred.mapper.class	org.apache.oozie.example.SampleMapper
mapred.reducer.class	org.apache.oozie.example.SampleReducer

Additional Details for MapReduce.Streaming jobs

Important!

If the job type is MapReduce.Streaming, the streaming mapper and reducer classes must be specified.

In this case, the UI will prompt the user to enter mapper and reducer values on the form and will take care of adding them to the job configuration with the appropriate names. If using the python client, however, be certain to add these values to the job configuration manually with the correct names:

Name	Example Value
edp.streaming.mapper	/bin/cat
edp.streaming.reducer	/usr/bin/wc

Additional Details for Java jobs

Data Source objects are not used directly with Java job types. Instead, any input or output paths must be specified as arguments at job launch either explicitly or by reference as described in Using Data Source References as Arguments. Using data source references is the recommended way to pass paths to Java jobs.

If configuration values are specified, they must be added to the job’s Hadoop configuration at runtime. There are two methods of doing this. The simplest way is to use the edp.java.adapt_for_oozie option described below. The other method is to use the code from this example to explicitly load the values.

The following special configuration values are read by sahara and affect how Java jobs are run:

• edp.java.main_class (required) Specifies the full name of the class containing main(String[] args)

  A Java job will execute the main method of the specified main class. Any arguments set during job launch will be passed to the program through the args array.

• oozie.libpath (optional) Specifies configuration values for the Oozie share libs, these libs can be shared by different workflows

• edp.java.java_opts (optional) Specifies configuration values for the JVM

• edp.java.adapt_for_oozie (optional) Specifies that sahara should perform special handling of configuration values and exit conditions. The default is False.

  If this configuration value is set to True, sahara will modify the job’s Hadoop configuration before invoking the specified main method. Any configuration values specified during job launch (excluding those beginning with edp.) will be automatically set in the job’s Hadoop configuration and will be available through standard methods.

  Secondly, setting this option to True ensures that Oozie will handle program exit conditions correctly.

At this time, the following special configuration value only applies when running jobs on a cluster generated by the Cloudera plugin with the Enable Hbase Common Lib cluster config set to True (the default value):

• edp.hbase_common_lib (optional) Specifies that a common Hbase lib generated by sahara in HDFS be added to the oozie.libpath. This for use when an Hbase application is driven from a Java job. Default is False.

The edp-wordcount example bundled with sahara shows how to use configuration values, arguments, and swift data paths in a Java job type. Note that the example does not use the edp.java.adapt_for_oozie option but includes the code to load the configuration values explicitly.

Additional Details for Shell jobs

A shell job will execute the script specified as main, and will place any files specified as libs in the same working directory (on both the filesystem and in HDFS). Command line arguments may be passed to the script through the args array, and any params values will be passed as environment variables.

Data Source objects are not used directly with Shell job types but data source references may be used as described in Using Data Source References as Arguments.

The edp-shell example bundled with sahara contains a script which will output the executing user to a file specified by the first command line argument.

Additional Details for Spark jobs

Data Source objects are not used directly with Spark job types. Instead, any input or output paths must be specified as arguments at job launch either explicitly or by reference as described in Using Data Source References as Arguments. Using data source references is the recommended way to pass paths to Spark jobs.

Spark jobs use some special configuration values:

• edp.java.main_class (required) Specifies the full name of the class containing the Java or Scala main method:

  • main(String[] args) for Java
  • main(args: Array[String] for Scala

  A Spark job will execute the main method of the specified main class. Any arguments set during job launch will be passed to the program through the args array.

• edp.spark.adapt_for_swift (optional) If set to True, instructs sahara to modify the job’s Hadoop configuration so that swift paths may be accessed. Without this configuration value, swift paths will not be accessible to Spark jobs. The default is False.

The edp-spark example bundled with sahara contains a Spark program for estimating Pi.

Special Sahara URLs

Sahara uses custom URLs to refer to objects stored in swift, in manila, or in the sahara internal database. These URLs are not meant to be used outside of sahara.

Sahara swift URLs passed to running jobs as input or output sources include a ”.sahara” suffix on the container, for example:

swift://container.sahara/object

You may notice these swift URLs in job logs, however, you do not need to add the suffix to the containers yourself. sahara will add the suffix if necessary, so when using the UI or the python client you may write the above URL simply as:

swift://container/object

Sahara internal database URLs have the form:

internal-db://sahara-generated-uuid

This indicates a file object in the sahara database which has the given uuid as a key.

Manila NFS filesystem reference URLS take the form:

manila://share-uuid/path

This format should be used when referring to a job binary or a data source stored in a manila NFS share.

EDP Requirements

The OpenStack installation and the cluster launched from sahara must meet the following minimum requirements in order for EDP to function:

OpenStack Services

When a Hadoop job is executed, binaries are first uploaded to a cluster node and then moved from the node local filesystem to HDFS. Therefore, there must be an instance of HDFS available to the nodes in the sahara cluster.

If the swift service is not running in the OpenStack installation:

• Job binaries may only be stored in the sahara internal database
• Data sources require a long-running HDFS

If the swift service is running in the OpenStack installation:

• Job binaries may be stored in swift or the sahara internal database
• Data sources may be in swift or a long-running HDFS

Cluster Processes

Requirements for EDP support depend on the EDP job type and plugin used for the cluster. For example a Vanilla sahara cluster must run at least one instance of these processes to support EDP:

• For Hadoop version 1:
  • jobtracker
  • namenode
  • oozie
  • tasktracker
  • datanode
• For Hadoop version 2:
  • namenode
  • datanode
  • resourcemanager
  • nodemanager
  • historyserver
  • oozie

EDP Technical Considerations

There are several things in EDP which require attention in order to work properly. They are listed on this page.

Transient Clusters

EDP allows running jobs on transient clusters. In this case the cluster is created specifically for the job and is shut down automatically once the job is finished.

Two config parameters control the behaviour of periodic clusters:

• periodic_enable - if set to ‘False’, sahara will do nothing to a transient cluster once the job it was created for is completed. If it is set to ‘True’, then the behaviour depends on the value of the next parameter.
• use_identity_api_v3 - set it to ‘False’ if your OpenStack installation does not provide keystone API v3. In that case sahara will not terminate unneeded clusters. Instead it will set their state to ‘AwaitingTermination’ meaning that they could be manually deleted by a user. If the parameter is set to ‘True’, sahara will itself terminate the cluster. The limitation is caused by lack of ‘trusts’ feature in Keystone API older than v3.

If both parameters are set to ‘True’, sahara works with transient clusters in the following manner:

1. When a user requests for a job to be executed on a transient cluster, sahara creates such a cluster.
2. Sahara drops the user’s credentials once the cluster is created but prior to that it creates a trust allowing it to operate with the cluster instances in the future without user credentials.
3. Once a cluster is not needed, sahara terminates its instances using the stored trust. sahara drops the trust after that.

API

Sahara REST API v1.1

1 General API information

This section contains base info about the sahara REST API design.

1.1 Authentication and Authorization

The sahara API uses the OpenStack Identity service as the default authentication service. When the Identity service is enabled, users who submit requests to the sahara service must provide an authentication token in the X-Auth-Token request header. A user can obtain the token by authenticating to the Identity service endpoint. For more information about the Identity service, please see the keystone project developer documentation

With each request, a user must specify the OpenStack tenant(now known as project) in the url path, for example: ‘/v1.1/{tenant_id}/clusters’. Sahara will perform the requested operation in the specified tenant using the provided credentials. Therefore, clusters may be created and managed only within tenants to which the user has access.

1.2 Request / Response Types

The sahara API supports the JSON data serialization format. This means that for requests that contain a body, the Content-Type header must be set to the MIME type value application/json. Also, clients should accept JSON serialized responses by specifying the Accept header with the MIME type value application/json or adding the .json extension to the resource name. The default response format is application/json if the client does not specify an Accept header or append the .json extension in the URL path.

Example:

GET /v1.1/{tenant_id}/clusters.json

or

GET /v1.1/{tenant_id}/clusters
Accept: application/json

1.3 Faults

The sahara API returns an error response if a failure occurs while processing a request. Sahara uses only standard HTTP error codes. 4xx errors indicate problems in the particular request being sent from the client and 5xx errors indicate server-side problems.

The response body will contain richer information about the cause of the error. An error response follows the format illustrated by the following example:

HTTP/1.1 400 BAD REQUEST
Content-type: application/json
Content-length: 126

{
    "error_name": "CLUSTER_NAME_ALREADY_EXISTS",
    "error_message": "Cluster with name 'test-cluster' already exists",
    "error_code": 400
}

The error_code attribute is an HTTP response code. The error_name attribute indicates the generic error type without any concrete ids or names, etc. The last attribute, error_message, contains a human readable error description.

2 API

• Sahara REST API Reference (OpenStack API Complete Reference - DataProcessing)

Miscellaneous

Requirements for Guests

Sahara manages guests of various platforms (for example Ubuntu, Fedora, RHEL, and CentOS) with various versions of the Hadoop ecosystem projects installed. There are common requirements for all guests, and additional requirements based on the plugin that is used for cluster deployment.

Common Requirements

• The operating system must be Linux
• cloud-init must be installed
• ssh-server must be installed
  • if a firewall is active it must allow connections on port 22 to enable ssh

Vanilla Plugin Requirements

If the Vanilla Plugin is used for cluster deployment the guest is required to have

• ssh-client installed
• Java (version >= 6)
• Apache Hadoop installed
• ‘hadoop’ user created

See Swift Integration for information on using Swift with your sahara cluster (for EDP support Swift integration is currently required).

To support EDP, the following components must also be installed on the guest:

• Oozie version 4 or higher
• mysql
• hive

See Building Images for Vanilla Plugin for instructions on building images for this plugin.

Hortonworks Plugin Requirements

This plugin does not have any additional requirements. Currently, only the CentOS Linux distribution is supported but other distributions will be supported in the future. To speed up provisioning, the HDP packages can be pre-installed on the image used. The packages’ versions depend on the HDP version being used.

Cloudera Plugin Requirements

Cloudera Plugin does not have any additional requirements, just build a CDH image to deploy the cluster.

See Building Images for Cloudera Plugin for instructions on building images for this plugin.

Swift Integration

Hadoop and Swift integration are the essential continuation of the Hadoop/OpenStack marriage. The key component to making this marriage work is the Hadoop Swift filesystem implementation. Although this implementation has been merged into the upstream Hadoop project, Sahara maintains a version with the most current features enabled.

• The original Hadoop patch can be found at https://issues.apache.org/jira/browse/HADOOP-8545
• The most current Sahara maintained version of this patch can be found in the Sahara Extra repository https://github.com/openstack/sahara-extra
• The latest compiled version of the jar for this component can be downloaded from http://sahara-files.mirantis.com/hadoop-swift/hadoop-swift-latest.jar

Hadoop patching

You may build the jar file yourself by choosing the latest patch from the Sahara Extra repository and using Maven to build with the pom.xml file provided. Or you may get the latest jar pre-built from the CDN at http://sahara-files.mirantis.com/hadoop-swift/hadoop-swift-latest.jar

You will need to put this file into the hadoop libraries (e.g. /usr/lib/share/hadoop/lib) on each job-tracker and task-tracker node for Hadoop 1.x, or each ResourceManager and NodeManager node for Hadoop 2.x in the cluster.

Hadoop configurations

In general, when Sahara runs a job on a cluster it will handle configuring the Hadoop installation. In cases where a user might require more in-depth configuration all the data is set in the core-site.xml file on the cluster instances using this template:

<property>
    <name>${name} + ${config}</name>
    <value>${value}</value>
    <description>${not mandatory description}</description>
</property>

There are two types of configs here:

1. General. The ${name} in this case equals to fs.swift. Here is the list of ${config}:

   • .impl - Swift FileSystem implementation. The ${value} is org.apache.hadoop.fs.swift.snative.SwiftNativeFileSystem
   • .connect.timeout - timeout for all connections by default: 15000
   • .socket.timeout - how long the connection waits for responses from servers. by default: 60000
   • .connect.retry.count - connection retry count for all connections. by default: 3
   • .connect.throttle.delay - delay in millis between bulk (delete, rename, copy operations). by default: 0
   • .blocksize - blocksize for filesystem. By default: 32Mb
   • .partsize - the partition size for uploads. By default: 4608*1024Kb
   • .requestsize - request size for reads in KB. By default: 64Kb

2. Provider-specific. The patch for Hadoop supports different cloud providers. The ${name} in this case equals to fs.swift.service.${provider}.

   Here is the list of ${config}:

   • .auth.url - authorization URL
   • .tenant
   • .username
   • .password
   • .domain.name - Domains can be used to specify users who are not in the tenant specified.
   • .trust.id - Trusts are optionally used to scope the authentication tokens of the supplied user.
   • .http.port
   • .https.port
   • .region - Swift region is used when cloud has more than one Swift installation. If region param is not set first region from Keystone endpoint list will be chosen. If region param not found exception will be thrown.
   • .location-aware - turn On location awareness. Is false by default
   • .apikey
   • .public

Example

For this example it is assumed that you have setup a Hadoop instance with a valid configuration and the Swift filesystem component. Furthermore there is assumed to be a Swift container named integration holding an object named temp, as well as a Keystone user named admin with a password of swordfish.

The following example illustrates how to copy an object to a new location in the same container. We will use Hadoop’s distcp command (http://hadoop.apache.org/docs/r0.19.0/distcp.html) to accomplish the copy. Note that the service provider for our Swift access is sahara, and that we will not need to specify the project of our Swift container as it will be provided in the Hadoop configuration.

Swift paths are expressed in Hadoop according to the following template: swift://${container}.${provider}/${object}. For our example source this will appear as swift://integration.sahara/temp.

Let’s run the job:

$ hadoop distcp -D fs.swift.service.sahara.username=admin \
 -D fs.swift.service.sahara.password=swordfish \
 swift://integration.sahara/temp swift://integration.sahara/temp1

After that just confirm that temp1 has been created in our integration container.

Limitations

Note: Please note that container names should be a valid URI.

Building Images for Cloudera Plugin

In this document you will find instructions on how to build Ubuntu and CentOS images with Cloudera Express (now only 5.0.0 and 5.3.0 versions are supported).

Apache Hadoop. To simplify the task of building such images we use Disk Image Builder.

Disk Image Builder builds disk images using elements. An element is a particular set of code that alters how the image is built, or runs within the chroot to prepare the image.

Elements for building Cloudera images are stored in Sahara extra repository

Note

Sahara requires images with cloud-init package installed:

• For CentOS
• For Ubuntu

To create cloudera images follow these steps:

1. Clone repository “https://github.com/openstack/sahara-image-elements” locally.

2. Use tox to build images.

   You can run “tox -e venv – sahara-image-create” command in sahara-image-elements directory to build images. By default this script will attempt to create cloud images for all versions of supported plugins and all operating systems (subset of Ubuntu, Fedora, and CentOS depending on plugin). To only create Cloudera images, you should use the “-p cloudera” parameter in the command line. If you want to create the image only for a specific operating system, you should use the “-i ubuntu|centos” parameter to assign the operating system (the cloudera plugin only supports Ubuntu and Centos). If you want to create the image only for a specific Cloudera version, you should use the “-v 5.0|5.3” parameter to assign the version. Below is an example to create Cloudera images for both Ubuntu and CentOS with Cloudera Express 5.3.0 version.

   tox -e venv -- sahara-image-create -p cloudera -v 5.3
   

   If you want to create only an Ubuntu image, you may use following example for that.

   tox -e venv -- sahara-image-create -p cloudera -i ubuntu -v 5.3
   

   NOTE: If you don’t want to use default values, you should explicitly set the values of your required parameters.

   The script will create required cloud images using image elements that install all the necessary packages and configure them. You will find the created images in the parent directory.

Note

Disk Image Builder will generate QCOW2 images, used with the default OpenStack Qemu/KVM hypervisors. If your OpenStack uses a different hypervisor, the generated image should be converted to an appropriate format.

The VMware Nova backend requires the VMDK image format. You may use qemu-img utility to convert a QCOW2 image to VMDK.

qemu-img convert -O vmdk <original_image>.qcow2 <converted_image>.vmdk

For finer control of diskimage-create.sh see the official documentation

Developer Guide

Programming HowTos and Tutorials

Development Guidelines

Coding Guidelines

For all the Python code in Sahara we have a rule - it should pass PEP 8. All Bash code should pass bashate.

To check your code against PEP 8 and bashate run:

$ tox -e pep8

Note

For more details on coding guidelines see file HACKING.rst in the root of Sahara repo.

Static analysis

The static analysis checks are optional in Sahara. but they are still very useful. The gate job will inform you if the number of static analysis warnings has increased after your change. We recommend to always check the static warnings.

To run the check commit yor change first and execute the following command:

$ tox -e pylint

Modification of Upstream Files

We never modify upstream files in Sahara. Any changes in upstream files should be made in the upstream project and then merged back in to Sahara. This includes whitespace changes, comments, and typos. Any change requests containing upstream file modifications are almost certain to receive lots of negative reviews. Be warned.

Examples of upstream files are default xml configuration files used to configure Hadoop, or code imported from the OpenStack Oslo project. The xml files will usually be found in resource directories with an accompanying README file that identifies where the files came from. For example:

$ pwd
/home/me/sahara/sahara/plugins/vanilla/v2_6_0/resources

$ ls
core-default.xml     hdfs-default.xml    oozie-default.xml   README.rst
create_oozie_db.sql  mapred-default.xml  post_conf.template  yarn-default.xml

Testing Guidelines

Sahara has a suite of tests that are run on all submitted code, and it is recommended that developers execute the tests themselves to catch regressions early. Developers are also expected to keep the test suite up-to-date with any submitted code changes.

Unit tests are located at sahara/tests/unit.

Sahara’s suite of unit tests can be executed in an isolated environment with Tox. To execute the unit tests run the following from the root of Sahara repo:

$ tox -e py27

Documentation Guidelines

All Sahara docs are written using Sphinx / RST and located in the main repo in doc directory. You can add/edit pages here to update http://docs.openstack.org/developer/sahara site.

The documentation in docstrings should follow the PEP 257 conventions (as mentioned in the PEP 8 guidelines).

More specifically:

1. Triple quotes should be used for all docstrings.
2. If the docstring is simple and fits on one line, then just use one line.
3. For docstrings that take multiple lines, there should be a newline after the opening quotes, and before the closing quotes.
4. Sphinx is used to build documentation, so use the restructured text markup to designate parameters, return values, etc. Documentation on the sphinx specific markup can be found here:

Run the following command to build docs locally.

$ tox -e docs

After it you can access generated docs in doc/build/ directory, for example, main page - doc/build/html/index.html.

To make docs generation process faster you can use:

$ SPHINX_DEBUG=1 tox -e docs

or to avoid sahara reinstallation to virtual env each time you want to rebuild docs you can use the following command (it could be executed only after running tox -e docs first time):

$ SPHINX_DEBUG=1 .tox/docs/bin/python setup.py build_sphinx

Note

For more details on documentation guidelines see file HACKING.rst in the root of Sahara repo.

Event log Guidelines

Currently Sahara keep with cluster useful information about provisioning. Cluster provisioning can be represented as a linear series of provisioning steps, which are executed one after another. Also each step would consist of several events. The amount of events depends on the step and the amount of instances in the cluster. Also each event can contain information about cluster, instance, and node group. In case of errors, this event would contain information about reasons of errors. Each exception in sahara contains a unique identifier that will allow the user to find extra information about the reasons for errors in the sahara logs. Here http://developer.openstack.org/api-ref-data-processing-v1.1.html#v1.1eventlog you can see an example of provisioning progress information.

This means that if you add some important phase for cluster provisioning to sahara code, it’s recommended to add new provisioning step for this phase. It would allow users to use event log for handling errors during this phase.

Sahara already have special utils for operating provisioning steps and events in module sahara/utils/cluster_progress_ops.py.

Note

It’s strictly recommended not use conductor event log ops directly to assign events and operate provisioning steps.

Note

You should not add a new provisioning step until the previous step successfully completed.

Note

It’s strictly recommended to use event_wrapper for events handling

OpenStack client usage guidelines

The sahara project uses several OpenStack clients internally. These clients are all wrapped by utility functions which make using them more convenient. When developing sahara, if you need to use a OpenStack client you should check the sahara.utils.openstack package for the appropriate one.

When developing new OpenStack client interactions in sahara, it is important to understand the sahara.service.sessions package and the usage of keystone Session and auth plugin objects(for example, Token or Password). Sahara is migrating all clients to use this authentication methodology, where available. For more information on using sessions with keystone, please see http://docs.openstack.org/developer/python-keystoneclient/using-sessions.html

Setting Up a Development Environment

This page describes how to setup a Sahara development environment by either installing it as a part of DevStack or pointing a local running instance at an external OpenStack. You should be able to debug and test your changes without having to deploy Sahara.

Setup a Local Environment with Sahara inside DevStack

See the main article.

Setup a Local Environment with an external OpenStack

1. Install prerequisites

On OS X Systems:

# we actually need pip, which is part of python package
$ brew install python mysql postgresql rabbitmq
$ pip install virtualenv tox

On Ubuntu:

$ sudo apt-get update
$ sudo apt-get install git-core python-dev python-virtualenv gcc libpq-dev libmysqlclient-dev python-pip rabbitmq-server
$ sudo pip install tox

On Fedora-based distributions (e.g., Fedora/RHEL/CentOS/Scientific Linux):

$ sudo yum install git-core python-devel python-virtualenv gcc python-pip mariadb-devel postgresql-devel erlang
$ sudo pip install tox
$ sudo wget http://www.rabbitmq.com/releases/rabbitmq-server/v3.2.2/rabbitmq-server-3.2.2-1.noarch.rpm
$ sudo rpm --import http://www.rabbitmq.com/rabbitmq-signing-key-public.asc
$ sudo yum install rabbitmq-server-3.2.2-1.noarch.rpm

On openSUSE-based distributions (SLES 12, openSUSE, Factory or Tumbleweed):

.. sourcecode:: console

$ sudo zypper in gcc git libmysqlclient-devel postgresql-devel python-devel python-pip python-tox python-virtualenv

2. Grab the code:

$ git clone git://github.com/openstack/sahara.git
$ cd sahara

3.1 Generate Sahara sample using tox:

tox -e genconfig

3.2 Create config file from the sample:

$ cp ./etc/sahara/sahara.conf.sample ./etc/sahara/sahara.conf

4. Look through the sahara.conf and modify parameter values as needed. For details see Sahara Configuration Guide
5. Create database schema:

$ tox -e venv -- sahara-db-manage --config-file etc/sahara/sahara.conf upgrade head

6. To start Sahara API and Engine processes call:

$ tox -e venv -- sahara-api --config-file etc/sahara/sahara.conf --debug
$ tox -e venv -- sahara-engine --config-file etc/sahara/sahara.conf --debug

Setup local OpenStack dashboard with Sahara plugin

Sahara UI Dev Environment Setup

This page describes how to setup Horizon for developing Sahara by either installing it as part of DevStack with Sahara or installing it in an isolated environment and running from the command line.

Install as a part of DevStack

See the DevStack guide for more information on installing and configuring DevStack with Sahara.

After Horizon installation, it will contain a Data Processing tab under Projects tab. Sahara UI source code will be located at $DEST/horizon/openstack_dashboard/contrib/sahara/content/data_processing where $DEST/ is usually /opt/stack/.

Isolated Dashboard for Sahara

These installation steps serve two purposes:

1. Setup a dev environment
2. Setup an isolated Dashboard for Sahara

Note The host where you are going to perform installation has to be able to connect to all OpenStack endpoints. You can list all available endpoints using the following command:

$ keystone endpoint-list

You can list the registered services with this command:

$ keystone service-list

1. Install prerequisites

$ sudo apt-get update
$ sudo apt-get install git-core python-dev gcc python-setuptools python-virtualenv node-less libssl-dev libffi-dev libxslt-dev

On Ubuntu 12.10 and higher you have to install the following lib as well:

$ sudo apt-get install nodejs-legacy

2. Checkout Horizon from git and switch to your version of OpenStack

Here is an example:

$ git clone https://github.com/openstack/horizon

Then install the virtual environment:

$ python tools/install_venv.py

3. Create a local_settings.py file

$ cp openstack_dashboard/local/local_settings.py.example openstack_dashboard/local/local_settings.py

4. Modify openstack_dashboard/local/local_settings.py

Set the proper values for host and url variables:

OPENSTACK_HOST = "ip of your controller"

If you are using Nova-Network with auto_assign_floating_ip=True add the following parameter:

SAHARA_AUTO_IP_ALLOCATION_ENABLED = True

5. If Sahara is not registered with the keystone service catalog, it may be added with the following commands. To use Sahara from Horizon without keystone registration, see Using the Data Processing Dashboard without Keystone Registration.

   $ keystone service-create --name sahara --type data-processing
   $ keystone endpoint-create --region RegionOne --service sahara --publicurl 'http://localhost:8386/v1.1/%(tenant_id)s'
   

   Note you should replace the ip and port in with the appropriate values.

6. Start Horizon

$ tools/with_venv.sh python manage.py runserver 0.0.0.0:8080

This will start Horizon in debug mode. That means the logs will be written to console and if any exceptions happen, you will see the stack-trace rendered as a web-page.

Debug mode can be disabled by changing DEBUG=True to False in local_settings.py. In that case Horizon should be started slightly differently, otherwise it will not serve static files:

$ tools/with_venv.sh  python manage.py runserver --insecure 0.0.0.0:8080

Note It is not recommended to use Horizon in this mode for production.

7. Applying changes

If you have changed any *.py files in horizon/openstack_dashboard/contrib/sahara/content/data_processing directory, Horizon will notice that and reload automatically. However changes made to non-python files may not be noticed, so you have to restart Horizon again manually, as described in step 6.

Using the Data Processing Dashboard without Keystone Registration

Note These modifications are strictly for a development environment

If Sahara is not registered as a service with keystone, Horizon must be modified so that the Sahara URL can be known and so service-based permissions do not prevent the Data Processing dashboard from displaying.

1. Modify openstack_dashboard/contrib/sahara/api/sahara.py:

   Add the following lines before def client(request):

   Note you should replace the ip and port in SAHARA_URL with the appropriate values.

   SAHARA_URL = "http://localhost:8386/v1.1"
   
   def get_sahara_url(request):
   
       if SAHARA_URL:
           url = SAHARA_URL.rstrip('/')
           if url.split('/')[-1] in ['v1.0', 'v1.1']:
               url = SAHARA_URL + '/' + request.user.tenant_id
           return url
   
       return base.url_for(request, SAHARA_SERVICE)
   

   After that modify sahara_url provided in def client(request):

   sahara_url=get_sahara_url(request)
   

2. Modify openstack_dashboard/dashboards/project/dashboard.py:

   Overload the register method in class Project to programmatically remove data-processing permissions from all panels.

   @classmethod
   def register(cls, panel):
       if hasattr(panel, 'permissions'):
          panel.permissions = tuple(
              [perm for perm in panel.permissions if not perm.startswith(
                  'openstack.services.data-processing')])
       super(Project, cls).register(panel)
   

   Alternatively the data-processing permissions can be removed manually from each panel under openstack_dashboard/contrib/sahara/content/data_processing

Tips and tricks for dev environment

1. Pip speedup

Add the following lines to ~/.pip/pip.conf

[global]
download-cache = /home/<username>/.pip/cache
index-url = <mirror url>

Note that the ~/.pip/cache folder should be created manually.

2. Git hook for fast checks

Just add the following lines to .git/hooks/pre-commit and do chmod +x for it.

#!/bin/sh
# Run fast checks (PEP8 style check and PyFlakes fast static analysis)
tools/run_fast_checks

You can added the same check for pre-push, for example, run_tests and run_pylint.

3. Running static analysis (PyLint)

Just run the following command

tox -e pylint

Setup DevStack

The DevStack could be installed on Fedora, Ubuntu and CentOS. For supported versions see DevStack documentation

We recommend to install DevStack not into your main system, but run it in a VM instead. That way you may avoid contamination of your system with various stuff. You may find hypervisor and VM requirements in the the next section. If you still want to install DevStack on top of your main system, just skip the next section and read further.

Start VM and set up OS

In order to run DevStack in a local VM, you need to start by installing a guest with Ubuntu 14.04 server. Download an image file from Ubuntu’s web site and create a new guest from it. Virtualization solution must support nested virtualization. Without nested virtualization VMs running inside the DevStack will be extremely slow lacking hardware acceleration, i.e. you will run QEMU VMs without KVM.

On Linux QEMU/KVM supports nested virtualization, on Mac OS - VMware Fusion. VMware Fusion requires adjustments to run VM with fixed IP. You may find instructions which can help below.

Start a new VM with Ubuntu Server 14.04. Recommended settings:

• Processor - at least 2 cores
• Memory - at least 8GB
• Hard Drive - at least 60GB

When allocating CPUs and RAM to the DevStack, assess how big clusters you want to run. A single Hadoop VM needs at least 1 cpu and 1G of RAM to run. While it is possible for several VMs to share a single cpu core, remember that they can’t share the RAM.

After you installed the VM, connect to it via SSH and proceed with the instructions below.

Install DevStack

The instructions assume that you’ve decided to install DevStack into Ubuntu 14.04 system.

1. Clone DevStack:

$ sudo apt-get install git-core
$ git clone https://git.openstack.org/cgit/openstack-dev/devstack.git

2. Create file local.conf in devstack directory with the following content:

[[local|localrc]]
ADMIN_PASSWORD=nova
MYSQL_PASSWORD=nova
RABBIT_PASSWORD=nova
SERVICE_PASSWORD=$ADMIN_PASSWORD
SERVICE_TOKEN=nova

# Enable Swift
enable_service s-proxy s-object s-container s-account

SWIFT_HASH=66a3d6b56c1f479c8b4e70ab5c2000f5
SWIFT_REPLICAS=1
SWIFT_DATA_DIR=$DEST/data

# Force checkout prerequisites
# FORCE_PREREQ=1

# keystone is now configured by default to use PKI as the token format which produces huge tokens.
# set UUID as keystone token format which is much shorter and easier to work with.
KEYSTONE_TOKEN_FORMAT=UUID

# Change the FLOATING_RANGE to whatever IPs VM is working in.
# In NAT mode it is subnet VMware Fusion provides, in bridged mode it is your local network.
# But only use the top end of the network by using a /27 and starting at the 224 octet.
FLOATING_RANGE=192.168.55.224/27

# Enable logging
SCREEN_LOGDIR=$DEST/logs/screen

# Set ``OFFLINE`` to ``True`` to configure ``stack.sh`` to run cleanly without
# Internet access. ``stack.sh`` must have been previously run with Internet
# access to install prerequisites and fetch repositories.
# OFFLINE=True

# Enable sahara
enable_plugin sahara git://git.openstack.org/openstack/sahara

In cases where you need to specify a git refspec (branch, tag, or commit hash) for the sahara in-tree devstack plugin (or sahara repo), it should be appended after the git repo URL as follows:

enable_plugin sahara git://git.openstack.org/openstack/sahara <some_git_refspec>

3. Sahara can send notifications to Ceilometer, if Ceilometer is enabled. If you want to enable Ceilometer add the following lines to local.conf file:

enable_plugin ceilometer git://git.openstack.org/openstack/ceilometer

4. Start DevStack:

$ ./stack.sh

5. Once previous step is finished Devstack will print Horizon URL. Navigate to this URL and login with login “admin” and password from local.conf.
6. Congratulations! You have OpenStack running in your VM and ready to launch VMs inside that VM :)

Managing sahara in DevStack

If you install DevStack with sahara included you can rejoin screen with rejoin-stack.sh command and switch to sahara tab. Here you can manage the sahara service as other OpenStack services. Sahara source code is located at $DEST/sahara which is usually /opt/stack/sahara.

Setting fixed IP address for VMware Fusion VM

1. Open file /Library/Preferences/VMware Fusion/vmnet8/dhcpd.conf
2. There is a block named “subnet”. It might look like this:

subnet 192.168.55.0 netmask 255.255.255.0 {
        range 192.168.55.128 192.168.55.254;

3. You need to pick an IP address outside of that range. For example - 192.168.55.20
4. Copy VM MAC address from VM settings->Network->Advanced
5. Append the following block to file dhcpd.conf (don’t forget to replace VM_HOSTNAME and VM_MAC_ADDRESS with actual values):

host VM_HOSTNAME {
        hardware ethernet VM_MAC_ADDRESS;
        fixed-address 192.168.55.20;
}

6. Now quit all the VMware Fusion applications and restart vmnet:

$ sudo /Applications/VMware\ Fusion.app/Contents/Library/vmnet-cli --stop
$ sudo /Applications/VMware\ Fusion.app/Contents/Library/vmnet-cli --start

7. Now start your VM, it should have new fixed IP address

Sahara UI Dev Environment Setup

This page describes how to setup Horizon for developing Sahara by either installing it as part of DevStack with Sahara or installing it in an isolated environment and running from the command line.

Install as a part of DevStack

See the DevStack guide for more information on installing and configuring DevStack with Sahara.

After Horizon installation, it will contain a Data Processing tab under Projects tab. Sahara UI source code will be located at $DEST/horizon/openstack_dashboard/contrib/sahara/content/data_processing where $DEST/ is usually /opt/stack/.

Isolated Dashboard for Sahara

These installation steps serve two purposes:

1. Setup a dev environment
2. Setup an isolated Dashboard for Sahara

Note The host where you are going to perform installation has to be able to connect to all OpenStack endpoints. You can list all available endpoints using the following command:

$ keystone endpoint-list

You can list the registered services with this command:

$ keystone service-list

1. Install prerequisites

$ sudo apt-get update
$ sudo apt-get install git-core python-dev gcc python-setuptools python-virtualenv node-less libssl-dev libffi-dev libxslt-dev

On Ubuntu 12.10 and higher you have to install the following lib as well:

$ sudo apt-get install nodejs-legacy

2. Checkout Horizon from git and switch to your version of OpenStack

Here is an example:

$ git clone https://github.com/openstack/horizon

Then install the virtual environment:

$ python tools/install_venv.py

3. Create a local_settings.py file

$ cp openstack_dashboard/local/local_settings.py.example openstack_dashboard/local/local_settings.py

4. Modify openstack_dashboard/local/local_settings.py

Set the proper values for host and url variables:

OPENSTACK_HOST = "ip of your controller"

If you are using Nova-Network with auto_assign_floating_ip=True add the following parameter:

SAHARA_AUTO_IP_ALLOCATION_ENABLED = True

5. If Sahara is not registered with the keystone service catalog, it may be added with the following commands. To use Sahara from Horizon without keystone registration, see Using the Data Processing Dashboard without Keystone Registration.

   $ keystone service-create --name sahara --type data-processing
   $ keystone endpoint-create --region RegionOne --service sahara --publicurl 'http://localhost:8386/v1.1/%(tenant_id)s'
   

   Note you should replace the ip and port in with the appropriate values.

6. Start Horizon

$ tools/with_venv.sh python manage.py runserver 0.0.0.0:8080

This will start Horizon in debug mode. That means the logs will be written to console and if any exceptions happen, you will see the stack-trace rendered as a web-page.

Debug mode can be disabled by changing DEBUG=True to False in local_settings.py. In that case Horizon should be started slightly differently, otherwise it will not serve static files:

$ tools/with_venv.sh  python manage.py runserver --insecure 0.0.0.0:8080

Note It is not recommended to use Horizon in this mode for production.

7. Applying changes

If you have changed any *.py files in horizon/openstack_dashboard/contrib/sahara/content/data_processing directory, Horizon will notice that and reload automatically. However changes made to non-python files may not be noticed, so you have to restart Horizon again manually, as described in step 6.

Using the Data Processing Dashboard without Keystone Registration

Note These modifications are strictly for a development environment

If Sahara is not registered as a service with keystone, Horizon must be modified so that the Sahara URL can be known and so service-based permissions do not prevent the Data Processing dashboard from displaying.

1. Modify openstack_dashboard/contrib/sahara/api/sahara.py:

   Add the following lines before def client(request):

   Note you should replace the ip and port in SAHARA_URL with the appropriate values.

   SAHARA_URL = "http://localhost:8386/v1.1"
   
   def get_sahara_url(request):
   
       if SAHARA_URL:
           url = SAHARA_URL.rstrip('/')
           if url.split('/')[-1] in ['v1.0', 'v1.1']:
               url = SAHARA_URL + '/' + request.user.tenant_id
           return url
   
       return base.url_for(request, SAHARA_SERVICE)
   

   After that modify sahara_url provided in def client(request):

   sahara_url=get_sahara_url(request)
   

2. Modify openstack_dashboard/dashboards/project/dashboard.py:

   Overload the register method in class Project to programmatically remove data-processing permissions from all panels.

   @classmethod
   def register(cls, panel):
       if hasattr(panel, 'permissions'):
          panel.permissions = tuple(
              [perm for perm in panel.permissions if not perm.startswith(
                  'openstack.services.data-processing')])
       super(Project, cls).register(panel)
   

   Alternatively the data-processing permissions can be removed manually from each panel under openstack_dashboard/contrib/sahara/content/data_processing

Quickstart guide

This guide will help you setup a vanilla Hadoop cluster using a combination of OpenStack command line tools and the sahara REST API.

1. Install sahara

• If you want to hack the code follow Setting Up a Development Environment.

OR

• If you just want to install and use Sahara follow Sahara Installation Guide.

2. Identity service configuration

To use the OpenStack command line tools you should specify environment variables with the configuration details for your OpenStack installation. The following example assumes that the Identity service is at 127.0.0.1:5000, with a user admin in the admin tenant whose password is nova:

$ export OS_AUTH_URL=http://127.0.0.1:5000/v2.0/
$ export OS_TENANT_NAME=admin
$ export OS_USERNAME=admin
$ export OS_PASSWORD=nova

With these environment variables set you can get an authentication token using the keystone command line client as follows:

$ keystone token-get

If authentication succeeds, the output will be as follows:

+-----------+----------------------------------+
|  Property |              Value               |
+-----------+----------------------------------+
|  expires  |       2013-07-08T15:21:18Z       |
|     id    | dd92e3cdb4e1462690cd444d6b01b746 |
| tenant_id | 62bd2046841e4e94a87b4a22aa886c13 |
|  user_id  | 720fb87141a14fd0b204f977f5f02512 |
+-----------+----------------------------------+

The id and tenant_id values will be used for creating REST calls to sahara and should be saved. The id value is the token provided by the Identity service, and the tenant_id is the UUID for the tenant name specified earlier. These values should be exported to environment variables for ease of use later.

$ export AUTH_TOKEN="dd92e3cdb4e1462690cd444d6b01b746"
$ export TENANT_ID="62bd2046841e4e94a87b4a22aa886c13"

3. Upload an image to the Image service

You will need to upload a virtual machine image to the OpenStack Image service. You can download pre-built images with vanilla Apache Hadoop installed, or build the images yourself:

• Download and install a pre-built image with Ubuntu 13.10

$ ssh user@hostname
$ wget http://sahara-files.mirantis.com/sahara-icehouse-vanilla-1.2.1-ubuntu-13.10.qcow2
$ glance image-create --name=sahara-icehouse-vanilla-1.2.1-ubuntu-13.10 \
   --disk-format=qcow2 --container-format=bare < ./sahara-icehouse-vanilla-1.2.1-ubuntu-13.10.qcow2

OR

• with Fedora 20

$ ssh user@hostname
$ wget http://sahara-files.mirantis.com/sahara-icehouse-vanilla-1.2.1-fedora-20.qcow2
$ glance image-create --name=sahara-icehouse-vanilla-1.2.1-fedora-20 \
   --disk-format=qcow2 --container-format=bare < ./sahara-icehouse-vanilla-1.2.1-fedora-20.qcow2

OR

• build the image using ../userdoc/diskimagebuilder.

Save the image id, this will be used during the image registration with sahara. You can get the image id using the glance command line tool as follows:

$ glance image-list --name sahara-icehouse-vanilla-1.2.1-ubuntu-13.10
 +--------------------------------------+---------------------------------------------+
 | ID                                   | Name                                        |
 +--------------------------------------+---------------------------------------------+
 | 3f9fc974-b484-4756-82a4-bff9e116919b | sahara-icehouse-vanilla-1.2.1-ubuntu-13.10  |
 +--------------------------------------+---------------------------------------------+

$ export IMAGE_ID="3f9fc974-b484-4756-82a4-bff9e116919b"

4. Register the image with the sahara image registry

Now you will begin to interact with sahara by registering the virtual machine image in the sahara image registry.

Register the image with the username ubuntu. Note, the username will vary depending on the source image used, for more please see Vanilla Plugin

$ sahara image-register --id $IMAGE_ID --username ubuntu

Tag the image to inform sahara about the plugin with which it shall be used:

$ sahara image-add-tag --id $IMAGE_ID --tag vanilla
$ sahara image-add-tag --id $IMAGE_ID --tag 1.2.1

Ensure that the image is registered correctly by querying sahara. If registered successfully, the image will appear in the output as follows:

$ sahara image-list
 +--------------------------------------------+---------------------------------------+----------+----------------+-------------+
 | name                                       | id                                    | username | tags           | description |
 +--------------------------------------------+---------------------------------------+----------+----------------+-------------+
 | sahara-icehouse-vanilla-1.2.1-ubuntu-13.10 | 3f9fc974-b484-4756-82a4-bff9e116919b  | ubuntu   | vanilla, 1.2.1 | None        |
 +--------------------------------------------+---------------------------------------+----------+----------------+-------------+

5. Create node group templates

Node groups are the building blocks of clusters in sahara. Before you can begin provisioning clusters you must define a few node group templates to describe their configurations.

Note, these templates assume that floating IP addresses are not being used, for more information please see Floating IP management

Create a file named ng_master_template_create.json with the following content:

{
    "name": "test-master-tmpl",
    "flavor_id": "2",
    "plugin_name": "vanilla",
    "hadoop_version": "1.2.1",
    "node_processes": ["jobtracker", "namenode"],
    "auto_security_group": true
}

Create a file named ng_worker_template_create.json with the following content:

{
    "name": "test-worker-tmpl",
    "flavor_id": "2",
    "plugin_name": "vanilla",
    "hadoop_version": "1.2.1",
    "node_processes": ["tasktracker", "datanode"],
    "auto_security_group": true
}

Use the sahara client to upload the node group templates:

$ sahara node-group-template-create --json ng_master_template_create.json
$ sahara node-group-template-create --json ng_worker_template_create.json

List the available node group templates to ensure that they have been added properly:

$ sahara node-group-template-list
 +------------------+--------------------------------------+-------------+-----------------------+-------------+
 | name             | id                                   | plugin_name | node_processes        | description |
 +------------------+--------------------------------------+-------------+-----------------------+-------------+
 | test-master-tmpl | b38227dc-64fe-42bf-8792-d1456b453ef3 | vanilla     | jobtracker, namenode  | None        |
 | test-worker-tmpl | 634827b9-6a18-4837-ae15-5371d6ecf02c | vanilla     | datanode, nodemanager | None        |
 +------------------+--------------------------------------+-------------+-----------------------+-------------+

Save the id for the master and worker node group templates as they will be used during cluster template creation. For example:

• Master node group template id: b38227dc-64fe-42bf-8792-d1456b453ef3
• Worker node group template id: 634827b9-6a18-4837-ae15-5371d6ecf02c

6. Create a cluster template

The last step before provisioning the cluster is to create a template that describes the node groups of the cluster.

Create a file named cluster_template_create.json with the following content:

{
    "name": "demo-cluster-template",
    "plugin_name": "vanilla",
    "hadoop_version": "1.2.1",
    "node_groups": [
        {
            "name": "master",
            "node_group_template_id": "b38227dc-64fe-42bf-8792-d1456b453ef3",
            "count": 1
        },
        {
            "name": "workers",
            "node_group_template_id": "634827b9-6a18-4837-ae15-5371d6ecf02c",
            "count": 2
        }
    ]
}

Upload the Cluster template using the sahara command line tool:

$ sahara cluster-template-create --json cluster_template_create.json

Save the template id for use in the cluster provisioning command. The cluster id can be found in the output of the creation command or by listing the cluster templates as follows:

$ sahara cluster-template-list
+-----------------------+--------------------------------------+-------------+-----------------------+-------------+
| name                  | id                                   | plugin_name | node_groups           | description |
+-----------------------+--------------------------------------+-------------+-----------------------+-------------+
| demo-cluster-template | c0609da7-faac-4dcf-9cbc-858a3aa130cd | vanilla     | master: 1, workers: 2 | None        |
+-----------------------+--------------------------------------+-------------+-----------------------+-------------+

7. Create cluster

Now you will provision the cluster. This step requires a few pieces of information that will be found by querying various OpenStack services.

Create a file named cluster_create.json with the following content:

{
    "name": "cluster-1",
    "plugin_name": "vanilla",
    "hadoop_version": "1.2.1",
    "cluster_template_id" : "c0609da7-faac-4dcf-9cbc-858a3aa130cd",
    "user_keypair_id": "stack",
    "default_image_id": "3f9fc974-b484-4756-82a4-bff9e116919b"
    "neutron_management_network": "8cccf998-85e4-4c5f-8850-63d33c1c6916"
}

The parameter user_keypair_id with the value stack is generated by creating a keypair. You can create your own keypair in the OpenStack Dashboard, or through the nova command line client as follows:

$ nova keypair-add stack --pub-key $PATH_TO_PUBLIC_KEY

If sahara is configured to use neutron for networking, you will also need to include the neutron_management_network parameter in cluster_create.json. Cluster instances will get fixed IP addresses in this network. You can determine the neutron network id with the following command:

$ neutron net-list

Create and start the cluster:

$ sahara cluster-create --json cluster_create.json
 +----------------------------+-------------------------------------------------+
 | Property                   | Value                                           |
 +----------------------------+-------------------------------------------------+
 | status                     | Validating                                      |
 | neutron_management_network | 8cccf998-85e4-4c5f-8850-63d33c1c6916            |
 | is_transient               | False                                           |
 | description                | None                                            |
 | user_keypair_id            | stack                                           |
 | updated_at                 | 2013-07-07T19:01:51                             |
 | plugin_name                | vanilla                                         |
 | anti_affinity              | []                                              |
 | node_groups                | [{u'count': 1, u'name': u'master',              |
 |                            | u'instances': [], u'volume_mount_prefix':       |
 |                            | u'/volumes/disk', u'created_at': u'2015-03-17   |
 |                            | 18:33:42', u'updated_at': None,                 |
 |                            | u'floating_ip_pool': u'70b8c139-096b-4b3b-b29f- |
 |                            | f42b16316758', u'image_id': None,               |
 |                            | u'volumes_size': 0, u'node_configs': {},        |
 |                            | u'node_group_template_id': u'09946a01-7973-4f63 |
 |                            | -9aca-7fc6d498d8a6', u'volumes_per_node': 0,    |
 |                            | u'node_processes': [u'jobtracker',              |
 |                            | u'namenode'], u'auto_security_group': True,     |
 |                            | u'security_groups': None, u'flavor_id': u'2'},  |
 |                            | {u'count': 2, u'name': u'workers',              |
 |                            | u'instances': [], u'volume_mount_prefix':       |
 |                            | u'/volumes/disk', u'created_at': u'2015-03-17   |
 |                            | 18:33:42', u'updated_at': None,                 |
 |                            | u'floating_ip_pool': u'70b8c139-096b-4b3b-b29f- |
 |                            | f42b16316758', u'image_id': None,               |
 |                            | u'volumes_size': 0, u'node_configs': {},        |
 |                            | u'node_group_template_id': u'ceb017bd-0568-42e9 |
 |                            | -890b-03eb298dc99f', u'volumes_per_node': 0,    |
 |                            | u'node_processes': [u'tasktracker',             |
 |                            | u'datanode'], u'auto_security_group': True,     |
 |                            | u'security_groups': None, u'flavor_id': u'2'}]  |
 | management_public_key      | ssh-rsa BBBBB3NzaB1yc2EAAAADAQABAAABAQCziEF+3oJ |
 |                            | ki6Fd1rvuiducJ470DN9ZFagiFbLfcwqu7TNKee10uice5P |
 |                            | KmvpusXMaL5LiZFTHafbFJfNUlah90yGpfsYqbcx2dMNqoU |
 |                            | EF4ZvEVO7RVU8jCe7DXBEkBFGQ1x/v17vyaxIJ8AqnFVSuu |
 |                            | FgfcHuihLAC250ZlfNWMcoFhUy6MsBocoxCF6MVal5Xt8nw |
 |                            | Y8o8xTQwd/f4wbAeAE3P0TaOCpXpMxxLL/hMDALekdxs1Gh |
 |                            | Mk0k5rbj4oD9AKx8+/jucIxS6mmwqWwwqo7jmy2jIsukOGZ |
 |                            | 1LdeNe0ctOX56k1LoZybzMzT6NbgUwfuIRbOwuryy2QbWwV |
 |                            | gX6t Generated by Sahara                        |
 | status_description         |                                                 |
 | hadoop_version             | 1.2.1                                           |
 | id                         | c5e755a2-b3f9-417b-948b-e99ed7fbf1e3            |
 | trust_id                   | None                                            |
 | info                       | {}                                              |
 | cluster_template_id        | c0609da7-faac-4dcf-9cbc-858a3aa130cd            |
 | name                       | cluster-1                                       |
 | cluster_configs            | {}                                              |
 | created_at                 | 2013-07-07T19:01:51                             |
 | default_image_id           | 3f9fc974-b484-4756-82a4-bff9e116919b            |
 | tenant_id                  | 3fd7266fb3b547b1a45307b481bcadfd                |
 +----------------------------+-------------------------------------------------+

Verify the cluster launched successfully by using the sahara command line tool as follows:

$ sahara cluster-list
 +-----------+--------------------------------------+--------+------------+
 | name      | id                                   | status | node_count |
 +-----------+--------------------------------------+--------+------------+
 | cluster-1 | c5e755a2-b3f9-417b-948b-e99ed7fbf1e3 | Active | 3          |
 +-----------+--------------------------------------+--------+------------+

The cluster creation operation may take several minutes to complete. During this time the “status” returned from the previous command may show states other than “Active”.

8. Run a MapReduce job

Check that your Hadoop installation is working properly by running an example job on the cluster manually.

• Login to the NameNode via ssh:

$ ssh ubuntu@<namenode_ip>

• Switch to the hadoop user:

$ sudo su hadoop

• Go to the shared hadoop directory and run the simplest MapReduce example:

$ cd /usr/share/hadoop
$ hadoop jar hadoop-examples-1.2.1.jar pi 10 100

Congratulations! Now you have the Hadoop cluster ready on the OpenStack cloud.

How to Participate

Getting started

• Create account on Github (if you don’t have one)
  • Make sure that your local git is properly configured by executing git config --list. If not, configure user.name, user.email
• Create account on Launchpad (if you don’t have one)
• Subscribe to OpenStack general mail-list
• Subscribe to OpenStack development mail-list
• Create OpenStack profile
• Login to OpenStack Gerrit with your Launchpad id
  • Sign OpenStack Individual Contributor License Agreement
  • Make sure that your email is listed in identities
• Subscribe to code-reviews. Go to your settings on http://review.openstack.org
  • Go to watched projects
  • Add openstack/sahara, openstack/sahara-extra, openstack/python-saharaclient, openstack/sahara-image-elements

How to stay in touch with the community?

• If you have something to discuss use OpenStack development mail-list. Prefix mail subject with [Sahara]
• Join #openstack-sahara IRC channel on freenode
• Weekly on Thursdays at 1400 UTC and 1800 UTC (on alternate weeks)
• IRC channel: #openstack-meeting-alt (1800UTC) and #openstack-meeting-3 (1400UTC)

How to send your first patch on review?

• Checkout Sahara code from Github
• Carefully read http://docs.openstack.org/infra/manual/developers.html#development-workflow
  • Pay special attention to http://docs.openstack.org/infra/manual/developers.html#committing-a-change
• Apply and commit your changes
• Make sure that your code passes PEP8 checks and unit-tests. See Development Guidelines
• Send your patch on review
• Monitor status of your patch review on https://review.openstack.org/#/

How to build Oozie

Note

Apache does not make Oozie builds, so it has to be built manually.

Download

• Download tarball from Apache mirror

• Unpack it with

  $ tar -xzvf oozie-4.0.1.tar.gz
  

Hadoop Versions

To build Oozie the following command can be used:

$ {oozie_dir}/bin/mkdistro.sh -DskipTests

By default it builds against Hadoop 1.1.1. To built it with 2.x Hadoop version:

• hadoop-2 version in pom.xml files should be changed. It could be done manually or with following command(You should replace 2.x.x to your hadoop version):

  $ find . -name pom.xml | xargs sed -ri 's/2.3.0/2.x.x/'
  

• build command should be launched with -P hadoop-2 flag

JDK Versions

By default, the build configuration enforces that JDK 1.6.* is being used.

There are 2 build properties that can be used to change the JDK version requirements:

• javaVersion specifies the version of the JDK used to compile (default 1.6)
• targetJavaVersion specifies the version of the generated bytecode (default 1.6)

For example, to specify 1.7 JDK version, build command should contain -D javaVersion=1.7 -D tagetJavaVersion=1.7 flags.

Build

To build Ozzie with 2.6.0 hadoop and 1.7 JDK versions following command can be used:

$ {oozie_dir}/bin/mkdistro.sh assembly:single -P hadoop-2 -D javaVersion=1.7 -D targetJavaVersion=1.7 -D skipTests

Also, pig version can be passed as maven property with -D pig.version=x.x.x flag.

Similar instruction to build oozie.tar.gz you may find there: http://oozie.apache.org/docs/4.0.0/DG_QuickStart.html#Building_Oozie

Adding Database Migrations

The migrations in sahara/db/migration/alembic_migrations/versions contain the changes needed to migrate between Sahara database revisions. A migration occurs by executing a script that details the changes needed to upgrade or downgrade the database. The migration scripts are ordered so that multiple scripts can run sequentially. The scripts are executed by Sahara’s migration wrapper which uses the Alembic library to manage the migration. Sahara supports migration from Icehouse or later.

Any code modifications that change the structure of the database require a migration script so that previously existing databases will continue to function when the new code is released. This page gives a brief overview of how to add the migration.

Generate a New Migration Script

New migration scripts can be generated using the sahara-db-manage command.

To generate a migration stub to be filled in by the developer:

$ sahara-db-manage --config-file /path/to/sahara.conf revision -m "description of revision"

To autogenerate a migration script that reflects the current structure of the database:

$ sahara-db-manage --config-file /path/to/sahara.conf revision -m "description of revision" --autogenerate

Each of these commands will create a file of the form revision_description where revision is a string generated by Alembic and description is based on the text passed with the -m option.

Follow the Sahara Naming Convention

By convention Sahara uses 3-digit revision numbers, and this scheme differs from the strings generated by Alembic. Consequently, it’s necessary to rename the generated script and modify the revision identifiers in the script.

Open the new script and look for the variable down_revision. The value should be a 3-digit numeric string, and it identifies the current revision number of the database. Set the revision value to the down_revision value + 1. For example, the lines:

# revision identifiers, used by Alembic.
revision = '507eb70202af'
down_revision = '006'

will become:

# revision identifiers, used by Alembic.
revision = '007'
down_revision = '006'

Modify any comments in the file to match the changes and rename the file to match the new revision number:

$ mv 507eb70202af_my_new_revision.py 007_my_new_revision.py

Add Alembic Operations to the Script

The migration script contains method upgrade(). Since Kilo release Sahara doesn’t support downgrades. Fill in this method with the appropriate Alembic operations to perform upgrades. In the above example, an upgrade will move from revision ‘006’ to revision ‘007’.

Command Summary for sahara-db-manage

You can upgrade to the latest database version via:

$ sahara-db-manage --config-file /path/to/sahara.conf upgrade head

To check the current database version:

$ sahara-db-manage --config-file /path/to/sahara.conf current

To create a script to run the migration offline:

$ sahara-db-manage --config-file /path/to/sahara.conf upgrade head --sql

To run the offline migration between specific migration versions:

$ sahara-db-manage --config-file /path/to/sahara.conf upgrade <start version>:<end version> --sql

Upgrade the database incrementally:

$ sahara-db-manage --config-file /path/to/sahara.conf upgrade --delta <# of revs>

Create new revision:

$ sahara-db-manage --config-file /path/to/sahara.conf revision -m "description of revision" --autogenerate

Create a blank file:

$ sahara-db-manage --config-file /path/to/sahara.conf revision -m "description of revision"

This command does not perform any migrations, it only sets the revision. Revision may be any existing revision. Use this command carefully:

$ sahara-db-manage --config-file /path/to/sahara.conf stamp <revision>

To verify that the timeline does branch, you can run this command:

$ sahara-db-manage --config-file /path/to/sahara.conf check_migration

If the migration path does branch, you can find the branch point via:

$ sahara-db-manage --config-file /path/to/sahara.conf history

Sahara Testing

We have a bunch of different tests for Sahara.

Unit Tests

In most Sahara sub repositories we have _package_/tests/unit or _package_/tests that contains Python unit tests.

Integration tests

We have integration tests for the main Sahara service and they are located in sahara/tests/integration. The main purpose of these integration tests is to run some kind of scenarios to test Sahara using all plugins. You can find more info about it in sahara/tests/integration/README.rst.

Scenario integration tests

New scenario integration tests were implemented in Sahara, you can see how use and run it here: sahara/tests/scenario/README.rst

Tempest tests

We have some tests in Tempest (https://github.com/openstack/tempest) that are testing Sahara. Here is a list of currently implemented tests:

• REST API tests are checking how the Sahara REST API works. The only part that is not tested is cluster creation, more info about api tests - http://docs.openstack.org/developer/tempest/field_guide/api.html
• CLI tests are checking read-only operations using the Sahara CLI, more info - http://docs.openstack.org/developer/tempest/field_guide/cli.html

Log Guidelines

Levels Guidelines

During the Kilo release cycle the sahara community defined the following log levels:

• Debug: Shows everything and is likely not suitable for normal production operation due to the sheer size of logs generated (e.g. scripts executions, process execution, etc.).
• Info: Usually indicates successful service start/stop, versions and such non-error related data. This should include largely positive units of work that are accomplished (e.g. service setup and configuration, cluster start, job execution information).
• Warning: Indicates that there might be a systemic issue; potential predictive failure notice (e.g. job execution failed).
• Error: An error has occurred and the administrator should research the error information (e.g. cluster failed to start, plugin violations of operation).
• Critical: An error has occurred and the system might be unstable, anything that eliminates part of sahara’s intended functionalities; immediately get administrator assistance (e.g. failed to access keystone/database, failed to load plugin).

Formatting Guidelines

Now sahara uses string formatting defined in PEP 3101 for logs.

LOG.warning(_LW("Incorrect path: {path}").format(path=path))

Translation Guidelines

All log levels except Debug requires translation. None of the separate cli tools packaged with sahara contain log translations.

• Debug: no translation
• Info: _LI
• Warning: _LW
• Error: _LE
• Critical: _LC

Background Concepts for Sahara

Pluggable Provisioning Mechanism

Sahara could be integrated with 3rd party management tools like Apache Ambari and Cloudera Management Console. The integration is achieved using plugin mechanism.

In short, responsibilities are divided between Sahara core and plugin as follows. Sahara interacts with user and provisions infrastructure (VMs). Plugin installs and configures Hadoop cluster on the VMs. Optionally Plugin could deploy management and monitoring tools for the cluster. Sahara provides plugin with utility methods to work with VMs.

A plugin must extend sahara.plugins.provisioning:ProvisioningPluginBase class and implement all the required methods. Read Plugin SPI for details.

The instance objects provided by Sahara have remote property which could be used to work with VM. The remote is a context manager so you can use it in with instance.remote: statements. The list of available commands could be found in sahara.utils.remote.InstanceInteropHelper. See Vanilla plugin source for usage examples.

Plugin SPI

Plugin interface

get_versions()

Returns all versions of Hadoop that could be used with the plugin. It is responsibility of the plugin to make sure that all required images for each hadoop version are available, as well as configs and whatever else that plugin needs to create the Hadoop cluster.

Returns: list of strings - Hadoop versions

Example return value: [“1.2.1”, “2.3.0”, “2.4.1”]

get_configs( hadoop_version)

Lists all configs supported by plugin with descriptions, defaults and targets for which this config is applicable.

Returns: list of configs

Example return value: ((“JobTracker heap size”, “JobTracker heap size, in MB”, “int”, “512”, “mapreduce”, “node”, True, 1))

get_node_processes( hadoop_version)

Returns all supported services and node processes for a given Hadoop version. Each node process belongs to a single service and that relationship is reflected in the returned dict object. See example for details.

Returns: dictionary having entries (service -> list of processes)

Example return value: {“mapreduce”: [“tasktracker”, “jobtracker”], “hdfs”: [“datanode”, “namenode”]}

get_required_image_tags( hadoop_version)

Lists tags, that should be added to OpenStack Image via Image Registry. Tags are used to filter Images by plugin and hadoop version.

Returns: list of tags

Example return value: [“tag1”, “some_other_tag”, ...]

validate(cluster)

Validates a given cluster object. Raises SaharaException with meaningful message.

Returns: None

Example exception: <NotSingleNameNodeException {code=’NOT_SINGLE_NAME_NODE’, message=’Hadoop cluster should contain only 1 NameNode instance. Actual NN count is 2’ }>

validate_scaling(cluster, existing, additional)

To be improved.

Validates a given cluster before scaling operation.

Returns: list of validation_errors

update_infra(cluster)

Plugin has a chance to change cluster description here. Specifically, plugin must specify image for VMs could change VMs specs in any way it needs. For instance, plugin can ask for additional VMs for the management tool.

Returns: None

configure_cluster(cluster)

Configures cluster on provisioned by sahara VMs. In this function plugin should perform all actions like adjusting OS, installing required packages (including Hadoop, if needed), configuring Hadoop, etc.

Returns: None

start_cluster(cluster)

Start already configured cluster. This method is guaranteed to be called only on cluster which was already prepared with configure_cluster(...) call.

Returns: None

scale_cluster(cluster, instances)

Scale an existing cluster with additional instances. Instances argument is a list of ready-to-configure instances. Plugin should do all configuration operations in this method and start all services on those instances.

Returns: None

get_edp_engine(cluster, job_type)

Returns an EDP job engine object that supports the specified job_type on the given cluster, or None if there is no support. The EDP job engine object returned must implement the interface described in Elastic Data Processing (EDP) SPI. The job_type is a String matching one of the job types listed in Job Types.

Returns: an EDP job engine object or None

decommission_nodes(cluster, instances)

Scale cluster down by removing a list of instances. Plugin should stop services on a provided list of instances. Plugin also may want to update some configurations on other instances, so this method is the right place to do that.

Returns: None

convert(config, plugin_name, version, template_name, cluster_template_create)

Provides plugin with ability to create cluster based on plugin-specific config. Sahara expects plugin to fill in all the required fields. The last argument is the function that plugin should call to save the Cluster Template. See “Cluster Lifecycle for Config File Mode” section below for clarification.

on_terminate_cluster(cluster)

When user terminates cluster, sahara simply shuts down all the cluster VMs. This method is guaranteed to be invoked before that, allowing plugin to do some clean-up.

Returns: None

get_open_ports(node_group)

When user requests sahara to automatically create security group for the node group (auto_security_group property set to True), sahara will call this plugin method to get list of ports that need to be opened.

Returns: list of ports to be open in auto security group for the given node group

def get_edp_job_types(versions)

Optional method, which provides ability to see all supported job types for specified plugin versions

Returns: dict with supported job types for specified versions of plugin

def recommend_configs(self, cluster, scaling=False)

Optional method, which provides recommendations for cluster configuration before creating/scaling operation.

Returns: None

Object Model

Here is a description of all the objects involved in the API.

Notes:

• cluster and node_group have ‘extra’ field allowing plugin to persist any complementary info about the cluster.
• node_process is just a process that runs at some node in cluster.

Example list of node processes:

1. jobtracker
2. namenode
3. tasktracker
4. datanode

• Each plugin may have different names for the same processes.

Config

An object, describing one configuration entry

Property	Type	Description
name	string	Config name.
description	string	A hint for user, what this config is used for.
config_type	enum	possible values are: ‘string’, ‘integer’, ‘boolean’, ‘enum’.
config_values	list	List of possible values, if config_type is enum.
default_value	string	Default value for config.
applicable_target	string	The target could be either a service returned by get_node_processes(...) call in form of ‘service:<service name>’, or ‘general’.
scope	enum	Could be either ‘node’ or ‘cluster’.
is_optional	bool	If is_optional is False and no default_value is specified, user should provide a value.
priority	int	1 or 2. A Hint for UI. Configs with priority 1 are always displayed. Priority 2 means user should click a button to see the config.

User Input

Value provided by user for a specific config.

Property	Type	Description
config	config	A config object for which this user_input is provided.
value	...	Value for the config. Type depends on Config type.

Instance

An instance created for cluster.

Property	Type	Description
instance_id	string	Unique instance identifier.
instance_name	string	OpenStack Instance name.
internal_ip	string	IP to communicate with other instances.
management_ip	string	IP of instance, accessible outside of internal network.
volumes	list	List of volumes attached to instance. Empty if ephemeral drive is used.
nova_info	object	Nova Instance object.
username	string	Username, that sahara uses for establishing remote connections to instance.
hostname	string	Same as instance_name.
fqdn	string	Fully qualified domain name for this instance.
remote	helpers	Object with helpers for performing remote operations

Node Group

Group of instances.

Property	Type	Description
name	string	Name of this Node Group in Cluster.
flavor_id	string	OpenStack Flavor used to boot instances.
image_id	string	Image id used to boot instances.
node_processes	list	List of processes running on each instance.
node_configs	dict	Configs dictionary, applied to instances.
volumes_per_node	int	Number of volumes mounted to each instance. 0 means use ephemeral drive.
volumes_size	int	Size of each volume (GB).
volumes_mount_prefix	string	Prefix added to mount path of each volume.
floating_ip_pool	string	Floating IP Pool name. All instances in the Node Group will have Floating IPs assigned from this pool.
count	int	Number of instances in this Node Group.
username	string	Username used by sahara to establish remote connections to instances.
configuration	dict	Merged dictionary of node configurations and cluster configurations.
storage_paths	list	List of directories where storage should be placed.

Cluster

Contains all relevant info about cluster. This object is is provided to the plugin for both cluster creation and scaling. The “Cluster Lifecycle” section below further specifies which fields are filled at which moment.

Property	Type	Description
name	string	Cluster name.
tenant_id	string	OpenStack Tenant id where this Cluster is available.
plugin_name	string	Plugin name.
hadoop_version	string	Hadoop version running on instances.
default_image_id	string	OpenStack image used to boot instances.
node_groups	list	List of Node Groups.
cluster_configs	dict	Dictionary of Cluster scoped configurations.
cluster_template_id	string	Cluster Template used for Node Groups and Configurations.
user_keypair_id	string	OpenStack keypair added to instances to make them accessible for user.
neutron_management_network	string	Neutron network ID. Instances will get fixed IPs in this network if ‘use_neutron’ config is set to True.
anti_affinity	list	List of processes that will be run on different hosts.
description	string	Cluster Description.
info	dict	Dictionary for additional information.

Validation Error

Describes what is wrong with one of the values provided by user.

Property	Type	Description
config	config	A config object that is not valid.
error_message	string	Message that describes what exactly is wrong.

Elastic Data Processing (EDP) SPI

EDP job engine objects provide methods for creating, monitoring, and terminating jobs on Sahara clusters. Provisioning plugins that support EDP must return an EDP job engine object from the get_edp_engine(cluster, job_type) method described in Plugin SPI.

Sahara provides subclasses of the base job engine interface that support EDP on clusters running Oozie or on Spark standalone clusters. These are described below.

Job Types

Some of the methods below test job type. Sahara supports the following string values for job types:

• Hive
• Java
• Pig
• MapReduce
• MapReduce.Streaming
• Spark
• Shell

Note, constants for job types are defined in sahara.utils.edp

Job Status Values

Several of the methods below return a job status value. A job status value is a dictionary of the form:

{‘status’: job_status_value}

where job_status_value is one of the following string values:

• DONEWITHERROR
• FAILED
• TOBEKILLED
• KILLED
• PENDING
• RUNNING
• SUCCEEDED

Note, constants for job status are defined in sahara.utils.edp

EDP Job Engine Interface

The sahara.service.edp.base_engine.JobEngine class is an abstract class with the following interface:

cancel_job(job_execution)

Stops the running job whose id is stored in the job_execution object.

Returns: None if the operation was unsuccessful or an updated job status value

get_job_status(job_execution)

Returns the current status of the job whose id is stored in the job_execution object.

Returns: a job status value

run_job(job_execution)

Starts the job described by the job_execution object

Returns: a tuple of the form (job_id, job_status_value, job_extra_info)

• job_id is required and must be a string that allows the EDP engine to uniquely identify the job.
• job_status_value may be None or a job status value
• job_extra_info may be None or optionally a dictionary that the EDP engine uses to store extra information on the job_execution_object.

validate_job_execution(cluster, job, data)

Checks whether or not the job can run on the cluster with the specified data. Data contains values passed to the /jobs/<job_id>/execute REST API method during job launch. If the job cannot run for any reason, including job configuration, cluster configuration, or invalid data, this method should raise an exception.

Returns: None

get_possible_job_config(job_type)

Returns hints used by the Sahara UI to prompt users for values when configuring and launching a job. Note that no hints are required.

See Elastic Data Processing (EDP) for more information on how configuration values, parameters, and arguments are used by different job types.

Returns: a dictionary of the following form, containing hints for configs, parameters, and arguments for the job type:

{‘job_config’: {‘configs’: [], ‘params’: {}, ‘args’: []}}

• args is a list of strings
• params contains simple key/value pairs
• each item in configs is a dictionary with entries for ‘name’ (required), ‘value’, and ‘description’

get_supported_job_types()

This method returns the job types that the engine supports. Not all engines will support all job types.

Returns: a list of job types supported by the engine

Oozie Job Engine Interface

The sahara.service.edp.oozie.engine.OozieJobEngine class is derived from JobEngine. It provides implementations for all of the methods in the base interface but adds a few more abstract methods.

Note, the validate_job_execution(cluster, job, data) method does basic checks on the job configuration but probably should be overloaded to include additional checks on the cluster configuration. For example, the job engines for plugins that support Oozie add checks to make sure that the Oozie service is up and running.

get_hdfs_user()

Oozie uses HDFS to distribute job files. This method gives the name of the account that is used on the data nodes to access HDFS (such as ‘hadoop’ or ‘hdfs’). The Oozie job engine expects that HDFS contains a directory for this user under /user/

Returns: a string giving the username for the account used to access HDFS on the cluster.

create_hdfs_dir(remote, dir_name)

The remote object remote references a node in the cluster. This method creates the HDFS directory dir_name under the user specified by get_hdfs_user() in the HDFS accessible from the specified node. For example, if the HDFS user is ‘hadoop’ and the dir_name is ‘test’ this method would create ‘/user/hadoop/test’.

The reason that this method is broken out in the interface as an abstract method is that different versions of Hadoop treat path creation differently.

Returns: None

get_oozie_server_uri(cluster)

Returns the full URI for the Oozie server, for example http://my_oozie_host:11000/oozie. This URI is used by an Oozie client to send commands and queries to the Oozie server.

Returns: a string giving the Oozie server URI.

get_oozie_server(self, cluster)

Returns the node instance for the host in the cluster running the Oozie server

Returns: a node instance

get_name_node_uri(self, cluster)

Returns the full URI for the Hadoop NameNode, for example http://master_node:8020.

Returns: a string giving the NameNode URI.

get_resource_manager_uri(self, cluster)

Returns the full URI for the Hadoop JobTracker for Hadoop version 1 or the Hadoop ResourceManager for Hadoop version 2.

Returns: a string giving the JobTracker or ResourceManager URI

Spark Job Engine

The sahara.service.edp.spark.engine.SparkJobEngine class provides a full EDP implementation for Spark standalone clusters.

Note, the validate_job_execution(cluster, job, data) method does basic checks on the job configuration but probably should be overloaded to include additional checks on the cluster configuration. For example, the job engine returned by the Spark plugin checks that the Spark version is >= 1.0.0 to ensure that spark-submit is available.

get_driver_classpath(self)

Returns driver class path.

Returns: a string of the following format ‘ –driver-class-path class_path_value‘

Sahara Cluster Statuses Overview

All Sahara Cluster operations are performed in multiple steps. A Cluster object has a Status attribute which changes when Sahara finishes one step of operations and starts another one. Also a Cluster object has a Status description attribute which changes whenever Cluster errors occur.

Sahara supports three types of Cluster operations:

• Create a new Cluster
• Scale/Shrink an existing Cluster
• Delete an existing Cluster

Creating a new Cluster

1. Validating

Before performing any operations with OpenStack environment, Sahara validates user input.

There are two types of validations, that are done:

• Check that a request contains all necessary fields and that the request does not violate

any constraints like unique naming, etc.

• Plugin check (optional). The provisioning Plugin may also perform any specific checks like a Cluster topology validation check.

If any of the validations fails during creating, the Cluster object will still be kept in the database with an Error status. If any validations fails during scaling the Active Cluster, it will be kept with an Active status. In both cases status description will contain error messages about the reasons of failure.

2. InfraUpdating

This status means that the Provisioning plugin is performing some infrastructure updates.

3. Spawning

Sahara sends requests to OpenStack for all resources to be created:

• VMs
• Volumes
• Floating IPs (if Sahara is configured to use Floating IPs)

It takes some time for OpenStack to schedule all the required VMs and Volumes, so sahara will wait until all of the VMs are in an Active state.

4. Waiting

Sahara waits while VMs’ operating systems boot up and all internal infrastructure components like networks and volumes are attached and ready to use.

5. Preparing

Sahara prepares a Cluster for starting. This step includes generating the /etc/hosts file, so that all instances can access each other by a hostname. Also Sahara updates the authorized_keys file on each VM, so that VMs can communicate without passwords.

6. Configuring

Sahara pushes service configurations to VMs. Both XML and JSON based configurations and environmental variables are set on this step.

7. Starting

Sahara is starting Hadoop services on Cluster’s VMs.

8. Active

Active status means that a Cluster has started successfully and is ready to run EDP Jobs.

Scaling/Shrinking an existing Cluster

1. Validating

Sahara checks the scale/shrink request for validity. The Plugin method called for performing Plugin specific checks is different from the validation method in creation.

2. Scaling

Sahara performs database operations updating all affected existing Node Groups and creating new ones to join the existing Node Groups.

3. Adding Instances

Status is similar to Spawning in Custer creation. Sahara adds required amount of VMs to the existing Node Groups and creates new Node Groups.

4. Configuring

Status is similar to Configuring in Cluster creation. New instances are being configured in the same manner as already existing ones. The VMs in the existing Cluster are also updated with a new /etc/hosts file.

5. Decommissioning

Sahara stops Hadoop services on VMs that will be deleted from a Cluster. Decommissioning a Data Node may take some time because Hadoop rearranges data replicas around the Cluster, so that no data will be lost after that Data Node is deleted.

6. Deleting Instances

Sahara sends requests to OpenStack to release unneeded resources:

• VMs
• Volumes
• Floating IPs (if they are used)

7. Active

The same Active status as after Cluster creation.

Deleting an existing Cluster

1. Deleting

The only step, that releases all Cluster’s resources and removes it from the database.

Error State

If the Cluster creation fails, the Cluster will enter the Error state. This status means the Cluster may not be able to perform any operations normally. This cluster will stay in the database until it is manually deleted. The reason for failure may be found in the sahara logs. Also, the status description will contain information about the error.

If an error occurs during the Adding Instances operation, Sahara will first try to rollback this operation. If a rollback is impossible or fails itself, then the Cluster will also go into an Error state. If a rollback was successful, Cluster will get into an Active state and status description will contain a short message about the reason of Adding Instances failure.

Other Resources

Project hosting

Launchpad hosts the Sahara project. The Sahara project homepage on Launchpad is http://launchpad.net/sahara.

Launchpad credentials

Creating a login on Launchpad is important even if you don’t use the Launchpad site itself, since Launchpad credentials are used for logging in on several OpenStack-related sites. These sites include:

• Wiki
• Gerrit (see Code Reviews with Gerrit)
• Jenkins (see Continuous Integration with Jenkins)

Mailing list

The mailing list email is openstack-dev@lists.openstack.org with subject prefix [sahara]. To participate in the mailing list subscribe to the list at http://lists.openstack.org/cgi-bin/mailman/listinfo

Bug tracking

Report Sahara bugs at https://bugs.launchpad.net/sahara

Feature requests (Blueprints)

Sahara uses specs to track feature requests. Blueprints are at https://blueprints.launchpad.net/sahara. They provide a high-level summary of proposed changes and track associated commits. Sahara also uses specs for in-depth descriptions and discussions of blueprints. Specs follow a defined format and are submitted as change requests to the openstack/sahara-specs repository. Every blueprint should have an associated spec that is agreed on and merged to the sahara-specs repository before it is approved.

Technical support

Sahara uses Ask OpenStack to track Sahara technical support questions. Questions related to Sahara should be tagged with ‘sahara’.

Code Reviews with Gerrit

Sahara uses the Gerrit tool to review proposed code changes. The review site is http://review.openstack.org.

Gerrit is a complete replacement for Github pull requests. All Github pull requests to the Sahara repository will be ignored.

See Gerrit Workflow Quick Reference for information about how to get started using Gerrit. See Development Workflow for more detailed documentation on how to work with Gerrit.

Continuous Integration with Jenkins

Each change made to Sahara core code is tested with unit and integration tests and style checks flake8.

Unit tests and style checks are performed on public OpenStack Jenkins managed by Zuul. Unit tests are checked using python 2.7.

The result of those checks and Unit tests are +1 or -1 to Verify column in a code review from Jenkins user.

Integration tests check CRUD operations for Image Registry, Templates and Clusters. Also a test job is launched on a created Cluster to verify Hadoop work.

All integration tests are launched by Jenkins on the internal Mirantis OpenStack Lab. Jenkins keeps a pool of VMs to run tests in parallel. Even with the pool of VMs integration testing may take a while. Jenkins is controlled for the most part by Zuul which determines what jobs are run when. Zuul status is available by address: Zuul Status. For more information see: Sahara Hadoop Cluster CI.

The integration tests result is +1 or -1 to Verify column in a code review from Sahara Hadoop Cluster CI user.

You can put sahara-ci-recheck in comment, if you want to recheck sahara-ci jobs. Also, you can put recheck in comment, if you want to recheck both jenkins and sahara-ci jobs.