F5BigCneIrule

Overview

The F5BigCneIrule Custom Resource (CR) enables F5’s powerful iRules feature. iRules greatly extend how application traffic is processed by the Traffic Management Microkernel (TMM) Proxy Pod. You can add the iRule in the F5BigCneIrule CR, and then that can be attached to a F5BigContextSecure or any other usecase CRs (example: DNS Virtual Server and F5BigAlgFtp). Additional information about F5’s iRules can be found at the iRules Home.

This document guides you through understanding, configuring and installing an F5BigCneIrule and F5BigContextSecure CR.

CR parameter

Parameter	Description
spec.iRule	Specifies both single-line or multi-line iRule commands that can be attached to Context Secure or DNS Virtual Server CRs.

CR Example

apiVersion: k8s.f5net.com/v1
kind: F5BigCneIrule
metadata:
  name: cnfs-dns-irule
  namespace: cnf-gateway
spec:
  iRule: >
    when DNS_REQUEST {
      if { [IP::addr [IP::remote_addr] equals 10.10.1.0/24] } {
        cname cname.siterequest.com
      } else {
        host 10.20.20.20
      }
    }

CR shortName

CR shortNames provide an easy way to view installed CRs, and their configuration parameters. The CR shortName can also be used to delete the CR instance. The F5BigCneIrule CR shortName is irule.

View CR instance:

kubectl get irule -n <namespace>

View CR configuration:

kubectl get irule -n <namespace> -o yaml

iRule Events

Important: All iRules Events that have been supported by BIP Next will now be supported by CNF.

Note: Please notice that CNF doesn’t support HTTP_REQUEST and HTTP_RESPONSE iRules Events.

For example:

1. RULE_INIT : Triggered when an iRule is added or is modified.

   Examples:

    when RULE_INIT {
       set ::count 0
    }
   

    # static namespace is available in 10.0.0+
    when RULE_INIT {
      set ::count 0
    }
   

2. CLIENT_ACCEPTED with TCP : Triggered when a client has established a connection with TCP.

   Example:

     when CLIENT_ACCEPTED {
        log local0.debug "CLIENT_ACCEPTED"
        TCP::collect
       }
   

3. CLIENT_ACCEPTED with UDP : Triggered when a client has established a connection with UDP.

   Example:

     when CLIENT_ACCEPTED {
        log local0. "Client connection accepted over UDP."
     }
   

4. CLIENT_DATA with TCP : Triggered each time new data is received from the client while the connection is in “collect” state with TCP.

   Example:

     when CLIENT_DATA {
        set tcplen [TCP::payload length]
        log local0.debug "CLIENT_DATA ($tcplen)"
   
         #Assume that you need at least 20 bytes of data for some purpose
           if { $tcplen >= 20 } {
             log local0.debug "Collected at least 20 bytes. releasing"
             #Release collected data
             TCP::release
             # Collect new data - CLIENT_DATA will be called again
             TCP::collect
            }
     }
   

5. CLIENT_DATA with UDP : Triggered each time new data is received from the client while the connection is in “collect” state with UDP.

   Example:

    when CLIENT_DATA {
      if { [UDP::payload 50] contains "XYZ" } {
         pool xyz_servers
         persist uie "[IP::client_addr]:[UDP::client_port]" 300
     }
   }
   

6. DNS_REQUEST : Triggered when the system receives a DNS request.

   Example:

   when DNS_REQUEST {
    if { [IP::addr [IP::remote_addr] equals 10.10.1.0/24] } {
       cname cname.siterequest.com
    } else {
      host 10.20.20.20
    }
   }
   

7. DNS_RESPONSE : Triggered when the system responds to a DNS request.

   Example:

   when DNS_RESPONSE {
      if { [LB::server addr] equals "10.10.10.10" } {
         log local0. "Alert: [DNS::rrname] resolved to backup server"
      }     
    }
   

iRule Validation

If there are any validation errors, like syntax, semantics, and referential integrity errors, then the F5Ingress Validator Webhook will not allow the iRule to be applied.

Example:

Error from server: error when creating "irule_cnf.yaml": admission webhook "f5validate. f5net .com" denied the request: undefined procedure: [RESOLV:: RESOLV::lookup nt found".]

Requirements

Ensure you have:

• Installed the BIG-IP Controller Pod.
• A Linux based workstation.

Installation

Use these steps to install F5BigCneIrule and F5BigContextSecure CRs.

Tip: Open a second shell to view the CNFs Event Logs while installing.

1. Copy the example F5BigCneIrule CR into a YAML file:

   apiVersion: k8s.f5net.com/v1
   kind: F5BigCneIrule
   metadata:
     name: cnf-irule
     namespace: cnf-gateway
   spec:
     iRule: >
       when CLIENT_DATA {
         if { [UDP::payload 50] contains "XYZ" } {
            pool xyz_servers
            persist uie "[IP::client_addr]:[UDP::client_port]" 300
         }
       }
   

2. Install the F5BigCneIrule CR:

   kubectl apply -f cnf-irule-cr.yaml
   

   In this example, the BIG-IP Controller logs indicate the F5BigCneIrule CR was added/updated:

   I0202 12:00:00.12347   1 event.go:282 Event(v1.ObjectReference{Kind:"F5Irule",
   F5Irule cnf-gateway/cnf-irule was added/updated
   

3. Copy the example F5BigContextSecure CR into a YAML file:

   apiVersion: "k8s.f5net.com/v1"
   kind: F5BigContextSecure
   metadata:
     name: "cnf-context"
     namespace: "cnf-gateway"
   spec:
     destinationAddress: "10.20.2.37/32"
     ipv6destinationAddress: "2002::10:20:2:37/128"
     destinationPort: 80
     ipProtocol: "tcp"
     profile: "tcp"
     iRules: ["cnf-irule"]
   

4. Install the F5BigContextSecure CR:

   kubectl apply -f cnf-context-cr.yaml
   

   In this example, the BIG-IP Controller logs indicate the F5BigContextSecure CR was added/updated:

   I0202 12:00::00.12345  1 event.go:282] Event(v1.ObjectReference{Kind:\"F5ContextSecure\",
   ContextSecure cnf-gateway/cnf-context-secure was added/updated
   

Note: The DNS iRule CRs can be attached to DNS Virtual Server CR, for example, see the following steps.

1. Copy the example DNS F5BigCneIrule CR into a YAML file:

   apiVersion: k8s.f5net.com/v1
   kind: F5BigCneIrule
   metadata:
     name: dns-req
     namespace: cnf-gateway
   spec:
     iRule: >
     when DNS_REQUEST {
         # set debug level
         # 0 no debugging
         # 1 light debugging
         # 2 full debugging 
   
    set debugging 2
   
    set request_name [string tolower [DNS::question name]]
    set request_name [string trimleft $request_name "-"]
   
    if { $debugging >= 1 } {
        log local0.debug "query contains: $request_name"
    }
   
    if { $debugging >= 1 } {
        if { $debugging >= 2 } {
            log local0.debug " [DNS::question name] Request for local DNS Expres FQDN. Exit the irule"
        }
        DNS::drop  
        return
    } elseif { $debugging >= 1 } {
        if { $debugging >= 2 } {
            log local0.debug " [DNS::question name] Request not local: bypass dnsx"
        }
        DNS::disable dnsx
    } else {   
    }
   } 
   

2. Install the DNS F5BigCneIrule CR:

   kubectl apply -f cnf-irule-cr.yaml
   

   In this example, the BIG-IP Controller logs indicate the DNS F5BigCneIrule CR was added/updated:

   I0202 12:00:00.12347   1 event.go:282 Event(v1.ObjectReference{Kind:"F5Irule",
   F5Irule cnf-gateway/cnf-irule was added/updated
   

3. Copy the example DNS Virtaul Server CR into a YAML file i.e., Copy the example F5BigDnsCache CR into a YAML file:

   apiVersion: "k8s.f5net.com/v1"
   kind: F5BigDnsCache
   metadata:
     name: "cnf-dnscache"
     namespace: "cnf-gateway"
   spec:
     cacheType: transparent
     transparent:
       localZones:
        - name: example.com
        zoneType: static
        records:
          - example.com. IN AAAA 2002::10:11:12:13
   

4. Install the F5BigDnsCache CR:

   kubectl apply -f cnf-dnscache-cr.yaml
   

   In this example, the BIG-IP Controller logs indicate the F5BigDnsCache CR was added/updated:

   I0208 12:00:00.12345   1 event.go:282] Event(v1.ObjectReference{Kind:"F5Dnscache", 
   F5Dnscache cnf-gateway/cnf-dnscache was added/updated
   

5. Copy the F5BigDnsApp into a YAML file:

   apiVersion: "k8s.f5net.com/v1"
   kind: F5BigDnsApp
   metadata:
     name: "cnf-dnsapp"
     namespace: "cnf-gateway"
   spec:
     ipProtocol: "udp"
     iRules: ["dns-req"] 
     destination:
       ipv6Address: "2002::192:168:100:201"
       port: 53
    snat:
     type: "automap"
    dns:
      dnsCache: "cnf-dnscache"
      dns64Mode: "secondary"
      dns64Prefix: "64:ff9b::"
      dns64AdditionalSectionRewrite: "v4-only"
    pool:
      members:
        - address: "2002::10:10:10:100"
        - address: "2002::10:10:10:101"
    monitors:
      dns:
        enabled: true
        queryName: "webapp.net."
        queryType: "aaaa"
        recv: "2002::10:10:20:200"
   

6. Install the F5BigDnsApp CR:

   kubectl apply -f cnf-dnsapp-cr.yaml
   

   In this example, the BIG-IP Controller logs indicate the F5BigDnsApp CR was added/updated:

   I0208 12:00:00.12345   1 event.go:282] Event(v1.ObjectReference{Kind:"F5Dns",
   F5Dns cnf-gateway/cnf-dnsapp was added/updated
   

iRules statistics

If the TMM Debug sidecar is enabled (default), use the steps below to verify iRules statistics.

1. Log in to the TMM debug Pod:

   In this example, the TMM debug container is in the cnf-gateway namespace:

   kubectl exec -it deploy/f5-tmm -c debug -n cnf-gateway -- bash
   

2. Verify the iRules statstics applied in F5BigContextSecure CR:

   tmctl -d /var/tmstat/blade/ -w 200 rule_stat
   

   name           event_type   priority  failures  aborts  total_ executions  avg_cycles   max_cycles  min_cycles
   ------------   -----------  --------  --------  ------  -----------------  -----------  ----------  ----------   
   irule          CLIENT_DATA         0         0       0                  2       84793        87464        0             
   

Multiple iRules with F5BigContextSecure and DNS Virtual Server CRs

Example of multiple iRules applied in F5BigContextSecure CR:

  apiVersion: "k8s.f5net.com/v1"
  kind: F5BigContextSecure
  metadata:
    name: "cnf-context"
    namespace: "cnf-gateway"
  spec:
    destinationAddress: "10.20.2.37/32"
    ipv6destinationAddress: "2002::10:20:2:37/128"
    destinationPort: 80
    ipProtocol: "tcp"
    profile: "tcp"
    iRules: ["cnf-irule2, cnf-irule3"]

Example of multiple iRules applied in DNS Virtual Servers CR:

F5BigDnsCache

   apiVersion: "k8s.f5net.com/v1"
   kind: F5BigDnsCache
   metadata:
     name: "cnf-dnscache"
     namespace: "cnf-gateway"
   spec:
     cacheType: transparent
     transparent:
       localZones:
        - name: example.com
        zoneType: static
        records:
          - example.com. IN AAAA 2002::10:11:12:13

F5BigDnsApp

   apiVersion: "k8s.f5net.com/v1"
   kind: F5BigDnsApp
   metadata:
     name: "cnf-dnsapp"
     namespace: "cnf-gateway"
   spec:
     ipProtocol: "udp"
     iRules: ["dns-req1, dns-req2"] 
     destination:
       ipv6Address: "2002::192:168:100:201"
       port: 53
    snat:
     type: "automap"
    dns:
      dnsCache: "cnf-dnscache"
      dns64Mode: "secondary"
      dns64Prefix: "64:ff9b::"
      dns64AdditionalSectionRewrite: "v4-only"
    pool:
      members:
        - address: "2002::10:10:10:100"
        - address: "2002::10:10:10:101"
    monitors:
      dns:
        enabled: true
        queryName: "webapp.net."
        queryType: "aaaa"
        recv: "2002::10:10:20:200"

iRules with and without priority

Example F5BigCneIrule CR with priority

  apiVersion: "k8s.f5net.com/v1"
  kind: F5BigCneIrule
  metadata:
    name: "cnf-irule2"
    namespace: "cnf-gateway"
  spec:
    iRule: >
   when CLIENT_ACCEPTED priority 200 {
       set DEBUG 1
           #check the client IP address is it from Public IP range
               if {($DEBUG > 0 )} {
                   if {($DEBUG > 0 )} { log local0.debug "Client IP APps address from irule2" }
                   LSN::disable
                   return
               } else {
                   if {($DEBUG > 0 )} { log local0.debug "Client IP Apps address is private" }
               }
   }

Note: When multiple iRules are associated with a virtual server, the iRule with a lower priority value (higher numerical value) will be executed before the iRule with a higher priority value (lower numerical value).

Example F5BigCneIrule CR without priority

  apiVersion: "k8s.f5net.com/v1"
  kind: F5BigCneIrule
  metadata:
    name: "cnf-irule2"
    namespace: "cnf-gateway"
  spec:
    iRule: >
   when CLIENT_ACCEPTED {
       set DEBUG 1
           #check the client IP address is it from Public IP range
               if {($DEBUG > 0 )} {
                   if {($DEBUG > 0 )} { log local0.debug "Client IP APps address from irule2" }
                   LSN::disable
                   return
               } else {
                   if {($DEBUG > 0 )} { log local0.debug "Client IP Apps address is private" }
               }
   }

Note: If an iRule is applied to a virtual server without a specific priority assigned, it is considered to have the default priority. Multiple iRules with the same priority will be executed in the order in which they were inserted into the virtual server’s configuration.

Feedback

Provide feedback to improve this document by emailing cnfdocs@f5.com.