Custom knowledge object coordination for standard mode federated providers

If you plan to run federated searches that invoke your custom knowledge objects over a standard mode federated provider, identify the knowledge objects that you want to use in your searches and verify that they are present on the federated search head and the remote search head. Ensuring that custom knowledge objects are present on the local and remote search heads helps your federated searches to complete without errors and return correct results.

For example, if you are running a standard mode federated search that references a custom calculated field, the calculated field definition must be present on the local and remote sides of the federated search. If the calculated field doesn't exist on the remote search head, the remote search head can't apply the calculated field to search results from the federated provider. If the calculated field exists only on the remote search head, the search fails.

Skip this topic if you are using a transparent mode federated provider. When you use transparent mode federated search, the Splunk software brings your local custom knowledge objects to the remote search head through automatic bundle replication.

Example of a custom lookup in a standard mode federated search

Say you are using standard mode federated search, and you want to run a federated search that includes a custom CSV file-based lookup named empAddress. This lookup finds events in your search results with employeeID fields and adds corresponding address, city, country and postal_code field-value pairs to those events.

All CSV file-based lookups have two parts: a lookup definition, and a lookup table file. In this case, the lookup definition and lookup table file have the names empAddress and employee_addresses.csv, respectively.

For this example, you run two searches. The first search applies the lookup to results from a remote index on the federated provider:

| search index=federated:remote_index | lookup empAddress employeeID

The second search applies the lookup to search results from an index on the local deployment as well as a remote index on the federated provider.

| search index=local_index OR index=federated:remote_index | lookup empAddress employeeID

The following table tells you how these standard mode federated searches run, depending on the location of their lookup definitions and lookup table files.

Location of lookup definition and lookup table file	Result of running the lookup search over a standard mode federated provider
Only on the local federated search head (FSH)	The first search completes successfully but does not return results or error messages. The second search completes successfully, returning results only from the federated search head. It does not display error messages.
Only on the remote search head (RSH)	The Splunk software terminates both searches and displays error messages for them.
Same definition and file exist on both the FSH and the RSH	Both searches succeed with results from both the FSH and the RSH.

Before you run a standard mode federated search that involves a lookup, you must ensure that the lookup table file and lookup definition are duplicated on the local and remote sides of the search. If you are searching over multiple standard mode federated providers, you need to manually upload the same lookup table file to each federated provider, and you need to create identical lookup definitions on each federated provider.

The importance of duplication over naming

When you prepare to run federated searches with knowledge objects over standard mode federated providers, you can arrange for your searches to run without knowledge object errors by ensuring that there are knowledge objects with the same names on the local and remote sides of the search. However, if these identically-named local and remote knowledge objects have different definitions, this practice might cause your searches to return incorrect results.

Improve your chance of getting correct results from a standard mode federated search that involves knowledge objects by duplicating the definitions of those knowledge objects on the local and remote search heads. When the knowledge object definitions and related files (such as CSV files, for CSV file lookups) are in sync on the local and remote sides of the search, you get consistent search results.

Ensure a custom knowledge object exists on federated and remote search heads

After you identify the custom knowledge objects that you are using in your federated searches, make sure those knowledge objects are present on the federated search head as well as the remote search head on the federated provider. In most cases the easiest way to do this is through Splunk Web.

Prerequisites

• Knowledge object verification requires admin access to the local and remote search heads involved. If you do not have admin access to a Splunk platform deployment where you must duplicate knowledge objects, coordinate this work with the administrator of that deployment.
• Learn about federated provider service accounts. See Service accounts and federated search security.

Steps

1. Identify a knowledge object that you want to use in your federated searches.
2. Verify that the knowledge object exists with identical definitions on the local and remote deployments involved in the search by looking it up in Settings on each deployment. See Help with knowledge objects.
3. If the knowledge object does not exist on a deployment involved in the search, duplicate its definition on the deployment.
4. Ensure that the remote instance of the knowledge object has its permissions set so that the federated provider service account can access it. See Manage knowledge object permissions in the Knowledge Manager Manual.
5. If the knowledge object is a lookup, duplicate the lookup file or collection and upload or install it in the federated provider.

Repeat this process for each knowledge object you intend to use in your federated searches.

Help with knowledge objects

The following table lists knowledge object definitions, files, and collections that you must duplicate on your federated and remote search heads if you want to use them in federated searches. You can verify the existence of a knowledge object by looking it up in Settings for your local deployment and the remote deployments involved in the federated search.

All links go to topics in the Knowledge Manager Manual unless otherwise indicated.

Type of knowledge object	Items that must be duplicated among the federated and remote search heads	For more information
Custom search-time field extraction	Field extraction configurations	About fields
Calculated field	Calculated field definition	About calculated fields
Field alias	Field alias definition	Create field aliases in Splunk Web
CSV file lookup	Lookup definition CSV lookup table file	Define a CSV lookup in Splunk Web
External lookup	Lookup definition External lookup script	Create external lookups for apps in Splunk Cloud Platform or Splunk Enterprise in the Developer Guide on the Developer Portal
KV Store lookup	Lookup definition KV store collection	Define a KV store lookup in Splunk Web
Geospatial lookup	Lookup definition The .kmz or .kml lookup table file	Define a geospatial lookup in Splunk Web
Event type	Event type definition	About event types
Search macro	Search macro definition	Define search macros in Settings
Tag	Tag definition	Define and manage tags in Settings