Usage of HostRule

HostRule to Virtual Service Matching Using FQDN/FQDNType

A given HostRule is applied to a virtual service if the virtual service hosts the FQDN mentioned in the HostRule CRD. This FQDN must exactly match the one the virtual service is hosting. However, to simplify the user experience and provide an easy way to apply a HostRule to an individual or multiple virtual services, the

FQDNType

field can be employed. It provides great flexibility when it comes to specifying the string in the FQDN field.

With the FQDN Type, one of the three matching criteria listed below can be specified:

Exact
: Matches the string character by character to the virtual service FQDNs in an exact match fashion.
Wildcard
: Matches the string to multiple virtual service FQDNs and matches the FQDNs with the provided string as the suffix. The string must start with a * to qualify for wildcard matching.
fqdn: *.alb.vmware.com    
fqdnType: Wildcard
Contains
: Matches the string to multiple virtual service FQDNs and matches the FQDNs with the provided string as a substring of any possible FQDNs programmed by
AKO
.
fqdn: Shared-VS-L7-1  
fqdnType: Contains
The
fqdnType
field defaults to
Exact
.

Enable/Disable Virtual Host

HostRule CRD can be used to activate/deactivate corresponding virtual services created by

AKO

on

VMware Avi Load Balancer

. This removes any virtual host related configuration from the data plane (

VMware Avi Load Balancer

Service Engines) in addition to deactivating traffic on the virtual host/FQDN.

enableVirtualHost: false

This property can be applied only for secure FQDNs and cannot be applied for insecure routes. The default value is

true

.

Express httppolicyset Object Refs

HostRule CRD can be used to express

httppolicyset

references.

The

httppolicyset

objects must be pre-created in the

Avi Load Balancer Controller

.

httpPolicy:
  policySets:
  - "avi-secure-policy-ref"
  overwrite: false

The

httppolicyset

currently is only applicable for secure FQDNs and cannot be applied for insecure routes. The order of evaluation of the

httppolicyset

rules is in the same order they appear in the CRD definition. The list of

httppolicyset

rules is always intepreted as an

AND

operation.

AKO

currently uses

httppolicyset

objects on the SNI virtual services to route traffic based on host/path matches. These rules are always at a lower index than the

httppolicyset

objects specified in the CRD object. If a user wants to overwrite all

httppolicyset

objects on an SNI virtual service with the ones specified in the HostRule CRD, the

overwrite

flag can be set to

true

. The default value for

overwrite

is

false

.

Express WAF Policy Object Refs

HostRule CRD can be used to express WAF policy references. Create the WAF policy object in the

Avi Load Balancer Controller

prior to the CRD creation as follows:

wafPolicy: "avi-waf-policy"

This property can be applied only for secure FQDNs and cannot be applied for insecure routes. WAF policies are useful when deep layer 7 packet filtering is required.

Express Custom Application Profiles

HostRule CRD can be used to express application profile references. Create the application profile reference in the

Avi Load Balancer Controller

prior to the CRD creation. The application profile must be of Type

APPLICATION_PROFILE_TYPE_HTTP

.

applicationProfile: "my-app-ref"

This property can be applied only for secure FQDNs and cannot be applied for insecure routes. The application profiles can be used for various HTTP/HTTP2 protocol settings.

Express Custom ICAP profile

HostRule CRD can be used to express a single ICAP profile reference per host. The ICAP profile reference must have been created in the

Avi Load Balancer Controller

prior to this CRD creation.

icapProfile:
- avi-icap-ref

This property can be applied for both secure and insecure hosts through EVH parent and child virtual services, SNI child Virtual Services, and dedicated virtual services. The ICAP Profile can be used for transporting HTTP traffic to 3rd party services for processes such as content sanitization and antivirus scanning. For more information, see Internet Content Adaptation Protocol topic in the

VMware Avi Load Balancer

Configuration Guide

Express Custom Analytics Profiles

HostRule CRD is used to express analytics profile references.Create the analytics profile reference in the

