#Envoy Gateway Operator

#Overview

This document provides an overview of how envoy-gateway-operator works in ACP. It explains the relationships between the main custom resources and runtime instances involved in Envoy Gateway, including EnvoyGatewayCtl, GatewayClass, Gateway, EnvoyProxy, envoy-gateway instance, and envoy-proxy instance.

The envoy-gateway-operator packages the upstream envoy-gateway Helm chart as an Operator, so you can deploy and manage an envoy-gateway instance declaratively through the EnvoyGatewayCtl custom resource instead of managing the chart or rendered resources directly.

In ACP 4.3, envoy-gateway-operator packages the upstream envoy-gateway Helm chart version 1.7.0.

Because the Operator is maintained by the platform, it is also upgraded automatically together with the platform, which helps reduce the operational overhead of manually maintaining the Envoy Gateway installation.

This document also describes how to create an EnvoyGatewayCtl, which is the entry point for deploying and managing Envoy Gateway through the platform.

After you understand the basic concepts in this document and create an EnvoyGatewayCtl, continue with Gateway, Route, and Policy configuration in that order by following the documents listed in Next Step.

#Architecture

The following workflow shows how envoy-gateway-operator, EnvoyGatewayCtl, GatewayClass, Gateway, and EnvoyProxy work together to deploy and manage Envoy Gateway and its data plane.

1. After you install envoy-gateway-operator and create an EnvoyGatewayCtl, the operator deploys an envoy-gateway instance and creates a corresponding GatewayClass. The GatewayClass name follows the <namespace>-<name> pattern. In this document, we use the recommended default example: cpaas-default in the envoy-gateway-operator namespace, which is also the default configuration prefilled on the Create EnvoyGatewayCtl page. In this case, the generated GatewayClass is envoy-gateway-operator-cpaas-default.

   Each EnvoyGatewayCtl must have a unique combination of namespace and name, so the corresponding GatewayClass names are also unique. When creating a Gateway, you select the appropriate GatewayClass to determine which envoy-gateway instance manages it.

2. When you create a Gateway that references this GatewayClass, the envoy-gateway instance takes ownership of that Gateway. If the Gateway references an EnvoyProxy through .spec.infrastructure.parametersRef, that EnvoyProxy is used to control how the underlying envoy-proxy instance is deployed.

3. The envoy-gateway instance then provisions and manages the corresponding envoy-proxy instance, which serves as the data plane and handles incoming traffic for that Gateway.

4. You can create HTTPRoute, TCPRoute, UDPRoute, GRPCRoute, or TLSRoute resources and attach them to the Gateway to define how traffic is matched and forwarded to backend Services. You can also attach traffic policies such as ClientTrafficPolicy or BackendTrafficPolicy for more advanced behavior.

#Related custom resources

The following custom resources are involved in deploying Envoy Gateway and configuring traffic behavior.

#Operator-related custom resources

We recommend deploying a single envoy-gateway instance via EnvoyGatewayCtl per cluster for typical use cases.

For advanced scenarios, EnvoyGatewayCtl also allows you to deploy multiple envoy-gateway instance resources within the same cluster for stronger control and isolation, such as different deployment mode.

#Gateway API related custom resources

These resources describe the routing semantics of the gateway, including how traffic enters the gateway, how requests are matched and forwarded to backends, and what policies are applied during traffic processing.

For more details about these standard Gateway API resources, please refer to the Gateway API Concepts and Configure GatewayAPI Policy.

#Envoy Gateway deploy-related custom resources

These resources are used to control how Envoy Gateway and its data plane are deployed. This section focuses on the deployment-related custom resource used by this document.

In the recommended deployment pattern, each Gateway references its own dedicated EnvoyProxy through .spec.infrastructure.parametersRef. When you create a Gateway from the Web Console by using an EnvoyGatewayCtl-created GatewayClass, the console automatically creates a companion EnvoyProxy resource with the same name and namespace. This one-to-one mapping lets you control the Gateway's deployment configuration, such as replicas, resources, and scheduling, by updating the corresponding EnvoyProxy resource.

#Install Envoy Gateway via Envoy Gateway Operator

#Prerequisites

Please ensure that you have read the Overview and Architecture sections before proceeding.

#Installation

#Step 1: Install Envoy Gateway Operator

1. Navigate to Administrator -> Marketplace -> OperatorHub
2. Locate the Alauda build of Envoy Gateway under Networking Category and click Install

#Step 2: Create an EnvoyGatewayCtl with the Recommended Default Values

The following default values match the recommended example used throughout this document.

1. Navigate to Administrator -> Marketplace -> OperatorHub

2. Locate the Alauda build of Envoy Gateway under the Networking category, then click it to open the details page.

3. Navigate to the All Instances tab

4. Click Create, then in the displayed dialog box, locate the EnvoyGatewayCtl Instance Type section and click Create

5. The Create EnvoyGatewayCtl page displays the following configuration options:

   Field	Default Value	Description	YAML Path
   Name	cpaas-default	Name of the Envoy Gateway instance	.metadata.name
   Namespace	envoy-gateway-operator	Namespace of the Envoy Gateway instance. Each namespace can have only one EnvoyGatewayCtl.	.metadata.namespace
   Replica	1	Replica count of the Envoy Gateway deployment	.spec.deployment.replicas
   Deploy Ns Mode	ControllerNamespace	Determines whether the gateway deployment is installed in the gateway namespace or the controller namespace. For details, see deployment mode	.spec.config.envoyGateway.provider.kubernetes.deploy.type
   Resources	1C1G	Resource requests and limits of the Envoy Gateway deployment	.spec.deployment.resources

   Recommendation: Use the default values for typical deployments. Click Create to proceed.

#Configuration Via YAML

As an alternative to the Web Console, you can create an EnvoyGatewayCtl by applying YAML.

Default Config:

apiVersion: envoy-gateway.alauda.io/v1
kind: EnvoyGatewayCtl
metadata:
  name: cpaas-default
  namespace: envoy-gateway-operator
spec:
  config:
    envoyGateway:
      provider:
        kubernetes:
          deploy:
            type: ControllerNamespace
        type: Kubernetes
  deployment:
    replicas: 1
    resources:
      limits:
        cpu: '1'
        memory: 1024Mi
      requests:
        cpu: 100m
        memory: 256Mi

#Advanced Config Via EnvoyGatewayCtl

EnvoyGatewayCtl is the custom resource used to configure an envoy-gateway instance. Its spec maps directly to the values of the upstream envoy-gateway Helm chart. When you need to modify EnvoyGatewayCtl, refer to the upstream chart values documentation for the available configuration options.

For detailed information about available configuration options, please refer to envoy-gateway-chart-values.

#Example: Enable Backend Routing

The following example shows how to enable backend routing in the EnvoyGatewayCtl spec:

apiVersion: envoy-gateway.alauda.io/v1
kind: EnvoyGatewayCtl
metadata:
  name: cpaas-default
  namespace: envoy-gateway-operator
spec:
  config:
    envoyGateway:
      extensionApis:
        enableBackend: true # Enable backend routing in EnvoyGatewayCtl not the envoygateway configmap
      provider:
        kubernetes:
          deploy:
            type: ControllerNamespace
        type: Kubernetes
  deployment:
    replicas: 1
    resources:
      limits:
        cpu: '1'
        memory: 1024Mi
      requests:
        cpu: 100m
        memory: 256Mi

#Next Step

After the Envoy Gateway operator and EnvoyGatewayCtl are ready, continue with the following tasks in order:

• Configure GatewayAPI Gateway
• Configure GatewayAPI Route
• Configure GatewayAPI Policy
• Tasks for Envoy Gateway