Container Service for Kubernetes:Custom Gateway configuration

How it works

Two configuration scopes are available:

When both scopes are configured, Gateway-level parameters take precedence.

When to use each scope:

• Use Gateway-level configuration when different Gateways in the same class need distinct resource profiles (for example, different replica counts for production vs. staging).

• Use GatewayClass-level configuration to apply a shared baseline to all Gateways in a class, and let individual Gateways override only the fields that differ.

Before you begin

Before configuring, note the following constraints:

• A Gateway resource can only reference an EnvoyProxy in the same namespace.

• If both envoyDeployment.replicas and envoyHpa are configured, omit replicas under envoyDeployment. The Horizontal Pod Autoscaler (HPA) manages the replica count.

Configure a single Gateway

Reference an EnvoyProxy resource from the infrastructure.parametersRef field of the Gateway:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: eg
spec:
  gatewayClassName: eg
  infrastructure:
    parametersRef:
      group: gateway.envoyproxy.io
      kind: EnvoyProxy
      name: custom-proxy-config
  listeners:
    - name: http
      protocol: HTTP
      port: 80
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: custom-proxy-config
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyDeployment:
        replicas: 2
        container:
          resources:
            requests:
              cpu: 500m
              memory: 1Gi
            limits:
              cpu: 1
              memory: 2Gi

Configure all Gateways in a GatewayClass

Reference an EnvoyProxy resource from the parametersRef field of the GatewayClass:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
  parametersRef:
    group: gateway.envoyproxy.io
    kind: EnvoyProxy
    name: custom-proxy-config
    namespace: default
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: custom-proxy-config
  namespace: default
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyDeployment:
        replicas: 2
        container:
          resources:
            requests:
              cpu: 500m
              memory: 1Gi
            limits:
              cpu: 1
              memory: 2Gi

All Gateway resources under this GatewayClass inherit these parameters. A Gateway that references its own EnvoyProxy overrides these class-level values for that Gateway only.

EnvoyProxy field reference

The following example shows the full set of commonly used fields:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: custom-proxy-config
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyDeployment:
        replicas: 2          # Omit if envoyHpa is also configured.
        strategy:
          rollingUpdate:
            maxSurge: 2
            maxUnavailable: 1
        pod:
          affinity: ...
          tolerations: ...
          nodeSelector: ...
        container:
          resources:
            requests:
              cpu: 500m
              memory: 1Gi
            limits:
              cpu: 1
              memory: 2Gi
      envoyService:
        annotations:
          key: value
        labels:
          key: value
        type: LoadBalancer
        loadBalancerClass: ...
        externalTrafficPolicy: Cluster # or Local
      envoyHpa:
        minReplicas: 1
        maxReplicas: 10
        metrics:
        - type: Resource
          resource:
            name: cpu
            target:
              type: Utilization
              averageUtilization: 80
        - type: Resource
          resource:
            name: memory
            target:
              type: Utilization
              averageUtilization: 80
      envoyPDB:
        minAvailable: 1

The following table describes the top-level fields under kubernetes:

For the complete EnvoyProxy API specification, see EnvoyProxy.