eg-gateway

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create a GatewayClass and Gateway resource for Envoy Gateway. The Gateway defines how traffic enters the cluster through one or more listeners. Each listener specifies a protocol, port, and optional hostname. This skill generates the correct listener configuration for HTTP, HTTPS, TLS passthrough, TCP, and UDP protocols.

为Envoy Gateway创建GatewayClass和Gateway资源。Gateway定义了流量如何通过一个或多个监听器进入集群。每个监听器指定了协议、端口以及可选的主机名。本技能会为HTTP、HTTPS、TLS透传、TCP和UDP协议生成正确的监听器配置。

Instructions

操作步骤

Step 1: Set variables

步骤1：设置变量

Determine the Gateway name and protocols. If the user did not provide values, use these defaults:

Name: (required, no default)
Protocols:
```
http
```
(if not specified)

Parse the

Protocols

argument into a list. Supported values:

http

https

tls-passthrough

tcp

udp

确定Gateway名称和协议。如果用户未提供值，请使用以下默认值：

名称：（必填，无默认值）
协议：
```
http
```
（未指定时）

将

Protocols

参数解析为列表。支持的值：

http

、

https

、

tls-passthrough

、

tcp

、

udp

。

Step 2: Generate the GatewayClass

步骤2：生成GatewayClass

Every Gateway references a GatewayClass. Generate this cluster-scoped resource if it does not already exist:

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  # The controller name must match the Envoy Gateway installation.
  # This is the default value; change it only for multi-tenant deployments
  # where each tenant runs a separate Envoy Gateway controller.
  controllerName: gateway.envoyproxy.io/gatewayclass-controller

When to use parametersRef: If you need to customize the Envoy proxy configuration (resource limits, access logging, custom bootstrap), attach an EnvoyProxy resource via
parametersRef
on the GatewayClass or Gateway:
yaml
spec:
  parametersRef:
    group: gateway.envoyproxy.io
    kind: EnvoyProxy
    name: custom-proxy-config
    namespace: default      # Required when set on GatewayClass

每个Gateway都引用一个GatewayClass。如果该集群级资源不存在，请生成它：

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  # 控制器名称必须与Envoy Gateway的安装配置匹配。
  # 这是默认值；仅在多租户部署场景下修改，每个租户运行独立的Envoy Gateway控制器。
  controllerName: gateway.envoyproxy.io/gatewayclass-controller

何时使用parametersRef：如果您需要自定义Envoy代理配置（资源限制、访问日志、自定义引导程序），请通过GatewayClass或Gateway上的
parametersRef
关联EnvoyProxy资源：
yaml
spec:
  parametersRef:
    group: gateway.envoyproxy.io
    kind: EnvoyProxy
    name: custom-proxy-config
    namespace: default      # 在GatewayClass上设置时为必填项

Step 3: Generate the Gateway

步骤3：生成Gateway

Build the Gateway resource with listeners based on the requested protocols.

根据请求的协议构建带有监听器的Gateway资源。

HTTP only

仅HTTP

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${Name}
  namespace: default          # TODO: Change to your target namespace
spec:
  gatewayClassName: eg
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      # allowedRoutes controls which namespaces can attach Routes to this listener.
      # "Same" = only Routes in the Gateway's namespace. "All" = any namespace.
      allowedRoutes:
        namespaces:
          from: Same          # TODO: Change to "All" for cross-namespace routing

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${Name}
  namespace: default          # TODO: 修改为您的目标命名空间
spec:
  gatewayClassName: eg
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      # allowedRoutes控制哪些命名空间可以将Route关联到该监听器。
      # "Same" = 仅允许Gateway所在命名空间的Route。"All" = 允许所有命名空间。
      allowedRoutes:
        namespaces:
          from: Same          # TODO: 如需跨命名空间路由，请改为"All"

HTTPS only

仅HTTPS

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${Name}
  namespace: default          # TODO: Change to your target namespace
  annotations:
    # Uncomment to enable automatic certificate management with cert-manager.
    # See the /eg-tls skill for full cert-manager integration.
    # cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  gatewayClassName: eg
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      # hostname is required for cert-manager to issue certificates.
      # It also scopes which SNI values this listener accepts.
      hostname: "*.example.com"   # TODO: Set your domain
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            group: ""
            name: example-tls     # TODO: Name of the TLS Secret (cert-manager creates this)
      allowedRoutes:
        namespaces:
          from: All

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${Name}
  namespace: default          # TODO: 修改为您的目标命名空间
  annotations:
    # 取消注释以启用cert-manager自动证书管理。
    # 查看/eg-tls技能了解完整的cert-manager集成方法。
    # cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  gatewayClassName: eg
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      # hostname是cert-manager颁发证书的必填项。
      # 它还限定了该监听器接受的SNI值范围。
      hostname: "*.example.com"   # TODO: 设置您的域名
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            group: ""
            name: example-tls     # TODO: TLS Secret的名称（由cert-manager创建）
      allowedRoutes:
        namespaces:
          from: All

