shell-operator

Shell-operator is an integration layer for Kubernetes that allows you to run event-driven scripts (bash, python, kubectl, etc.) in response to cluster events. It treats scripts as 'hooks' that are triggered by Kubernetes object events. It is designed to be an easier alternative to operator-sdk for users who want to use familiar shell tools instead of writing complex Go code.

Key capabilities include:

• Event Triggers: Hooks can be triggered by add, update, or delete events.
• Filtering: Monitor specific objects using selectors and property filters.
• Configuration: Hook bindings are defined via JSON or YAML documents emitted to the script's stdout.
• Webhooks: Supports validating webhook machinery and conversion webhook machinery for Kubernetes resources.

The shell-operator configuration system uses a three-layer priority model to set runtime parameters. The highest-priority source wins:

1. CLI flag (explicitly passed)
2. Environment variable
3. Hardcoded default

This allows for flexible deployment, such as using environment variables in containerized environments while allowing manual overrides via CLI flags during debugging or local development.

A hook is an executable file (script or compiled program) that Shell-operator runs in response to specific events. Hooks receive input data and return results via files. The paths to these files are provided to the hook through environment variables.

Key characteristics:

• Can be written in any language (e.g., Bash, Python, Go).
• Executables are discovered via a recursive search in the configured hooks directory.
• The lib subdirectory within the hooks directory is ignored during discovery.

You can use the includeSnapshotsFrom parameter to pass up-to-date lists of objects from one binding to another. This is useful when a hook needs to react to one object (e.g., a Pod) but also requires data from another (e.g., a ConfigMap).

To optimize memory, you can set keepFullObjectsInMemory: false. This will cause the object field to be omitted in snapshots, objects (Synchronization), and object (Event) fields, leaving only the filterResult if a jqFilter is defined.

kubernetes:
- name: pods
  kinds: Pod   
  keepFullObjectsInMemory: false

An HTTP server used for a conversion webhook requires a certificate issued by a CA. You can automate this process using the provided gen-certs.sh script.

Prerequisite: The gen-certs.sh script requires the cfssl utility to be installed on your system.

./gen-certs.sh

To remove the example, delete the Helm release, the namespace, and the MutatingWebhookConfiguration resource.

helm delete --namespace=example-206 example-206
kubectl delete ns example-206
kubectl delete mutatingwebhookconfiguration/example-206

Hooks can export Prometheus metrics by writing JSON operations to the $METRICS_PATH file. Shell-operator automatically adds a hook label containing the relative path to the hook script.

Supported metric types and their JSON formats:

• Counter: Use "action":"add" to increase the value.
• Gauge: Use "action":"set" to set a specific value.
• Histogram: Use "action":"observe" to record a duration with specific buckets.

Note: There are shortcut fields "add" and "set" that can be used instead of specifying both action and value, but these may be deprecated in future releases.

To test the execution rate limiting functionality, you can build the example as a Docker image and install it using Helm. This example demonstrates a hook subscribed to crontab resources that is configured to execute no more than once every 5 seconds.

docker build -t localhost:5000/shell-operator:example-220 .
docker push localhost:5000/shell-operator:example-220
helm upgrade --install \
    --namespace example-220 \
    --create-namespace \
    example-220 .

To remove all resources created by this example, delete the Helm release, the namespace, and the Custom Resource Definition (CRD).

helm delete --namespace=example-210 example-210
kubectl delete ns example-210
kubectl delete crd crontabs.stable.example.com

To remove the resources created by the monitor-namespaces example, delete the example namespace and remove the custom Docker image.

$ kubectl delete ns/example-monitor-namespaces
$ docker rmi registry.mycompany.com/shell-operator:monitor-namespaces

To remove the example and all associated resources, including the namespace and the custom resource definition (CRD), run the following commands:

helm delete --namespace=example-220 example-220
kubectl delete ns example-220
kubectl delete crd crontabs.stable.example.com

To remove all resources created by the monitor-pods example, execute the following commands to delete the cluster roles, bindings, namespace, and the local Docker image.

kubectl delete clusterrolebinding/monitor-pods
kubectl delete clusterrole/monitor-pods
kubectl delete ns/example-monitor-pods
docker rmi registry.mycompany.com/shell-operator:monitor-pods