#Tasks for Envoy Gateway

#Prerequisites

1. Configure EnvoyGatewayCtl
2. Configure Gateway
3. Configure Route

#Introduction

When applying configuration changes in the Gateway API, there are three primary approaches available:

1. Direct modification of the HTTP/TCP/UDP Route or Gateway.
2. Modification through PolicyAttachment provided by Gateway Api and Envoy Gateway.
3. Modification on the global configuration level of the envoy-gateway instance.

#HTTP/TCP/UDP Route

• HTTPRoute specification
• TCPRoute specification
• UDPRoute specification

#PolicyAttachment Via TargetRefs

Envoy Gateway provides a rich custom policy mechanism that can be attached to gateway resources through the Gateway API's PolicyAttachment model.

Envoy Gateway policies are divided into multiple types, including security policies, traffic management policies and more. These policies can be applied to different levels of resources, such as Gateway, HTTPRoute, or Service.

The Gateway API's PolicyAttachment mechanism allows users to attach policies to gateway resources in a declarative way. This mechanism is implemented through the targetRefs field, which specifies the target resource for policy application. For example, policies can be attached to specific Gateways, HTTPRoutes, or Services.

Policy types supported by Envoy Gateway include:

Using the PolicyAttachment mechanism, users can flexibly add, modify, or delete policies without modifying core resource definitions, achieving separation of concerns and better resource management.

#Global Configuration

The configuration related to envoy-gateway instance itself or global-level configuration related to all gateways belongs to this envoy-gateway instance, such as deployment mode or backend routing.

We recommend using EnvoyGatewayCtl to manage those global configurations.

#Common Tasks For Route Config

#Advanced Configuration

#OpenTelemetry(Otel)

Please follow instructions in OpenTelemetry Integration, but use EnvoyGatewayCtl to modify the envoy-gateway-config.

#How To Attach to Listener Created In Other Namespace

In the Gateway's listener configuration, you need to specify which namespaces are allowed to attach Routes to it.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
spec:
  listeners:
    - name: http-80
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All # without limit
    - name: http-81
      protocol: HTTP
      port: 81
      allowedRoutes:
        namespaces:
          from: Same # only allow routes in the same namespace
    - name: http-82
      protocol: HTTP
      port: 82
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              team: frontend # only allow routes in the namespace with label team=frontend

Please refer to Cross-Namespace routing for more details.

#How To Use Cert Created In Other Namespace

To use a certificate created in another namespace, you need to create a ReferenceGrant in the namespace where the certificate is created. Please follow instructions in cross-namespace-certificate-references and referencegrant.

#How To Use SSL passthrough

Please follow instructions in

• tls
• tls-passthrough

#How To Change SSL Cipher

Please follow instructions in customize-gateway-tls-parameters

cat <<EOF | kubectl apply -f -
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: ClientTrafficPolicy
metadata:
  name: enforce-tls-13
  namespace: default
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: eg
  tls:
    minVersion: "1.3"
EOF

the .spec.tls in ClientTrafficPolicy is clienttlssettings

#How To Specify NodePort When Using NodePort Service

When using a NodePort service, kubernetes assigns a NodePort port number to each service port. When accessing the service through a node IP, you should use the corresponding NodePort port number rather than the service port.

There are two approaches to handle this:

Manually retrieve the NodePort assignment by following get nodeport from svc port

Manually specify the NodePort in the EnvoyProxy configuration instead of letting Kubernetes automatically assign it.

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: demo
spec:
  ipFamily: DualStack
  provider:
    kubernetes:
      envoyDeployment:
        container:
          imageRepository: registry.alauda.cn:60080/acp/envoyproxy/envoy
      envoyService:
        patch:
          type: StrategicMerge
          value:
            spec:
              ports:
                - nodeport: 31888
                  port: 80
        type: NodePort
    type: Kubernetes

#How To Add Pod Annotation in EnvoyGateway

Add pod annotation

#How To Set NodeSelector And Tolerations For envoy-gateway-operator

update the Subscription resources

