#Configure GatewayAPI Gateway

#Overview

This document explains how to configure a Gateway after the Envoy Gateway operator and EnvoyGatewayCtl are ready. A Gateway defines how traffic enters the gateway, while the companion EnvoyProxy controls how the underlying Envoy data plane is deployed.

In the recommended workflow, this document comes after Envoy Gateway Operator and before Configure GatewayAPI Route.

#Prerequisites

Please ensure that you have completed the following before proceeding:

1. Read Envoy Gateway Operator to understand the basic concepts and resource relationships
2. Install the Envoy Gateway operator and create an EnvoyGatewayCtl

#Gateway Basics

#What is a Gateway

A Gateway is the entry point for traffic entering your cluster. It defines how external requests are received and routed to your backend services. A Gateway mainly defines:

• Listeners: Define the ports, protocols, and hostnames the gateway listens on
• GatewayClass: Selects which gateway controller manages this Gateway
• Infrastructure reference: References an EnvoyProxy that controls how the underlying Envoy data plane is deployed

#Gateway Exposure (Service Type)

Service Type configures how the gateway is exposed through the underlying Envoy Service. There are three modes: LoadBalancer, NodePort, and ClusterIP.

In YAML, this setting is configured in the companion EnvoyProxy resource at .spec.provider.kubernetes.envoyService.type.

#LoadBalancer (Recommended)

The advantage is ease of use and high-availability load balancing capabilities. To use LoadBalancer, the cluster must have LoadBalancer support, which can be enabled via MetalLB.

#NodePort

The advantage is that it doesn't require any external dependencies.

However, using NodePort has these disadvantages:

• When using NodePort, Kubernetes assigns NodePort port numbers that differ from the service's own ports. You must use the NodePort port number for access, not the service port.
• The service can be accessed via any node IP address in the cluster, which may pose potential security risks.

#How to Get the Correct Port When Using NodePort

In the Gateway details page, when Service Type is NodePort, the listener list displays the NodePort column showing the assigned port numbers. You can also use the following command:

kubectl get svc -n ${ENVOYGATEWAYCTL_NS} -l gateway.envoyproxy.io/owning-gateway-name=${GATEWAY_NAME} -o=jsonpath="{.items[0].spec.ports[?(@.port==${PORT})].nodePort}"

The output is the NodePort.

#ClusterIP

Very convenient if you don't need external exposure.

#Listener Configuration

A Listener defines the port and protocol for the gateway to listen on. In HTTP or HTTPS protocols, different hostnames can be treated as different listeners.

You cannot create a listener with a conflicting port, protocol, or hostname.

You must create at least one listener in the Gateway.

#Port and Protocol

Each listener is configured with a port number and a protocol. Supported protocols are: HTTP, HTTPS, TCP, UDP, TLS.

#AllowRouteNS

By default, Routes can only attach to a Gateway in the Same namespace. To allow cross-namespace routing, use the Allowed Routes Namespace field:

• Same: Allow Routes in the same namespace to attach to this listener.
• All: Allow Routes in any namespace to attach to this listener.
• Selector: Allow Routes in namespaces matched by the selector to attach to this listener.

In ACP, a project is identified by labels on namespaces, for example cpaas.io/project: <project-name>. If you want a listener to be used only by Routes from a specific project, use Selector and match the project label on the target namespaces.

The listener's Allowed Routes Namespace setting and its protocol together determine which listeners are available in the Route Web Console when you publish a route to a listener.

For more information, see attach to gateway created in other ns.

#TLS Configuration

For HTTPS and TLS protocols, you need to configure TLS settings.

TLS Modes:

Certificate Requirements:

• By default, you can only use secrets created in the same namespace
• The secret must be of type kubernetes.io/tls and contain tls.crt and tls.key keys
• For cross-namespace secrets, see use secret created in other ns

#EnvoyProxy (Deployment Configuration)

Envoy Gateway uses the EnvoyProxy resource to control gateway deployment configurations. We recommend creating a dedicated EnvoyProxy resource for each Gateway and referencing it through the Gateway's .spec.infrastructure.parametersRef field.

When you create a Gateway from the Web Console by using a GatewayClass created by EnvoyGatewayCtl, the console automatically creates a companion EnvoyProxy resource with the same name and namespace.

