Setting up Routing Rules using CRDs

Overview

Custom Resource Definitions (CRDs) are used to extend the Kubernetes APIs server with additional schemas. To know more, click here.

The Avi Kubernetes Operator (AKO) supports some CRD objects (installed through helm). The CRDs are relevant to:

Operators:
Users of this category:

  • Are aware of the Avi-related semantics
  • Have access to the Avi controller
  • Manage the lifecycle of AKO

Developers:
Users of this category:

  • Are owners of microservices deployed in Kubernetes
  • Are assumed to know basic routing principles but may not know the specifics of Avi attributes

Advantages of CRDs

Some load balancers allow configuration options via annotations.

The following are the advantages of using CRDs:

  • Versioning: CRDs allow AKO to version fields appropriately due to the dependency on the Avi Controller Versions. In general, this helps preserve unique states across various deployment versions.

  • Syntactical Validations: CRDs can be used to verify syntax at the time of creation of the CRD object. This saves API cost and facilitates quicker feedback using a combination of field constraints and effective status messages.

  • Role segregation: CRDs can benefit from the Role-based access control (RBAC) policies of Kubernetes and allow stricter access to a group of users.

Types of CRDs Supported in AKO

AKO categorizes the CRDs into:

  • Layer 7: These CRD objects are used to express layer 7 traffic routing rules.

  • Infrastructure: These CRD objects are used to control Avi’s infrastructure components like Ingress class, SE group properties etc.

Layer 7 CRDs

The following are the Layer 7 CRDs currently available in AKO:

HostRule

The HostRule CRD is used to express additional virtual host properties. The virtual host FQDN is matched from either the Kubernetes ingress or OpenShift route-based objects.

A sample HostRule CRD looks as shown below:


apiVersion: ako.vmware.com/v1alpha1
kind: HostRule
metadata:
  name: my-host-rule
  namespace: red
spec:
  virtualhost:
    fqdn: foo.region1.com # mandatory
    fqdnType: Exact
    enableVirtualHost: true
    tls: # optional
      sslKeyCertificate:
        name: avi-ssl-key-cert
        type: ref
      sslProfile: avi-ssl-profile
      termination: edge
    gslb:
      fqdn: foo.com
    httpPolicy: 
      policySets:
      - avi-secure-policy-ref
      overwrite: false
    datascripts:
    - avi-datascript-redirect-app1
    wafPolicy: avi-waf-policy
    applicationProfile: avi-app-ref
    analyticsProfile: avi-analytics-ref
    errorPageProfile: avi-errorpage-ref
    analyticsPolicy: # optional
      fullClientLogs:
        enabled: true
        throttle: HIGH
      logAllHeaders: true
    tcpSettings:
      listeners:
      - port: 8081
      - port: 6443
        enableSSL: true
      loadBalancerIP: 10.10.10.1
    aliases: # optional
    -  bar.com
    -  baz.com

Usage of HostRule

HostRule CRD can be created in a given namespace where the operator requires better control. This section explains the details and associated rules of using each field of the HostRule CRD.

Enable/Disable Virtual Host

HostRule CRD can be used to enable/disable corresponding virtual services created by AKO on Avi. This removes any virtual host related configuration from the data plane (Avi Service Engines) in addition to disabling traffic on the virtual host/FQDN.

This configuration is enabled by default. To disable virtual host, use

enableVirtualHost: _False_

Note: Enable/Disable virtual hosts can be applied only for secure FQDNs and cannot be applied for insecure routes.

Express httppolicyset Object Refs

HostRule CRD can be used to express httppolicyset references.

Note: The httppolicyset objects should be pre-created in the Avi 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 httpolicyset rules is in the same order they appear in the CRD definition. The list of httpolicyset rules are always interpreted as an AND operation.

AKO currently uses the 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. By default, the value of overwrite is set to False. To overwrite all httppolicyset objects on a SNI virtual service with the ones specified in the HostRule CRD, set the overwrite flag to True.

Express WAF Policy Object Refs

HostRule CRD can be used to express WAF policy references.

Note: Create the WAF policy object in the Avi 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.

Note: Create the application profile reference in the Avi Controller prior to the CRD creation. The application profile should 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 SSL Key and Certificates

For the Avi Kubernetes Operator 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
      termination: edge

Here, Name refers to an Avi object of the type Ref.

Currently, edge is the only type of termination that is supported.