Avi Load Balancer Controller

prior to this CRD creation.

analyticsProfile: avi-analytics-ref`

This property can be applied only for secure FQDNs and cannot be applied for insecure routes. The analytics profiles can be used for various Network/HTTP/Health score analytics settings, log processing, and so on.

Express Custom Error Page Profiles

HostRule CRD can be used to express error page profile references.Create the error page profile reference in the

Avi Load Balancer Controller

prior to this CRD creation.

errorPageProfile: avi-errorpage-ref

This property can be applied only for secure FQDNs and cannot be applied for insecure routes. The error page profiles can be used to send a custom error page to the client generated by the proxy.

Express DataScripts

HostRule CRD can be used to express error DataScript references.Create the DataScript references in the

Avi Load Balancer Controller

prior to this CRD creation.

datascripts:    
- avi-datascript-redirect-app1

This property can be applied only for secure FQDNs and cannot be applied for insecure routes. The DataScripts can be used to apply custom scripts to data traffic. The order of evaluation of the DataScripts is in the same order they appear in the CRD definition.

Express TLS Configuration

For the

AKO

to control the TLS termination from a privileged namespace, the HostRule CRD can be created in such a namespace.

tls:
 sslKeyCertificate:
   name: avi-ssl-key-cert
   type: ref
   alternateCertificate:
     name: avi-ssl-key-cert2
     type: ref
 sslProfile: avi-ssl-profile
 termination: edge

Here,

name

refers to an

VMware Avi Load Balancer

object with the

Type

as

ref

. Alternatively, we also support a kubernetes

Secret

to be specified where the

sslkeyandcertificate

object is created by

AKO

using the

Secret

.

tls:
 sslKeyCertificate:
   name: k8s-app-secret
   type: secret
 termination: edge

Currently, only Edge is supported as the type of termination.

An

alternateCertificate

option is provided if the application needs to be configured to provide multiple server certificates, typically when trying to configure both RSA and ECC signed certificates. The

Avi Load Balancer Controller

allows a virtual service to be configured with two certificates at a time, one each of RSA and ECC. This enables the Controller to negotiate the optimal algorithm or cipher with the client. If the client supports ECC, the ECC algorithm is preferred, and RSA is used as a fallback in cases where the clients do not support ECC.

The

sslProfile

, additionally, can be used to determine the set of SSL versions and ciphers to accept for SSL/TLS terminated connections. If the

sslProfile

is not defined,

AKO

defaults to the

sslProfile

System-Standard-PFS

defined in

VMware Avi Load Balancer

.

Configure GSLB FQDN

A GSLB FQDN can be specified within the HostRule CRD. This is only used if

AKO

is used with

AMKO

and not otherwise.

gslb:      
fqdn: foo.com

This additional FQDN inherits all the properties of the root FQDN specified under the virtualHost section. Use this flag if you would want traffic with a GSLB FQDN to get routed to a site local FQDN. For example, in the above CRD, the client request from a GSLB DNS will arrive with the host header as

foo.com

to the VIP hosting

foo.region1.com

in

region1

. This CRD property would ensure that the request is routed appropriately to the backend service of

foo.region1.com

.

In SNI mode, if a GSLB FQDN is specified for an insecure hostname (defined in an Ingress or OpenShift route) or a secure hostname in an OpenShift route with the

insecureEdgeTerminationPolicy

set to

Allow

, the GSLB FQDN can only be defined for a limited number of such hostnames per shared parent virtual service. This is because specifying a GSLB FQDN adds one httppolicyset to the parent-shared virtual service for each hostname in the above category. However, there is a limitation on the number of httppolicysets that can be associated with a virtual service, depending on the license. For example, an Enterprise license supports a limit of sixteen (16). Therefore, if a SMALL shard size is used in the

AKO

configuration and

AKO

creates only one shared parent virtual service, the GSLB FQDN will be configured for the first sixteen hostnames processed in the above category.

This knob is currently supported only with the SNI model and not with Enhanced Virtual Hosting model. The

includeAliases

is used by

AMKO

. Whenever a GSLB FQDN is provided, and the

useCustomGlobalFqdn

is set to

true

in

AMKO

, a GSLB Service is created for the GSLB FQDN instead of the local FQDN(hostname). For more information, see

Deriving GslbService FQDNs

topic in the

Avi Multi-Cluster Kubernetes Operator

Guide.

When this flag is set to

false

, the Domain Name of the GSLB Service is set to the GSLB FQDN. When this flag is set to

true

in addition to the GSLB FQDN,

AMKO

adds the FQDNs mentioned under aliases to domain names of the GSLB Service.

Configure Aliases for FQDN

The Aliases field adds the ability to have multiple FQDNs configured under a specific route/ingress for the child virtual service instead of creating the route/ingress multiple times.

aliases:
   - bar.com  
   - baz.com

This list of FQDNs inherits all the properties of the root FQDN specified under the virtualHost section. Traffic arrives with the host header as

bar.com

to the VIP hosting

foo.region1.com

and this CRD property would ensure that the request is routed appropriately to the backend service of

foo.region1.com

.

Aliases field must contain unique FQDNs and must not contain GSLB FQDN or the root FQDN. Users must ensure that the

fqdnType

is set as

Exact

before setting this field.

Express Custom Network Security Policy Object Ref

HostRule CRD can be used to express network security policy object references. The network security policy object must be created in the

Avi Load Balancer Controller

before this CRD creation. The

networkSecurityPolicy

setting, in addition to any other parameters provided in the HostRule, is only applied to Parent virtual services and dedicated virtual services. The

networkSecurityPolicy

setting does not have any effect on child virtual services.

networkSecurityPolicy: avi-network-security-policy-ref

This property is available only in HostRule v1beta1 schema definition.
Since the HostRule CRD is unknown of the misconfigurations that may occur if it is applied to a Child virtual service during the creation process, the HostRule will still be accepted.
AKO
will print a warning message regarding this.

Configure Analytics Policy

The HostRule CRD can be used to configure analytics policies such as enable/disable non-significant logs, throttle the number of non-significant logs per second on each SE, enable/disable logging of all headers, and, so on:

analyticsPolicy:
fullClientLogs:
enabled: true
throttle: HIGH
logAllHeaders: true

The throttle will be in effect only when

enabled

is set to

true

. The possible values of throttle are

DISABLED (0)

,

LOW (50)

,

MEDIUM (30)

, and HIGH (10).

AKO

sets the duration of logging the non-significant logs to infinity by default.It is recommended to deactivate the non-significant logs when it is no longer required.

Configure TCP Settings

The TCP Settings section is responsible for configuring Parent virtual service specific parameters using the HostRule CRD. The

tcpSettings

block, in addition to any other parameters provided in the HostRule, is only applied to Parent virtual services and dedicated virtual services.

The

tcpSettings

block does not have any effect on child VSes. To consume TCP setting configurations for parent virtual services, the HostRule must be matched to a Shared/Dedicated VS FQDN, using the existing

fqdn

field in HostRule. When dedicated virtual services are created corresponding to a single application, shared virtual services host multiple application FQDNs. Therefore, to apply a HostRule to a dedicated VS, users can simply provide the application FQDN in the HostRule

fqdn

field. For Shared virtual services, users can either provide the

AKO

programmed shared virtual service FQDN, or utilize the

fqdnType: Contains

parameter with the Shared virtual service name itself.

fqdn: foo.com     # dedicated VS
fqdnType: Exact
tcpSettings:
 listeners:
 - port: 6443
   enableSSL: true


fqdn: Shared-VS-L7-1.admin.avi.com    # AKO configured Shared VS fqdn
fqdnType: Exact
tcpSettings:
 loadBalancerIP: 10.10.10.1


fqdn: Shared-VS-L7-1      # bound for clusterName--Shared-VS-L7-1
fqdnType: Contains
tcpSettings:
 loadBalancerIP: 10.10.10.1

Custom Ports

: To overwrite the ports opened for the virtual services created by

AKO

, users can provide the port details under the listeners setting. The ports mentioned under this section overwrite the default open ports, 80 and 443 (SSL enabled). This is applicable only for Shared or Dedicated virtual services.

tcpSettings:
 listeners:
 - port: 80
 - port: 8081
 - port: 6443
   enableSSL: true

At least one of the ports that are mentioned in the setting must have the
enableSSL
field set to
true
.
If
enableHTTP2
is set to
true
, then the HTTP2 traffic will be supported from client to Service Engine.

L7 Static IP

: The

loadBalancerIP

field can be used to provide a valid, preferred IPv4 address for L7 virtual services created for the Shared or Dedicated virtual service. The preferred IP must be part of the IPAM configured for the Cloud, and must not overlap with any other IP addresses already in use. When misconfigurations occur,

AKO

fails to configure the virtual service, appropriately throwing an ERROR log for the same.

tcpSettings:  
loadBalancerIP: 10.10.10.199

The HostRule CRD is not aware of the misconfigurations while it is being created and so, the HostRule will be accepted.

L7Rule

The

L7rule

field can be used to specify the name of L7Rule CRD. It is used to modify select VS Properties which are not part of HostRule CRD.

This property is available only in HostRule v1beta1 schema definition.

Enable Regular Expression in path

Express Application Root Redirect path

fqdn: test-avi.vmware.com
fqdnType: Exact
applicationRootPath: /foo
 

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: test-ingress
spec:
rules:
- host: test-avi.vmware.com
  http:
    paths:
      - backend:
          service:
            name: my-app-0
            port:
              number: 80
        path: /bar
        pathType: ImplementationSpecific
      - backend:
          service:
            name: my-app-1
            port:
              number: 443
        path: /
        pathType: Exact
tls:
- hosts:
    - test-avi.vmware.com
  secretName: ingress-secret
 

Status Messages

Accepted HostRule Object:

$ kubectl get hr
NAME                 HOST                  STATUS     AGE
secure-waf-policy    foo.avi.internal      Accepted   3d3h

A HostRule is accepted only when all the reference objects specified inside it exist in the

Avi Load Balancer Controller

.

A Rejected HostRule Object:

$ kubectl get hr
NAME                     HOST                  STATUS     AGE
secure-waf-policy-alt    foo.avi.internal      Rejected   2d23h

The reason for rejection can be obtained from the status:

status:
error: duplicate fqdn foo.avi.internal found in default/secure-waf-policy-alt
status: Rejected

Caveats

Converting Insecure FQDNs to Secure

The HostRule CRD can be used to convert an insecure host FQDN to a secure one. This is done by specifying a TLS section in the CRD object. The

sslKeyCertificate

is provided for the FQDN, will override all

sslkeyandcertificates

generated for the FQDN. This is useful if:

The operator wants to convert an insecure ingress FQDN to secure.
The operator wants to override any existing secrets for a given host FQDN and define TLS termination semantics.

Certificate Precedence

If the ingress object specifies a secret for SNI termination and the HostRule CRD also specifies a

sslKeyCertificate

for the same

virtualhost

, the

sslkeycertificate

in the HostRule CRD will take precedence over the Secret object associated with the Ingress.

HostRule Deletion

If a HostRule is deleted, all the settings for the FQDNs are withdrawn from the

Avi Load Balancer Controller

.

HostRule Admission

A HostRule CRD is only admitted if all the objects referenced in it, exist in the

Avi Load Balancer Controller

. If after admission, the object references are deleted out-of-band, the

AKO

does not re-validate the associated HostRule CRD objects. The user needs to manually edit or delete the object for new changes to take effect.

Duplicate FQDN rules

Two HostRule CRDs cannot be used for the same FQDN information across namespaces. If

AKO

finds a duplicate FQDN in more than one HostRules,

AKO

honors the first HostRule that gets created and rejects the others. When

AKO

reboots occur, the CRD that gets honored might not be the same as the one honored earlier.