When you create a Gateway by applying YAML, you are responsible for keeping the Gateway .spec.infrastructure.parametersRef and the referenced EnvoyProxy resource consistent.

This one-to-one mapping approach provides better isolation and more granular control over deployment configurations such as:

• Replicas
• Resource limits and requests
• Node selectors
• Service type and annotations
• Image repository

#Image Repository

The image repository is pre-configured with the default value for your cluster. Do not modify it unless necessary.

For other deployment configuration methods, see deployment-mode.

#Create Gateway

#Via Web Console

1. Navigate to Alauda Container Platform -> Networking -> Gateway -> Gateways
2. Click the Create Gateway button
3. On the Create Gateway page, select the GatewayClass created by your EnvoyGatewayCtl. In the recommended default example from Envoy Gateway Operator, this is envoy-gateway-operator-cpaas-default.

The page displays the following configuration options:

#Listener Configuration

When creating or editing a listener, you can configure the following:

#HTTPS Protocol Configuration

When selecting HTTPS as the protocol:

#TLS Protocol Configuration

When selecting TLS as the protocol:

Configuration Fields

For TLS mode details, see TLS Configuration.

#Via YAML

Replace envoy-gateway-operator-cpaas-default with the GatewayClass created by your own EnvoyGatewayCtl if you are not using the recommended default example.

The following minimal example creates an HTTP Gateway and a dedicated EnvoyProxy.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: demo
  namespace: demo
spec:
  infrastructure:
    parametersRef:
      group: gateway.envoyproxy.io
      kind: EnvoyProxy
      name: demo
  gatewayClassName: envoy-gateway-operator-cpaas-default
  listeners:
    - name: http
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: demo
  namespace: demo
spec:
  provider:
    kubernetes:
      envoyService:
        type: ClusterIP
      envoyDeployment:
        replicas: 1
        container:
          imageRepository: registry.alauda.cn:60080/acp/envoyproxy/envoy
          resources:
            limits:
              cpu: '1'
              memory: 1Gi
            requests:
              cpu: '1'
              memory: 1Gi
    type: Kubernetes

#Complete Example with Multiple Listener Types

If you need more listener types, use the following complete example:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: demo
  namespace: demo
spec:
  infrastructure:
    parametersRef:
      group: gateway.envoyproxy.io
      kind: EnvoyProxy
      name: demo
  gatewayClassName: envoy-gateway-operator-cpaas-default
  listeners:
    - name: http
      port: 80
      hostname: a.com
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Same
    - name: https
      port: 443
      hostname: a.com
      protocol: HTTPS
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        mode: Terminate
        certificateRefs:
          - name: demo-tls
    - name: tls-passthrough
      port: 8443
      hostname: tls.example.com
      protocol: TLS
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        mode: Passthrough
    - name: tls-terminate
      port: 9443
      hostname: secure.example.com
      protocol: TLS
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        mode: Terminate
        certificateRefs:
          - name: demo-tls
    - name: tcp
      port: 8080
      protocol: TCP
      allowedRoutes:
        namespaces:
          from: Same
    - name: udp
      port: 8081
      protocol: UDP
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: demo
  namespace: demo
spec:
  provider:
    kubernetes:
      envoyService:
        type: ClusterIP
      envoyDeployment:
        replicas: 1
        container:
          imageRepository: registry.alauda.cn:60080/acp/envoyproxy/envoy
          resources:
            limits:
              cpu: '1'
              memory: 1Gi
            requests:
              cpu: '1'
              memory: 1Gi
    type: Kubernetes

#View Gateway Details

In the Gateway details page, the listener list shows the following information:

#Listener and Route Reference

Use the following rules when attaching Route resources to a Gateway.

#Hostname

The hostname in a listener is a unique identifier for listeners that have the same protocol. You cannot add or update a conflicting listener in a gateway.

#Hostname Intersection Rule

When a request arrives, it is matched against the intersection of the Listener's hostname and the Route's hostnames. Only hostnames in the intersection are used for routing traffic.

#Supported Route Kinds

Each listener supports different route kinds based on its protocol:

When configuring routes, ensure they match the protocol of the listener they attach to. For example, you cannot attach an HTTPRoute to a TCP listener.

#Next Step

After the Gateway is ready, continue with Configure GatewayAPI Route. If you need advanced traffic control after routes are attached, continue with Configure GatewayAPI Policy.