Last updated on: 2024-04-23 04:45:25.

VirtualServer

VirtualServer resource defines the load balancing configuration for a domain name.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
 apiVersion: "cis.f5.com/v1"
 kind: VirtualServer
 metadata:
   name: coffee-virtual-server
   labels:
     f5cr: "true"
 spec:
   host: coffee.example.com
   virtualServerAddress: "172.16.3.4"
   pools:
   - path: /coffee
     service: svc-2
     servicePort: 80
   serviceAddress:
   - icmpEcho: "enable"
     arpEnabled: true
     routeAdvertisement: "all"

Important

  • CIS will only process custom resources with f5cr label set as true. See lines 5-6 above.
  • The above VirtualServer is insecure. Attach a TLSProfile to make it secure.

Open API Schema Validation for VirtualServer

Components

VirtualServer Components

Parameter Type Required Default Description
host String Optional N/A Virtual Host.
hostAliases Array of strings Optional N/A List of additional host names for a virtual server other than the primary host.
pools List of pools Required N/A List of BIG-IP Pools.
virtualServerAddress String Optional N/A IP4/IP6 Address of BIG-IP Virtual Server. IP address can also be replaced by a reference to a Service_Address.
serviceAddress List of service addresses Optional N/A Service address definition allows you to add a number of properties to your (virtual) server address.
ipamLabel String Optional N/A IPAM label name for IP address management which is map to ip-range in IPAM controller deployment.
virtualServerName String Optional N/A Custom name of BIG-IP Virtual Server.
virtualServerHTTPPort Integer Optional 80 Custom HTTP port for the Virutal Server.
virtualServerHTTPSPort Integer Optional 443 Custom HTTPS port for the Virtual Server.
tlsProfileName String Optional N/A Describes the TLS configuration for BIG-IP Virtual Server.
rewriteAppRoot String Optional N/A Rewrites the path in the HTTP Header (and Redirects) from “/” (root path) to specifed path.
waf String Optional N/A Reference to WAF policy on BIG-IP.
snat String Optional auto Reference to SNAT pool on BIG-IP. The supported values are none, auto, self and the BIG-IP SNATPool path.
allowVlans List of VLANs Optional N/A List of VLAN objects from which to allow traffic.
httpTraffic String Optional allow Configure behavior of HTTP Virtual Server. The allowed values are: allow: allow HTTP (default), none: only HTTPs, redirect: redirect HTTP to HTTPS.
hostGroup String Optional N/A Associated VirutalServers are grouped based on “hostGroup” parameter. MultiHost support for VS CRD is achieved using this parameter. See the section below on MultiHost support using hostGroup Parameter.
persistenceProfile String Optional cookie CIS uses the AS3 default persistence profile. VirtualServer CRD resource takes precedence over Policy CRD. Allowed values are existing BIG-IP Persistence profiles.
htmlProfile String Optional N/A Pathname of existing BIG-IP HTML profile. VirtualServer CRD resource takes precedence over Policy CRD. Allowed values are existing BIG-IP HTML profiles. |
dos String Optional N/A Pathname of existing BIG-IP DoS policy.
botDefense String Optional N/A Pathname of existing BIG-IP botDefense policy.
profileMultiplex String Optional N/A CIS uses the AS3 default profileMultiplex profile. Allowed values are existing BIG-IP profileMultiplex profiles..
profiles Object Optional N/A BIG-IP TCP Profiles.
tcp Object Optional N/A BIG-IP TCP client and server profiles.
policyName String Optional N/A Name of Policy CRD to attach profiles/policies defined in it.
iRules Array of strings Optional N/A iRules to be attached to the VirtualServer.
allowSourceRange String Optional N/A Comma-separated list of CIDR addresses to allow inbound to services corresponding to VirtualServer CRD. Allowed values are comma-separated, CIDR formatted, IP addresses. For example: 1.2.3.4/32,2.2.2.0/24
httpMrfRoutingEnabled Boolean Optional false Specifies whether to use the HTTP message routing framework (MRF) functionality. This property is available on BIG-IP 14.1 and above.
additionalVirtualServerAddresses String Optional N/A List of virtual addresses additional to virtualServerAddress to which virtual will be listening. Uses AS3 virtualAddresses parameter to expose Virtual server which will listen to each IP address in the list.
partition String Optional N/A BIG-IP Partition.
hostPersistence Object Optional N/A Persist session rule action will be added to the VS Policy based on the host. Allowed values are existing BIG-IP Persist session.
defaultPool defaultPool Optional N/A Default BIG-IP Pool for virtual server

