The alb module: examples

This section provides examples of the traffic-ingress infrastructure configuration for the alb module in different environments. The infrastructure is defined by ClusterALBInstance (cluster-scoped) and ALBInstance (namespaced) objects, while the way traffic is accepted is set by the spec.inlet.type parameter.

The module supports two inlet types:

• LoadBalancer — traffic is accepted through a Service object of the LoadBalancer type (cloud providers or bare metal with MetalLB). Available for both ClusterALBInstance and ALBInstance.
• HostPort — traffic is accepted on node ports without an external load balancer. Available for ClusterALBInstance only.

Examples of publishing applications and configuring routes are provided in the User guide, and gateway management and diagnostics are covered in the Administrator guide.

Example for a cloud provider (LoadBalancer inlet)

In cloud clusters, traffic is usually accepted through the LoadBalancer inlet: the platform creates a Service object of the LoadBalancer type, and the cloud provider assigns an external address to it.

apiVersion: network.deckhouse.io/v1alpha1
kind: ClusterALBInstance
metadata:
  name: main
spec:
  gatewayName: public-gw
  inlet:
    type: LoadBalancer
    loadBalancer: {}

To configure the cloud load balancer, specify the required Service annotations in the spec.inlet.loadBalancer.serviceAnnotations parameter. For example, for a Network Load Balancer in AWS:

apiVersion: network.deckhouse.io/v1alpha1
kind: ClusterALBInstance
metadata:
  name: main
spec:
  gatewayName: public-gw
  inlet:
    type: LoadBalancer
    loadBalancer:
      serviceAnnotations:
        service.beta.kubernetes.io/aws-load-balancer-type: "nlb"

Example for bare metal with the MetalLB load balancer

If there is no external cloud load balancer, you can use the metallb module for the LoadBalancer inlet.

1. Enable the metallb module:

   apiVersion: deckhouse.io/v1alpha1
   kind: ModuleConfig
   metadata:
     name: metallb
   spec:
     enabled: true
     version: 2

2. Create a MetalLoadBalancerClass object with an address pool. Place the MetalLB balancers on the same nodes as the Envoy Proxy pods of the alb module (in typical scenarios, frontend nodes labeled node-role.deckhouse.io/frontend are used for this):

   apiVersion: network.deckhouse.io/v1alpha1
   kind: MetalLoadBalancerClass
   metadata:
     name: alb
   spec:
     addressPool:
       - 192.168.2.100-192.168.2.150
     isDefault: false
     nodeSelector:
       node-role.deckhouse.io/frontend: ""
     type: L2

3. Create a ClusterALBInstance object, specifying the created load balancer class in the spec.inlet.loadBalancer.loadBalancerClass parameter:

   apiVersion: network.deckhouse.io/v1alpha1
   kind: ClusterALBInstance
   metadata:
     name: main
   spec:
     gatewayName: public-gw
     inlet:
       type: LoadBalancer
       loadBalancer:
         loadBalancerClass: alb
         serviceAnnotations:
           # Number of addresses allocated from the pool declared in MetalLoadBalancerClass.
           network.deckhouse.io/l2-load-balancer-external-ips-count: "1"

Example for bare metal without an external load balancer (HostPort inlet)

If no external load balancer is used and traffic must be accepted directly on node ports, use the HostPort inlet. This inlet type is available for ClusterALBInstance only.

apiVersion: network.deckhouse.io/v1alpha1
kind: ClusterALBInstance
metadata:
  name: main
spec:
  gatewayName: public-gw
  inlet:
    type: HostPort
    hostPort:
      httpPort: 80
      httpsPort: 443

To place the Envoy Proxy pods of the alb module only on dedicated nodes, set the nodeSelector and tolerations parameters for the ClusterALBInstance.

Accepting traffic behind an external L7 balancer (Proxy Protocol)

If the alb module runs behind an external L7 balancer (for example, Cloudflare, Qrator, or a third-party balancer), enable Proxy Protocol to receive the real client addresses. Additionally, use the spec.originalIPDetection parameter to restrict the list of subnets that are allowed to provide headers with the client address.

apiVersion: network.deckhouse.io/v1alpha1
kind: ClusterALBInstance
metadata:
  name: main
spec:
  gatewayName: public-gw
  inlet:
    type: HostPort
    hostPort:
      httpPort: 80
      httpsPort: 443
  useProxyProtocol: true
  originalIPDetection:
    setRealIPFrom:
      - 10.0.0.0/16

Separating public and administrative zones

If public and administrative traffic must be separated, create a dedicated Gateway object for each zone and restrict the acceptance of administrative traffic with the spec.acceptRequestsFrom parameter. The decision to allow a connection is made by the real connection address, not by the request headers.

The public gateway accepts traffic from anywhere:

apiVersion: network.deckhouse.io/v1alpha1
kind: ClusterALBInstance
metadata:
  name: public
spec:
  gatewayName: public-gw
  inlet:
    type: LoadBalancer
    loadBalancer: {}

The administrative gateway accepts traffic only from trusted subnets:

apiVersion: network.deckhouse.io/v1alpha1
kind: ClusterALBInstance
metadata:
  name: admin
spec:
  gatewayName: admin-gw
  inlet:
    type: LoadBalancer
    loadBalancer: {}
  acceptRequestsFrom:
    - 1.2.3.4/32
    - 10.0.0.0/16

Then create separate ListenerSet objects and routes for each gateway, attaching administrative applications to the admin-gw Gateway object and public ones to public-gw. Examples of creating routes are provided in the User guide.

Publishing within a namespace (LoadBalancer inlet via ALBInstance)

If the traffic-ingress infrastructure is managed by the application team within its own namespace, use the ALBInstance object. It supports the LoadBalancer inlet only, and the Gateway, ListenerSet, and route objects are located in the same namespace.

apiVersion: network.deckhouse.io/v1alpha1
kind: ALBInstance
metadata:
  name: app-gw
  namespace: prod
spec:
  gatewayName: app-gw
  inlet:
    type: LoadBalancer
    loadBalancer: {}

Once the ALBInstance object reaches the Ready state, create ListenerSet and HTTPRoute objects in the same namespace. A complete example is provided in the Publishing an application through an ALBInstance object section of the user guide.