HTTP + HTTPS (most common for production)

HTTP + HTTPS（生产环境最常用）

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${Name}
  namespace: default          # TODO: Change to your target namespace
  annotations:
    # cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  gatewayClassName: eg
  listeners:
    # HTTP listener - typically used for HTTPS redirects
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All
    # HTTPS listener - primary traffic endpoint
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.example.com"   # TODO: Set your domain
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            group: ""
            name: example-tls     # TODO: Name of the TLS Secret
      allowedRoutes:
        namespaces:
          from: All

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${Name}
  namespace: default          # TODO: 修改为您的目标命名空间
  annotations:
    # cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  gatewayClassName: eg
  listeners:
    # HTTP监听器 - 通常用于HTTPS重定向
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All
    # HTTPS监听器 - 主要流量端点
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.example.com"   # TODO: 设置您的域名
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            group: ""
            name: example-tls     # TODO: TLS Secret的名称
      allowedRoutes:
        namespaces:
          from: All

TLS Passthrough

TLS透传

For TLS passthrough, the Gateway does not terminate TLS. The encrypted stream passes directly to the backend, which handles TLS termination. Use TLSRoute (not HTTPRoute) with this mode.

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${Name}
  namespace: default          # TODO: Change to your target namespace
spec:
  gatewayClassName: eg
  listeners:
    - name: tls-passthrough
      protocol: TLS
      port: 443
      hostname: "app.example.com" # TODO: SNI hostname for routing
      tls:
        mode: Passthrough
      allowedRoutes:
        kinds:
          - kind: TLSRoute       # Only TLSRoute is valid for Passthrough mode
        namespaces:
          from: All

对于TLS透传，Gateway不会终止TLS。加密流直接传递到后端，由后端处理TLS终止。此模式需配合TLSRoute（而非HTTPRoute）使用。

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${Name}
  namespace: default          # TODO: 修改为您的目标命名空间
spec:
  gatewayClassName: eg
  listeners:
    - name: tls-passthrough
      protocol: TLS
      port: 443
      hostname: "app.example.com" # TODO: 用于路由的SNI主机名
      tls:
        mode: Passthrough
      allowedRoutes:
        kinds:
          - kind: TLSRoute       # 透传模式仅支持TLSRoute
        namespaces:
          from: All

TCP

TCP listeners forward raw TCP streams. Each TCP listener requires a unique port because there is no application-layer discriminator (no hostname or path matching).

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${Name}
  namespace: default          # TODO: Change to your target namespace
spec:
  gatewayClassName: eg
  listeners:
    - name: tcp
      protocol: TCP
      port: 8088              # TODO: Set your TCP port
      allowedRoutes:
        kinds:
          - kind: TCPRoute    # Only TCPRoute is valid for TCP protocol

TCP监听器转发原始TCP流。每个TCP监听器需要一个唯一的端口，因为没有应用层鉴别器（无主机名或路径匹配）。

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${Name}
  namespace: default          # TODO: 修改为您的目标命名空间
spec:
  gatewayClassName: eg
  listeners:
    - name: tcp
      protocol: TCP
      port: 8088              # TODO: 设置您的TCP端口
      allowedRoutes:
        kinds:
          - kind: TCPRoute    # TCP协议仅支持TCPRoute

UDP

UDP listeners forward raw UDP datagrams. Like TCP, each listener requires a unique port.

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${Name}
  namespace: default          # TODO: Change to your target namespace
spec:
  gatewayClassName: eg
  listeners:
    - name: udp
      protocol: UDP
      port: 5300              # TODO: Set your UDP port
      allowedRoutes:
        kinds:
          - kind: UDPRoute    # Only UDPRoute is valid for UDP protocol

UDP监听器转发原始UDP数据报。与TCP类似，每个监听器需要一个唯一的端口。

yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${Name}
  namespace: default          # TODO: 修改为您的目标命名空间
spec:
  gatewayClassName: eg
  listeners:
    - name: udp
      protocol: UDP
      port: 5300              # TODO: 设置您的UDP端口
      allowedRoutes:
        kinds:
          - kind: UDPRoute    # UDP协议仅支持UDPRoute

Step 4: Apply and verify

步骤4：应用并验证

bash

kubectl apply -f gateway.yaml
kubectl get gateway/${Name} -o yaml