Note

  • virtualServerName is ignored when using the hostGroup and ltm virtual server is created with default naming convention. The default name for a virtual server created on BIG-IP is “crd_<virtual IP address>_<virtual server port>”. For example: crd_172_16_3_4_80.

Default Pool Components

Parameter Type Required Default Description
service String Required N/A Service deployed in kubernetes cluster
serviceNamespace String Optional N/A Namespace of service, define it if service is present in a namespace other than the one where Virtual Server Custom Resource is present
servicePort Integer or String Required N/A Port to access Service.Could be service port, service port name or targetPort of the service
loadBalancingMethod String Optional round-robin Allowed values are existing BIG-IP Load Balancing methods for pools.
nodeMemberLabel String Optional N/A List of Nodes to consider in NodePort Mode as BIG-IP pool members. This Option is only applicable for NodePort Mode
monitors monitor Optional N/A Specifies multiple monitors for VS Pool
serviceDownAction String Optional none Specifies connection handling when member is non-responsive
reselectTries Integer Optional 0 Maximum number of attempts to find a responsive member for a connection
reference String Required N/A Allowed values are bigip or service
name String Optional N/A pool name or reference to the pool name existing on bigip

Pool Components

Parameter Type Required Default Description
path String Required N/A Path to access the service.
service String Required N/A Service deployed in Kubernetes cluster.
waf String Optional N/A Reference to WAF policy on BIG-IP
loadBalancingMethod String Optional N/A Allowed values are existing BIG-IP Load Balancing methods for pools.
nodeMemberLabel String Optional N/A List of Nodes to consider in NodePort mode as BIG-IP pool members. This option is only applicable for NodePort mode.
servicePort String Required N/A targetPort to access service.
monitor Monitor Optional N/A Health Monitor to check the health of Pool Members.
MinimumMonitors Integer or String Optional N/A Member is down when fewer than the minimum number of monitors report it healthy. Specify “all” to require all of the monitors to be up.
monitors Monitor Optional N/A Specifies multiple monitors for VS Pool.
rewrite String Optional N/A Rewrites the path in the HTTP Header while submitting the request to Server in the pool.
serviceNamespace String Optional N/A Namespace of service. Define it if service is present in a namespace other than the one where Virtual Server Custom Resource is present.
serviceDownAction String Optional N/A Specifies connection handling when member is non-responsive. Examples: drop, none, reselect, reset
reselectTries Integer Optional 0 Maximum number of attempts to find a responsive member for a connection.
hostRewrite String Optional N/A Rewrites the hostname http header while submitting the request to pool members.
weight Integer Optional N/A weight allocated to service A in AB deployment
alternateBackends List of string Optional N/A List of alternate backends for AB deployment

Note

The parameter monitors takes priority over monitor if both are provided in the VirtualServer spec.

alternateBackends Components

Parameter Type Required Default Description
service String Required N/A service name for alternate backend
serviceNamespace String Required N/A namespace of the backend service if its present in namespace different than virtual server CR
weight Integer Required N/A weight allocated for the alternate backend service

Monitor Components

Parameter Type Required Default Description
type String Required N/A HTTP, HTTPS, or TCP.
send String Required GET /rn HTTP request string to send.
recv String Optional N/A String or RegEx pattern to match in first 5,120 bytes of backend response.
interval Int Required 5 Seconds between health queries.
timeout Int Optional 16 Seconds before query fails.
targetPort Int Optional 0 The port (if any) that the monitor should probe. If 0 (default) then pool member port is used. Translates to “Alias Server Port” on BIG-IP pool.
name String Required N/A Reference to health monitor name existing on BIG-IP.
reference String Required N/A Value should be bigip for referencing custom monitor on the BIG-IP.
sslProfile String Optional N/A sslProfile to attach to custom https monitor created on BIGIP.Applicable only for type “https” monitor.

Note

  • Health Monitor associated with the first path will be considered if multiple paths have the same backend.
  • The monitor can be a reference to an existing healthmonitor on the BIG-IP system, in which case name and reference are required parameters.
  • For creating a health monitor object on the BIG-IP with UserInput, type, send, and interval are required parameters.

TCP Profile Components

Parameter Type Required Default Description
client String Required Custom_TCP CIS uses the AS3 default TCP client profile. Allowed values are existing BIG-IP TCP Client profiles.
server String Optional N/A Allowed values are existing BIG-IP TCP Server profiles. Note: Server TCP Profile can only be used along with Client profile.

Service Address Components

Parameter Type Required Default Description
arpEnabled Boolean Optional true If true (default), the system services ARP requests on this address.
icmpEcho String Optional enable If enabled (default), the system answers ICMP echo requests on this address. Values: enable, disable, and selective.
routeAdvertisement String Optional disable If enabled, the route is advertised. Values: enable, disable, selective, always, any, and all.
spanningEnabled Boolean Optional false If true, this enables all BIG-IP systems in the device group to listen for and process traffic on the same virtual address.
trafficGroup String Optional default Specifies the traffic group to which the Service_Address belongs.

