Configuring Proxy with Apache Knox
Also available as:
loading table of contents...

Defining Cluster Topologies

The Knox Gateway supports one or more clusters. Each cluster configuration is defined in a topology deployment descriptor file in the $gateway/conf/topologies directory and is deployed to a corresponding WAR file in the $gateway/data/deployments directory. These files define how the gateway communicates with each cluster.

Topology Deployment Descriptor File Sections

The descriptor is an XML file contains the following sections:

  • gateway/provider -- configuration settings enforced by the Knox Gateway while providing access to the cluster.

  • service -- defines the service URLs used by the gateway to proxy communications from external clients.

Cluster Topology Provider and Service Roles

The gateway automatically redeploys the cluster whenever it detects a new topology descriptor file, or detects a change in an existing topology descriptor file.

The following table provides an overview of the providers and services:

Type Role Description
gateway/provider hostmap Maps external to internal node hostnames, replacing the internal hostname with the mapped external name when the hostname is embedded in a response from the cluster.
authentication Integrates an LDAP store to authenticate external requests accessing the cluster via the Knox Gateway. Refer to Set Up LDAP Authentication for more information.
federation Defines HTTP header authentication fields for an SSO or federation solution provider. Refer to Set up HTTP Header Authentication for Federation/SSO
identity-assertion Responsible for the way that the authenticated user's identity is asserted to the service that the request is intended for. Also maps external authenticated users to an internal cluster that the gateway asserts as the current session user or group. Refer to Configure Identity Assertion for more information.
authorization Service level authorization that restricts cluster access to specified users, groups, and/or IP addresses. Refer to Configure Service Level Authorization for more information.
webappsec Configures a web application security plugin that provides protection filtering against Cross Site Request Forgery Attacks. Refer to Configure Web Application Security for more information.
HA provider high availability Syncs all Knox instances to use the same topologies credentials keystores.
service $service_name Binds a service with an internal URL that the gateway uses to proxy requests from external clients to the internal cluster services. Refer to “Configure Service URLs” for more information. E.G., NAMENODE, HDFS, JOBTRACKER, HIVE, KAFKA, STORM, etc.


Cluster topology descriptors have the following XML format: