Splunk Edge Processor Setup

Prerequisites

Tool or access	Purpose	Verify
Bash and Python 3	Run bundled setup and validation helpers	bash --version && python3 --version
Required product/platform access	Inspect or configure the selected target	Complete the documented preflight
Credential files for live modes	Keep secrets out of chat	Verify paths only

Workflow Overview

┌───────────┐   ┌───────────────┐   ┌───────────────┐   ┌─────────────────┐
│ Preflight │ → │ Render/review │ → │ Apply/handoff │ → │ Validate evidence │
└───────────┘   └───────────────┘   └───────────────┘   └─────────────────┘

When to Activate

• Installing Edge Processor, managing EP pipelines, routing forwarders, or handling Cisco Data Fabric / telemetry pipeline management requests that need Splunk Platform edge routing and transformation.
• Preview and review the splunk edge processor setup workflow before any live apply phase.
• Diagnose failed prerequisites, generated assets, configuration, or validation evidence.

Scope

Follow the documented read-only or render-first path whenever it is available. This skill does not imply permission to mutate live systems. Require explicit apply flags, protected credentials, and operator review for state changes.

Examples

Inspect the supported setup modes before selecting one:

bash skills/splunk-edge-processor-setup/scripts/setup.sh --help

Expected output: usage, supported modes, and required arguments are displayed without changing the target environment.

Inspect validation modes before running completion checks:

bash skills/splunk-edge-processor-setup/scripts/validate.sh --help

Expected output: offline, live, and completion options are displayed when the skill supports them; help exits without mutation.

Troubleshooting

Issue	Cause	Resolution
Preflight fails	A required tool or access path is missing	Resolve it before rendering or applying
Rendered assets are incomplete	Required non-secret inputs are absent	Complete intake and render again
Apply is blocked	Review, credentials, or explicit acceptance is missing	Use the documented handoff
Validation is incomplete	Live evidence is unavailable	Record the gap and keep completion open

This skill covers the full Edge Processor surface: control-plane object management plus Linux instance install plus pipeline / destination / source-type lifecycle, all from one render-first workflow.

For newer Cisco Data Fabric wording, this is the Splunk Platform edge-routing and data-shaping route. Keep native Observability Metrics Pipeline Management requests in splunk-observability-deep-native-workflows unless the user needs log/event pipelines, forwarder routing, or edge transformation.

Treat AI-powered data management recommendations as UI/operator handoffs until Splunk publishes a stable public API for accepting generated schema, field extraction, or pipeline changes. Review generated SPL2 through splunk-spl2-pipeline-kit before promoting it into Edge Processor pipelines.

Architecture First

• Two control planes: Splunk Cloud Platform tenant (<tenant>.scs.splunk.com) AND Splunk Enterprise 10.0+ data management node. Choose with --ep-control-plane cloud|enterprise.
• Control-plane API base is operator-supplied: Splunk has not published a stable public REST API base path for EP control-plane objects (source types, destinations, pipelines). The skill renders the JSON payloads as a source of truth and provides an apply-objects.sh that applies them via REST when EP_API_BASE is set. Without that operator-supplied transport it prints the manual UI checklist and exits nonzero so --phase apply cannot report a mutation that never happened. Offline validation remains available.
• Default destination is critical — without one, unprocessed data is silently dropped. The renderer refuses to render a plan with destinations but no default destination, and validate.sh re-checks at runtime.
• EP instance install command is operator-supplied — Splunk's Manage instances UI generates a one-shot install command containing a join token. Stage it via write_secret_file.sh and reference it through EP_INSTALL_CMD_FILE; the rendered host scripts execute it under the service user without ever placing the token in argv.
• Multi-instance — multiple EP instances behind a DNS record let forwarders route via a single hostname.
• Shared SPL2 kit — use splunk-spl2-pipeline-kit for complex SPL2 authoring, SPL-to-SPL2 review, and PCRE2 migration lint before previewing pipelines in the Edge Processor UI.
• FIPS mode — pass --ep-fips-mode enabled only for non-containerized EP instances. FIPS mode is not supported for Docker/containerized EP.

Agent Behavior — Credentials

Never paste EP API tokens, install command bodies, or HEC tokens into chat.

