Last updated on: 2023-05-31 04:59:08.

Migrating to NextGen Routes¶

Overview¶

NextGenRoute Controller uses extendedConfigMap for extending the native resources (routes). All the routes are grouped by namespaces or namespace-labels into RouteGroups. Each RouteGroup shares the same vsAddress, vsName, and policy CR, which is specified in extendedConfigMap. In order to migrate to NextGen F5 recommends creating an extended ConfigMap and policy CR, then modifying the CIS deployment accordingly.

Migration using defaultRouteGroup¶

Currently, RouteGroup are expected to define per namespace or namespace label as follows:

Using Namespace¶

extendedRouteSpec:
- namespace: foo
  vserverAddr: 10.8.0.4
  vserverName: nextgenroutes
  allowOverride: true
- namespace: bar
  vserverAddr: 10.8.0.5
  allowOverride: false

Using Namespace Label¶

extendedRouteSpec:
- namespaceLabel: environment=dev
  vserverAddr: 10.8.3.11
  vserverName: nextgenroutes
  bigIpPartition: dev
  policyCR: default/sample-policy
- namespaceLabel: environment=test
  vserverAddr: 10.8.3.12
  policyCR: default/sample-policy

Note

To make migration seamless, you can use defaultRouteGroup. Once migration is successful, and CIS creates a virtual server on BIG-IP, then extendedRouteSpec can be leveraged to create multiple virtual servers.

Legacy CIS VirtualServer Parameters¶

In legacy routes, all http/https routes are grouped into a single virtual server on BIG-IP. The following CIS deployment args are used for the legacy virtual server creation:

Parameter	Description
route-http-vserver	vserverName for http server
route-https-vserver	vserverName for https server
route-vserver-addr	vserver address

NextGen Routes defaultRouteGroup¶

In NextGen controller, you can provide the same servername and address in baseRouteSpec using defaultRouteGroup as follows:

data:
  extendedSpec: |
    baseRouteSpec:
     tlsCipher:
       tlsVersion: 1.2
       ciphers: DEFAULT
       cipherGroup: /Common/f5-default
     defaultTLS:
       clientSSL: /Common/clientssl
       serverSSL: /Common/serverssl
       reference: bigip
     defaultRouteGroup:
       vserverAddr: 10.8.0.10
       vserverName: ose_server
       policyCR: ""

Parameter	Required	Description
vserverAddr	Required	Bind address for virtual server for OpenShift Route objects
vserverName	Required	The name of the http virtual server for OpenShift Routes
policyCR	Optional	Name of Policy CR to in which to attach defined profiles/policies

Note

The parameters defaultRouteGroup and extendedRouteSpec are mutually exclusive. Error out on extendedConfigMap processing with invalid configuration error.
The https virtual server name is automatically created using vserverName. For example: <vserverName>_<https_port_no>.

Prerequisites¶

Before migrating to NextGen Routes, stop the running CIS.

NextGen Route Migration Tool¶

This tool helps in migrating from Legacy Routes to NextGen Routes and generates the required Extended ConfigMap, policyCR (if the AS3 override ConfigMap file is provided), and CIS deployment file which can be used to migrate to NextGen Routes mode. See the NextGen Migration Tool on GitHub

Example Migration to NextGen Routes¶

Legacy CIS Configuration¶

 args: [
   "--bigip-username=admin",
   "--bigip-password=admin",
   "--bigip-url=10.10.10.20",
   "--bigip-partition=openshift",
   "--pool-member-type=cluster",
   "--openshift-sdn-name=/Common/openshift_vxlan",
   "--manage-routes=true",
   "--namespace=f5demo",
   "--namespace=f5demo2",
   "--route-vserver-addr=10.192.75.107",
   "--log-level=DEBUG",
   "--log-as3-response=true",
   "--route-http-vserver=test_unsecure_vs",
   "--route-https-vserver=test_secure_vs",
   "--default-client-ssl=/Common/clientssl",
   "--default-server-ssl=/Common/serverssl",
   "--tls-version=1.3",
   "--cipher-group=/Common/f5-default",
   "--insecure=true",
   "--route-label=f5type=systest",
   ]