hostPersistence Components

Parameter Type Required Default Description
method String Required N/A Allowed values are existing BIG-IP Persist session values.
metaData Object Optional N/A Attributes to be configured based on the hostPersistence Method.

hostPersistence metaData Params

Parameter Type Required for Persist Methods Default Description
name String cookieInsert, cookieRewrite, cookiePassive, cookieHash N/A Name of cookie.
key String universal, hash, carp N/A The key to use.
netmask String sourceAddress, destinationAddress N/A Network mask.
timeout Integer sourceAddress, destinationAddress, universal, carp, hash, cookieHash N/A Timeout value in seconds.
expiry String cookieInsert, cookieRewrite N/A Expiration duration expressed as [Nd][HH:MM[:SS]].
offset Integer cookieHash N/A Offset into hash.
length Integer cookieHash N/A Substring length.

Note

  • hostPersistence will be configured when host is present in the Virtual Server CR.
  • method value none will disable the persistence for the respective host.
  • metaData params should be configured as per the Method name.

Custom Virtual Server Name

CRD allows the user to create a custom name for the virtual servers on BIG-IP using the virtualServerName parameter.

By deploying this yaml file in your cluster, CIS will create a Virtual Server on BIG-IP as “<virtual server name>_<virtual server port>”. For example: cafe_virtual_server_80.

This is optional to use. The default name for a virtual server created on BIG-IP is “crd_<virtual IP address>_<virtual server port>”. For example: crd_172_16_3_4_80.

custom-virtual-name.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
apiVersion: "cis.f5.com/v1"
kind: VirtualServer
metadata:
  name: my-new-virtual-server
  labels:
    f5cr: "true"
spec:
  # This is an insecure virtual, Please use TLSProfile to secure the virtual
  # check out tls examples to understand more.
  host: cafe.example.com
  virtualServerAddress: "172.16.3.4"
  virtualServerName: "cafe-virtual-server"
  pools:
  - path: /coffee
    service: svc-2
    servicePort: 80

Note

  • virtualServerName is ignored when using the hostGroup and ltm virtual server is created with default naming convention.

Custom Virtual Port in CRD

You can configure the virtual address port number in CRD. This is required if you want to use the same VIP with different port numbers for different domains. There are two options for configuring:

virtualServerHTTPPort

By deploying this yaml file in your cluster, CIS will create a Virtual Server on BIG-IP with VIP custom http port as 500. It will load balance the traffic for domain cafe.example.com.

custom-http-port.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
apiVersion: "cis.f5.com/v1"
kind: VirtualServer
metadata:
  name: my-new-virtual-server
  labels:
    f5cr: "true"
spec:
  host: cafe.example.com
  virtualServerAddress: "172.16.3.4"
  virtualServerHTTPPort: 8080
  pools:
  - path: /coffee
    service: svc-2
    servicePort: 80

virtualServerHTTPSPort

By deploying this yaml file in your cluster, CIS will create a Virtual Server on BIG-IP with VIP custom https port as 500. It will load balance the traffic for domain cafe.example.com.

custom-https-port.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
apiVersion: "cis.f5.com/v1"
kind: VirtualServer
metadata:
  name: my-new-virtual-server
  labels:
    f5cr: "true"
spec:
  host: cafe.example.com
  virtualServerAddress: "172.16.3.4"
  virtualServerHTTPSPort: 8443
  pools:
  - path: /coffee
    service: svc-2
    servicePort: 80

Virtual Server Custom Resource without Host Parameter

You can create a simple HTTP Virtual Server without the Host parameter. By deploying the following YAML file in your cluster, CIS will create a Virtual Server on BIG-IP with VIP 172.16.3.4 and attach a policy that forwards the traffic to pool svc-1 when the URI path segment is /coffee.

Important

This is an insecure virtual server, please use TLSProfile to secure the virtual.

virtual-with-hostGroup.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
apiVersion: "cis.f5.com/v1"
kind: VirtualServer
metadata:
  name: hoHost-single-pool
  labels:
    f5cr: "true"
spec:
  # This is an insecure virtual, Please use TLSProfile to secure the virtual
  # check out tls examples to understand more.
  virtualServerAddress: "172.16.3.4"
  pools:
  - path: /coffee
    service: svc-1
    servicePort: 80

MultiHost support using hostGroup Parameter