Express Custom Analytics Profiles

HostRule CRD is used to express analytics profile references.
Ensure that the analytics profile reference is created in the Avi Controller prior to this CRD creation.
The analytics profiles can be used for various Network/HTTP/Healthscore analytics settings, log processing etc.
To express analytics profile references, use analyticsProfile: avi-analytics-ref.

Note: This property can be applied only for secure FQDNs and cannot be applied for insecure routes.

Express Custom Error Page Profiles

HostRule CRD can be used to express error page profile references.
Ensure that the error page profile reference is created in the Avi Controller prior to this CRD creation.
The error page profiles can be used to send a custom error page to the client generated by the proxy.
To express error page profile references, use errorPageProfile: avi-errorpage-ref.

Note: This property can be applied only for secure FQDNs and cannot be applied for insecure routes.

Express DataScripts

HostRule CRD can be used to express error DataScript references.
Ensure that the DataScript references are created in the Avi Controller prior to this CRD creation.
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.

To express DataScript references
datascript: - avi-datascript-redirect-app1

Express TLS Configuration

For the Kubernetes operator 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
      sslProfile: avi-ssl-profile
      termination: edge

Here,

  • name: Refers to an Avi object with the Type as ref.
  • sslProfile: 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 Avi.

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

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

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

Configure Aliases for FQDN

The Aliases field adds the ability to have multiple FQDNs configured under a specific route/ingress for the child VS 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.

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, etc.:


      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 disable 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 VSes and dedicated VSes. The tcpSettings block does not have any effect on child VSes.

In order to consume TCP setting configurations for parent VSes, the HostRule must be matched to a Shared/Dedicated VS FQDN, using the existing fqdn field in HostRule. Where dedicated virtual services are created corresponding to a single application, Shared virtual services host multiple application FQDNs. Therefore, in order to apply a HostRule to a dedicated VS, users can simply provide the application FQDN in the HostRule fqdn field. For Shared virtual services however, 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
    tcpSetting:
      listeners:
      - port: 6443
        enableSSL: true


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


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

Custom Ports:
In order 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 overwrites 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

Note: At least one of the ports that are mentioned in the setting must have the enableSSL field set to true.

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. In case of misconfigurations, AKO fails to configure the virtual service appropriately throwing and ERROR log for the same.


    tcpSettings:
      loadBalancerIP: 10.10.10.199

Note: The HostRule CRD is not aware of the misconfigurations while it is being created, therefore the HostRule will be Accepted nonetheless.

Status Messages

The status messages are used to give instant feedback about the reference objects specified in the HostRule CRD.

Following are some of the sample status messages:

Accepted HostRule Object


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

A Rejected HostRule Object


 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.

HostRule Deletion

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

HostRule Admission

A HostRule CRD is only admitted if all the objects referenced in it, exist in the Avi Controller. If after admission the object references are deleted out-of-band, then 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. In case of AKO reboots, the CRD that gets honored might not be the same as the one honored earlier.

HTTP Rule

The path matching rules in the ingress or route objects define traffic routing rules to the microservices. The HTTPRule CRD can be used as a complimentary object to control additional layer 7 properties like algorithm, hash, and tls re-encrypt use cases.

A sample HTTPRule object is as shown below:


apiVersion: ako.vmware.com/v1alpha1
kind: HTTPRule
metadata:
   name: my-http-rule
   namespace: purple-l7
spec:
  fqdn: foo.avi.internal
  paths:
  - target: /foo
    healthMonitors:
    - my-health-monitor-1
    - my-health-monitor-2
    loadBalancerPolicy:
      algorithm: LB_ALGORITHM_CONSISTENT_HASH
      hash: LB_ALGORITHM_CONSISTENT_HASH_SOURCE_IP_ADDRESS
    tls: ## This is a re-encrypt to pool
      type: reencrypt # Mandatory [re-encrypt]
      sslProfile: avi-ssl-profile
      destinationCA:  |-
        -----BEGIN CERTIFICATE-----
        [...]
        -----END CERTIFICATE-----

Note: The HTTPRule only applies to paths in the Ingress/Route objects which are specified in the same namespace as the HTTPRule CRD.

Usage of the HTTPRule CRD

The HTTPRule CRD does not have any Avi specific semantics. Hence you are free to express your preferences using this CRD without any knowledge of the Avi objects. Each HTTPRule CRD must be bound to a FQDN (both secure or insecure) to subscribe to rules for a specific hostpath combinations.

