# Configure Cross-Namespace References

Cross-namespace references let platform teams operate shared Gateways, backends, and Secrets while application teams manage their own Routes and Consumers. Gateway API requires an explicit authorization at each namespace boundary so that creating a resource in one namespace does not grant access to resources owned by another team.

The required authorization depends on the relationship:

| Relationship                                           | Authorization                                                              |
| ------------------------------------------------------ | -------------------------------------------------------------------------- |
| Route to a Gateway in another namespace                | The Gateway listener selects the Route namespace with `allowedRoutes`.     |
| Route to a backend in another namespace                | A `ReferenceGrant` in the backend namespace permits the Route reference.   |
| Gateway to a TLS Secret in another namespace           | A `ReferenceGrant` in the Secret namespace permits the Gateway reference.  |
| `Consumer` to a credential Secret in another namespace | A `ReferenceGrant` in the Secret namespace permits the Consumer reference. |

Cross-namespace traffic references are supported through Gateway API resources. The Ingress resource and APISIX routing CRDs do not support cross-namespace traffic references. The `Consumer` credential reference is an implementation-specific use of `ReferenceGrant`.

These mechanisms authorize relationships between resources; they do not grant users permission to create or modify those resources. Use [Kubernetes RBAC to delegate Gateway API access](https://docs.api7.ai/ingress-controller/production/gateway-api-access-control.md) before configuring cross-namespace references.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Complete the following prerequisites:

* [Set up the Ingress Controller and gateway](https://docs.api7.ai/ingress-controller/set-up-ingress-controller-and-gateway.md) with Gateway API resources.
* Install the Gateway API CRDs supported by the installed Ingress Controller release.
* Use an account with permission to create the namespaces and resources in each example.

The examples use a Gateway named `apisix` and a GatewayProxy named `apisix-config` in the `aic` namespace. These are the names created by the APISIX setup tutorial.

## Allow a Route to Use a Backend in Another Namespace[​](#allow-a-route-to-use-a-backend-in-another-namespace "Direct link to Allow a Route to Use a Backend in Another Namespace")

The following example creates an HTTPRoute in `tenant-a`, attaches it to the Gateway in `aic`, and forwards requests to a Service in `backend-ns`:

<!-- -->

The Gateway owner authorizes attachment from `tenant-a`, while the backend owner separately authorizes access to the `httpbin` Service.

### Create the Namespaces[​](#create-the-namespaces "Direct link to Create the Namespaces")

Create the Route and backend namespaces:

```
kubectl create namespace tenant-a

kubectl create namespace backend-ns
```

Kubernetes automatically adds the immutable `kubernetes.io/metadata.name` label to every namespace. The Gateway listener will use that label to select `tenant-a`; no custom namespace label is required.

### Create the Backend Service[​](#create-the-backend-service "Direct link to Create the Backend Service")

Create a deployment and Service in `backend-ns`:

httpbin-deployment.yaml

```
apiVersion: apps/v1

kind: Deployment

metadata:

  name: httpbin

  namespace: backend-ns

spec:

  replicas: 1

  selector:

    matchLabels:

      app: httpbin

  template:

    metadata:

      labels:

        app: httpbin

    spec:

      containers:

      - name: httpbin

        image: kennethreitz/httpbin

        ports:

        - containerPort: 80

---

apiVersion: v1

kind: Service

metadata:

  name: httpbin

  namespace: backend-ns

spec:

  ports:

  - port: 80

    targetPort: 80

    protocol: TCP

  selector:

    app: httpbin
```

Apply the manifest:

```
kubectl apply -f httpbin-deployment.yaml
```

### Authorize the Backend Reference[​](#authorize-the-backend-reference "Direct link to Authorize the Backend Reference")

A `ReferenceGrant` must be created in the namespace containing the referenced object. Create the following grant in `backend-ns` to allow HTTPRoute resources in `tenant-a` to reference the `httpbin` Service:

backend-referencegrant.yaml

```
apiVersion: gateway.networking.k8s.io/v1

kind: ReferenceGrant

metadata:

  name: allow-httpbin-from-tenant-a

  namespace: backend-ns

spec:

  from:

  - group: gateway.networking.k8s.io

    kind: HTTPRoute

    namespace: tenant-a

  to:

  - group: ""

    kind: Service

    name: httpbin
```

The `from` entry trusts HTTPRoute resources in `tenant-a`. The `to` entry limits that trust to the `httpbin` Service in the ReferenceGrant's namespace. The `to.name` field is optional, but omitting it would permit references to every Service in `backend-ns` that is covered by a matching grant.

Apply the grant before creating the Route:

```
kubectl apply -f backend-referencegrant.yaml
```

### Create the Route[​](#create-the-route "Direct link to Create the Route")

Create an HTTPRoute in `tenant-a` that attaches to the Gateway in `aic` and references the Service in `backend-ns`:

httpbin-route.yaml

```
apiVersion: gateway.networking.k8s.io/v1

kind: HTTPRoute

metadata:

  name: httpbin-route

  namespace: tenant-a

spec:

  parentRefs:

  - name: apisix

    namespace: aic

  rules:

  - matches:

    - path:

        type: PathPrefix

        value: /ip

    backendRefs:

    - kind: Service

      name: httpbin

      namespace: backend-ns

      port: 80

      weight: 1
```

Apply the Route:

```
kubectl apply -f httpbin-route.yaml
```

### Authorize the Route Attachment[​](#authorize-the-route-attachment "Direct link to Authorize the Route Attachment")

By default, a Gateway listener accepts Routes only from the Gateway's namespace. Configure `allowedRoutes` on the listener to select the `tenant-a` namespace. Preserve any other listeners or settings required by your existing Gateway:

gateway.yaml

```
apiVersion: gateway.networking.k8s.io/v1

kind: Gateway

metadata:

  name: apisix

  namespace: aic

spec:

  gatewayClassName: apisix

  listeners:

  - name: http

    protocol: HTTP

    port: 80

    allowedRoutes:

      namespaces:

        from: Selector

        selector:

          matchLabels:

            kubernetes.io/metadata.name: tenant-a

  infrastructure:

    parametersRef:

      group: apisix.apache.org

      kind: GatewayProxy

      name: apisix-config
```

Using the immutable namespace-name label prevents users who can modify ordinary namespace labels from changing which namespaces may attach Routes to the Gateway.

Apply the updated Gateway:

```
kubectl apply -f gateway.yaml
```

To accept Routes from every namespace, set `from: All` instead:

```
allowedRoutes:

  namespaces:

    from: All
```

caution

Using `from: All` in a multi-tenant or untrusted cluster lets any namespace attach HTTPRoute resources to this listener. A Route may claim a hostname before an authorized Route or expose backends through the shared Gateway. Prefer an explicit namespace selector.

### Verify the Route[​](#verify-the-route "Direct link to Verify the Route")

Forward the gateway Service port to your local machine. In the APISIX setup tutorial, both the Gateway and Service are in `aic`:

```
kubectl port-forward -n <gateway-service-namespace> \

  svc/<gateway-service-name> 9080:80 &
```

Send a request to the Route:

```
curl -i "http://127.0.0.1:9080/ip"
```

You should receive an `HTTP/1.1 200 OK` response similar to the following:

```
{

  "origin": "127.0.0.1"

}
```

If the request fails, inspect the Route's parent conditions. `Accepted` and `ResolvedRefs` should both be `True`:

```
kubectl describe httproute httpbin-route -n tenant-a
```

## Allow a Gateway to Reference a TLS Secret[​](#allow-a-gateway-to-reference-a-tls-secret "Direct link to Allow a Gateway to Reference a TLS Secret")

When a Gateway listener uses a certificate Secret in another namespace, the Secret owner must authorize the reference. For example, if the `apisix` Gateway is in `aic` and the Secret is named `test-tls-secret` in `certificates`, create this grant in `certificates`:

certificate-referencegrant.yaml

```
apiVersion: gateway.networking.k8s.io/v1

kind: ReferenceGrant

metadata:

  name: allow-gateway-from-aic

  namespace: certificates

spec:

  from:

  - group: gateway.networking.k8s.io

    kind: Gateway

    namespace: aic

  to:

  - group: ""

    kind: Secret

    name: test-tls-secret
```

Apply the grant before updating the Gateway:

```
kubectl apply -f certificate-referencegrant.yaml
```

Then include the Secret namespace in the listener's `certificateRefs` entry:

```
listeners:

- name: https

  protocol: HTTPS

  port: 443

  tls:

    mode: Terminate

    certificateRefs:

    - group: ""

      kind: Secret

      name: test-tls-secret

      namespace: certificates
```

After applying the Gateway, verify that the HTTPS listener reports `ResolvedRefs=True`:

```
kubectl describe gateway apisix -n aic
```

See [Configure TLS Between Client and Gateway](https://docs.api7.ai/ingress-controller/tls-and-mtls/configure-downstream-https.md) for the complete certificate and HTTPS Route configuration.

## Allow a Consumer to Reference a Credential Secret[​](#allow-a-consumer-to-reference-a-credential-secret "Direct link to Allow a Consumer to Reference a Credential Secret")

When a `Consumer` and its credential Secret are in different namespaces, the Secret owner must authorize the reference. Create the `ReferenceGrant` before applying or upgrading the Consumer. Without a matching grant, the admission webhook rejects the Consumer when the webhook is enabled. If the Consumer is admitted without a grant, the controller reports `Available=False` and does not program the credential.

Create the Consumer and Secret namespaces:

```
kubectl create namespace consumer-ns

kubectl create namespace secret-ns
```

Create a key-auth credential Secret in `secret-ns`:

consumer-credential.yaml

```
apiVersion: v1

kind: Secret

metadata:

  name: consumer-credentials

  namespace: secret-ns

type: Opaque

stringData:

  key: example-api-key
```

Create a ReferenceGrant in `secret-ns` that allows Consumer resources in `consumer-ns` to reference this Secret:

consumer-referencegrant.yaml

```
apiVersion: gateway.networking.k8s.io/v1

kind: ReferenceGrant

metadata:

  name: allow-consumers-from-consumer-ns

  namespace: secret-ns

spec:

  from:

  - group: apisix.apache.org

    kind: Consumer

    namespace: consumer-ns

  to:

  - group: ""

    kind: Secret

    name: consumer-credentials
```

Create the Consumer in `consumer-ns`. The `gatewayRef` identifies the Gateway for which the credential should be programmed:

consumer.yaml

```
apiVersion: apisix.apache.org/v1alpha1

kind: Consumer

metadata:

  name: example-consumer

  namespace: consumer-ns

spec:

  gatewayRef:

    name: apisix

    namespace: aic

  credentials:

  - type: key-auth

    name: primary-key

    secretRef:

      name: consumer-credentials

      namespace: secret-ns
```

Apply the Secret and grant before the Consumer:

```
kubectl apply -f consumer-credential.yaml

kubectl apply -f consumer-referencegrant.yaml

kubectl apply -f consumer.yaml
```

Wait for the Consumer to report that the credential was programmed successfully:

```
kubectl wait --for=condition=Available \

  consumers.apisix.apache.org/example-consumer \

  -n consumer-ns \

  --timeout=60s
```

If the condition remains `False`, inspect its message and confirm that the grant's `from.namespace`, `to.name`, and metadata namespace match the Consumer and Secret:

```
kubectl describe consumer example-consumer -n consumer-ns
```
