Add a custom descriptor to Apache Knox

How to add a custom descriptor to Apache Knox using Cloudera Manager.

Custom descriptors can be deployed to Apache Knox using Cloudera Manager. These descriptors, combined with referenced provider configurations, are transformed into Knox topologies. Using Cloudera Manager means that these descriptors only ever need to be changed in one place to affect all Knox Gateway instances in the cluster.

Fundamentally, descriptors contain the declaration of services to proxy and a reference to provider configuration defining how authentication and authorization for those proxied services should be handled. A descriptor also may similarly declare Knox applications as topologies do.

Service declarations consist of at least the name of the service being proxied. They optionally include one or more endpoint URLs and one or more service-specific parameters.

Descriptors optionally include discovery information, allowing Knox to dynamically discover the endpoint URLs for the declared services.

  1. Define the descriptor contents:
    1. From Cloudera Manager > Knox > Configuration, add a new entry in Knox Gateway Advanced Configuration Snippet (Safety Valve) for conf/cdp-resources.xml_role_safety_valve.
    2. Name the topology, specify the providerConfigRef, and enumerate the services and associated service URLs.
      Optional service details include version (E.G., HIVE:version=0.13.0) and service parameters (E.G., HIVE:httpclient.connectionTimeout=5m)
    Static URL Example (HIVE and WEBHDFS with PAM authentication)
    • Name=my-custom-topology
    • Value=
      providerConfigRef=pam#
      HIVE:url=https://hive-host-1:10001/cliservice#
      WEBHDFS:url=https://hdfs-host-1:20470/webhdfs#
      WEBHDFS:url=https://hdfs-host-2:20470/webhdfs
    Discovery Example (HIVE and WEBHDFS with PAM authentication)
    • Name=my-discoverable-topology
    • Value=
      discoveryType=ClouderaManager#
      discoveryAddress=https://cm-host:7183#
      cluster=Cluster 1#
      providerConfigRef=pam#
      HIVE#
      WEBHDFS
  2. Save the changes.
  3. Refresh the Knox instances’ configuration: the Refresh needed stale configuration indicator appears; click it and wait until the refresh process completes.
  4. Validate:
    Using the Knox Admin UI (https://KNOX_GATEWAY_HOST:PORT/GATEWAY_PATH/gateway/manager/admin-ui/), navigate to the Topologies, and verify that your topology was generated with the services and URLs you specified.