The Multi-host feature allows CIS to support a single HTTP VirtualServer on BIG-IP for different hostnames. This is similar to how OpenShift routes work today. The benefit of using the multi-host feature is the ability to reuse the public IP Address on BIG-IP, which helps when Public IP addresses are limited.

You can configure VirtualServer CRD using the hostGroup parameter to club virtual servers with different hostnames into one in BIG-IP.

By deploying the following YAML file in your cluster, CIS will create a single HTTP Virtual Server on the BIG-IP system with different hostnames (in this example, coffee.example.com and tea.example.com) having the same hostGroup “cafe” and same ipamLabel “Dev”.

Important

  • This is an insecure virtual server, please use TLSProfile to secure the virtual.
  • You must use either virtualServerAddress or ipamLabel parameters with the same value in all VirtualServer CRDs.

Note

virtualServerName spec parameter is ignored when hostGroup is enabled. The default name for a virtual server created on BIG-IP is “crd_<virtual IP address>_<virtual server port>”. For example: crd_172_16_3_4_80.

noHost-single-pool-virtual.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
apiVersion: "cis.f5.com/v1"
kind: VirtualServer
metadata:
  name: coffee-virtual-server
  labels:
    f5cr: "true"
spec:
  # This is an insecure virtual, Please use TLSProfile to secure the virtual
  # check out tls examples to understand more.
  host: coffee.example.com
  hostGroup: cafe
  ipamLabel: Dev
  pools:
  - path: /mocha
    service: svc-2
    servicePort: 80
---
apiVersion: "cis.f5.com/v1"
kind: VirtualServer
metadata:
  name: tea-virtual-server
  labels:
    f5cr: "true"
spec:
  # This is an insecure virtual, Please use TLSProfile to secure the virtual
  # check out tls examples to understand more.
  host: tea.example.com
  hostGroup: cafe
  ipamLabel: Dev
  pools:
    - path: /greentea
      service: svc-2
      servicePort: 80

MultiPartition Support using partition spec parameter

CRD supports the MultiPartition feature for VirtualServer CR, where the user can provision BIG-IP in multiple partitions. This helps to easily manage the bigipConfig among the partitions. The MultiPartition feature also improves performance, as CIS processes only the partition when there is a change, instead of sending a unified AS3 declaration to all of the partitions on the BIG-IP every time a change/event is detected.

CIS processes multiple tenant information and still sends the single unified declaration to BIG-IP to avoid multiple posts to BIG-IP for the first time.

Note

AS3 post call is formed as mgmt/shared/appsvcs/declare/tenant1,tenant2.

Multiple VirtualServers do not share the same virtual server address across multiple partitions. F5 does not currently support VS sharing the same host group or host with the same address in multiple partitions. The following rules apply for all VS resources. - Virtual servers with the same host group should be in one partition. - Virtual servers with the same host should be in one partition. - Virtual servers with the same VS address should be in one partition. - Virtual servers cannot share the same VIP across multiple partitions, irrespective of port.

Example of VS using “partition” spec parameter (https://github.com/F5Networks/k8s-bigip-ctlr/tree/2.x-master/docs/config_examples/customResource/VirtualServer/partition)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
apiVersion: cis.f5.com/v1
kind: VirtualServer
metadata:
  labels:
   f5cr: "true"
  name: cr-foo1
  namespace: default
spec:
  # This is an insecure virtual, Please use TLSProfile to secure the virtual
  # check out tls examples to understand more.
  host: foo.example.com
  partition: dev
  pools:
  - monitor:
     interval: 20
     recv: a
     send: /
     timeout: 10
    type: http
    path: /foo
    service: pytest-svc-1
    servicePort: 80
  snat: auto
  virtualServerAddress: 10.8.3.11

Virtual Server Custom Resource with IPv6 Address

Virtual Server with IPv6
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
apiVersion: "cis.f5.com/v1"
kind: VirtualServer
metadata:
  name: cafe-virtual-server
  labels:
    f5cr: "true"
spec:
  # This is an insecure virtual, Please use TLSProfile to secure the virtual
  # check out TLS examples to understand more.
  host: cafe.example.com
  virtualServerAddress: "2001:0db8:85a3:0000:0000:8a2e:0370:7335"
  virtualServerName: "cafe-virtual-server"
  pools:
  - path: /coffee
    service: svc-2
    servicePort: 80

Virtual Server Custom Resource with hostAliases

hostAliases is used to specify additional host names for a virtual server other than the primary host. hostAliases is useful when you want to use a single virtual server to serve multiple domains and forward traffic to the same pools.

See Virtual Server with Host Aliases. example.

Examples Repository

View more examples on GitHub.


Note

To provide feedback on Container Ingress Services or this documentation, please file a GitHub Issue.