Configure Knox Topology Discovery through Ambari

Apache Knox supports automatic topology discovery through Apache Ambari, eliminating the need to manually create and maintain topology XML files for supported services in an ODP cluster.

When the KNOX_GATEWAY component is configured or started, the Ambari agent generates a descriptor file at the following location:

/etc/knox/conf/descriptors/odp-<cluster-name>.json

/etc/knox/conf/topologies/<cluster-name>.xml

This guide explains how to configure automatic topology discovery, manage discovery credentials, verify generated topology files, identify supported services, and troubleshoot common issues.

1. Configure Automatic Knox Topology Discovery

To enable automatic topology discovery, create a dedicated Ambari service account and configure the required credentials in the Knox alias keystore.

1.1 Create an Ambari Service Account

Create a dedicated Ambari service account with the built-in Cluster User role. This role provides the read-only permissions required for service discovery without granting administrative or write access.

To create and configure the service account:

1. In the Ambari UI, navigate to Manage Ambari > Users.
2. Create a dedicated service account.
3. Open the service account and locate its cluster permissions.
4. Assign the Cluster User role to the account.
5. Save the changes.

Knox uses this account to perform the following read-only Ambari REST API requests:

services?fields=components/host_components/HostRoles

configurations/service_config_versions?is_current=true

Important: Use a dedicated service account for discovery. Do not use personal credentials or the cluster administrator account.

1.2 Create Knox Discovery Credential Aliases

Knox retrieves the Ambari service account credentials from two aliases stored in its encrypted credential keystore.

These aliases are not created by default and must be configured for each Knox instance.

To create the discovery aliases:

1. Log in to the host where Knox is installed.
2. Run the following command to create the username alias:

/usr/odp/<version>/knox/bin/knoxcli.sh create-alias ambari.discovery.user --value <service-account>

3. 
   Run the following command to create the password alias:

/usr/odp/<version>/knox/bin/knoxcli.sh create-alias ambari.discovery.password

4. When prompted, enter the password for the Ambari service account.

1.3 Secure Ambari Discovery Credentials

Store the Ambari discovery credentials only in the Knox alias keystore. The keystore encrypts credentials using the Knox master secret.

Do not store the credentials in the following locations:

• Descriptor JSON files: These files are stored outside Ambari's SECRET handling mechanism and might be accessible to users with permissions to /etc/knox/conf.
• Topology parameters: Topology files are plain configuration files and can expose credentials.
• Ambari password properties: Storing the credentials as an Ambari PASSWORD-typed property creates an additional copy in the Ambari database.

Unlike credentials used exclusively by an individual service, the discovery account can read configuration information across the cluster. Storing an additional copy in Ambari increases potential exposure through configuration exports and backups.

The Knox RESTInvoker retrieves discovery credentials from the Knox aliases. Therefore, storing credentials in Ambari does not eliminate the need to configure the Knox keystore.

Configure Automatic Credential Provisioning (Optional)

If automatic credential provisioning is required, you can configure a Knox-specific Ambari property, such as:

knox-env/ambari_discovery_password

If you use this approach, restrict access to the Knox configuration page in Ambari.

Note: No additional discovery configuration is required. The discovery-address value is automatically populated from ambariLevelParams, and the topology generation logic is implemented in the KNOX_GATEWAY Ambari agent scripts.

2. Verify Automatic Topology Generation

After configuring the discovery credentials, verify that Knox generates the descriptor and topology files.

2.1 Verify the Generated Descriptor File

Whenever KNOX_GATEWAY is configured or started, the Ambari agent rewrites the descriptor file.

To verify the descriptor file:

1. Log in to the Knox host.
2. Verify that the following file exists:

/etc/knox/conf/descriptors/odp-<cluster-name>.json

3. Open the descriptor file and verify that it contains the expected cluster information.

The descriptor provides the information required for Knox to discover supported services through Ambari.

2.2 Verify the Generated Topology File

The Knox DescriptorsMonitor checks the conf/descriptors/ directory approximately every five seconds.

When it detects a change in descriptor content, Knox queries Ambari and generates the corresponding topology XML file.