A HTTPRule CRD would be Rejected if the corresponding HostRule CRD does not exist.

Express Load Balancer Algorithm

The load balancer policies are a predefined set of values to choose from.
Currently, the following values are supported for load balancer policy:

  • LB_ALGORITHM_CONSISTENT_HASH
  • LB_ALGORITHM_CORE_AFFINITY
  • LB_ALGORITHM_FASTEST_RESPONSE
  • LB_ALGORITHM_FEWEST_SERVERS
  • LB_ALGORITHM_FEWEST_TASKS
  • LB_ALGORITHM_LEAST_CONNECTIONS
  • LB_ALGORITHM_LEAST_LOAD
  • LB_ALGORITHM_NEAREST_SERVER
  • LB_ALGORITHM_RANDOM
  • LB_ALGORITHM_ROUND_ROBIN
  • LB_ALGORITHM_TOPOLOGY

To configure the load balancer policy for a given ingress path, 


  target: /foo 
     loadBalancerPolicy:
       algorithm: LB_ALGORITHM_CONSISTENT_HASH

This rule is applied all paths matching /foo and subsets of /foo/xxx.

To know more, refer to the Load Balancing Algorithm article.

Express Health Monitors

The HTTPRule CRD can be used to express health monitor references.
Ensure that the health monitor reference is created in the Avi Controller prior to this CRD creation.

To express health monitor references, use: 


healthMonitors:
  - my-health-monitor-1
  - my-health-monitor-2

The health monitors can be used to verify server health. A server (Kubernetes pods in this case) is marked as UP only when all the health monitors return successful responses.

Reencrypt Traffic to the Services

While AKO can terminate TLS traffic, it also provides an option where the users can choose to re-encrypt the traffic between the Avi SE and the backend application server. The following option is provided for reencrypt:


    tls: ## This is a re-encrypt to pool
      type: reencrypt # Mandatory [re-encrypt]
      sslProfile: avi-ssl-profile

If the sslProfile is not defined, AKO defaults to sslProfile System-Standard to exchange the tls parameters like TLS versions, ciphers etc.

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 sslProfile System-Standard defined in Avi.

As a further enhancement, you can specify a destination CA, that uses a PKI profile to validate the server certificates.

Status Messages

The status messages are used to give instant feedback on whether a HTTPRule CRD was accepted or rejected.

Example of a HTTP Rule


$ kubectl get httprule
NAME            HOSTRULE                     STATUS     AGE
my-http-rules   default/secure-waf-policy    Accepted   5h34m

Avi Infra Setting

Avi Infra Setting provides a way to segregate Layer-4/Layer-7 virtual services to have properties based on different underlying infrastructure components, like Service Engine Group, intended VIP Network etc.

A sample Avi Infra Setting is as shown below:


apiVersion: ako.vmware.com/v1alpha1
kind: AviInfraSetting
metadata:
  name: my-infra-setting
spec:
  seGroup:
    name: compact-se-group
  network:
    vipNetworks:
      - networkName: vip-network-10-10-10-0-24
        cidr: 10.10.10.0/24
    nodeNetworks:
      - networkName: node-network-10-10-20-0-24
        cidrs:
        - 10.10.20.0/24
    enableRhi: true
    bgpPeerLabels:
      - peer1
      - peer2
  l7Settings:
    shardSize: MEDIUM

Avi Infra Setting with Services, Ingress or Routes

Avi Infra Setting is a cluster scoped CRD and can be attached to the intended Services, Kubernetes Ingresses and OpenShift Routes as discussed in this section.

Attaching Avi Infra Setting to Services

Avi Infra setting resources can be attached to Services using Gateway APIs, or simply by using annotations.

Using Gateway API
Gateway APIs provide interfaces to structure Kubernetes service networking.

AKO supports Gateway APIs via the servicesAPI flag in the values.yaml.

The Avi Infra Setting resource can be attached to a Gateway Class object, via the .spec.parametersRef as shown below:


apiVersion: networking.x-k8s.io/v1alpha1
kind: GatewayClass
metadata:
  name: avi-gateway-class
spec:
  controller: ako.vmware.com/avi-lb
  parametersRef:
    group: ako.vmware.com
    kind: AviInfraSetting
    name: my-infrasetting

