specification: API Commons Rate Limits
specificationVersion: '0.1'
schema: https://raw.githubusercontent.com/api-evangelist/interface-research/main/schema/api-commons.yml#/$defs/RateLimits
provider: Contour
providerId: contour
created: '2026-05-04'
# Provenance stamped 2026-08-11: this artifact was written by the API Evangelist
# bulk sweep dated 2026-05-04, not harvested from the provider. See roadmap#35.
method: generated
modified: '2026-05-05'
reconciled: false
tags:
  - Envoy
  - Ingress Controller
  - Kubernetes
  - Networking
  - Open Source
  - Proxy
  - Rate Limiting
description: Contour itself is a Kubernetes ingress controller; its primary "API surface" is a set
  of Kubernetes Custom Resource Definitions (HTTPProxy, ContourConfiguration, ExtensionService) consumed
  in-cluster via the kube-apiserver. There is no Contour-hosted public API that imposes its own per-second
  request limits. Contour does, however, provide rate-limiting capabilities for the ingress traffic
  it manages - via local rate limiting (Envoy token-bucket) and global rate limiting (delegated to
  an external rate-limit service over Envoy's gRPC ratelimit protocol). Those are operator-configured
  limits applied to incoming HTTP traffic, not limits on the Contour API itself.
sources:
  - https://projectcontour.io/docs/main/config/rate-limiting/
  - https://projectcontour.io/docs/main/config/api/
limits:
  - name: Kubernetes API server limits
    scope: cluster
    metric: varies
    limit: governed by kube-apiserver
    notes: Contour CRDs are read and written via the cluster's kube-apiserver, so the effective limits
      are whatever the operator's APIServer configures (e.g. priority and fairness, max-mutating-requests-inflight).
  - name: Local (per-vhost) rate limiting
    scope: vhost
    metric: requests_per_second
    limit: operator-configured
    notes: Configured on HTTPProxy via spec.virtualhost.rateLimitPolicy.local; uses Envoy's token-bucket
      filter. Numeric values are set per deployment.
  - name: Global rate limiting
    scope: descriptor
    metric: requests_per_second
    limit: operator-configured
    notes: Delegated to an external rate-limit service (e.g. Envoy ratelimit) configured via ExtensionService
      and HTTPProxy rate-limit descriptors.
policies:
  - name: Operator-configured, not hosted
    description: Contour does not enforce per-second limits on its own control-plane APIs. Rate limits
      are configured by the operator on the data path (Envoy) and apply to ingress HTTP traffic, not
      to the Contour CRD API.
  - name: Local vs Global
    description: Local rate limiting runs in each Envoy proxy with no external dependency; global rate
      limiting consults a shared rate-limit service so multiple Envoys can share a budget.
  - name: Backoff and 429
    description: When an operator-configured limit is hit, Envoy returns HTTP 429; clients should honor
      the Retry-After header if the rate-limit service emits one.
notes: Contour is an open-source ingress controller, not a hosted API platform. There are no upstream
  per-second request limits on a public Contour API. Reconciled is false because there is no provider-published
  rate-limit document to reconcile against; this artifact captures Contour's own rate-limiting features
  rather than rate limits applied to Contour's APIs.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com