Shell-operator is a tool for running event-driven scripts in a Kubernetes cluster.

This operator is not an operator for a particular software product as prometheus-operator or kafka-operator. Shell-operator provides an integration layer between Kubernetes cluster events and shell scripts by treating scripts as hooks triggered by events. Think of it as an operator-sdk but for scripts.

Shell-operator provides:

  • Ease the management of a Kubernetes cluster: use the tools that Ops are familiar with. It can be bash, python, kubectl, etc.
  • Kubernetes object events: hook can be triggered by add, update or delete events. Learn more about hooks.
  • Object selector and properties filter: Shell-operator can monitor only particular objects and detect changes in their properties.
  • Simple configuration: hook binding definition is a JSON structure on stdout.


You need to have a Kubernetes cluster, and the kubectl must be configured to communicate with your cluster.

Steps to setup Shell-operator in your cluster are:

  • build an image with your hooks (scripts)
  • create necessary RBAC objects (for onKubernetesEvent binding)
  • run Pod with a built image

Build an image with your hooks

A hook is a script that, when executed with --config option, returns configuration in JSON. Learn more about hooks.

Let's create a small operator that will watch for all Pods in all Namespaces and simply log a name of a new Pod.

"onKubernetesEvent" binding is used to tell shell-operator about what objects we want to watch. Create the file with the following content:

#!/usr/bin/env bash

if [[ $1 == "--config" ]] ; then
  cat <<EOF
  {"onKubernetesEvent": [
  podName=$(jq -r .[0].resourceName $BINDING_CONTEXT_PATH)
  echo "Pod '${podName}' added"

You can use a prebuilt image flant/shell-operator:latest with bash, kubectl, jq and shell-operator binaries to build you own image. You just need to ADD your hook into /hooks directory in the Dockerfile.

Create the following Dockerfile in the directory where you created the file:

FROM flant/shell-operator:latest
ADD /hooks

Build image and push it to the Docker registry accessible by Kubernetes cluster:

$ docker build -t "my.registry.url/shell-operator:simple-hook" .
$ docker push my.registry.url/shell-operator:simple-hook

Install shell-operator in a cluster

We need to watch for Pods in all Namespaces. That means that we need specific RBAC definitions for shell-operator. For testing purposes we can allow all read actions with clusterrole/view:

$ kubectl create namespace shell-operator
$ kubectl create serviceaccount shell-operator \
  --namespace shell-operator
$ kubectl create clusterrolebinding shell-operator-view \
  --clusterrole=view \

Shell-operator can be deployed as a Pod. Put this manifest into the shell-operator.yaml file:

apiVersion: v1
kind: Pod
  name: shell-operator
  - name: shell-operator
    image: my.registry.url/shell-operator:simple-hook
  serviceAccountName: shell-operator-acc

Start shell-operator by applying a shell-operator.yml file:

kubectl apply -f shell-operator.yml

Run kubectl logs -f po/shell-operator and see that the hook will print new pod names:

... deploy/kubernetes-dashboard replicas increased by 2 ...
INFO     : QUEUE add [email protected]_EVENTS
INFO     : QUEUE add [email protected]_EVENTS
INFO     : TASK_RUN [email protected]_EVENTS
INFO     : Running hook '' binding 'KUBE_EVENTS' ...
Pod 'kubernetes-dashboard-769df5545f-4wnb4' added
INFO     : TASK_RUN [email protected]_EVENTS
INFO     : Running hook '' binding 'KUBE_EVENTS' ...
Pod 'kubernetes-dashboard-769df5545f-99xsb' added

This example is also available in /examples: monitor-pods.

Hook binding types


This binding has only one parameter: order of execution. Hooks are loaded at start and then hooks with onStartup binding are executed in order defined by parameter.

Example hook --config:



This binding is for periodical running of hooks. Schedule can be defined with granularity of seconds.

Example hook --config with 2 schedules:

  "schedule": [
   {"name":"every 10 min",
    "schedule":"*/10 * * * * *",
   {"name":"Every Monday at 8:05",
    "schedule":"* 5 8 * * 1"


This binding defines a subset of Kubernetes objects that Shell-operator will monitor and a jq filter for their properties.

Example of hook --config:

  "onKubernetesEvent": [
  {"name":"Execute on changes of namespace labels",
   "kind": "namespace",