Set up an Edge Processor in a Docker container

Perform the following steps to set up and run Edge Processor within a Docker container.

Prerequisites

  • Access to a functioning tenant in the Splunk Cloud Platform environment.

  • Docker installed on the host machines where the containers will be spun up.

Architecture overview

Setup and install

Perform the following steps in order to set up and install an Edge Processor on a Docker container.

Create a shared service principal

The following command provisions a single, shared service principal intended for consumption by multiple Edge Processor instances. This is typically performed once during initial setup, persisted in the principal.yaml file, and used to interact with other Splunk Cloud Platform services.
CODE 
docker run --rm \ 
	-e TENANT=<tenant-id> \ 
	-e TOKEN=<access-token> \ 
	splunk/edge-processor:<image-tag> \ 
	eptools setup > principal.yaml
Note: The value for TOKEN is located in the install script provided in your tenant's web UI. To locate it, navigate to the Edge Processors page, select or create a processor. Select Actions, and then Install/Uninstall from the dropdown menu in the top right-hand corner. Then set the Instance type to Docker. The token is visible in the resulting script.

Running a containerized instance

After provisioning a shared service principal, perform the following tasks to set up a containerized Edge Processor instance.

  1. Compile a list of ingress ports your instance will use to receive ingested data. To do so, navigate to the Edge Processors page in your tenant's web UI, and select the Shared Settings button in the top right-hand corner.

  2. Use Docker's -p flag to define your ports for all supported ingestion types. Map each port to the corresponding port on the host machine.

  3. Mount the principal.yaml file to the /opt/splunk-edge/etc/principal.yaml path within the container, publishing the ports gathered previously, and running the image:
    CODE 
    docker run -d \
  -e TENANT=<tenant-id> \
  -e GROUP_ID=<edge-processor-id> \
  -e TOKEN=<access-token> \
  -e MACHINE_HOSTNAME=$(hostname) \
  -v $(pwd)/principal.yaml:/opt/splunk-edge/etc/principal.yaml \
  -p <port-1>:<port-1> ··· -p <port-n>:<port-n> \
  splunk/edge-processor:<image-tag>
Note: GROUP_ID is used to associate new instances with a specific Edge Processor. This value can be found by selecting one of the processors listed on the Edge Processors page of your tenant's web UI, then copying its ID field (for example, 431e1ead-fd5b-4af8-ac89-ccae2ae81eda). This value also appears at the end of the page's URL.

Running multiple containerized instances

Because the generated service principal is designed to be shared by multiple Edge Processor instances, spinning up subsequent containers is as simple as rerunning the previous docker run command.

Modifying GROUP_ID between runs will register instances with different Edge Processors within your tenant all under the same service principal. The best practice is to restrict service principals to one per processor, in order to avoid unnecessary confusion and potential rate limiting. A single service principal can be used across different host machines if the same principal.yaml file is mounted in each container, but this is not a best practice.

Avoiding port conflicts on a single host

One complication of spinning up multiple instances on a single host is port availability. When running multiple containers on the same host machine, port conflicts become a bottleneck since each published container port must bind to a unique port on the host.

To prevent conflicts, publish the container port without pinning it to a specific host port (i.e., -p <container_port> instead of -p <host_port>:<container_port>). When the host port is omitted, Docker selects an available, ephemeral port at runtime and publishes the container port accordingly.

The trade-off of this approach is discoverability. Because host ports are assigned dynamically, clients don't know where to route traffic ahead of time. As a result, you must query the running containers to compile a per-host inventory of published ports, then distribute traffic among them using a load balancer or client-side routing. To list all running containers on the current host and their associated port mappings, run the following command:
JSON 
docker inspect $(docker ps -q) -f '
  {{- $id := slice .Id 0 12 -}}
  {{- range $cport, $bindings := .NetworkSettings.Ports -}}
    {{- if $bindings -}}
      {{- range $b := $bindings -}}
  {{ printf "%s: %s -> %s:%s\n" $id $cport $b.HostIp $b.HostPort }}
      {{- end -}}
    {{- end -}}
  {{- end -}}
'

Using statically assigned host ports

Instead of publishing ports dynamically, you can alternatively assign each container to a predefined host port within a reserved range. For example, if each container receives HEC events on port 8088, you can map instances to sequential ports 9001, 9002, 9003, etc. on the host:
JSON 
docker run -p 9001:8088 {···}
docker run -p 9002:8088 {···}
docker run -p 9003:8088 {···}
By reserving a dedicated port range, runtime ambiguity is reduced, and traffic routing is simplified. Upstream data sources can then distribute traffic across the known port range using client-side load balancing and a lightweight, external load balancer. This approach improves predictability and removes the need to query container metadata at runtime. However, it also requires manual coordination to ensure ports are allocated consistently and are not reused unintentionally.

Uninstall and cleanup

To uninstall a containerized Edge Processor instance, stop and (optionally) remove the container using the following command:
CODE 
docker stop <container-id> && docker rm <container-id>
After running the command, you should see the instance disappear from the UI within a few seconds. Once all instances associated with a specific service principal is uninstalled, the best practice (but not required) is to deprovision the service principal by running the following command:
CODE 
docker run --rm \
  -e TENANT=<tenant-id> \
  -e TOKEN=<access-token> \
  -v $(pwd)/principal.yaml:/opt/splunk-edge/etc/principal.yaml \
  splunk/edge-processor:<image-tag> \
  eptools cleanup
Note: The value for TOKEN is not the same as before. Instead, it is located in the Settings page of your tenant's Cloud Console UI. More specifically, navigate to https://console.scs.splunk.com/{tenant-id}/settings and copy the provided Access Token

Update the Docker image

The best practice is to use the latest stable container image when possible. This ensures access to the latest bug fixes and security patches for vulnerabilities in the base image's OS, installed dependencies, and our software. You can either use the latest tag or hand-pick a version from https://hub.docker.com/r/splunk/edge-processor/tags, then run the following command:
CODE 
docker pull splunk/edge-processor:<image-tag>
It should be noted that existing containers are not automatically updated when a new image is pulled. Instead, they must be stopped, removed, and recreated using the pulled image.

Additional considerations

  • Port changes made using the Edge Processor Shared settings page in the UI are not automatically propagated to Docker. When modifying these values, you'll need to manually stop all running containers still bound to the previous ports, recreate them with the new port mappings, then update all affected ingestion flows to target these new ports.

  • Containerizing Edge Processor does not provide any additional control over the deployed binary. The container image version is independent of the Edge Processor binary version, which will continue to follow the standard, non-container lifecycle managed by the Edge Processor team.

  • For systemd-managed deployments, use Docker's --restart=always policy when spinning up an Edge Processor container to ensure automatic recovery after failures or host restarts.