# Install Envoy Gateway

> [HTML Version](envoy-gateway.html)

**Envoy Gateway** is a Kubernetes traffic management tool used to expose BRIX application services through a unified entry point: the API Gateway.

Envoy Gateway enables you to:

- Route and redirect traffic.

- Provide TLS termination and request management.

- Implement load balancing.

- Utilize advanced network observability features.

Setting up and configuring Envoy Gateway involves the following steps:

1. [Download the Helm chart and configuration file](#download-chart).

2. [Fill out the configuration file](#config-file).

3. [Install the Helm chart into your Kubernetes cluster](#install-chart).

4. [Create a GatewayClass](#create-gatewayclass).

5. [Create a TLS certificate](#tls-certificate).

6. [Create a Gateway resource](#create-gateway).

7. [Configure an external IP address via MetalLB (optional)](#metallb-external-ip).

8. [Configure BRIX to work with Gateway API](#gateway-api-support).

**Important**: We strongly recommend running only one Gateway controller in your cluster to avoid HTTPRoute and Gateway resource conflicts, unpredictable routing, and increased system load. Running two controllers is only permitted temporarily (e.g., during migration) or in strictly isolated namespaces using different `GatewayClass` resources.

## Step 1: Download the Helm chart and configuration file

For online installation retrieve the `values-envoy-gateway.yaml` configuration file by running:

````
helm repo add brix365 https://charts.brix365.com  
helm repo update  
helm show values brix365/envoy-gateway > values-envoy-gateway.yaml

````
**Getting the configuration file for installation without internet access**

1. On a machine with internet access, download the latest version (latest) of the **envoy-gateway** chart:

````
helm repo add brix365 https://charts.brix365.com  
helm repo update  
helm pull brix365/envoy-gateway

2. ````
Copy the downloaded `envoy-gateway-X.Y.Z.tgz` chart archive to the target server where installation will take place.

3. Extract the `envoy-gateway-X.Y.Z.tgz` archive and create a copy of the `values.yaml` configuration file named `values-envoy-gateway.yaml`:

````
tar -xf envoy-gateway-X.Y.Z.tgz  
cp envoy-gateway/values.yaml values-envoy-gateway.yaml
````

## ````
Step 2: Fill out the configuration file

Define your Envoy Gateway deployment settings in the `values-envoy-gateway.yaml` file.

**Important**: Ensure that the `url: http://envoy-gateway-system-kube-prometheus-prometheus.envoy-gateway-system.svc` parameter correctly points to the path of your Prometheus service.

Sample values-envoy-gateway.yaml file

````
\## envoy-gateway settings  
gateway-helm:  
  deployment:  
    envoyGateway:  
      resources:  
        limits:  
          memory: 1024Mi  
        requests:  
          cpu: 100m  
          memory: 256Mi  
\## Configuration settings  
  config:  
    envoyGateway:  
      gateway:  
        controllerName: gateway.envoyproxy.io/gatewayclass-controller  
      provider:  
        type: Kubernetes
````

````
**Configuring private registry settings for offline installation in air-gapped environments**

  
To connect to a private registry:

1. Download the BRIX container images and push them to your local image registry. For details, see [Download BRIX images](downloadin-images-elma365.md).

2. In the file `values-envoy-gateway.yaml` file:

	- In the `image.repository` parameter, set the path to your private registry (format: `registry.example.com`).

	- In the `imagePullSecrets` parameter, specify the name of the secret containing your private registry credentials. This secret must be created manually and Base64-encoded.

````
\## envoy-gateway settings  
gateway-helm:  
  global:  
\## rivate registry connection parameters  
    imageRegistry: "registry.example.com/docker/addons/envoyproxy"  
    imagePullSecrets: \[\]  
    images:  
      envoy:  
\## Private registry address and secret  
        image: envoy  
        tag: distroless-v1.37.2  
      envoyGateway:  
\## Private registry address and path  
        image: /gateway:v1.7.2  
        pullSecrets: \[\]  
      ratelimit:  
\## Private registry address and path  
        image: "/ratelimit:05c08d03"  
        pullSecrets: \[\]
````

## ````
Step 3: Install the envoy-gateway chart in the Kubernetes cluster 

Use Helm to install the **envoy-gateway** chart in the `envoy-gateway-system` namespace:

- For online installation:

````
helm upgrade --install -n envoy-gateway-system envoy-gateway brix365/envoy-gateway -f values-envoy-gateway.yaml

- ````
For offline installation: Navigate to the directory containing the extracted chart and run:

````
helm upgrade --install envoy-gateway ./envoy-gateway -f values-envoy-gateway.yaml -n envoy-gateway-system

## ````
Step 4: Create a GatewayClass

The `GatewayClass` resource defines which controller handles `Gateway` resources across the cluster.

To create a `GatewayClass`, run:

````
kubectl apply -f - <<EOF  
apiVersion: gateway.networking.k8s.io/v1  
kind: GatewayClass  
metadata:  
  name: envoy-gateway  
spec:  
  controllerName: gateway.envoyproxy.io/gatewayclass-controller  
  parametersRef:  
    group: gateway.envoyproxy.io  
    kind: EnvoyProxy  
    name: custom-envoy-proxy  
    namespace: envoy-gateway-system  
EOF

## ````
Step 5: Create a TLS certificate

To enable HTTPS access, create a TLS certificate and add it to Kubernetes as a secret.

You can use either:

- A self-signed certificate (for details, see the [article on creating self-signed TLS/SSL certificates with OpenSSL](ssl-certificates.md).

- A certificate issued by a trusted Certificate Authority (CA).

To add the certificate to Kubernetes, create a TLS secret in the `kube-system` namespace using your **.crt** certificate file and  **.key **private key file:

````
kubectl create secret tls brix365-tls -n envoy-gateway-system \\  
\--cert=/etc/ssl/certs/selfsigned.crt \\  
\--key=/etc/ssl/private/selfsigned.key

````
where:

- `brix365-tls` is the secret name referenced in the `Gateway` resource.

- `--cert` is the path to the SSL/TLS certificate.

- `--key` is the path to the private key.

## Step 6: Create a Gateway

The `Gateway` resource defines how incoming traffic is handled in the cluster. It specifies listener ports, protocols, and TLS certificates used for HTTPS traffic:

1. Add the `Gateway` resource and link it to your `GatewayClass`:

````
kubectl apply -n envoy-gateway-system -f - <<EOF  
apiVersion: gateway.networking.k8s.io/v1  
kind: Gateway  
metadata:  
   name: envoy-gateway  
spec:  
   gatewayClassName: envoy-gateway  
   listeners:  
   - name: http  
     port: 80  
     protocol: HTTP  
     allowedRoutes:  
       namespaces:  
        from: All  
   - name: https  
     port: 443  
     protocol: HTTPS  
     tls:  
       mode: Terminate  
       certificateRefs:  
       - name: brix365-tls  
     allowedRoutes:  
       namespaces:  
         from: All  
EOF

````
where:

- `gatewayClassName` is the he controller that processes this `Gateway `resource.

- `listeners` is the list of entry points:

	- `port`: network port.

	- `protocol`: network protocol (HTTP or HTTPS).

	- `tls.mode: Terminate` terminates TLS connections at the `Gateway` layer.

	- `certificateRefs`  references the previously created Kubernetes TLS secret. The `name` value must match your [ certificate name](#add-certificate).

- `allowedRoutes` defines which namespaces are permitted to attach route resources.

2. Publish the `envoy-gateway` service using one of the following methods:

	- Via a third-party load balancer such as [MetalLB](#metallb-external-ip).

	- Via native `Gateway` features: to assign a `LoadBalancer` type to the service, run the following command (replace `<node\_ip>` with your node's accessible IP address, e.g., 192.168.1.10):

````
kubectl patch svc \$(kubectl get svc -n envoy-gateway-system -o name | grep envoy-gateway | head -1 | sed 's|service/||') -n envoy-gateway-system -p '\{"spec": \{"type": "LoadBalancer", "externalIPs":\["<node\_ip>"\]\}\}'

## ````
Step 7: Configure an external IP Address via MetalLB (optional)

Proper Gateway API functionality requires direct internet exposure with a public IP address assigned to a cluster node via a `NodePort` service. Once the `Gateway` resource is created, a `LoadBalancer` service is automatically generated to handle incoming traffic.

You can deploy MetalLB, which functions similarly to cloud-based load balancers. MetalLB utilizes Layer 2 (ARP/NDP) mechanisms or BGP routing to assign IP addresses to `LoadBalancer` services generated by `Gateway`.

**When to use MetalLB**

  
Deploying MetalLB is necessary when:

1. **The node lacks a public IP address**. MetalLB provides a Virtual IP (VIP) from a pre-configured IP address pool. In L2 mode, the active node accepts incoming traffic on this VIP, maintaining high availability (keepalive-like behavior).

2. **High availability is required**. If the active node fails in L2 mode, another node automatically takes over the VIP after ARP/NDP tables update. BGP mode offers even faster failover times via routing protocols.

3. **External clients need access to Gateway API services**. Services such as `LoadBalancer` referenced by the `Gateway` resource require a real IP address accessible outside the cluster. Additionally, direct access is required if specific IP addresses are set in the Gateway's `addresses` field.

When MetalLB is NOT required:

1. **A public IP address is already available on the node**. You can use a standard `NodePort` service with direct node access (for instance, if the `Gateway` uses `hostNetwork: true` or manually assigned `NodePort`.

2. **The cluster is hosted in a public cloud**. Cloud providers offer managed load balancers (NLB, ALB, L7 Load Balancers) that automatically assign IP addresses to `LoadBalancer` services.

3. **The Gateway controller binds directly to host ports**. If `hostNetwork` is set to` true`, Gateway controllers like `envoy-gateway` or `istio` accept connection directly on host ports without needing an external load balancer.

4. **You are running a non-production test environment**. A simpler and quicker approach is using a `NodePort` service bound to the node's IP address.

5. **Another load balancer (e.g., OpenELB) is already installed**. MetalLB will conflict with existing components if both attempt to manage the same IP address pools.

To check if your `Gateway` service has an external IP assigned, run:

````
kubectl get svc -n envoy-gateway-system

````
Check the `EXTERNAL-IP` column:

- If an IP address is displayed, external access is already configured.

- If it shows `<pending>` or `<none>`, no external load balancer is present:

	- In cloud Kubernetes clusters: The cloud load balancer will provision automatically—no action needed;

	- In on-premises or test environments: You can deploy MetalLB.

### Install MetalLB

To deploy MetalLB for external `Gateway` routing:

1. Install MetalLB:

````
kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.15.3/config/manifests/metallb-native.yaml

2. ````
Monitor pod startup status and wait for all components to run:

````
kubectl get pods -n metallb-system -w

3. ````
Configure an IP address pool:

````
kubectl apply -f - <<EOF  
apiVersion: metallb.io/v1beta1  
kind: IPAddressPool  
metadata:  
  name: host-ip-pool  
  namespace: metallb-system  
spec:  
  addresses:  
  - 192.168.29.176-192.168.29.176  
\---  
apiVersion: metallb.io/v1beta1  
kind: L2Advertisement  
metadata:  
  name: host-ip-adv  
  namespace: metallb-system  
spec:  
  ipAddressPools:  
  - host-ip-pool  
EOF

````
where `192.168.29.176` is a sample host IP address. Replace it with an available, externally accessible host IP address from your Kubernetes cluster.

4. Verify the `Gateway` service configuration:

````
kubectl get svc -n envoy-gateway-system

````
Your `Gateway` resource is now ready to route BRIX application traffic.

## Step 8: Configure BRIX to work with Gateway API

Once `Gateway` is installed, enable Gateway API support in your BRIX configuration.

In your `values-brix365.yaml` configuration file, add or modify the following parameters:

````
global:  
 …  
  gatewayAPI:  
    ## Enable Gateway API (HTTPRoute)  
    enabled: true  
    parentRefs:  
    - name: envoy-gateway  
      namespace: envoy-gateway-system

````
where:

- `enabled` enables Gateway API instead of Ingress;

- `parentRefs` specifies the target `Gateway` resource through which BRIX is exposed.

hese values must match the parameters of your previously created `Gateway` resource.

For details on editing system parameters, see the [article on modifying BRIX parameters](change-settings-enterprise.md).