For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

BackendConfigPolicy

Use a BackendConfigPolicy resource to configure connection settings for a backend.

Policy attachment

You can apply BackendConfigPolicies to individual Kubernetes services, any backend that matches a specific label, or a global service in your ambient mesh.

Individual backend

You can use the spec.targetRefs section in the BackendConfigPolicy resource to apply policies to a specific backend, such as a Kubernetes Service or a Backend resource.

The following example BackendConfigPolicy resource specifies connection settings for the httpbin service.

kind: BackendConfigPolicy
apiVersion: gateway.kgateway.dev/v1alpha1
metadata:
  name: httpbin-policy
  namespace: httpbin
spec:
  targetRefs:
    - name: httpbin
      group: ""
      kind: Service
  connectTimeout: 5s
  perConnectionBufferLimitBytes: 1024

Backends with specific label

Instead of applying the policy to a specific service or Backend, you can also use a label selector to apply the policy to all services or Backends that match the label.

The following example shows a BackendConfigPolicy resource that applies connection settings to all Kubernetes services that have the app: httpbin and service: httpbin labels.

kind: BackendConfigPolicy
apiVersion: gateway.kgateway.dev/v1alpha1
metadata:
  name: httpbin-policy
  namespace: httpbin
spec:
  targetSelectors:
    - group: networking.istio.io
      kind: Service
      matchLabels:
        app: httpbin
        service: httpbin
  connectTimeout: 5s
  commonHttpProtocolOptions:
    maxHeadersCount: 15
    maxRequestsPerConnection: 100

Global service

If you use kgateway with an Istio ambient mesh and you exposed services across multiple clusters by using the solo.io/service-scope=global label, Istio automatically creates ServiceEntry resources in each of your clusters that use the same global hostname. You can then use the global hostname to send and load balance requests across multiple clusters.

To apply connection settings to all service instances that are exposed by this global hostname, you can apply a BackendConfigPolicy to an Istio hostname as shown in the following example.

kind: BackendConfigPolicy
apiVersion: gateway.kgateway.dev/v1alpha1
metadata:
  name: httpbin-policy-alias
  namespace: gwtest
spec:
  targetSelectors:
    - group: networking.istio.io
      kind: Hostname
      matchLabels:
        app: httpbin
        service: httpbin
  connectTimeout: 5s
  commonHttpProtocolOptions:
    maxHeadersCount: 15
    maxRequestsPerConnection: 100

Policy priority and merging rules

If you apply multiple BackendConfigPolicy resources to the same backend, policies are merged at the field level.

The following rules apply:

• If you apply multiple BackendConfigPolicy resources that set the same top-level field, only the oldest policy is enforced for that field. Policies with a later timestamp are ignored for that field. If two policies share the same creation timestamp, they are tie-broken alphabetically by resource name.
• BackendConfigPolicy resources that set different top-level fields are merged and are enforced in combination.
• Native Kubernetes Gateway API policies, such as BackendTLSPolicy, have higher priority than BackendConfigPolicy for TLS configuration. If both a BackendConfigPolicy and a BackendTLSPolicy target the same backend, the BackendTLSPolicy’s TLS settings are enforced and the spec.tls field in the BackendConfigPolicy is ignored.

Multiple BackendConfigPolicies

The following example shows two BackendConfigPolicy resources that target the same httpbin Service. The bcp-older BackendConfigPolicy was created first and sets connectTimeout and upstreamProxyProtocol. The bcp-newer BackendConfigPolicy is created later and sets connectTimeout and circuitBreakers.

kind: BackendConfigPolicy
apiVersion: gateway.kgateway.dev/v1alpha1
metadata:
  name: bcp-older
spec:
  targetRefs:
    - name: httpbin
      group: ""
      kind: Service
  connectTimeout: 5s
  upstreamProxyProtocol:
    version: V2
---
kind: BackendConfigPolicy
apiVersion: gateway.kgateway.dev/v1alpha1
metadata:
  name: bcp-newer
spec:
  targetRefs:
    - name: httpbin
      group: ""
      kind: Service
  connectTimeout: 99s
  circuitBreakers:
    maxConnections: 1024
    maxPendingRequests: 1024
    maxRequests: 1024
    maxRetries: 3

Because both policies set connectTimeout, only the value from bcp-older is enforced and the value from bcp-newer is ignored. Because circuitBreakers is only set in bcp-newer, it is merged with bcp-older’s fields and both are enforced in combination.

Conflict with BackendTLSPolicy

If you apply both a BackendConfigPolicy and a BackendTLSPolicy to the same backend, the following rules apply:

• TLS configuration: BackendTLSPolicy is enforced. Because BackendTLSPolicy is a native Kubernetes Gateway API resource, it has higher priority than BackendConfigPolicy for TLS. The spec.tls field in the BackendConfigPolicy is ignored.
• Upstream proxy protocol: If the BackendConfigPolicy sets upstreamProxyProtocol, both policies are enforced in combination. The BackendTLSPolicy’s TLS socket is placed inside the proxy protocol wrapper, regardless of which policy was created first.
• All other BackendConfigPolicy fields (connectTimeout, tcpKeepalive, circuitBreakers, healthCheck, outlierDetection, dns): These fields are not affected by the BackendTLSPolicy and are enforced unchanged.

conditions:
- type: Overridden
  status: "True"
  reason: ConflictedWithBackendTLSPolicy