# example of nodeSelector and tolerations
kubectl patch subscription envoy-gateway-operator  -n envoy-gateway-operator   --type='merge' -p '
{
  "spec": {
    "config": {
      "nodeSelector": {
        "node-role.kubernetes.io/infra": ""
      },
      "tolerations": [
        {
          "effect": "NoSchedule",
          "key": "node-role.kubernetes.io/infra",
          "operator": "Equal",
          "value": "reserved"
        }
      ]
    }
  }
}'

#How To Set NodeSelector And Tolerations For envoy-gateway

update the EnvoyGatewayCtl resources

# in default $NAME=cpaas-default and $NS=envoy-gateway-operator
kubectl patch envoygatewayctl $NAME -n $NS --type='merge' -p '
{
  "spec": {
    "deployment": {
      "pod": {
        "nodeSelector": {
          "node-role.kubernetes.io/infra": ""
        },
        "tolerations": [
          {
            "effect": "NoSchedule",
            "key": "node-role.kubernetes.io/infra",
            "operator": "Equal",
            "value": "reserved"
          }
        ]
      }
    }
  }
}'

#How To Set NodeSelector And Tolerations For envoy-proxy

update the EnvoyProxy resources

kubectl patch envoyproxy $NAME -n $NS --type='merge' -p '
{
  "spec": {
    "provider": {
      "kubernetes": {
        "envoyDeployment": {
          "pod": {
            "nodeSelector": {
              "node-role.kubernetes.io/infra": ""
            },
            "tolerations": [
              {
                "effect": "NoSchedule",
                "key": "node-role.kubernetes.io/infra",
                "operator": "Equal",
                "value": "reserved"
              }
            ]
          }
        }
      }
    }
  }
}'

#How to use hostNetwork in envoy-gateway

Using hostNetwork: true allows the Envoy proxy pods to use the host's network namespace directly. This can be useful for:

• Achieving better network performance
• Accessing gateway via node ip

Considerations:

• Pods using hostNetwork will bind directly to the host's network interfaces
• Port conflicts may occur if multiple pods try to use the same port on the same node
• Security isolation is reduced as pods share the host's network namespace
• You should use nodeSelector or affinity rules to control pod placement and avoid port conflicts

#Configuration

Update the EnvoyProxy resource to enable hostNetwork:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: demo
  namespace: demo
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyDeployment:
        patch:
          type: StrategicMerge
          value:
            spec:
              template:
                spec:
                  hostNetwork: true                    # Enable host network mode
                  dnsPolicy: ClusterFirstWithHostNet   # Required when using hostNetwork for proper DNS resolution
        pod:
          nodeSelector:                                # Recommended: control pod placement to avoid port conflicts
            gateway: "demo"

Known Limitations:

• To avoid requiring privileged permissions, Envoy Gateway automatically adds an offset of 10000 to privileged ports (1-1023), e.g., 80 → 10080, 443 → 10443
• When accessing the gateway via node IP in hostNetwork mode, you must use the offset port (e.g., http://<node-ip>:10080 instead of port 80)

#How to Access LoadBalancer VIP from Within the Cluster

By default, Envoy Gateway creates LoadBalancer services with externalTrafficPolicy: Local. This policy preserves client source IP addresses but has an important limitation: requests from cluster nodes without Envoy Gateway pods will fail because traffic is not forwarded to other nodes.

Solution 1: Use Service ClusterIP (Recommended for in-cluster access)

For applications running inside the cluster, use the service ClusterIP instead of the LoadBalancer VIP. This avoids the routing limitation entirely.

Solution 2: Change to Cluster Traffic Policy

If you need to access the LoadBalancer VIP from any cluster node, change externalTrafficPolicy to Cluster:

kubectl patch envoyproxy $GATEWAY_NAME -n $GATEWAY_NS --type='json' -p='[  
  {"op": "replace", "path": "/spec/provider/kubernetes/envoyService/externalTrafficPolicy", "value": "Cluster"}  
]'

#More configuration

Please refer to EnvoyGateway Tasks