Sample Route¶

 apiVersion: route.openshift.io/v1
 kind: Route
 metadata:
   annotations:
     virtual-server.f5.com/clientssl: /Common/bar-clientssl
     virtual-server.f5.com/serverssl: /Common/bar-serverssl
     virtual-server.f5.com/balance: least-connections-node
     virtual-server.f5.com/allow-source-range: "1.2.3.4/32,2.2.2.0/24"
     virtual-server.f5.com/waf: /Common/WAF_Policy
     virtual-server.f5.com/health: |
       [
         {
           "path": "pytest-bar-1.com/",
           "send": "HTTP GET /",
           "interval": 5,
           "timeout": 10
         }
       ]
   labels:
     f5type: systest
   name: svc-pytest-bar-1-com
   namespace: f5demo
 spec:
   host: pytest-bar-1.com
   path: /
   tls:
     termination: edge
   to:
     kind: Service
     name: svc-pytest-bar-1-com
     weight: 100
   wildcardPolicy: None

Migrating to NextGenRoutes¶

1. Install the CRDs

Install the F5 CRDs using following Commands:

kubectl create -f https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/master/docs/config_examples/customResourceDefinitions/customresourcedefinitions.yml

2. Create Extended ConfigMap using defaultRouteGroup

Extended ConfigMap is required with the NextGen Route Controller.

You can create an extended ConfigMap for the given example by defining the vserverAddr the same as the route-vserver-addr parameter in the CIS deployment.

apiVersion: v1
kind: ConfigMap
metadata:
  name: global-spec-config
  namespace: f5demo2
data:
    extendedSpec: |
      baseRouteSpec:
       tlsCipher:
         tlsVersion: 1.3
         cipherGroup: /Common/f5-default
       defaultTLS:
         clientSSL: /Common/clientssl
         serverSSL: /Common/serverssl
         reference: bigip
       defaultRouteGroup:
         vserverAddr: 10.192.75.107
         vserverName: ose_server
         policyCR:

Note

Make sure to use the namespace where you created the ConfigMap monitored by CIS.

3. Prepare the Policy CR (Optional)

Optionally, you can continue using WAF and AllowSourceRange annotations in routes. You can create the Policy CR as follows for WAF and AllowSourceRange annotations:

apiVersion: cis.f5.com/v1
kind: Policy
metadata:
  labels:
    f5cr: "true"
  name: sample-policy
  namespace: f5demo2
spec:
  l7Policies:
    waf: /Common/WAF_Policy
  l3Policies:
    allowSourceRange:
      - 1.2.3.4/32
      - 2.2.2.0/24

Note

If WAF/AllowSourceRange is defined in both route annotation and Policy CR, route annotation takes the priority by default.
You can use the Policy CR to extend the virtual server capabilities even more.
Make sure to use the namespace where you created the Policy CR monitored by CIS.

4. Update the CIS deployment parameters and start

Configure controller-mode: openshift to use NextGen Route controller in CIS.

- --controller-mode=openshift

Configure extended ConfigMap and specify that in the CIS deployment parameter.

- --route-spec-configmap=f5demo2/global-spec-config

Remove the route-vserver-addr parameter from the CIS deployment and define as vserverAddr in extendedConfigMap.
Remove route-http-vserver and route-https-vserver parameters from the CIS deployment and define as vserverName in extendedConfigMap. CIS will add the suffix _443 for secure virtual server. See step 2 above.
Remove default-client-ssl and default-server-ssl parameters from the CIS deployment and define them under baseRouteSpec in extendedConfigMap. See step 2 above.
Remove tls-version, cipher-group, and ciphers parameters from the CIS deployment and define them under baseRouteSpec in extendedConfigMap. See step 2 above.
Remove override-as3-declaration parameter as it is no longer supported with NextGen Routes. You can use the Policy CR to extend the virtual server capabilities. See an example on GitHub.

"--bigip-username=admin",
"--bigip-password=admin",
"--bigip-url=10.10.10.20",
"--bigip-partition=openshift",
"--pool-member-type=cluster",
"--openshift-sdn-name=/Common/openshift_vxlan",
"--controller-mode=openshift",
"--namespace=f5demo",
"--namespace=f5demo2",
"--log-level=DEBUG",
"--log-as3-response=true",
"--route-spec-configmap=f5demo2/global-spec-config",
"--insecure=true",
"--route-label=f5type=systest",

Note

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

Previous Next