Create a federated index

After you set up one or more remote Splunk platform deployments as standard mode federated providers for your local Splunk platform deployment, you need to create federated indexes for use in federated searches. Each federated index you create maps to one remote dataset on a standard mode federated provider.

Federated indexes do not ingest or store data or events. Federated indexes cannot be targets for data inputs. The function of a federated index is to route your federated search to a specific dataset on a standard mode federated provider.

The Splunk platform creates federated indexes on the federated search head of your local deployment.

In this task, you:

• Provide the name of the federated index.
• Select a standard mode federated provider. The federated provider must contain the remote dataset to which the federated index is mapped.
• Specify the remote dataset to which the federated index is mapped.

You can map a federated index to only one remote dataset at a time. If a federated provider contains several remote datasets over which you want to run federated searches, define a separate federated index for each dataset.

Transparent mode federated providers do not use federated indexes. If you are running all of your federated searches in transparent mode, you can skip this topic.

See About federated search for an overview of the standard and transparent modes of federated search.

Specifying remote datasets

When you create a federated index, you map the index to a specific remote dataset on a standard mode federated provider. Remote datasets can be events indexes, saved searches, or data models.

Remote dataset type	Definition
Index	Each events index on a federated provider is a searchable dataset.
Saved search	The result set produced by a run of a saved search on a federated provider is a searchable dataset.
Data model	The set of events defined by a data model on a federated provider is a searchable dataset.

You can map a federated index to an accelerated data model and then search it with the tstats command. See Run federated searches.

Use saved search datasets to route around federated search limitations

You can use saved search datasets to get around certain limitations of federated searches over a standard mode federated provider. For example, standard mode federated searches cannot be the following kinds of searches:

• Searches that use metrics search commands such as mstats to search data in metrics indexes.
• Searches that use any generating commands other than search, from, or tstats.

However, you can create federated indexes that map to saved search datasets that use these commands. Then you can write federated searches that reference those federated indexes. See Run federated searches.

Remote dataset restrictions

The following kinds of indexes, saved searches, and data models cannot be used as remote datasets for federated searches. Do not map federated indexes to them.

• Metrics indexes
• Federated indexes
• Saved searches that contain references to federated indexes
• Data models with constraint searches that refer to federated indexes

The saved search and data model limitations relate to the fact that federated search does not support federated index chaining.

Review the permission settings on saved searches or data models that you want to use as federated search datasets. These knowledge objects must either be shared globally, or they must have the same app context as the federated provider that the federated index is associated with. In either case they must be shared with read permissions enabled.

For example, if you are creating a federated index for a federated provider that is associated with the Search app, any saved search dataset for that index must be shared with the Search app as well, or shared globally.

See Manage knowledge object permissions in the Knowledge Manager Manual.

Ensure federated index replication to search head cluster members in your local Splunk Enterprise deployment

If your local deployment uses Splunk Cloud Platform, you can ignore this section.

If your local deployment uses Splunk Enterprise with a search head cluster as its search tier and you are going to run federated search with a standard mode federated provider, you must use the deployer to distribute an additional configuration to the server.conf files on your search head cluster members. This configuration enables your federated index definitions to replicate to each member of the search head cluster.

Do not create federated indexes until you have pushed this configuration to your search head cluster members. Federated index definitions that you create before you push this configuration are not replicated to search head cluster members after you push the configuration. Searches using federated indexes that have not been properly replicated can fail or return incorrect search results.

Use the deployer to push a configuration bundle that adds conf_replication_include.indexes = true to the [shclustering] stanza of server.conf on each member of your search head cluster. To use the deployer you must have an admin or similar role with the admin_all_objects capability.

For more information about using the deployer to push updates to search head cluster members, see Use the deployer to distribute apps and configuration updates in the Distributed Search manual.

Prerequisites for federated index creation

• Read About federated search to familiarize yourself with federated search concepts and terminology.
• To create federated indexes, you must have a role with the admin_all_objects and indexes_edit capabilities.
  • If you use Splunk Cloud Platform, the sc_admin role has these capabilities by default. See Define roles on the Splunk platform with capabilities in the Securing Splunk Cloud Platform manual.
  • If you use Splunk Enterprise, the admin role has these capabilities by default. See Define roles on the Splunk platform with capabilities in the Securing Splunk Enterprise manual.
• You must define one or more federated providers. See Define a federated provider.
• If your local deployment uses Splunk Enterprise and has a search head cluster as its search tier, you must use the deployer to distribute an additional configuration to the server.conf files on your search head cluster members. This configuration enables your federated index definitions to replicate to each member of the search head cluster. See Ensure federated index replication to search head cluster members in your local Splunk Enterprise deployment.
• Know the names of the remote datasets to which you want your federated indexes to map.

Steps

1. On the local deployment, in Splunk Web, go to Settings > Federated Search.
2. On the Federated Indexes tab, select Add Federated Index.
3. Using the following table, specify the settings for your federated index.
   

   Setting	Description	Default value
   Federated Index Name	Specify the name of the federated index you're creating. The name must reference the remote dataset it maps to. Federated index names have the following restrictions: They may contain only lower-case letters, numbers, underscores, and hyphens. They must begin with a letter or number. They cannot be more than 2048 characters in length. They cannot contain the string "kvstore".	No default
   Federated Provider	Select the standard mode federated provider that contains the dataset to which this federated index will map.	No default
   Remote Dataset	Specify the remote Dataset Type that this federated index maps to and provide the Dataset Name. For Dataset Name, provide the name of a dataset of the selected Dataset Type that currently exists on the selected federated provider.	Dataset Type defaults to Index. Dataset Name has no default.

4. Select Save to save the federated index configuration.

The index is created on the federated search head of your local deployment.

In Splunk Web, you can view the federated indexes that you create for your deployment by selecting Settings > Federated Search > Federated Indexes.

Do not designate federated indexes as default indexes for roles or data inputs.

Give your users access to federated indexes

After you create a federated index, give your federated search users access to the index. If you do not do this, your users cannot search the remote dataset that the federated index maps to.

Just as with normal Splunk indexes, you grant access to federated indexes at the role level. This lets you grant federated index access to certain groups of users while disallowing access to other user groups.

To learn how to add a federated index to the set of searchable indexes for a role, see the section on federated indexes in Service accounts and federated search security.

Ensure service account roles can access remote datasets

Service account roles for standard mode federated providers must also have read permissions for any remote datasets that you expect your federated search users to access through federated indexes. For example, if you are going to set up a federated index that maps to a data model on a federated provider, make sure that the service account role for that federated provider has read permissions for that data model.

For more information about setting permissions for knowledge objects like saved searches and data models, see Manage knowledge object permissions.

Reference federated indexes in federated searches

After you create your federated indexes, you can reference them in federated searches. When you reference a federated index in a search, you are searching over the remote dataset to which the federated index maps. See Run federated searches.