Learn Multigress - Multi-tenant Routing & Namespace Isolation

#Introduction

A platform usually serves many teams, each with its own domains and applications. Episode 10 covers multi-tenant routing and namespace isolation: how a single gateway can serve many namespaces, how to constrain the gateway's scope, and patterns for managing shared gateways safely and cleanly.

The key concept in this episode is ReferenceGrant. Without this explicit permission, cross-namespace routing won't work — it's the built-in access control of the Gateway API that limits each team's reach.

#Domain-Based Routing Across Namespaces

#One Gateway, Many Namespaces

The most common pattern: the gateway belongs to the platform team in the multigress-system namespace, while each tenant's applications live in their own namespaces. Routing stays one HTTPRoute per tenant:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: tenant-a-route
  namespace: team-a
spec:
  parentRefs:
    - name: main-gateway
      namespace: multigress-system
  hostnames:
    - "a.example.com"
  rules:
    - backendRefs:
        - name: app-a
          port: 8080

The route in the team-a namespace points to a Gateway in another namespace. To be accepted, tenant A must provide a ReferenceGrant in its own namespace:

apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
  name: allow-gateway
  namespace: team-a
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: team-a
  to:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: main-gateway

Notice the direction of permission: the ReferenceGrant is created in the namespace that hosts the route, and declares that the route may point to a specific Gateway. This makes cross-namespace access an explicit grant, not just a convention.

#Adding a New Tenant

Adding the next tenant is just duplicating the pattern above with a different namespace, domain, and service:

kubectl get httproute -A
kubectl get referencegrant -A

The kubectl get httproute -A command shows all cross-namespace routes. It's also a quick way to detect routes missing a ReferenceGrant — their status becomes RefNotPermitted.

#Gateway Scoping and Namespace Isolation Patterns

#allowedRoutes on the Gateway

Platforms want to limit which namespaces may bind to their gateway. This is configured on the Gateway via allowedRoutes:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: main-gateway
  namespace: multigress-system
spec:
  gatewayClassName: multigress
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              tenant: "true"

With from: Selector, only namespaces labeled tenant: true may create routes to this gateway. This is a powerful form of gateway scoping to prevent rogue namespaces from siphoning traffic.

#Isolation Patterns

Three common isolation patterns you can choose from:

• Shared gateway: one gateway for all tenants, isolated per domain. Cost-efficient, centrally controlled.
• Gateway per team: each namespace has its own gateway. Full isolation, higher cost.
• Gateway per environment: separate staging and prod gateways, isolated per environment.

Choose the pattern based on organization size and compliance requirements.

#Managing Shared Gateways for Many Teams

#A Healthy Operating Model

A shared gateway succeeds when there's an explicit agreement. Recommended practices:

• Clear ownership: the platform team manages GatewayClass and Gateway; tenants manage their own routes.
• Separate domains: each tenant only holds its allocated hostnames, enforced via hostname on the listener.
• Rate limit per tenant: use BackendTrafficPolicy to stop one tenant from consuming all resources.
• Observability per label: tag routes with a tenant label to split metrics in Prometheus.

apiVersion: gateway.multigress.io/v1
kind: BackendTrafficPolicy
metadata:
  name: tenant-a-policy
  namespace: team-a
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      name: tenant-a-route
  rateLimit:
    type: Global
    rps: 50

The policy above limits tenant A to 50 requests per second. Rate limiting is covered in depth in episode 14.

#Avoiding Conflicts Between Tenants

The most common conflict is two tenants registering the same hostname. Detect it by checking whether a hostname is already in use:

kubectl get httproute -A -o jsonpath="{range .items[*]}{.metadata.namespace}{'/'}{.metadata.name}{' => '}{.spec.hostnames}{'\n'}{end}"

The kubectl get httproute -A -o jsonpath=... command lists the hostnames per route. If two routes use the same hostname, traffic will be split nondeterministically — a sign that domain allocation needs to be tightened.

#Closing

Episode 10 equipped you with a multi-tenant structure: cross-namespace routing with ReferenceGrant, scope limits via allowedRoutes and labels, and a clear operating model for shared gateways between teams.

The key takeaways:

• Cross-namespace routes require a ReferenceGrant in the route's namespace.
• allowedRoutes on the listener limits which namespaces may bind.
• Isolation patterns: shared gateway, gateway per team, or per environment.
• A shared gateway needs ownership, domain allocation, and per-tenant rate limits.
• Hostname duplication between tenants isn't prevented automatically; a review process is needed.

In the next episode 11 we'll discuss configuration management & GitOps — storing Multigress manifests in Git, validating configuration changes, applying safe rollout patterns, and managing overlays across environments. Your multi-tenant structure will become the basis of a real GitOps repo.