Concepts

Kubernetes Search answers one question well: what is true in my cluster right now, from inside Splunk, without storing anything. This page explains the model so the rest of the documentation makes sense.

Live access, not ingestion

The Monitoring apps (and most Splunk content) work by ingesting: an agent collects logs, metrics, and events and forwards them into a Splunk index, where you search the stored copy. That gives you history, retention, and alerting - at the cost of storage and license volume.

Kubernetes Search works the other way around. When you run a command, it calls the Kubernetes API live and streams the answer straight into your search. Nothing is written to an index. The consequences are worth internalizing:

• Always current. You see the cluster as it is at the moment you search, not as it was when an agent last sampled it.
• No storage, no license volume. Results aren’t indexed, so they cost no disk and count against no ingest quota.
• No history of its own. You see the present. For trends over time and retention you still want ingestion - see the comparison. The two approaches are complementary, not competing. You can still alert on current state by scheduling a search - see Use cases.

How it works

When you run | k8s kind=pods namespace=payments, the command runs on the search head. It connects directly to the cluster’s API server using the credential you registered, performs the equivalent of kubectl get pods -n payments, and emits one search row per object.

There is no agent in your cluster and nothing to install cluster-side. The only things Kubernetes Search needs are a network route from the search head to the API server and a credential. That is the whole footprint: a search head reaching out to an API, on demand, when someone runs a search.

Because the work happens on the search head, the app installs there only - never on indexers or forwarders.

What you can query

Five search commands cover the common kubectl verbs. Each is documented in full in the Command reference:

• | k8s - list or get resources of any kind (pods, deployments, nodes, custom resources), namespaced or cluster-scoped, with label and field selectors.
• | k8slogs - stream pod logs, with tail, since, and previous (crashed-container) options.
• | k8sevents - list Kubernetes events, filtered by type, reason, or the object they target.
• | k8sdescribe - fetch a single object together with the events that reference it, the way kubectl describe does.
• | k8syaml - reformat the JSON the other commands return into kubectl-style YAML.

Everything is read-only. Kubernetes Search queries your clusters; it never applies, scales, deletes, or otherwise mutates them.

Multiple clusters

Register as many clusters as your license allows, then target them with context=:

| k8s kind=nodes context=production
| k8s kind=nodes context=prod-*
| k8s kind=nodes context=*

A glob or * fans out to every matching cluster in parallel, and each row carries a cluster field so you can tell results apart and aggregate across them. See Clusters for registration and the comparison for why a single Splunk pane across many clusters is a distinct advantage.

Caching

Repeating a search, or fanning a dashboard panel across clusters, shouldn’t hammer your API servers. Kubernetes Search keeps a short-lived disk cache on the search head:

Override the freshness per search with cache=. Use cache=0 to bypass the cache and always hit the API, or a duration like cache=5m to accept results up to that old:

| k8s kind=pods namespace=payments cache=0
| k8s kind=pods namespace=payments cache=5m

Rows from | k8s, | k8sevents, and | k8sdescribe report _cache_hit and, on a hit, _cache_age_seconds, so you always know how fresh the data is (| k8slogs reads logs live and doesn’t cache their content). Secrets are never cached. You can disable the cache entirely from the Setup page. The Command reference documents the cache= option per command.

Access and credentials

Two things gate a search: the run_k8s_search capability (can this Splunk user run the commands at all) and the credential model for each cluster (whose Kubernetes permissions the search runs under). Kubernetes Search supports a shared cluster credential, per-user credentials, and Kubernetes user impersonation - each with different isolation guarantees. This is important to get right on sensitive clusters, so it has its own page: Access control.

What Kubernetes Search is not

• Not a historical store. You see current state. For dashboards over time, retention, and trend-based alerting, ingest with Monitoring Kubernetes and use Kubernetes Search alongside it. The comparison lays out when to reach for which. (Alerting on current state is supported - see Use cases.)
• Not an indexed data source. It writes nothing to an index, defines no source types, and is not a Common Information Model (CIM) data source. There is no index= to search and no field extractions to maintain - results exist only for the life of your search.
• Not a log tail. | k8slogs returns a snapshot of the log at query time. There is no live follow - re-run the search to see newer lines.
• Bounded by Kubernetes retention. Events typically live about an hour in the API server, and pod logs only as long as the node keeps them. Kubernetes Search can only return what the cluster still has.
• Read-only. It is a window into your clusters, not a control plane.