bash skills/shared/scripts/write_secret_file.sh /tmp/ep_api_token
bash skills/shared/scripts/write_secret_file.sh /tmp/ep_install_cmd.sh
bash skills/shared/scripts/write_secret_file.sh /tmp/ep_hec_token

The rendered scripts read tokens via --*-token-file flags and never embed the value in rendered output.

Quick Start

Render a single-instance Edge Processor in a Splunk Cloud tenant with one S2S destination and one filtering pipeline:

bash skills/splunk-edge-processor-setup/scripts/setup.sh \
  --phase render \
  --ep-control-plane cloud \
  --ep-tenant-url https://example.scs.splunk.com \
  --ep-name prod-ep \
  --ep-instances "ep01.example.com=systemd" \
  --ep-target-daily-gb 50 \
  --ep-source-types "syslog_router" \
  --ep-destinations "primary=type=s2s;host=idx-cluster.example.com;port=9997;index_routing=specify_for_no_index:summary" \
  --ep-default-destination primary \
  --ep-pipelines "filter_dev=partition=Keep;sourcetype=app:dev;spl2_file=pipelines/filter_dev.spl2;destination=primary"

Apply to the control plane (requires EP_API_BASE; without it the command emits a manual UI checklist and exits nonzero):

EP_API_BASE=https://<tenant-api-base> EP_API_TOKEN_FILE=/tmp/ep_api_token \
bash skills/splunk-edge-processor-setup/scripts/setup.sh --phase apply --ep-tenant-url https://example.scs.splunk.com

Install an instance on Linux (systemd):

EP_INSTALL_CMD_FILE=/tmp/ep_install_cmd.sh \
bash skills/splunk-edge-processor-setup/scripts/setup.sh --phase install-instance \
  --ep-tenant-url https://example.scs.splunk.com --ep-instances "ep01.example.com=systemd"

Validate rendered assets (structural check only — fast, no network):

bash skills/splunk-edge-processor-setup/scripts/validate.sh

Validate live against the control plane REST (requires --ep-api-base, --ep-api-token-file, and --ep-name; --ep-tenant-url is used for handoff messages):

bash skills/splunk-edge-processor-setup/scripts/validate.sh \
  --live \
  --ep-tenant-url https://example.scs.splunk.com \
  --ep-name prod-ep \
  --ep-api-base https://api.us-east-1.splunkcloud.com/<tenant>/edge-processor/v1 \
  --ep-api-token-file /tmp/ep_api_token

What It Renders

Under splunk-edge-processor-rendered/:

• control-plane/edge-processors/<name>.json — EP control-plane object (TLS settings).
• control-plane/source-types/<name>.json.
• control-plane/destinations/<name>.json.
• control-plane/pipelines/<name>.spl2 (SPL2 source-of-truth) and pipelines/<name>.json (API payload).
• control-plane/apply-objects.sh — orchestrates POST/PUT/DELETE in dependency order when EP_API_BASE is set; otherwise prints a manual UI checklist and fails closed without mutation.
• host/<host>/install-with-systemd.sh — cgroup + service user, splunk-edge service unit; consumes the operator-supplied install command via EP_INSTALL_CMD_FILE.
• host/<host>/install-without-systemd.sh — direct nohup install.
• host/<host>/install-docker.sh — Docker compose skeleton (image + env are operator-supplied from the tenant install command).
• host/<host>/uninstall.sh.
• forwarder-templates/outputs.conf — DNS-driven forwarder outputs.
• pipelines/templates/*.spl2 — shared SPL2 starters from splunk-spl2-pipeline-kit for the edgeProcessor profile.
• validate.sh — control-plane health and default-destination guard.
• handoffs/acs-allowlist.json — ACS allowlist plan stub for s2s + hec features.

Out of Scope

• Live automated SPL→SPL2 conversion (use Splunk's in-product tool; this repo renders compatibility lint and review guidance only).
• Automatic acceptance of AI-powered data management recommendations.
• Multi-tenant org management on Splunk Cloud.
• Destinations not yet documented in Splunk's public EP destination catalog (Kafka, Azure Event Hubs).
• RBAC management on the EP control plane.
• Automatic resolution of the EP control-plane REST API base — the operator supplies EP_API_BASE when applying via REST.
• Containerized FIPS mode.

References

• reference.md for full source-type / destination / pipeline syntax, the systemd unit template, and the ACS allowlist hand-off contract.
• template.example for the non-secret intake worksheet.