ngx_steadybit_sleep_module
is a third-party NGINX module that allows you to introduce artificial delays (sleep) into HTTP request processing. This is useful for testing, chaos engineering, and simulating network latency in development or staging environments.
- Add a configurable delay to HTTP requests using a custom directive
- Supports millisecond granularity
- Designed for use with NGINX and NGINX Ingress (Red Hat UBI)
- NGINX (built from source, or compatible with dynamic modules)
- Compatible with NGINX Ingress images based on Red Hat UBI (e.g.,
nginx/nginx-ingress:5.0.0-ubi
) - GCC, make, and standard build tools (for building the module)
make
# The built module will be in dist/ngx_steadybit_sleep_module.so
Two example Dockerfiles are provided to demonstrate how to compile and use this module:
Builds the module using the open-source NGINX base image. This is suitable for:
- Development and testing environments
- Open-source NGINX deployments
- Community-based NGINX Ingress Controller
docker build -f Dockerfile.community -t steadybit/nginx-sleep-module:community .
Builds the module using Red Hat Universal Base Image (UBI) with NGINX. This is suitable for:
- Enterprise environments
- Red Hat-based deployments
- OpenShift deployments
- NGINX Ingress Controller based on UBI images (e.g.,
nginx/nginx-ingress:5.0.0-ubi
)
IMPORTANT DISCLAIMER: This is a modified UBI image. It is not certified or supported by Red Hat, Inc. This modified image is distributed under the MIT License (see LICENSE file). The original Red Hat UBI End User License Agreement applies to the underlying UBI components (see UBI-EULA.pdf).
docker build -f Dockerfile.ubi -t steadybit/nginx-sleep-module:ubi .
Note: These Dockerfiles serve as examples showing how to compile and integrate the module into different NGINX base images. You can adapt them to your specific NGINX Ingress Controller image and requirements.
- Copy the built
.so
file to your NGINX modules directory (e.g.,/usr/lib/nginx/modules/
). - Load the module in your
nginx.conf
:load_module modules/ngx_steadybit_sleep_module.so;
- Use the directive in your server/location block:
location /test-sleep { sb_sleep_ms 500; # Sleep for 500 milliseconds proxy_pass http://backend; }
When using this module with NGINX Ingress Controller, additional configuration is required:
Snippets must be enabled on your NGINX Ingress Controller:
# Method 1: Controller arguments
--enable-snippets
# Method 2: ConfigMap option
kubectl patch configmap <ingress-configmap> -n <namespace> --type=merge -p '{"data":{"enable-snippets":"true"}}'
# Method 3: NGINX Ingress Operator
kubectl patch NginxIngress nginxingress-controller -n nginx-ingress --type=merge -p '{"spec":{"controller":{"enableSnippets":true}}}'
Load the module using the ConfigMap approach:
kubectl patch configmap nginxingress-controller-nginx-ingress \
-n nginx-ingress \
--type=merge \
-p '{
"data": {
"main-snippets": "load_module /usr/lib/nginx/modules/ngx_steadybit_sleep_module.so;"
}
}'
The module can then be used via configuration snippets in Ingress resources:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example-ingress
annotations:
nginx.ingress.kubernetes.io/configuration-snippet: |
sb_sleep_ms 500;
spec:
# ... ingress spec
load_module modules/ngx_steadybit_sleep_module.so;
http {
server {
listen 8080;
location /sleep {
sb_sleep_ms 1000;
return 200 'Slept for 1 second';
}
}
}
A test script is provided:
cd ngx_steadybit_sleep_module
bash test-sleep-module.sh
This will build NGINX with the module, start a test server, and run latency tests against the endpoints.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
IMPORTANT: This project creates modified UBI images that are not certified or supported by Red Hat, Inc.
This module depends on:
- NGINX core (licensed under the 2-clause BSD license)
- Red Hat Universal Base Image (UBI) (subject to the Red Hat UBI End User License Agreement)
Licensing Terms:
- This module and its modifications are distributed under the MIT License (see LICENSE)
- The underlying Red Hat UBI components remain subject to the Red Hat UBI End User License Agreement (see UBI-EULA.pdf)
- No Red Hat trademarks or logos are used in the modified images
Please refer to the respective license texts for details:
- NGINX License
- Red Hat UBI EULA (also available locally as UBI-EULA.pdf)