Install Envoy Gateway

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.
  2. Fill out the configuration file.
  3. Install the Helm chart into your Kubernetes cluster.
  4. Create a GatewayClass.
  5. Create a TLS certificate.
  6. Create a Gateway resource.
  7. Configure an external IP address via MetalLB (optional).
  8. Configure BRIX to work with Gateway API.

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.

Шаг 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

  1. Copy the downloaded envoy-gateway-X.Y.Z.tgz chart archive to the target server where installation will take place.
  2. 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.
  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:

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.
  • allowedRoutes defines which namespaces are permitted to attach route resources.
  1. Publish the envoy-gateway service using one of the following methods:
    • Via a third-party load balancer such as MetalLB.
    • 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

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

kubectl get pods -n metallb-system -w

  1. 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.

  1. 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.

install-istio.html install-nodelocal-dns-cache.html