Define a federated provider

The first step to setting up federated search on your local Splunk platform deployment is defining one or more federated providers for that deployment. A federated provider is a remote data source that contains the remote datasets that you want to search on your local deployment with your federated searches.

Prerequisites

• Read About federated search to familiarize yourself with federated search concepts and terminology.
• You must have a role with the admin_all_objects and indexes_edit capabilities.
  • If you use the Splunk Cloud Platform, the sc_admin role has these capabilities by default. See Manage Splunk Cloud users and roles in Securing the Splunk Platform.
  • If you use Splunk Enterprise, the admin role has these capabilities by default. See Define roles on the Splunk platform with capabilities in Securing the Splunk Platform.
• Gather the unique host names of the remote Splunk platform deployments that you want to set up as federated providers. The format of the host name depends on whether your local Splunk platform deployment uses search head clustering.

Deployment type	Uses search head clustering?	Host name format	Host name example
Splunk Cloud Platform	No	<stack name>.splunkcloud.com	buttercupgames.splunkcloud.com
Splunk Cloud Platform	Yes	shc1.<stack name>.splunkcloud.com	shc1.buttercupgames.splunkcloud.com
Splunk Enterprise	No	<deployment name>.splunk.com	buttercupgames.splunk.com
Splunk Enterprise	Yes	<deployment name>-shc.splunk.com or shc-<deployment name>.splunk.com	shc-buttercupgames.splunk.com or buttercupgames-shc.splunk.com

You can find the <stack name> or <deployment name> in the URL for a Splunk platform deployment.

When you connect to a Splunk Cloud Platform federated provider that uses search head clustering, in most cases you will connect to the load balancer for the cluster when you use the URLs described above. The load balancer can manage disruptions if individual search heads within the cluster go offline.

• Create a service user account on each remote Splunk platform deployment that you want to set up as a federated provider. See Create a federated provider service account.

Steps

1. Go to Settings > Federated Search.
2. On the Federated Providers tab, click Add Federated Provider.
3. Using the following table, specify the settings for your federated provider.
   

   Setting	Description	Default value
   Federated Provider Type	Determines the federated provider type. Currently this setting is fixed. You can define only federated providers that are remote Splunk platform deployments.	Splunk
   Federated Provider Name	Select a unique name for the federated provider. The provider name can contain only alphanumeric characters and underscores. The provider name cannot be the string splunk by itself. You can use this string with other alphanumeric characters. For example, abcsplunk is a valid provider name.	No default
   Remote Host	Provide the host name and port number for the federated provider, separated by a colon character. For example: buttercupgames.splunkcloud.com:8089. You can provide an IP address instead of a host name. You can provide any legitimate port number. 8089, the standard management port number, should work for any federated provider. If you use Splunk Cloud Platform and are having trouble connecting to port 8089 on a remote Splunk Cloud Platform deployment, contact Splunk Support to check that the management port is open on the federated provider. For the purposes of federated search, communication between local and remote Splunk platform search heads is facilitated by an internal REST API endpoint.	No default
   Service Account Username and Service Account Password	These settings are for a service account that is set up on the federated provider. This dedicated user account allows the federated search head on your local instance to search datasets on the federated provider. If you do not already have a service account on the federated provider, create one. See Create a federated provider service account.	No default
   Application Short Name	Specify the short name of an app to apply an application context to searches on the federated provider. If Local Knowledge Objects is turned on, provide the short name of an app that is installed on the federated search head of your local Splunk provider. If Local Knowledge Objects is turned off, provide the short name of an app that is installed on the remote search head of the federated provider. If you leave this setting blank, the Splunk software applies search, the short name of the Search & Reporting app, to this setting. See About providing application contexts for federated providers.	search
   Local Knowledge Objects	This switch determines whether the portions of federated searches that are processed on this federated provider use knowledge objects from your local federated search head, or knowledge objects from the remote search head on this federated provider. See About knowledge objects in federated searches. Disable this setting if you are setting up a Splunk Enterprise deployment as a federated provider.	Enabled

4. Click Save to save the federated provider configuration.

Create a federated provider service account

Before you define a remote Splunk platform deployment as a federated provider, create a service user account on that remote deployment. This service account enables secure communication between the federated search head on your local deployment and the federated provider.

To set up a service account, follow these steps on the remote Splunk platform deployment that you intend to configure as a federated provider:

• Create a new role. This role must be dedicated to the service account for the federated provider. You can implement role-based restrictions that limit the indexes and datasets that this role can search. To ensure that the service account role has the essential capabilities for running searches, make sure the role inherits its baseline capabilities from the User role.
  • If you use Splunk Cloud Platform, see Manage Splunk Cloud users and roles in Securing the Splunk Platform.
  • If you use Splunk Enterprise, see Create and manage roles with Splunk Web in Securing the Splunk Platform.
• Create a new user account. Assign the new service account role to that user account.
  • If you use Splunk Cloud Platform, see Manage Splunk Cloud users and roles in Securing the Splunk Platform.
  • If you use Splunk Enterprise, see Create and manage users with Splunk Web in Securing the Splunk Platform.