To verify topology generation:

1. Review the Knox logs for the following message:

Generated topology <cluster-name>.xml because the associated descriptor ... changed.

2. Verify that the generated topology file exists:

/etc/knox/conf/topologies/<cluster-name>.xml

3. Open the topology file and verify that the discovered services and URLs match the installed Ambari components.

Note: Only services that Knox can successfully discover are included in the generated topology. If an installed service is missing, review Sections 3 and 4 to determine whether automatic discovery is supported.

2.3 Understand Topology Regeneration Behavior

Automatic topology generation follows these rules:

• The Ambari agent rewrites odp-<cluster-name>.json whenever KNOX_GATEWAY is configured or started.
• The Knox DescriptorsMonitor checks the descriptor directory approximately every five seconds.
• Knox regenerates the topology only when the descriptor content changes.
• If the descriptor content remains unchanged, Knox does not regenerate the topology, including after restarts.
• Only services that Knox can successfully discover are included in the generated topology.

3. Review Services Supported for Automatic Discovery

The following table lists the Knox service descriptors and corresponding Ambari components supported for automatic topology discovery.

4. Review Services Not Supported for Automatic Discovery

The following services are not currently configured for automatic Knox topology discovery.

Note: These limitations apply to automatic Knox service discovery. They do not necessarily indicate that the services are unavailable in the ODP cluster.

5. Troubleshoot Knox Service Discovery

Use the following troubleshooting information to identify and resolve common issues with automatic topology discovery.

5.1 Resolve Missing Ambari Discovery Credentials

Issue

Knox cannot retrieve the Ambari discovery username or password.

The logs display one of the following errors:

No username is configured for Ambari service discovery.
(RESTInvoker.java:125)

No password is configured for Ambari service discovery.

The ambari.discovery.user or ambari.discovery.password alias is missing from the Knox credential keystore.

Resolution

1. Create the missing alias as described in Section 1.2.
2. Reconfigure KNOX_GATEWAY in Ambari to trigger descriptor generation.
3. Verify that Knox successfully generates the topology.

5.2 Resolve Service URL Validation Errors

Issue

Knox fails to validate a discovered service URL.

The logs display an error similar to the following:

URL validation failed ... http://host:{SOME_PROPERTY}
Illegal character in authority

The service discovery mapping references an Ambari configuration property that is not defined.

For example, the mapping might reference hbase.rest.port when the property is not configured.

Resolution

1. Identify the unresolved property in the error message.
2. Verify whether the property exists in the corresponding Ambari service configuration.
3. Perform one of the following actions:
   • Configure the missing property in Ambari, if the service supports it.
   • Remove the unsupported service from the descriptor.
4. Reconfigure KNOX_GATEWAY and verify topology generation.

5.3 Resolve Missing Service Endpoints

Issue

Knox cannot discover a valid endpoint for a service.

The logs display the following error:

No valid URLs were discovered for <SERVICE>

One of the following conditions applies:

• The required Ambari component is not installed.
• The service is missing from the discovery component configuration mapping.

Knox excludes services that are not included in the discovery allow-list.

Resolution

1. Verify that the required Ambari service component is installed.
2. If you are adding support for a new service, verify its entry in the following file:

ambari-service-discovery-component-config-mapping.properties

3. Add the required service mapping if it is missing.
4. Reconfigure KNOX_GATEWAY and verify that the service appears in the generated topology.

5.4 Apply Topology Changes After Rebuilding or Restarting Knox

Issue

Changes to a Knox service definition are not applied after rebuilding or restarting Knox.

Cause

Knox recompiles a topology when the modification time of the topology XML file changes.

Changes to underlying service.xml, rewrite.xml, or JAR files do not automatically trigger topology recompilation.

Resolution

1. Update the modification time of the generated topology XML file:

touch /etc/knox/conf/topologies/<cluster-name>.xml

2. Verify that Knox reloads the topology.
3. If the issue persists, check whether a packaged service definition inside a JAR is taking precedence over the modified service definition.

5.5 Resolve CSS and JavaScript Resource Errors

