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

Migrating to NextGen Routes

Overview

NextGenRoute Controller uses extended ConfigMap 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 extended ConfigMap. 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

  1. The parameters defaultRouteGroup and extendedRouteSpec are mutually exclusive. Error out on extended ConfigMap processing with invalid configuration error.
  2. 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

To install F5 CRDs, run the following commands:

export CIS_VERSION=<cis-version>
# For example
# export CIS_VERSION=v2.12.0
kubectl create -f https://raw.githubusercontent.com/F5Networks/k8s-bigip-ctlr/${CIS_VERSION}/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: extended-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
  1. Configure controller-mode: openshift to use NextGen Route controller in CIS.
- --controller-mode=openshift
  1. Configure extended ConfigMap and specify that in the CIS deployment parameter.
- --extended-spec-configmap=f5demo2/extended-spec-config
  1. Remove the route-vserver-addr parameter from the CIS deployment and define as vserverAddr in extended ConfigMap.
  2. Remove route-http-vserver and route-https-vserver parameters from the CIS deployment and define as vserverName in extended ConfigMap. CIS will add the suffix _443 for secure virtual server. See step 2 above.
  3. Remove default-client-ssl and default-server-ssl parameters from the CIS deployment and define them under baseRouteSpec in extended ConfigMap. See step 2 above.
  4. Remove tls-version, cipher-group, and ciphers parameters from the CIS deployment and define them under baseRouteSpec in extended ConfigMap. See step 2 above.
  5. 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",
"--extended-spec-configmap=f5demo2/extended-spec-config",
"--insecure=true",
"--route-label=f5type=systest",

Note

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