Save a record of the user ID and password for the service user account. You need those credentials for the Service Account Username and Service Account Password fields when you configure the remote Splunk platform deployment as a federated provider.

About providing application contexts for federated providers

The Application Short Name setting provides an application context for the searches you run against remote datasets on the federated provider. Setting an application context for a federated provider serves three purposes:

• Knowledge-object scoping. Provision of an application context ensures that federated searches which use the federated provider are limited to the knowledge objects that are associated with the named application. For example, if a federated provider has the Search & Reporting app as its application context, federated searches you run with it can use or reference only the lookups, aliases, search-time field extractions, and other knowledge objects that are associated with the Search & Reporting app. If you run a search that references a lookup or calculated field that is associated with another application, such as Enterprise Security or Splunk IT Service Intelligence, it will fail because it can't find those knowledge objects in the Search & Reporting app.
• Provision of workload management limits. The application context allows administrators of the federated provider to set app-based workload management limits on your federated searches.
• Logging and auditing. The application context simplifies logging and auditing of the federated provider.

If you are unsure what applications are installed on a specific Splunk platform deployment, go to Apps > Manage Apps on that deployment. This takes you to the Apps listing page, where the short names of the installed apps are provided in the Folder name column.

It is possible to create multiple federated provider configurations that use the same remote host name and port but which have different application contexts, as long as each federated provider configuration has a unique name. For example, the following three federated provider configurations can be used concurrently even though they all search data on the same remote host:

Federated Provider Name	Remote Host	Application Short Name
buttercupgames-search	buttercup.games.splunkcloud.com:8089	search
buttercupgames-custom1	buttercup.games.splunkcloud.com:8089	your_custom_app1
buttercupgames-custom2	buttercup.games.splunkcloud.com:8089	your_custom_app2

Interoperation with Local Knowledge Objects

If Local Knowledge Objects is turned on for your federated provider, its Application Short Name must be set to an application that is installed on the federated search head on your local Splunk platform deployment. Local Knowledge Objects causes the portion of the federated search that takes place on the federated provider to use knowledge objects from the federated search head. It uses knowledge objects that have the application context indicated by Application Short Name.

See About knowledge objects in federated searches.

About knowledge objects in federated searches

When you run a federated search, it's important to understand what sets of knowledge objects are being applied to that search. Because the search is spread across multiple Splunk platform deployments, it can potentially apply knowledge objects to the search from all of those deployments. This practice can cause problems if you are not intimately aware of the knowledge object sets on each deployment included in your federated search.

For example, let's say you have a federated search that references a lookup configuration named http_status, and let's say that your search is set up to return results from datasets on two federated providers, as well as your own local Splunk platform deployment. If each of the Splunk platform deployments in your federated search has a lookup configuration named http_status, but each of those lookups references a different CSV lookup table, you might get a mismatched set of lookup fields applied to the results of your search.

Local Knowledge Objects ensures that federated search processes on the federated provider use only knowledge objects from the federated search head. In other words, if Local Knowledge Objects is switched on for all of the federated providers in your federated search, all of the remote search heads on those federated providers will use knowledge objects from your local federated search head when they process the federated search.

If you are setting up a Splunk Enterprise deployment as a federated provider, disable Local Knowledge Objects.

Local Knowledge Objects relies on knowledge bundle replication to move knowledge objects from the federated search head in your local Splunk platform deployment to the remote search heads in your remote Splunk platform deployments. Bundle replication between the federated search head and the federated provider can take a few minutes to complete. This means that if you switch Local Knowledge Objects on for a federated provider, you should wait a few minutes before you try to run federated searches that leverage datasets on that federated provider. If you try to search datasets on the federated provider before the bundle replication process completes, you may encounter search errors.

When the remote Splunk deployment uses search head clustering

If possible, disable the Local Knowledge Objects setting for federated providers on remote Splunk deployments that use search head clustering. This is especially important if you have set up the load balancer as the federated provider for the search head cluster. As load balancers manage data traffic for their clusters, they can drop knowledge object bundles on different cluster nodes from the cluster nodes on which they run federated searches. This can cause your federated searches to fail.

If your remote deployment uses search head clustering and you must use local knowledge objects for your federated searches, set up each of the search heads in the search head cluster as federated providers, and enable Local Knowledge Objects for each provider.

Interoperation with Application Short Name

If Local Knowledge Objects is turned on for your federated provider, its Application Short Name must be set to an application that is installed on the federated search head on your local Splunk platform deployment. Local Knowledge Objects causes the portion of the federated search that takes place on the federated provider to use knowledge objects from the federated search head. It uses knowledge objects that have the application context indicated by Application Short Name.

See About providing application contexts for federated providers.

Next steps

After you have defined one or more federated providers, you need to define one or more federated indexes and associate remote datasets from the federated providers to those federated indexes. For more information, see Define a federated index.