Understanding the Edge Processor startup script (OnPrem)

Onboard a new Edge Processor instance

First let’s examine the instance onboarding process to better understand the requirements for building compatible containers. For the most current, step-by-step instructions on adding a new Edge Processor, refer to Splunk Docs. In this overview, we'll focus on key details of this process.

Regardless of the method of scaling out, the process of provisioning a new instance is the same:

Open an Edge Processor in your browser and select Manage instances in the Actions dropdown menu. 

Then look at the script in the install/uninstall section of the Manage instances screen. This script is run on each new instance to install the Edge Processor binaries. Let’s break it down.

1. First it gets the most recent version of the splunk-edge bootstrapping binary:

   curl "https://<control_plane>:8089/servicesNS/-/splunk_pipeline_builders/dmx/packages/splunk-edge/v0.1.301-fb5e0c5e-20250404t180911/linux-amd64/splunk-edge.tar.gz" -O 

2. Then it checks to make sure the package matches a checksum:

   export SPLUNK_EDGE_PACKAGE_CHECKSUM=$(echo "$(sha512sum splunk-edge.tar.gz)" | cut -d " " -f 1) 
   if [[ "$SPLUNK_EDGE_PACKAGE_CHECKSUM" != 
   "4f3f0f07c9a8fe1b00f5804d0d16547ce034007411a26dccacdcafc8148fb09e" ]]; \ 
   then \ 
   echo "The installation package is invalid. The download did not complete as expected. Try downloading the package again."; \ 
   else \ 
   tar -xvzf splunk-edge.tar.gz 

3. Next it sets up some initial configuration files that tell the edge package details about the environment for which it’s being provisioned:

   echo "url: https://<control_plane>:8089/servicesNS/nobody/splunk_pipeline_builders/tenant/agent-management" > ./splunk-edge/etc/config.yaml
   echo "groupId: <edge_processor_guid>" >> ./splunk-edge/etc/config.yaml
   echo "env: production" >> ./splunk-edge/etc/config.yaml
   echo "eyJraWQiOiJzcGx1bOiJzdGF0aWMifQ.eyJpc3MiOiJhZG1pbiBmcm" > splunk-edge/var/token 

4. Finally, the Edge Processor binary runs:

   mkdir -p ./splunk-edge/var/log
   nohup ./splunk-edge/bin/splunk-edge run >> ./splunk-edge/var/log/install-splunk-edge.out 2>&1 </dev/null &
   fi  

It’s important to understand that the splunk-edge process is responsible for bootstrapping and overseeing a distinct Edge Processor runtime process. As the Edge Processor runtime is updated frequently and is managed independently from the bootstrapping, it can’t be packaged, installed, or managed in another way. This splunk-edge process has to run first on each Edge Processor node.

Now, let’s look at the key components of this script.

These are the installation components from step 3.

• echo "url: https://<control_plane>:8089/servicesNS/nobody/splunk_pipeline_builders/tenant/agent-management" > ./splunk-edge/etc/config.yaml
  The URL of the Splunk Edge Processor control plane configuration url. This is the same regardless of which Edge Processor instance is being provisioned.
• echo "groupId: <edge_processor_guid>" >> ./splunk-edge/etc/config.yaml
groupId is the unique identifier of the Edge Processor this node is going to be associated with. You can see this identifier very easily by opening up an Edge Processor in the UI.
  
• echo "env: production" >> ./splunk-edge/etc/config.yaml
Env is always production.
• "eyJhbGciOiJS………" > splunk-edge/var/tokenThe token listed in the file is a current valid Splunk authentication token. As we learned in the previous article, this token has a lifecycle that can’t be customized and has no programmatic retrieval.  

Let's also look at this component of the binary from step 4.

nohup ./splunk-edge/bin/splunk-edge run >>
./splunk-edge/var/log/install-splunk-edge.out

The splunk-edge binary is run in a silent and persistent way. This particular invocation of the binary isn’t service or container friendly, but at this point the key is to understand that after the variables and configurations are in place, running splunk-edge runs the rest of the process.

Offboard an existing Edge Processor node

Now that we understand the process involved in starting a new node, let’s take a quick look at removing a node by reviewing the commands in the Uninstall screen of the Manage instances page from before.

SPLUNK_EDGE_PID=$(pidof splunk-edge)
SPLUNK_EDGE_DIRECTORY=$(pwdx $SPLUNK_EDGE_PID | awk '{print $2}')
cd $SPLUNK_EDGE_DIRECTORY
kill $SPLUNK_EDGE_PID && ./splunk-edge/bin/splunk-edge offboard && rm -rf ./splunk-edge

This set of commands is meant to end the splunk-edge process on a node and issue the offboard command.

This offboard command is critical to maintaining a known-good list of instances in the UI. If you decommission instances without offboarding them, your UI will be left with orphaned instances as seen here:

Next steps

Now that we have a good understanding of how new Edge Processor instances are installed and uninstalled, we can move on to building a container that uses these scripts.