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	500	General requests per second
NORA_RATE_LIMIT_GENERAL_BURST	1000	Maximum burst for general requests

Configuration Examples

Docker Run

docker run -d \
  --name nora \
  -p 5000:5000 \
  -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

YAML Configuration

rate_limits:
  upload:
    rps: 2000
    burst: 5000
  general:
    rps: 1000
    burst: 2000

Command Line

nora serve \
  --rate-limit-upload-rps 2000 \
  --rate-limit-upload-burst 5000 \
  --rate-limit-general-rps 1000 \
  --rate-limit-general-burst 2000

---

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=500
NORA_RATE_LIMIT_GENERAL_BURST=1000

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_rate_limit_hits_total{type="upload"} - Upload rate limit violations
• nora_rate_limit_hits_total{type="general"} - General rate limit violations
• nora_requests_total - Total requests processed

Prometheus Query

# Rate limit hit rate over 5 minutes
rate(nora_rate_limit_hits_total[5m])

# Percentage of requests rate-limited
(rate(nora_rate_limit_hits_total[5m]) / rate(nora_requests_total[5m])) * 100

Alert Rules

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

      - alert: NoraRateLimitCritical
        expr: (rate(nora_rate_limit_hits_total[5m]) / rate(nora_requests_total[5m])) > 0.1
        for: 10m
        labels:
          severity: critical
        annotations:
          summary: "Over 10% of requests are being rate-limited"
          description: "Consider increasing rate limits"

---

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
• Monitoring Guide
• Performance Tuning