Check the Gateway status. All listeners should show

Accepted: True

and

Programmed: True

bash

kubectl describe gateway/${Name}

Get the Gateway's external address (once a LoadBalancer is provisioned):

bash

export GATEWAY_HOST=$(kubectl get gateway/${Name} -o jsonpath='{.status.addresses[0].value}')
echo "Gateway address: $GATEWAY_HOST"

bash

kubectl apply -f gateway.yaml
kubectl get gateway/${Name} -o yaml

检查Gateway状态。所有监听器应显示

Accepted: True

和

Programmed: True

：

bash

kubectl describe gateway/${Name}

获取Gateway的外部地址（LoadBalancer配置完成后）：

bash

export GATEWAY_HOST=$(kubectl get gateway/${Name} -o jsonpath='{.status.addresses[0].value}')
echo "Gateway address: $GATEWAY_HOST"

Listener design guidance

监听器设计指南

When to use multiple listeners on one Gateway:

HTTP + HTTPS on the same domain (common pattern for HTTPS redirect)
Multiple HTTPS domains sharing the same external IP
A mix of HTTP/HTTPS listeners on standard ports

When to use separate Gateways:

Different security boundaries (e.g., public vs internal)
Different infrastructure requirements (different EnvoyProxy configurations, different Service types)
TCP/UDP services that need dedicated ports with no listener contention
Multi-tenant isolation where each tenant manages their own Gateway

Listener isolation: Each listener has independent

allowedRoutes

configuration. You can restrict which Route types and namespaces can attach to each listener. This provides fine-grained access control:

yaml

allowedRoutes:
  kinds:
    - kind: HTTPRoute         # Only allow HTTPRoute, not GRPCRoute
  namespaces:
    from: Selector
    selector:
      matchLabels:
        gateway-access: "true"  # Only namespaces with this label

何时在一个Gateway上使用多个监听器：

同一域名上的HTTP + HTTPS（HTTPS重定向的常见模式）
多个HTTPS域名共享同一个外部IP
标准端口上的HTTP/HTTPS监听器混合使用

何时使用独立的Gateway：

不同的安全边界（例如，公共 vs 内部）
不同的基础设施要求（不同的EnvoyProxy配置、不同的Service类型）
需要专用端口且无监听器冲突的TCP/UDP服务
多租户隔离场景，每个租户管理自己的Gateway

监听器隔离：每个监听器有独立的

allowedRoutes

配置。您可以限制哪些Route类型和命名空间可以关联到每个监听器。这提供了细粒度的访问控制：

yaml

allowedRoutes:
  kinds:
    - kind: HTTPRoute         # 仅允许HTTPRoute，不允许GRPCRoute
  namespaces:
    from: Selector
    selector:
      matchLabels:
        gateway-access: "true"  # 仅允许带有此标签的命名空间

Cross-namespace references

跨命名空间引用

If the TLS Secret referenced by

certificateRefs

is in a different namespace than the Gateway, you must create a ReferenceGrant in the Secret's namespace:

yaml

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-gateway-secret-ref
  namespace: cert-namespace   # TODO: Namespace where the Secret lives
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: Gateway
      namespace: default      # TODO: Namespace where the Gateway lives
  to:
    - group: ""
      kind: Secret

如果

certificateRefs

引用的TLS Secret与Gateway不在同一个命名空间中，您必须在Secret所在的命名空间中创建ReferenceGrant：

yaml

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-gateway-secret-ref
  namespace: cert-namespace   # TODO: Secret所在的命名空间
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: Gateway
      namespace: default      # TODO: Gateway所在的命名空间
  to:
    - group: ""
      kind: Secret

Checklist

检查清单

GatewayClass exists and shows
```
Accepted: True
```
Gateway is created with listeners matching the requested protocols
All Gateway listeners show
```
Accepted: True
```
and
```
Programmed: True
```
Gateway has an external address assigned (for LoadBalancer-backed clusters)
HTTPS listeners reference a valid TLS Secret (or cert-manager annotation is set)
```
allowedRoutes
```
is configured appropriately for namespace and Route type restrictions
For cross-namespace Secret references: ReferenceGrant is in place

GatewayClass已存在且状态为
```
Accepted: True
```
Gateway已创建，监听器与请求的协议匹配
所有Gateway监听器显示
```
Accepted: True
```
和
```
Programmed: True
```
Gateway已分配外部地址（适用于LoadBalancer支持的集群）
HTTPS监听器引用了有效的TLS Secret（或已设置cert-manager注解）
```
allowedRoutes
```
已根据命名空间和Route类型限制进行了适当配置
对于跨命名空间Secret引用：ReferenceGrant已配置完成