Issue

The application page loads through Knox, but CSS or JavaScript resources return HTTP 404 errors from the gateway root.

Cause

The backend application generates root-relative asset URLs that are not covered by the configured HTML response rewrite rules.

Knox does not provide a generic href or src attribute rewriter.

Resolution

1. Identify the asset paths that return HTTP 404 errors.
2. Update the corresponding rewrite.xml file.
3. Add a content rewrite filter for the affected HTML asset paths using the following structure:

<filter>
 <content type="*/html">
 <!-- Add the required asset rewrite rules. -->
 </content>
</filter>

4. Refer to the following HBase UI rewrite configuration for an implementation example:

hbaseui/2.5.10/rewrite.xml

5. Reference rule:

HBASEUI/hbase/outbound/html/static

6. Reload the topology and verify that the application resources load successfully.

5.6 Resolve Redirects That Bypass the Knox Gateway

Issue

An application redirects users from the Knox gateway to the backend service URL.

For example:
/gateway/<topo>/ranger/

http://backend:6080/login.jsp

One of the following conditions applies:

• The service does not have an outbound Location header rewrite rule.
• Multiple Knox services use the same context path.

For example, configuring both RANGER and RANGERUI causes a conflict because both use the /ranger context path.

Resolution

1. Verify that the service defines the required outbound Location rewrite rule.
2. Check whether multiple services share the same gateway context path.
3. Remove conflicting service definitions.
4. For Ranger, configure only RANGERUI.
5. Reload the topology and verify that redirects remain within the Knox gateway.

5.7 Resolve SSL Handshake Errors

Issue

Knox fails to dispatch requests and displays an SSL handshake error.

The logs display an error similar to the following:

SSLHandshakeException
PKIX path building failed

An inbound rewrite rule is missing, or the rule name referenced by the service route does not match the corresponding definition in rewrite.xml.

As a result, Knox dispatches the client URL without applying the required rewrite.

Resolution

1. Open the affected service definition.
2. Identify the rewrite rule referenced by the route's apply attribute.
3. Open the corresponding rewrite.xml file.
4. Verify that the referenced rule exists and that its name matches exactly.
5. Correct any missing or mismatched rules.
6. Reload the topology and verify request routing.

Example: The hbaseui/2.5.10 service previously lacked the following inbound rewrite rule, which has been fixed in this build:

HBASEUI/hbase/inbound/master/root

5.8 Verify Descriptor and Topology File Names

Issue

The expected topology file is missing, or its name does not match the descriptor filename.

Cause

Knox uses the cluster field in the descriptor JSON to determine the generated topology filename.

The descriptor filename itself does not determine the topology name.

Resolution

1. Verify that the descriptor exists:

/etc/knox/conf/descriptors/odp-<cluster-name>.json

2. Open the descriptor and verify the value of the cluster field.
3. Verify that the corresponding topology file exists:

/etc/knox/conf/topologies/<cluster-name>.xml

4. Review the Knox logs for descriptor processing and topology generation errors.

6. Validate Knox Service Discovery on a New Cluster

After configuring Knox on a new ODP cluster, complete the following verification steps.

1. Create a dedicated Ambari service account and assign the Cluster User role. For more information, see Section 1.1.
2. Create the ambari.discovery.user and ambari.discovery.password aliases in the Knox credential keystore. For more information, see Section 1.2.
3. Reconfigure KNOX_GATEWAY in Ambari.
4. Verify that the following descriptor file is generated:

/etc/knox/conf/descriptors/odp-<cluster-name>.json

5. 
   Review the Knox logs and confirm that topology generation completes successfully:

Generated topology <cluster-name>.xml because the associated descriptor ... changed.

6. Verify that the following topology file exists:

/etc/knox/conf/topologies/<cluster-name>.xml

7. Open the generated topology file and verify that the discovered service URLs match the installed Ambari components and their configured endpoints.
8. Compare the discovered services with the supported and unsupported service lists in Sections 3 and 4.

Expected Result: Knox automatically generates the topology XML file for supported services discovered through Ambari without requiring manually maintained topology definitions.