Rate Limits Configuration

Overview

NORA implements rate limiting to protect the registry from excessive load. This guide covers default values, tuning guidelines, and monitoring.

Environment Variables

Variable	Default	Description
NORA_RATE_LIMIT_UPLOAD_RPS	200	Upload requests per second
NORA_RATE_LIMIT_UPLOAD_BURST	500	Maximum burst for uploads
NORA_RATE_LIMIT_GENERAL_RPS	100	General requests per second
NORA_RATE_LIMIT_GENERAL_BURST	200	Maximum burst for general requests
NORA_RATE_LIMIT_AUTH_RPS	10	Auth requests per second
NORA_RATE_LIMIT_AUTH_BURST	20	Maximum burst for auth requests
NORA_RATE_LIMIT_ENABLED	true	Enable/disable rate limiting

Configuration Examples

Docker Run

docker run -d \
  --name nora \
  -p 4000:4000 \
  -v /data/nora:/data \
  -e NORA_RATE_LIMIT_UPLOAD_RPS=2000 \
  -e NORA_RATE_LIMIT_UPLOAD_BURST=5000 \
  -e NORA_RATE_LIMIT_GENERAL_RPS=1000 \
  -e NORA_RATE_LIMIT_GENERAL_BURST=2000 \
  ghcr.io/getnora-io/nora:latest serve

Docker Compose

services:
  nora:
    image: ghcr.io/getnora-io/nora:latest
    environment:
      NORA_RATE_LIMIT_UPLOAD_RPS: 2000
      NORA_RATE_LIMIT_UPLOAD_BURST: 5000
      NORA_RATE_LIMIT_GENERAL_RPS: 1000
      NORA_RATE_LIMIT_GENERAL_BURST: 2000

config.toml

[rate_limit]
enabled = true

---

Tuning Guidelines

Small Team (< 10 developers)

Default values are sufficient:

NORA_RATE_LIMIT_UPLOAD_RPS=200
NORA_RATE_LIMIT_UPLOAD_BURST=500
NORA_RATE_LIMIT_GENERAL_RPS=100
NORA_RATE_LIMIT_GENERAL_BURST=200

Use case: Low-frequency builds, manual pushes, small CI/CD pipeline

---

Medium Team (10-50 developers)

Moderate increase recommended:

NORA_RATE_LIMIT_UPLOAD_RPS=1000
NORA_RATE_LIMIT_UPLOAD_BURST=2000
NORA_RATE_LIMIT_GENERAL_RPS=750
NORA_RATE_LIMIT_GENERAL_BURST=1500

Use case: Regular CI/CD, multiple parallel builds, active development

---

Large Team (50+ developers, Heavy CI/CD)

Significant increase for high throughput:

NORA_RATE_LIMIT_UPLOAD_RPS=2000
NORA_RATE_LIMIT_UPLOAD_BURST=5000
NORA_RATE_LIMIT_GENERAL_RPS=1000
NORA_RATE_LIMIT_GENERAL_BURST=2000

Use case: Continuous deployment, matrix builds, high-frequency pushes

---

Enterprise / Multi-tenant

Custom tuning based on load:

NORA_RATE_LIMIT_UPLOAD_RPS=5000
NORA_RATE_LIMIT_UPLOAD_BURST=10000
NORA_RATE_LIMIT_GENERAL_RPS=2000
NORA_RATE_LIMIT_GENERAL_BURST=5000

Use case: Multiple teams, 24/7 CI/CD, global deployments

---

Understanding Rate Limit Parameters

RPS (Requests Per Second)

• Definition: Average sustained rate of requests allowed
• Example: RPS=200 means 200 requests per second on average
• Effect: Requests exceeding this rate will be rate-limited

Burst

• Definition: Maximum spike of requests allowed temporarily
• Example: BURST=500 allows up to 500 requests in a short burst
• Effect: Handles traffic spikes without immediate rate limiting

Upload vs General

• Upload limits: Apply to image push operations (PUT, POST to /v2/)
• General limits: Apply to all other operations (pulls, catalog, tags)

---

Monitoring Rate Limits

Metrics Endpoint

Check /metrics for rate limit statistics:

curl http://localhost:4000/metrics | grep rate_limit

Key metrics:

• nora_http_requests_total{registry, method, status} — Total HTTP requests by registry, method, and status code

Prometheus Query

# Request rate over 5 minutes
rate(nora_http_requests_total[5m])

# 429 errors (rate-limited requests)
rate(nora_http_requests_total{status="429"}[5m])

Alert Rules

groups:
  - name: nora_rate_limits
    rules:
      - alert: NoraHighRateLimitHits
        expr: rate(nora_http_requests_total{status="429"}[5m]) > 10
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "NORA experiencing high rate limit violations"
          description: "{{ $value }} rate-limited requests per second"

---

Troubleshooting

Symptom: “429 Too Many Requests” errors

Cause: Rate limits exceeded

Solution:

1. Check current rate limit configuration
2. Monitor /metrics to identify which limit is hit (upload vs general)
3. Increase appropriate limits based on your workload
4. Restart NORA to apply new limits

Symptom: Slow image pushes during CI/CD

Cause: Upload rate limits too restrictive for parallel builds

Solution:

# Increase upload limits
NORA_RATE_LIMIT_UPLOAD_RPS=2000
NORA_RATE_LIMIT_UPLOAD_BURST=5000

Symptom: API calls timing out

Cause: General rate limits blocking metadata requests

Solution:

# Increase general limits
NORA_RATE_LIMIT_GENERAL_RPS=1000
NORA_RATE_LIMIT_GENERAL_BURST=2000

---

Best Practices

1. Start Conservative - Begin with default limits and increase based on metrics
2. Monitor Continuously - Set up Prometheus alerts for rate limit hits
3. Plan for Spikes - Set BURST values higher than RPS to handle traffic spikes
4. Separate Upload/General - Tune independently based on usage patterns
5. Document Changes - Keep track of limit adjustments and reasons
6. Load Testing - Test new limits in staging before production

---

Performance Impact

Rate limiting in NORA is very efficient:

• Overhead: < 1ms per request
• Memory: Negligible (token bucket algorithm)
• CPU: Minimal impact even at high RPS

Increasing limits has virtually no performance penalty on NORA itself. Limits exist purely to protect the server from excessive client load.

---

See Also

• Configuration Reference
• Production Guide
• Kubernetes Deployment