Hue High Availability

To make the Hue service highly available, you configure at least two instances of the Hue service, each on a different host. You also configure the nginx load balancer to direct traffic to an alternate host if the primary host becomes unavailable. This topic provides basic configuration information for using, installing, and configuring nginx. For information on advanced configurations, see the nginx documentation.


  • Network access via SSH to the host machines with the Hue role.

Preparing a Cluster for Hue High Availability

Minimum Required Role: Cluster Administrator (also provided by Full Administrator)

Follow these steps to prepare your cluster for Hue high availability.

  1. Configuring High Availability for a New Hue Service:

    Add the Hue service to your cluster using the Add a Service wizard. See Adding the Hue Service. Hue high availability requires at least two instances of the Hue Server role in your cluster. Starting with CDH 5.4.1, you can add a new Hue service with multiple Hue Server roles.

    For Kerberized clusters, the Add Service wizard will automatically add a colocated Kerberos Ticket Renewer role for each Hue Server role instance.

    Configuring High Availability for an Existing Hue Service:

    To add a Hue Server role to an existing Hue service on a Kerberized cluster, use the Add Role Instances wizard. Cloudera Manager will generate a validation error if the new Hue Server role does not have a colocated Kerberos Ticket Renewer role. To add a Hue role instance, see Adding a Hue Role Instance.

  2. Configure the backend database for high availability. For more information, consult the vendor documentation for the database that you configured for Hue.
  3. Configure the Hue instances in your cluster to connect to the backend database. See Using an External Database for Hue Using Cloudera Manager.

Installing the nginx Load Balancer

To enable high availability for Hue, install the nginx load balancer on one of the Hue instances. Clients access this instance through a designated port number, and the nginx load balancer directs the request to one of the Hue server instances.

  1. Using SSH, log in as the root user to the host machine of one of the Hue instances.
  2. Run the following command to install nginx:
    Red Hat/Centos:
    yum install nginx
    apt-get install nginx
  3. Create the following configuration file:
  4. Using the following text as a template, enter the configuration for your cluster in the hue.conf file:
    server {
        server_name NGINX_HOSTNAME;
        charset utf-8;
        listen 8001;
        # Or if running hue on https://
        ## listen 8001 ssl;
        ## ssl_certificate /path/to/ssl/cert;
        ## ssl_certificate_key /path/to/ssl/key;
        location / {
            proxy_pass http://hue;
            # Or if the upstream Hue instances are running behind https://
            ## proxy_pass https://hue;
        location /static/ {
            # Uncomment to expose the static file directories.
            ## autoindex on;
            # If Hue was installed with packaging install:
            alias /usr/lib/hue/build/static/;
            # Or if on a parcel install:
            ## alias /opt/cloudera/parcels/CDH/lib/hue/build/static/;
            expires 30d;
            add_header Cache-Control public;
    upstream hue {
        # List all the Hue instances here for high availability.
        server HUE_HOST1:8888 max_fails=3;
        server HUE_HOST2:8888 max_fails=3;
  5. Update the following items in the hue.conf file:
    • Replace NGINX_HOSTNAME with the URL of the host where you installed nginx. For example:
    • In the location/static block, comment or uncomment the alias lines depending on whether your cluster was installed using parcels or packages. (The comment indicator is #.)
    • In the upstream hue block, list all the hostnames, including port number, of the Hue instances in your cluster. For example:
      server max_fails=3;
      server max_fails=3;
      server max_fails=3;
    • If the Hue service in your cluster is configured to use SSL:
      • Uncomment these lines, and replace the path names with the correct values for your cluster:
        ## listen 8001 ssl;
        ## ssl_certificate /path/to/ssl/cert;
        ## ssl_certificate_key /path/to/ssl/key;
      • Uncomment the following line in the location / block:
        ## proxy_pass https://hue;
        and comment out the following line:
        proxy_pass http://hue;
      • Comment out the following line:
        listen 8001
  6. Run the following command to start nginx:
    sudo service nginx start
  7. Test your installation by opening the Hue application in a web browser, using the following URL:
    • Without SSL: http://NGINX_HOSTNAME:8001

    • With SSL: https://NGINX_HOSTNAME:8001

    Where NGINX_HOSTNAME is the name of the host machine where you installed nginx.

  8. Test high availability:
    1. Stop the Hue service instance on the host where you installed nginx.
    2. Access the Hue application as described in the previous step. If you can connect to the Hue application, you have successfully enabled high availability.