Learn OpenClaw - Multi-tenancy & Namespace Isolation

#Introduction

In episode 9 you managed policies through GitOps — every change documented, validated, and rollback-able. But there's a question that comes up as soon as your cluster is used by more than one team: how can multiple teams share a single OpenClaw platform without team A's policies breaking team B's services? This is the classic problem called multi-tenancy.

Episode 10 moves into the topic most commonly encountered in companies: sharing a platform. Its roadmap: first we understand the multi-tenancy model in OpenClaw, second we implement namespace-segmented policies and service scoping, and third we secure ingress and egress for different tenants. By the end of the episode, your cluster can be used by many teams with confidence.

#The Multi-tenancy Model in OpenClaw

#Why Tenancy Must Be Planned

Sharing a cluster is tempting: efficient, saves resources, one platform team maintains everything. But without clear separation, one team could deny another team's traffic, change labels used by shared policies, or even see policy configuration that should be confidential. Good multi-tenancy isn't just about technology — it's about boundaries: access boundaries, policy boundaries, and visibility boundaries.

OpenClaw uses Kubernetes namespaces as the primary tenancy unit. Each team gets a namespace (or a set of namespaces) as its "home", and OpenClaw ensures policies only apply within the defined scope. This approach is called soft multi-tenancy: namespaces are logically separated on top of a shared control plane.

apiVersion: openclaw.io/v1
kind: TenantConfig
metadata:
  name: billing-tenant
  namespace: billing
spec:
  namespaces:
    - billing
    - billing-worker
  serviceScoping:
    enabled: true
    scopeLabels:
      - tenant
      - service-tier
  policyIsolation: HARD
  ingressDomains:
    - billing.example.com

Note policyIsolation: HARD — this tells OpenClaw that policies from other tenants must not touch this namespace, and conversely this tenant's policies don't leak outward. ingressDomains limits which domains may serve this tenant.

#Soft vs Hard Isolation

There's a spectrum of tenant separation: soft isolation shares most infrastructure and only separates policies logically, suited for internal services with high trust; hard isolation separates further — policies, data, even traffic plane — suited for external tenants or environments with strict compliance rules. The choice between the two is determined by how dangerous the impact of one tenant's mistake would be on other tenants.

Soft isolation  : separate policies, shared logic, good for internal teams
Hard isolation  : separate policies + plane, for external/compliance tenants
One golden rule  : default deny across tenants, allow only what is explicit

The golden rule is simple and important: cross-tenant traffic must be denied by default. If the billing team needs to access the reporting team's services, that's written as an explicit exception — not because all services in the cluster automatically see each other.

#Namespace-Segmented Policies and Service Scoping

#Policies Locked to a Namespace

A good policy in a multi-tenant environment is one that understands context. A policy selector shouldn't just match the label app: billing — because that label might belong to another tenant. Selectors must be combined with namespaces so one policy never accidentally affects another team's services.

apiVersion: openclaw.io/v1
kind: ServicePolicy
metadata:
  name: billing-internal
  namespace: billing
spec:
  selector:
    matchNamespaces:
      - billing
      - billing-worker
    labels:
      app: billing
  rules:
    - from:
        - namespace: billing
          serviceAccount: billing-sa
      action: ALLOW
    - from:
        - any: true
      action: DENY

The key difference from previous policies: the matchNamespaces section limits the policy's scope to namespaces owned by the tenant, and the from rule requires the source to come from the same namespace. Policies like this are safe to duplicate across tenants because they won't touch each other.

#Service Scoping for Logical Isolation

Service scoping is the ability to limit a policy's references to specific services within a tenant. It answers the question "which services is this policy talking about?" — and the answer is locked in through scope labels, not ambiguous global names. For example, all services in a tenant are labeled tenant: billing, and all tenant policies reference that label.

kubectl get pods -n billing -l tenant=billing
openclawctl policy scope billing-internal --namespace billing

The command openclawctl policy scope billing-internal --namespace billing shows the list of services actually covered by that policy. This is a very useful debugging tool in a busy cluster: you can confirm a policy isn't broader than intended, and that new services not yet labeled tenant aren't accidentally pulled into the policy.

#Secure Multi-tenant Ingress and Egress

#Ingress Per Tenant

When many teams share a single ingress, you need clear separation at the front door: each tenant gets its own domain (or path prefix), and traffic to that domain may only reach services inside that tenant. OpenClaw allows binding an ingress domain to a tenant's namespace, so billing's domain can't route traffic to reporting's services.

apiVersion: openclaw.io/v1
kind: IngressPolicy
metadata:
  name: billing-ingress
  namespace: billing
spec:
  domains:
    - billing.example.com
    - api.billing.example.com
  routes:
    - pathPrefix: /api
      destination:
        service: billing-api
        port: 8080
  tls:
    mode: TERMINATE
    secretRef: billing-tls

Note that tls.secretRef points to the billing-tls secret owned by the billing tenant. Each tenant manages its own certificates — tenant A doesn't need to borrow or see tenant B's secrets. This secret separation is an important part of real ingress isolation.

#Egress Governed Per Tenant

The outbound direction also needs separation. Without control, tenant A's services could freely call any external endpoint, and tenant B suffers the consequences if tenant A makes connections that violate compliance. Per-tenant egress policies define which domains may be targeted and through which egress proxy.

apiVersion: openclaw.io/v1
kind: EgressPolicy
metadata:
  name: billing-egress
  namespace: billing
spec:
  enabled: true
  allowedDomains:
    - payment-gateway.example.net
    - billing-db.example.net
  denyDefault: true
  routeVia:
    egressProxy: openclaw-egress

With denyDefault: true, all outbound connections from the billing tenant are limited to the two listed domains. Outbound traffic passes through a shared egress proxy that gives a unified identity outside the cluster — a stable source IP for whitelisting on the external provider's side.

#Wrap-Up

In episode 10 you made a single cluster safely serve many teams: understanding the namespace-based tenancy model with soft or hard isolation options, writing policies segmented per namespace with service scoping and unambiguous label prefixes, and securing each tenant's entry and exit points with their own domains and egress policies.

Key takeaways:

• Namespace is the primary tenancy unit; restrict policies with matchNamespaces so they don't leak between tenants.
• Default deny across tenants is the golden rule — allow only explicit exceptions.
• Service scoping locks policy references to tenant-owned services via prefixed labels, not generic labels.
• Per-tenant ingress has its own domain and TLS secret; never share secrets between tenants.
• Egress policies with denyDefault: true restrict outbound connections and stabilize outbound identity via an egress proxy.

In the next episode, episode 11, we handle the last "valuable asset" on the configuration side: config management and secrets — how to store OpenClaw configuration securely, manage secrets for TLS and API keys, and validate configuration changes in the pipeline. See you there!