Using Annotation
In case the servicesAPI flag is not set to True, and AKO is not watching over the Gateway APIs, Services of Type LoadBalancer can specify the Avi Infra Setting using an annotation as shown below:


 annotations:
    aviinfrasetting.ako.vmware.com/name: "my-infrasetting"

Attaching Avi Infra Setting to Ingress

Avi Infra Settings can be applied to Ingress resources, using the IngressClass construct. IngressClass provides a way to configure Controller-specific load balancing parameters and applies these configurations to a set of Ingress objects. AKO supports listening to IngressClass resources in Kubernetes version 1.19+. The Avi Infra Setting reference can be provided in the Ingress Class as shown below:


apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: avi-ingress-class
spec:
  controller: ako.vmware.com/avi-lb
  parameters:
    apiGroup: ako.vmware.com
    kind: AviInfraSetting
    name: my-infrasetting

Attaching Avi Infra Setting to Routes

Avi Infra Settings with OpenShift Routes, via the annotation shown below:


 annotations:
    aviinfrasetting.ako.vmware.com/name: "my-infrasetting"

Using Avi Infra Setting

Configure Service Engine Group

The AviInfraSetting CRD can be used to configure Service Engine Groups for virtual services created corresponding to Services/Ingresses/ Routes. Ensure the Service Engine Group is created and configured in the Avi Controller prior to this CRD creation.


  seGroup:
      name: compact-se-group

Configure VIP Networks

The AviInfraSetting CRD can be used to configure VIP networks for virtual services created corresponding to Services/Ingresses/Openshift Routes. Ensure the network is present in the Avi Controller prior to this CRD creation.


   network:
         vipNetworks:
           - networkName: vip-network-10-10-10-0-24
             cidr: 10.10.10.0/24

Note: Multiple network names can be added to the CRD (only in case of AWS cloud). The Avi virtualservices flag will acquire a VIP from each of these specified networks. If Avi fails to allocate a VIP due to IP exhaustion, this results in complete failure of entire request. This is same as vip allocation failures in single VIP.

AKO 1.5.1 updates the schema to provide VIP network information in AviInfraSetting CRD. For further details, refer to the Upgrade Notes.

Configure Pool Placement Networks

AviInfraSetting CRD can be used to configure Pool Placement Settings on the AKO created Pools in order for the Service Engines to place the Pools on appropriate interfaces.


    network:
      nodeNetworks:
        - networkName: node-network-10-10-20-0-24
          cidrs:
          - 10.10.20.0/24

If two Kubernetes clusters have overlapping Pod CIDRs, the service engine needs to identify the right gateway for each of the overlapping CIDR groups. This is achieved by specifying the right placement network for the pools that helps the Service Engine place the pools appropriately.

Enable/Disable Route Health Injection

Avi Infra Setting CRD is used to enable/disable Route Health Injection (RHI) on the virtual services created by AKO.


network:
      enableRhi: true

This overrides the global enableRHI flag for the virtual services corresponding to the Avi Infra Setting.

Enable/Disable Public IP

The AviInfraSetting CRD can be used to enable/disable Public IP on the virtual services created by AKO.


    network:
      enablePublicIP: true

Note: Enabling Public IP is only supported for public clouds.

Configure BGP Peer Labels for BGP Virtual Services

AviInfraSetting CRD can be used to configure BGP Peer labels for BGP virtual services. AKO configures the virtual sevices with the appropriate peer labels, only when enableRHI is enabled, either during AKO installation via helm chart’s values.yaml or via the AviInfraSetting CRD itself. If not set to true, the AviInfraSetting resource will be marked Rejected,


    bgpPeerLabels:
      - peer1
      - peer2

Use Dedicated VIP for Ingress

AviInfraSetting CRD can be used to allocate a dedicated vip per Ingress FQDN.


    l7Settings:
      shardSize: DEDICATED

For the subset of ingresses, that refer to an ingress class which in turn refers to an AviInfraSetting CRD setting that has shardSize as DEDICATED, will get VIP per Ingress FQDN.

Document Revision History

Date Change Summary
April 31, 2021 Added the sections for Configure VIP Networks, Enable/Disable Public IP, and Configure BGP Peer Labels for BGP Virtual Services supported in AKO version 1.5.1
April 28, 2021 Added the section for Avi Infra Setting CRD, supported in AKO version 1.4.1
December 18, 2020 Updated the CRDs supported in AKO version 1.3.1
July 22, 2020 Published the article for Custom Resource Definitions