Admin guide

The process of deploying an application using the alb module includes the following steps:

1. Create a cluster-scoped Gateway object (using the ClusterALBInstance resource) or a namespaced Gateway object (using the ALBInstance resource) (gateway).
2. Create a ListenerSet object (manages the reception of incoming requests), which is bound to the Gateway object created in the previous step.
3. Create objects (routes) to route incoming requests to the application and bind them to the ListenerSet. The HTTPRoute, GRPCRoute, TCPRoute, and TLSRoute objects are used for routing (the appropriate one is selected based on the type of traffic to the published application).

Use with other modules and third-party solutions

The alb module can be used in a cluster simultaneously with the ingress-nginx module. In this case, it is recommended to use a separate ClusterIssuer object for them.

This allows you to issue separate certificates for the Ingress scheme (using the ingress-nginx module) and for the Gateway API scheme (using the alb module), managing the settings and certificate lifecycles independently.

Use of third-party Gateway API implementations is supported, provided that the cluster uses the following Gateway API object storage versions compatible with the alb module controller:

• BackendTLSPolicy: v1;
• GatewayClass: v1;
• Gateway: v1;
• ListenerSet: v1;
• GRPCRoute: v1;
• HTTPRoute: v1;
• ReferenceGrant: v1beta1;
• TCPRoute: v1alpha2;
• TLSRoute: v1.

During startup, the alb module controller checks the currently stored versions of Gateway API objects. If it detects a mismatch between the installed and required versions, it stops and does not proceed. If a given Gateway API object type is completely absent from the cluster, the controller automatically creates the required CRD version and then continues startup.

To manually verify version compatibility of the installed Gateway API objects in the cluster, use:

declare -A want=([gatewayclasses.gateway.networking.k8s.io]=v1 [gateways.gateway.networking.k8s.io]=v1 [grpcroutes.gateway.networking.k8s.io]=v1 [httproutes.gateway.networking.k8s.io]=v1 [listenersets.gateway.networking.k8s.io]=v1 [referencegrants.gateway.networking.k8s.io]=v1beta1 [tcproutes.gateway.networking.k8s.io]=v1alpha2 [tlsroutes.gateway.networking.k8s.io]=v1 [backendtlspolicies.gateway.networking.k8s.io]=v1); for crd in "${!want[@]}"; do got="$(d8 k get crd "$crd" -o jsonpath='{.spec.versions[?(@.storage==true)].name}' 2>/dev/null || true)"; if [[ "$got" == "${want[$crd]}" ]]; then echo "$crd OK storage=$got"; else echo "$crd FAILED cluster=${got:-MISSING} expected=${want[$crd]}"; fi; done | sort

Otherwise, the module only configures and manages Gateway objects associated with its designated GatewayClass, which minimizes the risk of conflicts when third-party Gateway API implementations are present.

Features of using the ClusterALBInstance and ALBInstance resources

You can use either the ClusterALBInstance or ALBInstance resource to publish user applications. The ClusterALBInstance resource can also be used to access DKP cluster system domains. In this case, before enabling the alb module, ensure that the global parameter publicDomainTemplate is specified. After enabling the module, configure access to system components via ClusterALBInstance.

Configuring access to DKP system components using the Gateway API

To grant access to the DKP cluster’s system domains using the alb module, specify the default gateway. To do this, follow these steps:

1. Enable the alb module in cluster configuration. Module settings are documented on the Configuration page.
2. Create a cluster-scoped ClusterALBInstance object with the required inlet type and settings.
3. Set spec.defaultDeckhouseGateway: true on that ClusterALBInstance object.
4. After applying the changes, check the status of the ClusterALBInstance object:

d8 k get clusteralbinstances

The ClusterALBInstance object must expose the managed Gateway object, and the instance itself must move to a ready state. After that, system ListenerSet objects and HTTPRoute objects must appear in the corresponding system namespaces of the cluster.

Algorithm for selecting the default DKP gateway when using multiple ClusterALBInstances

A cluster can have multiple cluster-scoped gateways simultaneously, each marked as the default gateway (with the defaultDeckhouseGateway: true flag set for the corresponding ClusterALBInstance). In that case, the default gateway is the Gateway object created by the oldest ClusterALBInstance object according to creationTimestamp. If no ClusterALBInstance object is marked as the default gateway, DKP allows the Gateway object created by the alb module for the instance named main to be used as the default gateway.

Changing the default DKP gateway

If DKP system domains need to move to another Gateway object, complete these steps:

1. Create a new ClusterALBInstance object that describes the required settings and set spec.defaultDeckhouseGateway: true on it.
2. In the current ClusterALBInstance object that provides the default DKP gateway, set spec.defaultDeckhouseGateway: false.
3. Check that all system ListenerSet objects now point to the new Gateway object in spec.parentRef.

Changing the inlet while keeping the current Gateway

To change the inlet used for an existing Gateway object, complete these steps:

1. Create a new ClusterALBInstance object or ALBInstance object with a different name but the same spec.gatewayName, using the required inlet type.
2. Check that the new traffic path works correctly.
3. Delete the obsolete ClusterALBInstance object or ALBInstance object.

Because gatewayName does not change, the Gateway object stays the same. In most cases, the ListenerSet object and routes do not need to be rewritten.

Opening an additional TCP port on the cluster-wide gateway

If a dedicated TCP port is needed in addition to the default HTTP/HTTPS listeners, add the spec.inlet.additionalPorts field to the corresponding ClusterALBInstance object, for example:

spec:
  gatewayName: public-gw
  inlet:
    type: LoadBalancer
    loadBalancer: {}
    additionalPorts:
      - port: 9000
        protocol: TCP

The controller adds a corresponding TCP traffic handler to the managed Gateway object with a section name (sectionName) like tcp-port-9000. Then a TCPRoute object may be created that points directly to that Gateway object and that sectionName:

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: app-tcp
  namespace: prod
spec:
  parentRefs:
    - name: public-gw
      namespace: d8-alb
      sectionName: tcp-port-9000
      port: 9000
  rules:
    - backendRefs:
        - name: tcp-svc
          port: 9000

If the same Gateway object is shared by several ClusterALBInstance objects, the additionalPorts set that actually reaches the Gateway object comes from the oldest ClusterALBInstance object. The others may report port conflicts in status.

Viewing Envoy Proxy Configuration

For troubleshooting, it is useful to inspect the configuration that the controller and the proxy configurator pushed into the Envoy Proxy instance that serves the Gateway object.

To do this, follow these steps:

1. Select an Envoy Proxy pod for the required Gateway object:

   d8 k -n d8-alb get pods -l alb.deckhouse.io/gateway=shared-gateway

2. Get the configuration through the following command:

   d8 k -n d8-alb exec -it <envoy-proxy-pod-name> pilot-agent request GET /config_dump

   If only one section of the configuration is needed, the required section may be requested explicitly:

   d8 k -n d8-alb exec -it <envoy-proxy-pod-name> pilot-agent request GET /config_dump?resource=dynamic_listeners
   d8 k -n d8-alb exec -it <envoy-proxy-pod-name> pilot-agent request GET /config_dump?resource=dynamic_route_configs
   d8 k -n d8-alb exec -it <envoy-proxy-pod-name> pilot-agent request GET /config_dump?resource=dynamic_active_clusters

This makes it easy to check whether the expected traffic handlers, virtual hosts, and upstream clusters appeared after changes to the ListenerSet object or Route object.